<div align="center">
[](https://badge.fury.io/py/mlipx)
[](https://zntrack.readthedocs.io/en/latest/)
[](https://github.com/zincware/zndraw)
[](https://github.com/basf/mlipx/issues)
[](https://mlipx.readthedocs.io/en/latest/?badge=latest)
[📘Documentation](https://mlipx.readthedocs.io) |
[🛠️Installation](https://mlipx.readthedocs.io/en/latest/installation.html) |
[📜Recipes](https://mlipx.readthedocs.io/en/latest/recipes.html) |
[🚀Quickstart](https://mlipx.readthedocs.io/en/latest/quickstart.html)
</div>
<div style="text-align: center;">
<h1>Machine-Learned Interatomic Potential eXploration</h1>
</div>
`mlipx` is a Python library designed for evaluating machine-learned interatomic
potentials (MLIPs). It offers a growing set of evaluation methods alongside
powerful visualization and comparison tools.
The goal of `mlipx` is to provide a common platform for MLIP evaluation and to
facilitate sharing results among researchers. This allows you to determine the
applicability of a specific MLIP to your research and compare it against others.
## Installation
Install `mlipx` via pip:
```bash
pip install mlipx
```
> [!NOTE]
> The `mlipx` package does not include the installation of any MLIP code, as we aim to keep the package as lightweight as possible.
> If you encounter any `ImportError`, you may need to install the additional dependencies manually.
## Quickstart
This section provides a brief overview of the core features of `mlipx`. For more detailed instructions, visit the [documentation](https://mlipx.readthedocs.io).
Most recipes support different input formats, such as data file paths, `SMILES` strings, or Materials Project structure IDs.
> [!NOTE]
> Because `mlipx` uses Git and [DVC](https://dvc.org/doc), you need to create a new project directory to run your experiments in. Here's how to set up your project:
>
> ```bash
> mkdir exp
> cd exp
> git init && dvc init
> ```
> If you want to use datafiles, it is recommend to track them with `dvc add <file>` instead of `git add <file>`.
> ```bash
> cp /your/data/file.xyz .
> dvc add file.xyz
> ```
### Energy-Volume Curve
Compute an energy-volume curve using the `mp-1143` structure from the Materials Project and MLIPs such as `mace-mp`, `sevennet`, and `orb_v2`:
```bash
mlipx recipes ev --models mace_mp,sevennet,orb_v2 --material-ids=mp-1143 --repro
mlipx compare --glob "*EnergyVolumeCurve"
```
> [!NOTE]
> `mlipx` utilizes [ASE](https://wiki.fysik.dtu.dk/ase/index.html),
> meaning any ASE-compatible calculator for your MLIP can be used.
> If we do not provide a preset for your model, you can either adapt the `models.py` file, raise an [issue](https://github.com/basf/mlipx/issues/new) to request support, or submit a pull request to add your model directly.
Below is an example of the resulting comparison:
> [!NOTE]
> Set your default visualizer path using: `export ZNDRAW_URL=http://localhost:1234`.
### Structure Optimization
Compare the performance of different models in optimizing multiple molecular structures from `SMILES` representations:
```bash
mlipx recipes relax --models mace_mp,sevennet,orb_v2 --smiles "CCO,C1=CC2=C(C=C1O)C(=CN2)CCN" --repro
mlipx compare --glob "*0_StructureOptimization"
mlipx compare --glob "*1_StructureOptimization"
```
### Nudged Elastic Band (NEB)
Run and compare nudged elastic band (NEB) calculations for a given start and end structure:
```bash
mlipx recipes neb --models mace_mp,sevennet,orb_v2 --datapath ../data/neb_end_p.xyz --repro
mlipx compare --glob "*NEBs"
```
## Python API
You can also use all the recipes from the `mlipx` command-line interface
programmatically in Python.
> [!NOTE]
> Whether you use the CLI or the Python API, you must work within a GIT
> and DVC repository. This setup ensures reproducibility and enables automatic
> caching and other features from DVC and ZnTrack.
```python
import mlipx
# Initialize the project
project = mlipx.Project()
# Define an MLIP
mace_mp = mlipx.GenericASECalculator(
module="mace.calculators",
class_name="mace_mp",
device="auto",
kwargs={
"model": "medium",
},
)
# Use the MLIP in a structure optimization
with project:
data = mlipx.LoadDataFile(path="/your/data/file.xyz")
relax = mlipx.StructureOptimization(
data=data.frames,
data_id=-1,
model=mace_mp,
fmax=0.1
)
# Reproduce the project state
project.repro()
# Access the results
print(relax.frames)
# >>> [ase.Atoms(...), ...]
```
Raw data
{
"_id": null,
"home_page": null,
"name": "mlipx",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.10",
"maintainer_email": null,
"keywords": "data-version-control, machine-learning, reproducibility, collaboration, machine-learned interatomic potential, mlip, mlff",
"author": "Sandip De",
"author_email": "sandip.de@basf.com",
"download_url": "https://files.pythonhosted.org/packages/21/6a/6891cea1b8ec171f82a160ab153298a58088eef3e27b0fe946c7c4ea71e9/mlipx-0.1.3.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n\n\n\n\n\n[](https://badge.fury.io/py/mlipx)\n[](https://zntrack.readthedocs.io/en/latest/)\n[](https://github.com/zincware/zndraw)\n[](https://github.com/basf/mlipx/issues)\n[](https://mlipx.readthedocs.io/en/latest/?badge=latest)\n\n[\ud83d\udcd8Documentation](https://mlipx.readthedocs.io) |\n[\ud83d\udee0\ufe0fInstallation](https://mlipx.readthedocs.io/en/latest/installation.html) |\n[\ud83d\udcdcRecipes](https://mlipx.readthedocs.io/en/latest/recipes.html) |\n[\ud83d\ude80Quickstart](https://mlipx.readthedocs.io/en/latest/quickstart.html)\n</div>\n\n<div style=\"text-align: center;\">\n <h1>Machine-Learned Interatomic Potential eXploration</h1>\n</div>\n\n`mlipx` is a Python library designed for evaluating machine-learned interatomic\npotentials (MLIPs). It offers a growing set of evaluation methods alongside\npowerful visualization and comparison tools.\n\nThe goal of `mlipx` is to provide a common platform for MLIP evaluation and to\nfacilitate sharing results among researchers. This allows you to determine the\napplicability of a specific MLIP to your research and compare it against others.\n\n## Installation\n\nInstall `mlipx` via pip:\n\n```bash\npip install mlipx\n```\n\n> [!NOTE]\n> The `mlipx` package does not include the installation of any MLIP code, as we aim to keep the package as lightweight as possible.\n> If you encounter any `ImportError`, you may need to install the additional dependencies manually.\n\n## Quickstart\n\nThis section provides a brief overview of the core features of `mlipx`. For more detailed instructions, visit the [documentation](https://mlipx.readthedocs.io).\n\nMost recipes support different input formats, such as data file paths, `SMILES` strings, or Materials Project structure IDs.\n\n> [!NOTE]\n> Because `mlipx` uses Git and [DVC](https://dvc.org/doc), you need to create a new project directory to run your experiments in. Here's how to set up your project:\n>\n> ```bash\n> mkdir exp\n> cd exp\n> git init && dvc init\n> ```\n> If you want to use datafiles, it is recommend to track them with `dvc add <file>` instead of `git add <file>`.\n> ```bash\n> cp /your/data/file.xyz .\n> dvc add file.xyz\n> ```\n\n### Energy-Volume Curve\n\nCompute an energy-volume curve using the `mp-1143` structure from the Materials Project and MLIPs such as `mace-mp`, `sevennet`, and `orb_v2`:\n\n```bash\nmlipx recipes ev --models mace_mp,sevennet,orb_v2 --material-ids=mp-1143 --repro\nmlipx compare --glob \"*EnergyVolumeCurve\"\n```\n\n> [!NOTE]\n> `mlipx` utilizes [ASE](https://wiki.fysik.dtu.dk/ase/index.html),\n> meaning any ASE-compatible calculator for your MLIP can be used.\n> If we do not provide a preset for your model, you can either adapt the `models.py` file, raise an [issue](https://github.com/basf/mlipx/issues/new) to request support, or submit a pull request to add your model directly.\n\nBelow is an example of the resulting comparison:\n\n![ZnDraw UI](https://github.com/user-attachments/assets/2036e6d9-3342-4542-9ddb-bbc777d2b093#gh-dark-mode-only \"ZnDraw UI\")\n![ZnDraw UI](https://github.com/user-attachments/assets/c2479d17-c443-4550-a641-c513ede3be02#gh-light-mode-only \"ZnDraw UI\")\n\n> [!NOTE]\n> Set your default visualizer path using: `export ZNDRAW_URL=http://localhost:1234`.\n\n### Structure Optimization\n\nCompare the performance of different models in optimizing multiple molecular structures from `SMILES` representations:\n\n```bash\nmlipx recipes relax --models mace_mp,sevennet,orb_v2 --smiles \"CCO,C1=CC2=C(C=C1O)C(=CN2)CCN\" --repro\nmlipx compare --glob \"*0_StructureOptimization\"\nmlipx compare --glob \"*1_StructureOptimization\"\n```\n\n![ZnDraw UI](https://github.com/user-attachments/assets/7e26a502-3c59-4498-9b98-af8e17a227ce#gh-dark-mode-only \"ZnDraw UI\")\n![ZnDraw UI](https://github.com/user-attachments/assets/a68ac9f5-e3fe-438d-ad4e-88b60499b79e#gh-light-mode-only \"ZnDraw UI\")\n\n### Nudged Elastic Band (NEB)\n\nRun and compare nudged elastic band (NEB) calculations for a given start and end structure:\n\n```bash\nmlipx recipes neb --models mace_mp,sevennet,orb_v2 --datapath ../data/neb_end_p.xyz --repro\nmlipx compare --glob \"*NEBs\"\n```\n\n![ZnDraw UI](https://github.com/user-attachments/assets/a2e80caf-dd86-4f14-9101-6d52610b9c34#gh-dark-mode-only \"ZnDraw UI\")\n![ZnDraw UI](https://github.com/user-attachments/assets/0c1eb681-a32c-41c2-a15e-2348104239dc#gh-light-mode-only \"ZnDraw UI\")\n\n\n## Python API\n\nYou can also use all the recipes from the `mlipx` command-line interface\nprogrammatically in Python.\n\n> [!NOTE]\n> Whether you use the CLI or the Python API, you must work within a GIT\n> and DVC repository. This setup ensures reproducibility and enables automatic\n> caching and other features from DVC and ZnTrack.\n\n```python\nimport mlipx\n\n# Initialize the project\nproject = mlipx.Project()\n\n# Define an MLIP\nmace_mp = mlipx.GenericASECalculator(\n module=\"mace.calculators\",\n class_name=\"mace_mp\",\n device=\"auto\",\n kwargs={\n \"model\": \"medium\",\n },\n)\n\n# Use the MLIP in a structure optimization\nwith project:\n data = mlipx.LoadDataFile(path=\"/your/data/file.xyz\")\n relax = mlipx.StructureOptimization(\n data=data.frames,\n data_id=-1,\n model=mace_mp,\n fmax=0.1\n )\n\n# Reproduce the project state\nproject.repro()\n\n# Access the results\nprint(relax.frames)\n# >>> [ase.Atoms(...), ...]\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Machine-Learned Interatomic Potential eXploration",
"version": "0.1.3",
"project_urls": {
"documentation": "https://mlipx.readthedocs.io",
"repository": "https://github.com/basf/mlipx"
},
"split_keywords": [
"data-version-control",
" machine-learning",
" reproducibility",
" collaboration",
" machine-learned interatomic potential",
" mlip",
" mlff"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "41d3c6e79388afa2b478dd702d7f83f9ca557fe454d31fa689e7c7f4201d8b3e",
"md5": "ea234db6ea672010985b579cc279c339",
"sha256": "7bc6591b4389214d9956ad290d8b2cdab8530ad6632f1ea20841840e816c5cde"
},
"downloads": -1,
"filename": "mlipx-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ea234db6ea672010985b579cc279c339",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.10",
"size": 60928,
"upload_time": "2024-12-12T14:13:33",
"upload_time_iso_8601": "2024-12-12T14:13:33.488204Z",
"url": "https://files.pythonhosted.org/packages/41/d3/c6e79388afa2b478dd702d7f83f9ca557fe454d31fa689e7c7f4201d8b3e/mlipx-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "216a6891cea1b8ec171f82a160ab153298a58088eef3e27b0fe946c7c4ea71e9",
"md5": "9ef30d77336c34db353f882d14016c6e",
"sha256": "3c70a0e6f921c420f3612e3aed7a8c5a125d18b7d8339fed9c8a98fc90f33c9e"
},
"downloads": -1,
"filename": "mlipx-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "9ef30d77336c34db353f882d14016c6e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.10",
"size": 39322,
"upload_time": "2024-12-12T14:13:35",
"upload_time_iso_8601": "2024-12-12T14:13:35.546117Z",
"url": "https://files.pythonhosted.org/packages/21/6a/6891cea1b8ec171f82a160ab153298a58088eef3e27b0fe946c7c4ea71e9/mlipx-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-12 14:13:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "basf",
"github_project": "mlipx",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mlipx"
}
JSON
