rootstock 0.5.0__py3-none-any.whl → 0.5.1__py3-none-any.whl

rootstock/clusters.py

@@ -12,7 +12,7 @@ from pathlib import Path
 # Registry of known clusters and their rootstock root directories
 CLUSTER_REGISTRY: dict[str, str] = {
     "modal": "/vol/rootstock",
-    "della": "/scratch/gpfs/SHARED/rootstock",
+    "della": "/scratch/gpfs/ROSENGROUP/common/rootstock",
 }
 
 # Known environment families (used for validation)

rootstock-0.5.1.dist-info/METADATA

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: rootstock
+Version: 0.5.1
+Summary: MLIP calculators with isolated Python environments
+License-File: LICENSE.md
+Requires-Python: >=3.10
+Requires-Dist: ase>=3.22
+Requires-Dist: numpy>=1.24
+Requires-Dist: packaging>=21.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Provides-Extra: mace
+Requires-Dist: mace-torch>=0.3; extra == 'mace'
+Requires-Dist: torch>=2.0; extra == 'mace'
+Provides-Extra: modal
+Requires-Dist: modal>=0.56; extra == 'modal'
+Description-Content-Type: text/markdown
+
+# Rootstock
+
+A proof-of-concept package for running MLIP (Machine Learning Interatomic Potential) calculators in isolated pre-built Python environments, communicating via the i-PI protocol over Unix sockets. Currently deployed on Princeton's Della cluster.
+
+## Quick Start
+
+```python
+from ase.build import bulk
+from rootstock import RootstockCalculator
+
+atoms = bulk("Cu", "fcc", a=3.6) * (5, 5, 5)
+
+with RootstockCalculator(
+    cluster="della",
+    model="mace",
+    checkpoint="medium",
+    device="cuda",
+) as calc:
+    atoms.calc = calc
+    print(atoms.get_potential_energy())
+    print(atoms.get_forces())
+```
+
+**Note:** Environments must be pre-built before use. See [Administrator Setup](#administrator-setup).
+
+## Installation
+
+```bash
+pip install rootstock
+# or
+uv pip install rootstock
+```
+
+## API
+
+The `model` parameter selects the environment family. The optional `checkpoint` parameter selects specific model weights (defaults to the environment's default if omitted).
+
+```python
+# Explicit checkpoint
+RootstockCalculator(cluster="della", model="mace", checkpoint="medium")
+
+# Default checkpoint (each environment has a sensible default)
+RootstockCalculator(cluster="della", model="uma")
+
+# Custom root path instead of a known cluster
+RootstockCalculator(root="/scratch/gpfs/ROSENGROUP/common/rootstock", model="mace")
+```
+
+## Available Models
+
+| Model | Checkpoint | Description |
+|-------|------------|-------------|
+| `mace` | `small` | MACE-MP-0 small |
+| `mace` | `medium` (default) | MACE-MP-0 medium |
+| `chgnet` | _(pretrained)_ | CHGNet pretrained universal model |
+| `uma` | `uma-s-1p1` (default) | Meta UMA small model (FAIRChem) |
+| `tensornet` | `TensorNet-MatPES-PBE-v2025.1-PES` (default) | TensorNet MatPES PBE (MatGL) |
+
+## Architecture
+
+```
+Main Process                          Worker Process (subprocess)
++-------------------------+          +-----------------------------+
+| RootstockCalculator     |          | Pre-built venv Python       |
+| (ASE-compatible)        |          | (mace_env/bin/python)       |
+|                         |          |                             |
+| server.py (i-PI server) |<-------->| worker.py (i-PI client)     |
+| - sends positions       |   Unix   | - receives positions        |
+| - receives forces       |  socket  | - calculates forces         |
++-------------------------+          +-----------------------------+
+```
+
+The worker process uses a pre-built virtual environment, providing:
+- **Fast startup**: No dependency installation at runtime
+- **Filesystem compatibility**: Works on NFS, Lustre, GPFS
+- **Reproducibility**: Same environment every time
+
+## Directory Structure
+
+```
+{root}/
+├── .python/                # uv-managed Python interpreters (portable)
+├── environments/           # Environment SOURCE files (*.py with PEP 723)
+│   ├── mace_env.py
+│   ├── chgnet_env.py
+│   ├── uma_env.py
+│   └── tensornet_env.py
+├── envs/                   # Pre-built virtual environments
+│   ├── mace_env/
+│   │   ├── bin/python
+│   │   ├── lib/python3.11/site-packages/
+│   │   └── env_source.py   # Copy of environment source
+│   └── ...
+├── home/                   # Fake HOME for build & workers
+│   ├── .cache/fairchem/    # FAIRChem weights
+│   └── .matgl/             # MatGL weights
+└── cache/                  # XDG_CACHE_HOME for well-behaved libs
+    ├── mace/
+    └── huggingface/
+```
+
+## CLI Commands
+
+```bash
+# Build a pre-built environment
+rootstock build <env_name> --root <path> [--models m1,m2] [--force]
+
+# Show status
+rootstock status --root <path>
+
+# Register an environment source file
+rootstock register <env_file> --root <path>
+
+# List environments
+rootstock list --root <path>
+```
+
+## Administrator Setup
+
+Environments must be pre-built before users can run calculations.
+
+### 1. Create Directory Structure
+
+```bash
+mkdir -p /scratch/gpfs/ROSENGROUP/common/rootstock/{environments,envs,cache,home}
+```
+
+### 2. Register Environment Source Files
+
+```bash
+rootstock register environments/mace_env.py --root /scratch/gpfs/ROSENGROUP/common/rootstock
+rootstock register environments/chgnet_env.py --root /scratch/gpfs/ROSENGROUP/common/rootstock
+rootstock register environments/uma_env.py --root /scratch/gpfs/ROSENGROUP/common/rootstock
+rootstock register environments/tensornet_env.py --root /scratch/gpfs/ROSENGROUP/common/rootstock
+```
+
+### 3. Build Environments
+
+```bash
+ROOT=/scratch/gpfs/ROSENGROUP/common/rootstock
+
+rootstock build mace_env --root $ROOT --models small,medium
+rootstock build chgnet_env --root $ROOT
+rootstock build uma_env --root $ROOT --models uma-s-1p1
+rootstock build tensornet_env --root $ROOT
+
+# Verify
+rootstock status --root $ROOT
+```
+
+## Local Development
+
+```bash
+uv venv && source .venv/bin/activate
+uv pip install -e ".[dev]"
+ruff check rootstock/
+ruff format rootstock/
+```

{rootstock-0.5.0.dist-info → rootstock-0.5.1.dist-info}/RECORD

@@ -1,14 +1,14 @@
 rootstock/__init__.py,sha256=Qu570ne-AeWn6IT4Us00iU43A0yoRlyYDygYvKHduVQ,956
 rootstock/calculator.py,sha256=0KpW3coJ0ealEIZkxq9i4kZV5AxqCX1xZqDI1HkUPA4,6257
 rootstock/cli.py,sha256=6YtUXs38Zc5BC0AjEaAygtmct6JAsfaGTX7Zn2K_imY,13815
-rootstock/clusters.py,sha256=JQdPgBl_eyyP3nWxg_JOvD0Kh7YTVVXsNq038ZusVJg,1207
+rootstock/clusters.py,sha256=V5hTxlpq6-u3rfYhOkndqS96oSw2nXG8nDsTePAp79U,1218
 rootstock/environment.py,sha256=e7AAKd7cECwnX-KHCdfelHYVqm3xa1mIvc2MGaTJwBs,6583
 rootstock/pep723.py,sha256=hgTcP7Tp8_z_DCrmX4VPAitijvujmbGmz2ng1VgNYks,4616
 rootstock/protocol.py,sha256=CgfYNc0aKOkAQ-D8tvUrVO5q1mg0Xwcl2F02ZvYOJCI,10169
 rootstock/server.py,sha256=H7kn1FHGGyrrPZtgRKdfagbAF-SxI89H3u85GSToYmY,9210
 rootstock/worker.py,sha256=ty13OPDcKd_Zy95MAnTwa063Glz_RfUTBDja9Lxy4SM,8961
-rootstock-0.5.0.dist-info/METADATA,sha256=AD3xqByFrIWK-j8LdWfAxJXFKvbsdgro7xX1x9PPp-Y,5993
-rootstock-0.5.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-rootstock-0.5.0.dist-info/entry_points.txt,sha256=rPiVll-qj1wq7wZQTwSl2aF22GLnnpDz37hkPLvqlh0,49
-rootstock-0.5.0.dist-info/licenses/LICENSE.md,sha256=ORJAYeKSWpOYZ89KWT8ETWFb2u6MvKK3AhrMReDMWrA,1072
-rootstock-0.5.0.dist-info/RECORD,,
+rootstock-0.5.1.dist-info/METADATA,sha256=hoHLVVE66Lm8q5uEAKYetK6x7bllBDN99H3LvpXrZqc,5562
+rootstock-0.5.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+rootstock-0.5.1.dist-info/entry_points.txt,sha256=rPiVll-qj1wq7wZQTwSl2aF22GLnnpDz37hkPLvqlh0,49
+rootstock-0.5.1.dist-info/licenses/LICENSE.md,sha256=ORJAYeKSWpOYZ89KWT8ETWFb2u6MvKK3AhrMReDMWrA,1072
+rootstock-0.5.1.dist-info/RECORD,,

rootstock-0.5.0.dist-info/METADATA

@@ -1,210 +0,0 @@
-Metadata-Version: 2.4
-Name: rootstock
-Version: 0.5.0
-Summary: MLIP calculators with isolated Python environments
-License-File: LICENSE.md
-Requires-Python: >=3.10
-Requires-Dist: ase>=3.22
-Requires-Dist: numpy>=1.24
-Requires-Dist: packaging>=21.0
-Requires-Dist: tomli>=2.0; python_version < '3.11'
-Provides-Extra: dev
-Requires-Dist: pytest>=7.0; extra == 'dev'
-Requires-Dist: ruff>=0.1; extra == 'dev'
-Provides-Extra: mace
-Requires-Dist: mace-torch>=0.3; extra == 'mace'
-Requires-Dist: torch>=2.0; extra == 'mace'
-Provides-Extra: modal
-Requires-Dist: modal>=0.56; extra == 'modal'
-Description-Content-Type: text/markdown
-
-# Rootstock
-
-Run MLIP (Machine Learning Interatomic Potential) calculators in isolated pre-built Python environments, communicating via the i-PI protocol over Unix sockets.
-
-## Quick Start
-
-```python
-from ase.build import bulk
-from rootstock import RootstockCalculator
-
-atoms = bulk("Cu", "fcc", a=3.6) * (5, 5, 5)
-
-# Using a known cluster
-with RootstockCalculator(
-    cluster="modal",       # or "della"
-    model="mace-medium",   # or "chgnet", "mace-small", etc.
-    device="cuda",
-) as calc:
-    atoms.calc = calc
-    print(atoms.get_potential_energy())
-    print(atoms.get_forces())
-
-# Or with an explicit root path
-with RootstockCalculator(
-    root="/scratch/gpfs/SHARED/rootstock",
-    model="mace-medium",
-    device="cuda",
-) as calc:
-    atoms.calc = calc
-    print(atoms.get_potential_energy())
-```
-
-**Note:** Environments must be pre-built before use. See [Administrator Setup](#administrator-setup).
-
-## Installation
-
-```bash
-pip install rootstock
-# or
-uv pip install rootstock
-```
-
-## Model String Format
-
-The `model` parameter encodes both the environment and model-specific argument:
-
-| `model=`            | Environment    | Model Arg           |
-|---------------------|----------------|---------------------|
-| `"mace-medium"`     | mace_env       | `"medium"`          |
-| `"mace-small"`      | mace_env       | `"small"`           |
-| `"mace-large"`      | mace_env       | `"large"`           |
-| `"chgnet"`          | chgnet_env     | `""` (default)      |
-| `"mace-/path/to/weights.pt"` | mace_env | `"/path/to/weights.pt"` |
-
-## Known Clusters
-
-| Cluster | Root Path |
-|---------|-----------|
-| `modal` | `/vol/rootstock` |
-| `della` | `/scratch/gpfs/SHARED/rootstock` |
-
-For other clusters, use `root="/path/to/rootstock"` directly.
-
-## Administrator Setup
-
-Environments must be pre-built before users can run calculations.
-
-### 1. Create Directory Structure
-
-```bash
-mkdir -p /scratch/gpfs/SHARED/rootstock/{environments,envs,cache}
-```
-
-### 2. Create Environment Source Files
-
-```bash
-# mace_env.py
-cat > /scratch/gpfs/SHARED/rootstock/environments/mace_env.py << 'EOF'
-# /// script
-# requires-python = ">=3.10"
-# dependencies = ["mace-torch>=0.3.0", "ase>=3.22", "torch>=2.0"]
-# ///
-"""MACE environment for Rootstock."""
-
-def setup(model: str, device: str = "cuda"):
-    from mace.calculators import mace_mp
-    return mace_mp(model=model, device=device, default_dtype="float32")
-EOF
-```
-
-### 3. Build Environments
-
-```bash
-# Build MACE environment with model pre-download
-rootstock build mace_env --root /scratch/gpfs/SHARED/rootstock --models small,medium,large
-
-# Build CHGNet environment
-rootstock build chgnet_env --root /scratch/gpfs/SHARED/rootstock
-
-# Verify
-rootstock status --root /scratch/gpfs/SHARED/rootstock
-```
-
-## Architecture
-
-```
-Main Process                          Worker Process (subprocess)
-+-------------------------+          +-----------------------------+
-| RootstockCalculator     |          | Pre-built venv Python       |
-| (ASE-compatible)        |          | (mace_env/bin/python)       |
-|                         |          |                             |
-| server.py (i-PI server) |<-------->| worker.py (i-PI client)     |
-| - sends positions       |   Unix   | - receives positions        |
-| - receives forces       |  socket  | - calculates forces         |
-+-------------------------+          +-----------------------------+
-```
-
-The worker process uses a pre-built virtual environment, providing:
-- **Fast startup**: No dependency installation at runtime
-- **Filesystem compatibility**: Works on NFS, Lustre, GPFS, Modal volumes
-- **Reproducibility**: Same environment every time
-
-## Directory Structure
-
-```
-{root}/
-├── environments/           # Environment SOURCE files (*.py with PEP 723)
-│   ├── mace_env.py
-│   └── chgnet_env.py
-├── envs/                   # Pre-built virtual environments
-│   ├── mace_env/
-│   │   ├── bin/python
-│   │   ├── lib/python3.11/site-packages/
-│   │   └── env_source.py   # Copy of environment source
-│   └── chgnet_env/
-└── cache/                  # XDG_CACHE_HOME for model weights
-    ├── mace/               # MACE models
-    └── huggingface/        # HuggingFace models
-```
-
-## CLI Commands
-
-```bash
-# Build a pre-built environment
-rootstock build <env_name> --root <path> [--models m1,m2] [--force]
-
-# Show status
-rootstock status --root <path>
-
-# Register an environment source file
-rootstock register <env_file> --root <path>
-
-# List environments
-rootstock list --root <path>
-```
-
-## Running on Modal
-
-```bash
-# Initialize volume and build environments (takes ~10-15 min)
-modal run modal_app.py::init_rootstock_volume
-
-# Test pre-built environments
-modal run modal_app.py::test_prebuilt
-
-# Show status
-modal run modal_app.py::inspect_status
-
-# Run benchmarks
-modal run modal_app.py::benchmark_v4
-```
-
-## Performance
-
-IPC overhead is <5% for systems with 1000+ atoms compared to direct in-process execution.
-
-| System Size | Atoms | Typical Overhead |
-|-------------|-------|------------------|
-| Small       | 64    | ~10-15%          |
-| Medium      | 256   | ~5-8%            |
-| Large       | 1000  | <5%              |
-
-## Local Development
-
-```bash
-uv venv && source .venv/bin/activate
-uv pip install -e ".[dev]"
-ruff check rootstock/
-ruff format rootstock/
-```