Update installation instructions

README.md

@@ -16,10 +16,18 @@ The technical roadmap for the modelforge package is outlined in the wiki.
 
 Documentation for how to use the package can be found at: https://modelforge.readthedocs.io/en/latest/
 
+Subpackages
+-----------
+
+- `modelforge`: Core infrastructure for training, evaluating, and managing neural network potentials.
+- `modelforge-curate`: Dataset curation API and tools for building standardized datasets.
+- `modelforge-ase`: ASE calculator wrapper for running modelforge potentials through ASE workflows.
+- `modelforge-openmm`: OpenMM wrapper for using modelforge models in OpenMM simulations.
+
 Installation
 ------------
 
-To set up a development environment, clone the repository and install the package in editable mode:
+To set up any environment, first clone the repository:
 ```bash
 git clone https://github.com/choderalab/modelforge.git
 ```
@@ -28,27 +36,70 @@ navigate to the modelforge root directory:
 cd modelforge
 ```
 
-Create a micromamba environment (or similar package manager) and activate it:
+### Install Core Package (`modelforge`)
+
+Create and activate the base environment:
 ```bash
-micromamba create -n modelforge -f devtools/conda-envs/test_env.yaml
+micromamba create -n modelforge -f devtools/conda-envs/env.yaml
 micromamba activate modelforge
 ``` 
 
-install via pip in editable mode:
+Install the core package:
+```bash
+pip install -e . --no-deps --config-settings editable-mode=strict
+```
+
+### Install Dataset Curation Subpackage (`modelforge-curate`)
+
+From the base `modelforge` environment:
 ```bash
-pip install -e . --config-settings editable-mode=strict
+pip install -e modelforge-curate --no-deps --config-settings editable-mode=strict
 ```
 
-Install the curate package:
+### Install ASE Integration Subpackage (`modelforge-ase`)
+
+Create and activate the ASE runtime environment:
 ```bash
-pip install -e modelforge-curate --config-settings editable-mode=strict
+micromamba create -n modelforge-ase -f devtools/conda-envs/env_modelforge_ase.yaml
+micromamba activate modelforge-ase
 ```
 
-Install the ASE package (GPL Licensed):
+Install `modelforge` and the ASE integration package:
 ```bash
-pip install -e modelforge-ase --config-settings editable-mode=strict
+pip install -e . --no-deps --config-settings editable-mode=strict
+pip install -e modelforge-ase --no-deps --config-settings editable-mode=strict
 ```
 
+### Install ASE Examples/Notebook Dependencies
+
+If you want to run ASE notebooks/examples (includes `ase`, `ipykernel`, `nglview`):
+
+```bash
+micromamba create -n modelforge-ase-examples -f devtools/conda-envs/env_modelforge_ase_examples.yaml
+micromamba activate modelforge-ase-examples
+pip install -e . --no-deps --config-settings editable-mode=strict
+pip install -e modelforge-ase --no-deps --config-settings editable-mode=strict
+python -m ipykernel install --user --name modelforge-ase-examples --display-name "Python (modelforge-ase-examples)"
+```
+
+### Install OpenMM Integration Subpackage (`modelforge-openmm`)
+
+Create and activate the OpenMM runtime environment:
+
+```bash
+micromamba create -n modelforge-openmm -f devtools/conda-envs/env_modelforge_openmm.yaml
+micromamba activate modelforge-openmm
+```
+
+Install `modelforge` and the OpenMM integration package:
+
+```bash
+pip install -e . --no-deps --config-settings editable-mode=strict
+pip install -e modelforge-openmm --no-deps --config-settings editable-mode=strict
+```
+
+Note: Test environments in `devtools/conda-envs/test_env*.yaml` are intended for CI/development testing and are intentionally separate from runtime/example environments.
+
 
 ### Copyright
 

devtools/README.md

@@ -13,10 +13,14 @@ Windows testing if you only plan to deploy on specific platforms. These are just
 
 ### Conda Environment:
 
-This directory contains the files to setup the Conda environment for testing purposes
+This directory contains YAML files that describe Conda environments for runtime, examples, and testing.
 
 * `conda-envs`: directory containing the YAML file(s) which fully describe Conda Environments, their dependencies, and those dependency provenance's
-  * `test_env.yaml`: Simple test environment file with base dependencies. Channels are not specified here and therefore respect global Conda configuration
+  * `env.yaml`: Base environment for core `modelforge` development/runtime use
+  * `env_modelforge_ase.yaml`: ASE integration runtime environment
+  * `env_modelforge_ase_examples.yaml`: ASE examples/notebooks environment (includes `ipykernel` and `nglview`)
+  * `test_env.yaml`: Core testing environment used by CI
+  * `test_env_modelforge_ase.yaml`: ASE testing environment used by CI
 
 ### Additional Scripts:
 

devtools/conda-envs/env_modelforge_ase.yaml

@@ -0,0 +1,39 @@
+name: modelforge-ase
+channels:
+  - conda-forge
+  - pytorch
+dependencies:
+  # Base modelforge runtime dependencies
+  - python
+  - pip
+  - h5py
+  - tqdm
+  - toml
+  - qcportal>=0.50
+  - qcelemental
+  - pytorch>=2.1
+  - loguru
+  - lightning>=2.0.8
+  - tensorboard
+  - torchvision
+  - openff-units>=0.3.1
+  - torchmetrics>=1.4
+  - pint>=0.24.1
+  - rdkit
+  - retry
+  - sqlitedict
+  - pydantic>=2
+  - ray-all
+  - graphviz
+  - wandb>=0.18.5
+  - tad-dftd3
+  - tad-mctc
+
+  # ASE integration dependency
+  - ase
+
+  # Python-only runtime dependencies not available from conda-forge
+  - pip:
+      - jax == 0.4.34
+      - flax==0.10.1
+      - pytorch2jax

devtools/conda-envs/env_modelforge_ase_examples.yaml

@@ -0,0 +1,43 @@
+name: modelforge-ase-examples
+channels:
+  - conda-forge
+  - pytorch
+dependencies:
+  # Base modelforge runtime dependencies
+  - python
+  - pip
+  - h5py
+  - tqdm
+  - toml
+  - qcportal>=0.50
+  - qcelemental
+  - pytorch>=2.1
+  - loguru
+  - lightning>=2.0.8
+  - tensorboard
+  - torchvision
+  - openff-units>=0.3.1
+  - torchmetrics>=1.4
+  - pint>=0.24.1
+  - rdkit
+  - retry
+  - sqlitedict
+  - pydantic>=2
+  - ray-all
+  - graphviz
+  - wandb>=0.18.5
+  - tad-dftd3
+  - tad-mctc
+
+  # ASE integration + notebook/example dependencies
+  - ase
+  - ipykernel
+  - nglview
+  - ipywidgets
+  - jupyterlab
+
+  # Python-only runtime dependencies not available from conda-forge
+  - pip:
+      - jax == 0.4.34
+      - flax==0.10.1
+      - pytorch2jax

devtools/conda-envs/env_modelforge_openmm.yaml

@@ -0,0 +1,40 @@
+name: modelforge-openmm
+channels:
+  - conda-forge
+  - pytorch
+dependencies:
+  # Base modelforge runtime dependencies
+  - python
+  - pip
+  - h5py
+  - tqdm
+  - toml
+  - qcportal>=0.50
+  - qcelemental
+  - pytorch>=2.1
+  - loguru
+  - lightning>=2.0.8
+  - tensorboard
+  - torchvision
+  - openff-units>=0.3.1
+  - torchmetrics>=1.4
+  - pint>=0.24.1
+  - rdkit
+  - retry
+  - sqlitedict
+  - pydantic>=2
+  - ray-all
+  - graphviz
+  - wandb>=0.18.5
+  - tad-dftd3
+  - tad-mctc
+
+  # OpenMM integration dependencies
+  - openmm
+  - openmm-torch
+
+  # Python-only runtime dependencies not available from conda-forge
+  - pip:
+      - jax == 0.4.34
+      - flax==0.10.1
+      - pytorch2jax