From 44172ebcaa7699e566dfe655fd7e41ec0bb2bd37 Mon Sep 17 00:00:00 2001 From: Nima Shoghi Date: Wed, 27 Nov 2024 15:47:51 -0500 Subject: [PATCH] Docs: Add comprehensive project documentation site Sets up Sphinx documentation with Read the Docs theme, including: - Installation guides for each backbone model - Detailed configuration and usage examples - Model backbone documentation - Contributing guidelines Adds GitHub Actions workflow to automatically build and deploy docs --- .github/workflows/docs.yml | 61 +++++++++ .gitignore | 3 +- README.md | 4 +- docs/Makefile | 19 +++ docs/backbones/eqV2.md | 0 docs/backbones/eqv2.md | 30 +++++ docs/backbones/{JMP.md => jmp.md} | 48 +------- docs/backbones/{M3GNet.md => m3gnet.md} | 16 --- docs/backbones/{ORB.md => orb.md} | 30 +++-- docs/conf.py | 45 +++++++ docs/contributing.md | 41 +++++++ docs/guides/model_usage.md | 66 ++++++++++ docs/guides/training_config.md | 157 ++++++++++++++++++++++++ docs/index.md | 45 +++++++ docs/installation.md | 92 ++++++++++++++ docs/introduction.md | 38 ++++++ docs/license.md | 27 ++++ docs/requirements.txt | 4 + 18 files changed, 649 insertions(+), 77 deletions(-) create mode 100644 .github/workflows/docs.yml create mode 100644 docs/Makefile delete mode 100644 docs/backbones/eqV2.md create mode 100644 docs/backbones/eqv2.md rename docs/backbones/{JMP.md => jmp.md} (66%) rename docs/backbones/{M3GNet.md => m3gnet.md} (86%) rename docs/backbones/{ORB.md => orb.md} (57%) create mode 100644 docs/conf.py create mode 100644 docs/contributing.md create mode 100644 docs/guides/model_usage.md create mode 100644 docs/guides/training_config.md create mode 100644 docs/index.md create mode 100644 docs/installation.md create mode 100644 docs/introduction.md create mode 100644 docs/license.md create mode 100644 docs/requirements.txt diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..2686e21 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,61 @@ +name: Deploy Documentation + +on: + push: + branches: + - main # or your default branch + paths: + - 'docs/**' + - '.github/workflows/docs.yml' + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment +concurrency: + group: "pages" + cancel-in-progress: true + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.10' + cache: 'pip' + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install -r docs/requirements.txt + pip install . + + - name: Build documentation + run: | + cd docs + make html + # Create .nojekyll file to allow files and folders starting with an underscore + touch _build/html/.nojekyll + + - name: Upload artifact + uses: actions/upload-pages-artifact@v2 + with: + path: docs/_build/html + + deploy: + needs: build + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v2 diff --git a/.gitignore b/.gitignore index 003a040..3c48a4c 100644 --- a/.gitignore +++ b/.gitignore @@ -223,4 +223,5 @@ md_results/ results_backup/ ZnMn2O4_*/ examples/matbench/data/ -bfg.jar \ No newline at end of file +bfg.jar +.dir2textignore diff --git a/README.md b/README.md index fe85cb9..142f4f3 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # MatterTune: A Unified Platform for Atomistic Foundation Model Fine-Tuning +[![Documentation Status](https://github.com/Fung-Lab/MatterTune/actions/workflows/docs.yml/badge.svg)](https://nimashoghi.github.io/mattertune/) + MatterTune is a flexible and powerful machine learning library designed specifically for fine-tuning state-of-the-art chemistry models. It provides intuitive interfaces for computational chemists to fine-tune pre-trained models on their specific use cases. ## Table of Contents @@ -181,7 +183,7 @@ Note: MatterTune requires PyTorch >= 2.0 and additional backbone-specific depend For development installation: ```bash -git clone https://github.com/nimashoghi/mattertune.git +git clone https://github.com/Fung-Lab/MatterTune.git cd mattertune pip install -e . ``` --> diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..08835bd --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,19 @@ +# Minimal makefile for Sphinx documentation + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/backbones/eqV2.md b/docs/backbones/eqV2.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/backbones/eqv2.md b/docs/backbones/eqv2.md new file mode 100644 index 0000000..dc330a1 --- /dev/null +++ b/docs/backbones/eqv2.md @@ -0,0 +1,30 @@ +# EquiformerV2 Backbone + +The EquiformerV2 backbone implements the EquiformerV2 model architecture in MatterTune. This is a state-of-the-art equivariant transformer model for molecular and materials property prediction. + +```{note} +This documentation is currently under development. Please check back later for complete documentation of the EquiformerV2 backbone. +``` + +## Key Features + +- Equivariant transformer architecture +- Support for both molecular and periodic systems +- State-of-the-art performance on various property prediction tasks + +## Basic Usage + +```python +from mattertune import MatterTuner +from mattertune.configs import EquiformerV2BackboneConfig + +config = { + "model": { + "name": "eqv2", + "ckpt_path": "path/to/pretrained.pt", + # Additional configuration options will be documented soon + } +} + +tuner = MatterTuner(config) +``` diff --git a/docs/backbones/JMP.md b/docs/backbones/jmp.md similarity index 66% rename from docs/backbones/JMP.md rename to docs/backbones/jmp.md index 4382a53..267264c 100644 --- a/docs/backbones/JMP.md +++ b/docs/backbones/jmp.md @@ -69,53 +69,7 @@ config = { "aint": 1000 } } - }, - # ... rest of config + } } tuner = MatterTuner(config) -``` - -## Property Prediction - -The JMP backbone supports predicting: - -1. System-level properties: - - Total energy - - Stress tensor - - Other graph-level scalar properties - -2. Atom-level properties: - - Per-atom forces - -Both conservative and non-conservative forces/stresses can be predicted. - -## Implementation Details - -The backbone is implemented in the `JMPBackboneModule` class which: - -- Loads pre-trained weights from checkpoints -- Constructs atomic graphs using the configured settings -- Handles normalization of inputs/outputs -- Manages training and inference - -The implementation includes: - -- Graph construction -- Property prediction heads -- Normalization utilities -- ASE calculator interface - -## Requirements - -The JMP backbone requires: -- JMP library -- PyTorch Geometric -- PyTorch - -These dependencies will be checked and validated when using the backbone. - -## References - -- JMP Paper/Documentation -- Source code in `mattertune/backbones/jmp/` diff --git a/docs/backbones/M3GNet.md b/docs/backbones/m3gnet.md similarity index 86% rename from docs/backbones/M3GNet.md rename to docs/backbones/m3gnet.md index 9a986f5..fe59367 100644 --- a/docs/backbones/M3GNet.md +++ b/docs/backbones/m3gnet.md @@ -71,23 +71,7 @@ The backbone is implemented in `M3GNetBackboneModule` which: 4. Manages normalization of inputs/outputs Key features: - - Energy-conserving force prediction - Three-body interactions for improved accuracy - Efficient graph construction - Support for periodic boundary conditions - -## Requirements - -The M3GNet backbone requires: -- matgl -- dgl (Deep Graph Library) -- torch - -These dependencies are automatically checked when using the backbone. - -## References - -- [M3GNet Paper](https://www.nature.com/articles/s43588-022-00349-3) -- [MatGL Documentation](https://materialsvirtuallab.github.io/matgl/) -- Source code in `src/mattertune/backbones/m3gnet/` diff --git a/docs/backbones/ORB.md b/docs/backbones/orb.md similarity index 57% rename from docs/backbones/ORB.md rename to docs/backbones/orb.md index fc48c89..ffac0e9 100644 --- a/docs/backbones/ORB.md +++ b/docs/backbones/orb.md @@ -2,7 +2,7 @@ The ORB backbone allows using pre-trained ORB models as a backbone in MatterTune. ORB is a library that provides pre-trained graph neural networks for predicting material properties. -## ORB Backbone Configuration +## Configuration To use an ORB backbone, specify the following configuration in your MatterTune config: @@ -19,10 +19,12 @@ class ORBBackboneConfig(FinetuneModuleBaseConfig): """The system configuration, controlling how to featurize a system of atoms.""" ``` -The key configuration options are: +### Key Parameters - `pretrained_model`: The name of the pre-trained ORB model to load. Must be one of the models available in the `orb_models` package. -- `system`: Configures how to convert an `ase.Atoms` object into the graph representation expected by ORB. The `radius` specifies the cutoff distance for including neighbors in the graph, and `max_num_neighbors` limits the maximum number of neighbors per node. +- `system`: Configures how to convert an `ase.Atoms` object into the graph representation expected by ORB: + - `radius`: Specifies the cutoff distance for including neighbors in the graph + - `max_num_neighbors`: Limits the maximum number of neighbors per node ## Supported Properties @@ -33,20 +35,24 @@ The ORB backbone supports predicting the following properties: - Stress (`StressesPropertyConfig` with `conservative=False`) - Generic graph properties (`GraphPropertyConfig`) +```{note} Conservative forces and stresses are currently not supported. +``` ## Implementation Details -The key components of the ORB backbone implementation in `backbones/orb/model.py` are: +The key components of the ORB backbone implementation are: -- `ORBBackboneModule`: The main module that loads the pre-trained ORB model and defines the forward pass. - - `create_model`: Loads the pre-trained ORB model specified by `pretrained_model` and initializes the output heads. - - `model_forward`: Runs the backbone model and output heads to predict the properties. - - `atoms_to_data`: Converts an `ase.Atoms` object to the graph representation expected by ORB using the configured `system` settings. +### ORBBackboneModule +The main module that loads the pre-trained ORB model and defines the forward pass: +- `create_model`: Loads the pre-trained ORB model and initializes output heads +- `model_forward`: Runs the backbone model and output heads to predict properties +- `atoms_to_data`: Converts `ase.Atoms` objects to ORB graph representation -- Output head creation (`_create_output_head`): Based on the property configuration, the appropriate ORB output head is initialized: - - `EnergyHead` for `EnergyPropertyConfig` - - `NodeHead` for `ForcesPropertyConfig` - - `GraphHead` for `StressesPropertyConfig` and `GraphPropertyConfig` +### Output Heads +Based on the property configuration, appropriate ORB output heads are initialized: +- `EnergyHead` for `EnergyPropertyConfig` +- `NodeHead` for `ForcesPropertyConfig` +- `GraphHead` for `StressesPropertyConfig` and `GraphPropertyConfig` The ORB backbone leverages the `orb_models` and `nanoflann` packages to load pre-trained models and efficiently construct graph representations suitable for the ORB architecture. diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..e4a17c7 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,45 @@ +from __future__ import annotations + +import os +import sys + +sys.path.insert(0, os.path.abspath("..")) + +project = "MatterTune" +copyright = "2023, MatterTune Team" +author = "MatterTune Team" + +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.napoleon", + "sphinx.ext.viewcode", + "sphinx.ext.githubpages", + "myst_parser", +] + +# MyST Markdown settings +myst_enable_extensions = [ + "colon_fence", + "deflist", + "dollarmath", + "fieldlist", + "html_admonition", + "html_image", + "replacements", + "smartquotes", + "tasklist", +] + +# Theme settings +html_theme = "sphinx_rtd_theme" +html_static_path = ["_static"] +html_logo = None +html_favicon = None + +# General settings +source_suffix = { + ".rst": "restructuredtext", + ".md": "markdown", +} +master_doc = "index" +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..bf85ceb --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,41 @@ +# Contributing to MatterTune + +We welcome contributions to MatterTune! Whether you're fixing bugs, adding new features, improving documentation, or reporting issues, your help is appreciated. + +## How to Contribute + +1. Fork the repository +2. Create a new branch for your feature +3. Make your changes +4. Submit a pull request + +For detailed contribution guidelines, please see our [Contributing Guidelines](https://github.com/Fung-Lab/MatterTune/blob/main/CONTRIBUTING.md) in the repository. + +## Development Setup + +1. Fork and clone the repository +2. Create a virtual environment +3. Install development dependencies +4. Run tests to ensure everything is working + +## Code Style + +We follow standard Python code style guidelines: +- Use Black for code formatting +- Follow PEP 8 guidelines +- Write descriptive docstrings +- Add type hints where appropriate + +## Testing + +Please ensure all tests pass before submitting a pull request: +```bash +pytest tests/ +``` + +## Documentation + +When contributing new features, please: +1. Add docstrings to new functions and classes +2. Update relevant documentation files +3. Add examples where appropriate diff --git a/docs/guides/model_usage.md b/docs/guides/model_usage.md new file mode 100644 index 0000000..71a7ca8 --- /dev/null +++ b/docs/guides/model_usage.md @@ -0,0 +1,66 @@ +# Model Usage Guide + +After training, you can use your model for predictions in several ways. This guide covers loading models and making predictions. + +## Loading a Model + +To load a saved model checkpoint (from a previous fine-tuning run), use the `load_from_checkpoint` method: + +```python +from mattertune.backbones import JMPBackboneModule + +model = JMPBackboneModule.load_from_checkpoint("path/to/checkpoint.ckpt") +``` + +## Making Predictions + +The `MatterTunePropertyPredictor` interface provides a simple way to make predictions for a single or batch of atoms: + +```python +from ase import Atoms +import torch + +# Create ASE Atoms objects +atoms1 = Atoms('H2O', + positions=[[0, 0, 0], [0, 0, 1], [0, 1, 0]], + cell=[10, 10, 10], + pbc=True) + +atoms2 = Atoms('H2O', + positions=[[0, 0, 0], [0, 0, 1], [0, 1, 0]], + cell=[10, 10, 10], + pbc=True) + +# Get predictions using the model's property predictor interface +property_predictor = model.property_predictor() +predictions = property_predictor.predict([atoms1, atoms2], ["energy", "forces"]) + +print("Energy:", predictions[0]["energy"], predictions[1]["energy"]) +print("Forces:", predictions[0]["forces"], predictions[1]["forces"]) +``` + +## Using as ASE Calculator + +Our ASE calculator interface allows you to use the model for molecular dynamics or geometry optimization: + +```python +from ase.optimize import BFGS + +# Create calculator from model +calculator = model.ase_calculator() + +# Set up atoms and calculator +atoms = Atoms('H2O', + positions=[[0, 0, 0], [0, 0, 1], [0, 1, 0]], + cell=[10, 10, 10], + pbc=True) +atoms.calc = calculator + +# Run geometry optimization +opt = BFGS(atoms) +opt.run(fmax=0.01) + +# Get optimized results +print("Final energy:", atoms.get_potential_energy()) +print("Final forces:", atoms.get_forces()) +``` diff --git a/docs/guides/training_config.md b/docs/guides/training_config.md new file mode 100644 index 0000000..10a07c1 --- /dev/null +++ b/docs/guides/training_config.md @@ -0,0 +1,157 @@ +# Training Configuration Guide + +MatterTune uses a comprehensive configuration system to control all aspects of training. This guide covers the key components and how to use them effectively. + +## Model Configuration + +Control the model architecture and training parameters: + +```python +model = mt.configs.JMPBackboneConfig( + # Specify pre-trained model checkpoint + ckpt_path="path/to/pretrained/model.pt", + + # Define properties to predict + properties=[ + mt.configs.EnergyPropertyConfig( + loss=mt.configs.MAELossConfig(), + loss_coefficient=1.0 + ), + mt.configs.ForcesPropertyConfig( + loss=mt.configs.MAELossConfig(), + loss_coefficient=10.0, + conservative=True # Use energy-conserving force prediction + ) + ], + + # Configure optimizer + optimizer=mt.configs.AdamWConfig(lr=1e-4), + + # Optional: Configure learning rate scheduler + lr_scheduler=mt.configs.CosineAnnealingLRConfig( + T_max=100, # Number of epochs + eta_min=1e-6 # Minimum learning rate + ) +) +``` + +## Data Configuration + +Configure data loading and processing: + +```python +data = mt.configs.AutoSplitDataModuleConfig( + # Specify dataset source + dataset=mt.configs.XYZDatasetConfig( + src="path/to/your/data.xyz" + ), + + # Control data splitting + train_split=0.8, # 80% for training + + # Configure batch size and loading + batch_size=32, + num_workers=4, # Number of data loading workers + pin_memory=True # Optimize GPU transfer +) +``` + +## Training Process Configuration + +Control the training loop behavior: + +```python +trainer = mt.configs.TrainerConfig( + # Hardware configuration + accelerator="gpu", + devices=[0, 1], # Use GPUs 0 and 1 + + # Training stopping criteria + max_epochs=100, + # OR: max_steps=1000, # Stop after 1000 steps + # OR: max_time=datetime.timedelta(hours=1), # Stop after 1 hour + + # Validation frequency + check_val_every_n_epoch=1, + + # Gradient clipping: Prevent exploding gradients + gradient_clip_val=1.0, + + # Early stopping configuration + early_stopping=mt.configs.EarlyStoppingConfig( + monitor="val/energy_mae", + patience=20, + mode="min" + ), + + # Model checkpointing + checkpoint=mt.configs.ModelCheckpointConfig( + monitor="val/energy_mae", + save_top_k=1, + mode="min" + ), + + # Configure logging + loggers=[ + mt.configs.WandbLoggerConfig( + project="my-project", + name="experiment-1" + ) + ] +) + +# Combine all configurations +config = mt.configs.MatterTunerConfig( + model=model, + data=data, + trainer=trainer +) +``` + +## Configuration Management + +MatterTune uses [`nshconfig`](https://github.com/nimashoghi/nshconfig) for configuration management, providing several ways to create and load configurations: + +### 1. Direct Construction + +```python +config = mt.configs.MatterTunerConfig( + model=mt.configs.JMPBackboneConfig(...), + data=mt.configs.AutoSplitDataModuleConfig(...), + trainer=mt.configs.TrainerConfig(...) +) +``` + +### 2. Loading from Files/Dictionaries + +```python +# Load from YAML +config = mt.configs.MatterTunerConfig.from_yaml('/path/to/config.yaml') + +# Load from JSON +config = mt.configs.MatterTunerConfig.from_json('/path/to/config.json') + +# Load from dictionary +config = mt.configs.MatterTunerConfig.from_dict({ + 'model': {...}, + 'data': {...}, + 'trainer': {...} +}) +``` + +### 3. Using Draft Configs + +```python +# Create a draft config +config = mt.configs.MatterTunerConfig.draft() + +# Set values progressively +config.model = mt.configs.JMPBackboneConfig.draft() +config.model.ckpt_path = "path/to/model.pt" +# ... set other values ... + +# Finalize the config +final_config = config.finalize() +``` + +For more advanced configuration management features, see the [nshconfig documentation](https://github.com/nimashoghi/nshconfig). diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..037d38d --- /dev/null +++ b/docs/index.md @@ -0,0 +1,45 @@ +# MatterTune Documentation + +MatterTune is a flexible and powerful machine learning library designed specifically for fine-tuning state-of-the-art chemistry models. It provides intuitive interfaces for computational chemists to fine-tune pre-trained models on their specific use cases. + +```{toctree} +:maxdepth: 1 +:caption: Getting Started + +introduction +installation +quick_start +``` + +```{toctree} +:maxdepth: 2 +:caption: User Guide + +guides/model_usage +guides/training_config +guides/data_handling +``` + +```{toctree} +:maxdepth: 2 +:caption: Model Backbones + +backbones/jmp +backbones/m3gnet +backbones/orb +backbones/eqv2 +``` + +```{toctree} +:maxdepth: 1 +:caption: Development + +contributing +license +``` + +## Indices and tables + +* {ref}`genindex` +* {ref}`modindex` +* {ref}`search` diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..a3ed7f2 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,92 @@ +# Installation Guide + +The installation of MatterTune consists of three stages: + +1. Configure environment dependencies for one specific backbone model +2. Install the MatterTune package +3. Set up additional dependencies for external datasets and data sources + +```{warning} +Since there are dependency conflicts between different backbone models, we strongly recommend creating separate virtual environments for each backbone model you plan to use. +``` + +## Backbone Installation + +Below are the installation instructions for our currently supported backbone models using conda and pip. + +### M3GNet + +```bash +conda create -n matgl-tune python=3.10 -y +pip install matgl +pip install torch==2.2.1+cu121 -f https://download.pytorch.org/whl/torch_stable.html +pip uninstall dgl +pip install dgl -f https://data.dgl.ai/wheels/torch-2.2/cu121/repo.html +pip install dglgo -f https://data.dgl.ai/wheels-test/repo.html +``` + +```{note} +Manual installation of `torch` and `dgl` packages after `matgl` installation is required to enable GPU acceleration for training. +``` + +### JMP + +Please follow the installation instructions in the [jmp-backbone repository](https://github.com/nimashoghi/jmp-backbone/blob/lingyu-grad/README.md). + +### ORB + +Please follow the installation instructions in the [orb-models repository](https://github.com/orbital-materials/orb-models). + +```bash +pip install "orb_models@git+https://github.com/nimashoghi/orb-models.git +``` + +### EquiformerV2 + +```bash +conda create -n eqv2-tune python=3.10 +conda activate eqv2-tune +pip install "git+https://github.com/FAIR-Chem/fairchem.git@omat24#subdirectory=packages/fairchem-core" --no-deps +pip install ase "e3nn>=0.5" hydra-core lmdb numba "numpy>=1.26,<2.0" orjson "pymatgen>=2023.10.3" submitit tensorboard "torch>=2.4" wandb torch_geometric h5py netcdf4 opt-einsum spglib +``` + +## MatterTune Package Installation + +```{important} +MatterTune should be installed after setting up the backbone model dependencies. +``` + +Clone the repository and install MatterTune by: + +```bash +pip install -e . +``` + +## External Dataset Installation + +### Matbench + +Clone the repo and install by: +```bash +git clone https://github.com/hackingmaterials/matbench +cd matbench +pip install -e . -r requirement-dev.txt +``` + +### Materials Project + +Install mp-api: +```bash +pip install mp-api +``` + +```{note} +There are currently dependency conflicts between mp-api and matbench packages. You may not be able to use both simultaneously in a single virtual environment. +``` + +### Materials Project Trajectories + +To access MPTraj data from our Hugging Face dataset: +```bash +pip install datasets +``` diff --git a/docs/introduction.md b/docs/introduction.md new file mode 100644 index 0000000..1a3c15f --- /dev/null +++ b/docs/introduction.md @@ -0,0 +1,38 @@ +# Introduction + +## Motivation + +Atomistic Foundation Models have emerged as powerful tools in molecular and materials science. However, the diverse implementations of these open-source models, with their varying architectures and interfaces, create significant barriers for customized fine-tuning and downstream applications. + +MatterTune is a comprehensive platform that addresses these challenges through systematic yet general abstraction of Atomistic Foundation Model architectures. By adopting a modular design philosophy, MatterTune provides flexible and concise user interfaces that enable intuitive and efficient fine-tuning workflows. + +## Key Features + +### Pre-trained Model Support +Seamlessly work with multiple state-of-the-art pre-trained models including: +- JMP +- EquiformerV2 +- M3GNet +- ORB + +### Flexible Property Predictions +Support for various molecular and materials properties: +- Energy prediction +- Force prediction (both conservative and non-conservative) +- Stress tensor prediction +- Custom system-level property predictions + +### Data Processing +Built-in support for multiple data formats: +- XYZ files +- ASE databases +- Materials Project database +- Matbench datasets +- Custom datasets + +### Training Features +- Automated train/validation splitting +- Multiple loss functions (MAE, MSE, Huber, L2-MAE) +- Property normalization and scaling +- Early stopping and model checkpointing +- Comprehensive logging with WandB, TensorBoard, and CSV support diff --git a/docs/license.md b/docs/license.md new file mode 100644 index 0000000..80ab1bb --- /dev/null +++ b/docs/license.md @@ -0,0 +1,27 @@ +# License Information + +MatterTune's core framework is licensed under the MIT License - see the [LICENSE](https://github.com/Fung-Lab/MatterTune/blob/main/LICENSE) file for details. + +## Backbone Licenses + +Each supported model backbone is subject to its own licensing terms: + +### JMP Backbone +Creative Commons Attribution-NonCommercial 4.0 International License (CC BY-NC 4.0) +[JMP License](https://github.com/facebookresearch/JMP/blob/main/LICENSE.md) + +### EquiformerV2 Backbone +Meta Research License +[EquiformerV2 License](https://huggingface.co/fairchem/OMAT24/blob/main/LICENSE) + +### M3GNet Backbone +BSD 3-Clause License +[M3GNet License](https://github.com/materialsvirtuallab/m3gnet/blob/main/LICENSE) + +### ORB Backbone +Apache License 2.0 +[ORB License](https://github.com/orbital-materials/orb-models/blob/main/LICENSE) + +```{important} +Please ensure compliance with the respective licenses when using specific model backbones in your project. For commercial use cases, carefully review each backbone's license terms or contact the respective authors for licensing options. +``` diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..7583cc9 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,4 @@ +sphinx>=4.0.0 +sphinx-rtd-theme>=1.0.0 +myst-parser>=0.18.0 +sphinx-autodoc-typehints>=1.12.0