atoms-vscode-runtime 0.1.0

Atoms VS Code Python runtime and MCP server for atomic structure analysis

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