Atoms VS Code

Visualize, analyze, and optimize atomic structures directly inside VS Code.

Atoms VS Code brings a full-featured atomic structure workbench into your editor — interactive 3D visualization with 3Dmol.js and Speck renderers, MACE-powered energy calculations and geometry optimizations, structural analysis (bonds, angles, RDF, coordination), frame-by-frame trajectory navigation, and an MCP server that lets GitHub Copilot and other LLM agents operate on your structures programmatically.

Developer: Sandip De
License: Apache 2.0

---

Features

3D Structure Visualization

• Dual rendering engines — 3Dmol.js (ball-and-stick, stick, sphere styles with adjustable ball scale) and Speck (space-filling with ambient occlusion, depth of field, outline, and custom atom/bond scaling)
• Unit cell display — toggle wireframe unit cell overlay
• Supercell replication — expand structures up to 8×8×8 along a, b, c axes
• Fullscreen mode — immersive viewer with overlay controls for frame navigation, energy plots, and playback

Trajectory & Frame Navigation

• Frame slider with numeric input and animated playback (configurable 100–5000 ms speed)
• Dual-range slider to select and load specific frame windows
• Configurable default frame window (last N frames)
• Color-coded frame markers for optimization jobs (running, done, unfinished, crashed)

Structural Analysis (6 tabs)

Tab	Description
⚡ Energy	Energy vs. frame plot (Plotly interactive), MACE single-point calculations with progress bar, resume from last computed, chunk size control, cancel, click-to-select frames, lasso/box selection, navigate & copy selections
🧪 Optimize	Geometry optimization — model selector, algorithm (BFGS / LBFGS / FIRE), fmax, max steps, cell optimization, dispersion D3, CuEq; live progress via JSONL polling; relaxation energy plot; step-by-step replay; multi-model overlay comparison; fullscreen relaxation viewer
📋 Summary	Formula, atom count, composition, cell lengths & angles, volume, density, PBC
📈 RDF	Radial distribution function with per-pair curves, configurable r_max and bins
📊 Bond Analysis	Bond distance distributions per element pair, statistics (count, mean, min, max, std)
📐 Angle Analysis	Bond angle distributions per triplet, statistics table

MACE Energy & Optimization

• Single-point MACE energy calculations across frame ranges
• Geometry optimization with BFGS, LBFGS, or FIRE
• Cell optimization via UnitCellFilter
• D3 dispersion corrections
• CuEq GPU acceleration mode
• Multi-model management — auto-discover .model files from configured directories, user-defined aliases
• Persistent sidecar caching — energy and optimization results stored alongside structure files, shared between UI and MCP server
• Resume tighter convergence runs from previous results
• Graceful cancellation via sentinel files

MCP Server (11 tools for LLM agents)

An integrated MCP server lets GitHub Copilot and other LLM-based agents interact with your structures:

Tool	Description
load_structure	Load any ASE-supported structure file
get_structure_summary_tool	Formula, composition, cell, volume, density
analyze_structure	Bond / angle / RDF / coordination analysis
calculate_energies	MACE single-point energies for a frame range
optimize_structure	Geometry optimization with MACE
cancel_optimization	Cancel a running optimization
list_models	List discovered MACE model files
get_frame_data	Retrieve XYZ + cell vectors for a frame
list_frames	List loaded frames and energy availability
export_frame_xyz	Export a frame as XYZ text
set_viewer_mode	Switch 3D viewer (3dmol / speck)

The MCP server shares cache files with the extension UI, so energies and optimizations computed via Copilot appear instantly in the webview and vice versa.

Additional Features

• Auto-load — automatically opens the structure viewer when you open a supported file in the explorer or editor
• Tab management — open each structure in its own tab, or reuse the existing panel
• Context menu — right-click structure files in the Explorer to load them directly
• Unfinished job resume — detects optimization jobs from previous sessions and offers to resume them
• Dependency check — prompts to install missing Python packages on first activation
• Smart Python resolution — checks ATOMS_VSCODE_PYTHON env var → atomsVscode.pythonPath setting → conda/virtualenv → workspace .venv → Python extension interpreter → fallback python

---

Supported File Formats

.traj · .xyz · .extxyz · .db · .cif · .poscar · .vasp · .pdb · .gen · .xsd · .res · .cell · .cfg · .lammps · .data — plus any format supported by ASE's ase.io.read()

---

Installation

Prerequisites

• VS Code ≥ 1.109.0
• Python ≥ 3.9
• Node.js and npm (for building from source)

Python Dependencies

Install into your Python environment:

pip install ase numpy scipy pandas plotly fastmcp

For MACE energy/optimization features:

pip install mace-torch

Install from Source

# Clone the repository
git clone <repo-url> atoms-vscode
cd atoms-vscode

# Install the Python runtime package
pip install -e .

# Build the VS Code extension
npm --prefix vscode-extension install
npm --prefix vscode-extension run compile

Install via VSIX

cd vscode-extension
npm install
npm run package
# Install the generated .vsix via VS Code: Extensions → ⋯ → Install from VSIX

---

Usage

Quick Start

1. Open VS Code in your project directory.
2. Open any supported structure file (.traj, .xyz, .cif, etc.) — the Atoms viewer opens automatically.
3. Or run Atoms: Open Structure Analysis from the Command Palette (Ctrl+Shift+P).
4. Right-click any structure file in the Explorer → Atoms: Load Structure by Path.

Commands

Command	Description
Atoms: Open Structure Analysis	Open the Atoms webview panel
Atoms: Load Structure by Path	Load a specific structure file (also in Explorer context menu)
Atoms: Summary Current Frame	Get a summary of the current frame
Atoms: Analyze Current Frame	Run structural analysis on the current frame

Settings

Configure in VS Code Settings or .vscode/settings.json:

Setting	Type	Default	Description
atomsVscode.pythonPath	string	""	Python executable for the analysis bridge. Leave empty for auto-detection.
atomsVscode.openInNewTab	boolean	true	Open each structure in its own tab vs. replacing the existing panel
atomsVscode.autoLoadOnFileOpen	boolean	true	Automatically open the viewer when a structure file is opened
atomsVscode.defaultRecentFrames	number	50	Number of most recent frames to load by default
atomsVscode.maceModelPath	string	""	Path to the active MACE model file
atomsVscode.maceModelDirs	array	[]	Directories to scan for .model files
atomsVscode.maceModelAliases	object	{}	Short name → model file path mapping
atomsVscode.maceDevice	string	"cpu"	Compute device (cpu, cuda)
atomsVscode.maceDispersion	boolean	false	Enable D3 dispersion corrections
atomsVscode.maceEnableCueq	boolean	false	Enable CuEq GPU acceleration mode

Example Workspace Settings

{
  "atomsVscode.pythonPath": "/path/to/your/python",
  "atomsVscode.maceModelPath": "/path/to/model.model",
  "atomsVscode.maceModelDirs": ["/path/to/models/directory"],
  "atomsVscode.maceDevice": "cpu"
}

Development (Debug Mode)

1. Open the atoms-vscode folder in VS Code.
2. Run npm --prefix vscode-extension install and npm --prefix vscode-extension run compile.
3. Press F5 to launch the Extension Development Host.
4. Open a structure file in the development host to test.

---

Architecture

┌──────────────────────────────────────────────────────┐
│  VS Code Extension (TypeScript)                      │
│  ├── extension.ts ─ activation, commands, state      │
│  ├── bridge.ts ─ JSON-RPC over stdio to Python       │
│  ├── webview.ts ─ HTML/JS template generation        │
│  ├── webview-app/main.js ─ browser-side UI           │
│  ├── cache.ts ─ energy & optimization sidecar cache  │
│  ├── model-discovery.ts ─ MACE model file scanner    │
│  ├── optimization-observer.ts ─ JSONL progress poll  │
│  ├── mcp-server-provider.ts ─ MCP server definition  │
│  └── mcp-display-bridge.ts ─ HTTP bridge for MCP→UI  │
├──────────────────────────────────────────────────────┤
│  Python Runtime (atoms_vscode_runtime)               │
│  ├── extension_bridge.py ─ JSON-RPC main loop,       │
│  │     load files, compute energies, optimize        │
│  ├── structural_analysis.py ─ bond, angle, RDF,      │
│  │     coordination analysis                         │
│  ├── services/analysis_api.py ─ high-level API       │
│  └── utils/analysis_helpers.py ─ cutoff estimation   │
├──────────────────────────────────────────────────────┤
│  MCP Server (mcp_server) ─ FastMCP over stdio        │
│  ├── server.py ─ 11 MCP tools                        │
│  ├── display_client.py ─ HTTP → display bridge       │
│  └── cache.py ─ shared cache (TS-compatible)         │
└──────────────────────────────────────────────────────┘

---

Troubleshooting

• No module named atoms_vscode_runtime — run pip install -e . from the repository root, or ensure your Python environment has the package installed.
• Wrong Python interpreter — set atomsVscode.pythonPath explicitly in settings.
• npm: command not found — ensure Node.js/npm are in your PATH; run npm --prefix vscode-extension run compile manually.
• MACE features unavailable — install mace-torch and set atomsVscode.maceModelPath to a valid .model file.
• Missing dependencies prompt — the extension will detect missing Python packages and offer to install them automatically.

---

License

Apache 2.0 — see LICENSE for details.

Developed by Sandip De