diff --git a/README.md b/README.md index aef8561a..0c6ba2c6 100644 --- a/README.md +++ b/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 diff --git a/devtools/README.md b/devtools/README.md index a81d19e6..4aeac36f 100644 --- a/devtools/README.md +++ b/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: diff --git a/devtools/conda-envs/env_modelforge_ase.yaml b/devtools/conda-envs/env_modelforge_ase.yaml new file mode 100644 index 00000000..1b17f52d --- /dev/null +++ b/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 diff --git a/devtools/conda-envs/env_modelforge_ase_examples.yaml b/devtools/conda-envs/env_modelforge_ase_examples.yaml new file mode 100644 index 00000000..382e2d4f --- /dev/null +++ b/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 diff --git a/devtools/conda-envs/env_modelforge_openmm.yaml b/devtools/conda-envs/env_modelforge_openmm.yaml new file mode 100644 index 00000000..40468516 --- /dev/null +++ b/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