atoms-vscode-runtime 0.1.0
Atoms VS Code Python runtime and MCP server for atomic structure analysis
Requires Python: >=3.9

# 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:

```bash
pip install ase numpy scipy pandas plotly fastmcp
```

For MACE energy/optimization features:

```bash
pip install mace-torch
```

### Install from Source

```bash
# 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

```bash
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

```json
{
  "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](vscode-extension/LICENSE) for details.

**Developed by Sandip De**