<!-- <img src="../figures/logo.png" alt="drawing" width="150"/> -->
<!-- [](https://codecov.io/gh/materialsproject/jobflow/) -->
<!-- [](https://pypi.org/project/jobflow/) -->
<!--  -->
<!-- [](https://doi.org/10.21105/joss.05995) -->
[Documentation](https://battmodels.github.io/asimtools/) | [GitHub](https://github.com/BattModels/asimtools)
# Atomic SIMulation Tools
This package is a lightweight workflow and simulation manager for reproducible
atomistic simulations that can be transferred across environments, calculators
and structures on Unix systems. By using in-built or user-defined asimmodules
and utilities, users can run/build their own simulation recipes and
automagically scale them locally or on slurm based clusters. The core idea is
to separate the dependence of the atomistic potential/calculator and the
simulations steps thereby allowing the same simulation to be run with multiple
calculators/codes and the same calculator to be used for multiple simulation
parameters without altering simulation code. Input and output files follow a
simple consistent file structure and format so that consistent analysis
pipelines can be used across users. For a concrete example of how ASIMTools
achieves this, see the [Developing Custom Asimmodules](https://eeg.engin.umich.edu/asimtools/asimplify.html) page.
## Developer philosophy
The goal of asimtools is to push all the complexity of workflow management,
best-practices, file management etc. into the backend such that the everyday
user only has to handle input files for existing workflows and asimmodule files
for workflows they want to implement.This allows the user to focus on doing the
science and designing experiments. The following are the guiding principles for
how asimtools should work:
- Asimmodules should resemble boilerplate ASE code as much as possible.
- Asimmodules should avoid explicitly depending on a calculator
- Asimmodules should not explicitly depend on the context/environment in which
they run
- It should be easy to debug individual asimmodules/parts in large workflows.
In addition, it should always be possible to debug/resubmit jobs without
using asimtools.
- Input file structure and format should be standard across all asimmodules. In
addition all input parameters should match how they would like without
asimtools i.e. do not provide an API!
- Job progress tracking must be incorporated for easy debugging
- Best practices should be built-in e.g. if multiple jobs of the same slurm
context are submitted simulataneously, it must be a job array.
## Philosophy on User Experience
The philosophy is to build "simulations" using building blocks of asimmodules.
Asimmodules are nothing but Python functions that return a dictionary, anything
can be done in the function code. These asimmodules can be as
complicated/efficient as you make them using any external packages you want and
can be optimized with time but can still be run within the framework. This
allows a test friendly way to transition from say a tutorial on the
ASE/pymatgen website to an asimtools asimmodule. So while complicated wrappers
are discouraged, they would still work as long as the asimmodule works. The
benefit out of the box is that you can make your asimmodule independent of
calculator or input structures and submit them easily.
We also aim to provide a standard set of robust and efficient simulation
protocols as we develop. You can see all the implemented workflows provided
with the package in the examples directory and modify them to your application.
If you have suggestions for improvements in methodology or code, please bring
up an issue on github!
## Getting Started
These instructions will give you a copy of the project up and running.
### Installing ASIMTools
If you prefer to use a conda a environment, you can create and activate one
using:
```
conda create -n asimtools python=3.9
conda activate asimtools
```
Then you can install asimtools either using pip or by cloning the source code
from github. Note that the cloned version might have some minor bug fixes that
are not included in the official PyPI release. It is also easier to go through
the examples if you clone the repository.
To install the latest asimtools release from PyPI, you can simply use
```
pip install asimtools
```
To install from source use
```
git clone
https://gitlab.com/ase/ase.git && cd ase pip install . cd ../
git clone https://github.com/BattModels/asimtools.git
cd asimtools
pip install .
```
We recommend you use the latest version of ASE since the ones on PyPI and
conda are quite outdated.
```
git clone https://gitlab.com/ase/ase.git
cd ase
pip install .
```
You can optionally install the dependencies used for development using
```
pip install ".[dev]"
```
Or install some popular Universal Machine Learning Interactomic Potentials
(matgl, mace-torh, chgnet) using
```
pip install ".[mlip]"
```
Making sure the correct versions and dependencies are installed correctly is
probably more stable if you follow their individual installation instructions.
Other individual calculators may need external packages for running them. For
example if you want to use Quantum Espresso or CASTEP, you will have to install
them. Similarly some asimmodules e.g. `lammps.py` might also need external
packages to be used. It is up to the user to make sure those are installed.
You will also need to setup some environment variables, these variables point
to global `env_input.yaml` and `calc_input.yaml` files with your favorite
configurations since these are commonly shared among simulations. You can also
directly specify them when running `asim-execute` (See `asim-execute -h`). You
can also provide a directory for ASIMTools to search for your custom
asimmodules. Examples of these files can be found in the examples.
Add the following to your `.bashrc`
```
export ASIMTOOLS_ENV_INPUT=/path/to/my/global/env_input.yaml
export ASIMTOOLS_CALC_INPUT=/path/to/my/global/calc_input.yaml
export ASIMTOOLS_ASIMMODULE_DIR=/path/to/my/asimmodule/dir
```
## Running the tests
To run tests for the workflow tools, from the tests directory, call:
pytest
To run the test suite on a component `component.py` , call:
pytest test_component.py
To run all tests for the provided asimmodules, `cd` into the examples directory
and call:
source run_all.sh
Or you can run a test for each individual example in its directory using:
source run.sh
If no errors are reported, the tests have passed. These tests simply test the
functionality of the code, not the scientific validity of the simulations!
To run tests for the provided asimmodules using slurm, you can similarly run
the bash scripts ending with `_slurm.sh`. This will submit a number of jobs,
none longer than 1 minute.
## Contributing
Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code
of conduct, and the process for submitting pull requests to us.
## Authors
- **Keith Phuthi**
[mkphuthi](https://github.com/mkphuthi)
- **Emil Annevelink**
[emilannevelink](https://github.com/emilannevelink)
See also the list of
[contributors](https://github.com/BattModels/asimtools.git/contributors)
who participated in this project.
## License
This project is licensed under the MIT License
<!-- ## Acknowledgments
- Hat tip to anyone whose code is used -->
Raw data
{
"_id": null,
"home_page": null,
"name": "asimtools",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Keith Phuthi <mkphuthi@gmail.com>",
"keywords": "high-throughput, workflow, atomistic, simulation",
"author": null,
"author_email": "Keith Phuthi <mkphuthi@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/38/4c/0afff4f83f46713bdc053abb3c8d5e2533ba75ac6ac0c35f9f1069f5f631/asimtools-0.0.2.tar.gz",
"platform": null,
"description": "<!-- <img src=\"../figures/logo.png\" alt=\"drawing\" width=\"150\"/> -->\n<!-- [](https://codecov.io/gh/materialsproject/jobflow/) -->\n<!-- [](https://pypi.org/project/jobflow/) -->\n<!--  -->\n<!-- [](https://doi.org/10.21105/joss.05995) -->\n\n[Documentation](https://battmodels.github.io/asimtools/) | [GitHub](https://github.com/BattModels/asimtools)\n\n# Atomic SIMulation Tools\n\nThis package is a lightweight workflow and simulation manager for reproducible\natomistic simulations that can be transferred across environments, calculators\nand structures on Unix systems. By using in-built or user-defined asimmodules\nand utilities, users can run/build their own simulation recipes and\nautomagically scale them locally or on slurm based clusters. The core idea is\nto separate the dependence of the atomistic potential/calculator and the\nsimulations steps thereby allowing the same simulation to be run with multiple\ncalculators/codes and the same calculator to be used for multiple simulation\nparameters without altering simulation code. Input and output files follow a\nsimple consistent file structure and format so that consistent analysis\npipelines can be used across users. For a concrete example of how ASIMTools\nachieves this, see the [Developing Custom Asimmodules](https://eeg.engin.umich.edu/asimtools/asimplify.html) page.\n\n## Developer philosophy\nThe goal of asimtools is to push all the complexity of workflow management,\nbest-practices, file management etc. into the backend such that the everyday\nuser only has to handle input files for existing workflows and asimmodule files\nfor workflows they want to implement.This allows the user to focus on doing the\nscience and designing experiments. The following are the guiding principles for\nhow asimtools should work:\n\n- Asimmodules should resemble boilerplate ASE code as much as possible.\n- Asimmodules should avoid explicitly depending on a calculator\n- Asimmodules should not explicitly depend on the context/environment in which \n they run\n- It should be easy to debug individual asimmodules/parts in large workflows.\n In addition, it should always be possible to debug/resubmit jobs without\n using asimtools.\n- Input file structure and format should be standard across all asimmodules. In\n addition all input parameters should match how they would like without\n asimtools i.e. do not provide an API!\n- Job progress tracking must be incorporated for easy debugging\n- Best practices should be built-in e.g. if multiple jobs of the same slurm\n context are submitted simulataneously, it must be a job array.\n\n## Philosophy on User Experience\nThe philosophy is to build \"simulations\" using building blocks of asimmodules.\nAsimmodules are nothing but Python functions that return a dictionary, anything\ncan be done in the function code. These asimmodules can be as\ncomplicated/efficient as you make them using any external packages you want and\ncan be optimized with time but can still be run within the framework. This\nallows a test friendly way to transition from say a tutorial on the\nASE/pymatgen website to an asimtools asimmodule. So while complicated wrappers\nare discouraged, they would still work as long as the asimmodule works. The\nbenefit out of the box is that you can make your asimmodule independent of\ncalculator or input structures and submit them easily.\n\nWe also aim to provide a standard set of robust and efficient simulation\nprotocols as we develop. You can see all the implemented workflows provided\nwith the package in the examples directory and modify them to your application.\nIf you have suggestions for improvements in methodology or code, please bring\nup an issue on github!\n\n## Getting Started\n\nThese instructions will give you a copy of the project up and running.\n\n### Installing ASIMTools\n\nIf you prefer to use a conda a environment, you can create and activate one\nusing: \n```\nconda create -n asimtools python=3.9\nconda activate asimtools\n```\n\nThen you can install asimtools either using pip or by cloning the source code\nfrom github. Note that the cloned version might have some minor bug fixes that\nare not included in the official PyPI release. It is also easier to go through\nthe examples if you clone the repository.\n\nTo install the latest asimtools release from PyPI, you can simply use\n\n```\npip install asimtools\n```\n\nTo install from source use\n\n```\ngit clone\nhttps://gitlab.com/ase/ase.git && cd ase pip install . cd ../\n\ngit clone https://github.com/BattModels/asimtools.git\ncd asimtools\npip install .\n```\n\nWe recommend you use the latest version of ASE since the ones on PyPI and\nconda are quite outdated.\n\n```\ngit clone https://gitlab.com/ase/ase.git\ncd ase\npip install .\n```\n\nYou can optionally install the dependencies used for development using\n\n```\npip install \".[dev]\"\n```\nOr install some popular Universal Machine Learning Interactomic Potentials\n(matgl, mace-torh, chgnet) using\n\n```\npip install \".[mlip]\"\n```\nMaking sure the correct versions and dependencies are installed correctly is\nprobably more stable if you follow their individual installation instructions.\n\nOther individual calculators may need external packages for running them. For\nexample if you want to use Quantum Espresso or CASTEP, you will have to install\nthem. Similarly some asimmodules e.g. `lammps.py` might also need external\npackages to be used. It is up to the user to make sure those are installed.\n\nYou will also need to setup some environment variables, these variables point\nto global `env_input.yaml` and `calc_input.yaml` files with your favorite\nconfigurations since these are commonly shared among simulations. You can also\ndirectly specify them when running `asim-execute` (See `asim-execute -h`). You\ncan also provide a directory for ASIMTools to search for your custom\nasimmodules. Examples of these files can be found in the examples.\n\nAdd the following to your `.bashrc`\n```\nexport ASIMTOOLS_ENV_INPUT=/path/to/my/global/env_input.yaml\nexport ASIMTOOLS_CALC_INPUT=/path/to/my/global/calc_input.yaml\nexport ASIMTOOLS_ASIMMODULE_DIR=/path/to/my/asimmodule/dir\n```\n\n## Running the tests\n\nTo run tests for the workflow tools, from the tests directory, call:\n\n pytest\n\nTo run the test suite on a component `component.py` , call:\n\n pytest test_component.py\n\nTo run all tests for the provided asimmodules, `cd` into the examples directory\nand call:\n\n source run_all.sh\n\nOr you can run a test for each individual example in its directory using:\n\n source run.sh\n\nIf no errors are reported, the tests have passed. These tests simply test the\nfunctionality of the code, not the scientific validity of the simulations!\n\nTo run tests for the provided asimmodules using slurm, you can similarly run\nthe bash scripts ending with `_slurm.sh`. This will submit a number of jobs,\nnone longer than 1 minute.\n \n## Contributing\n\nPlease read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code\nof conduct, and the process for submitting pull requests to us.\n\n## Authors\n\n - **Keith Phuthi**\n [mkphuthi](https://github.com/mkphuthi)\n - **Emil Annevelink**\n [emilannevelink](https://github.com/emilannevelink)\n\nSee also the list of\n[contributors](https://github.com/BattModels/asimtools.git/contributors)\nwho participated in this project.\n\n## License\n\nThis project is licensed under the MIT License\n\n<!-- ## Acknowledgments\n\n - Hat tip to anyone whose code is used -->\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A lightweight python package for managing and running atomic simulation workflows",
"version": "0.0.2",
"project_urls": {
"documentation": "https://battmodels.github.io/asimtools/",
"issues": "https://github.com/BattModels/asimtools/issues",
"repository": "https://github.com/BattModels/asimtools"
},
"split_keywords": [
"high-throughput",
" workflow",
" atomistic",
" simulation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a88352652a2959dbe87a0fd5bc737d60deb7ff0cae6e2c443e484bf87d77e124",
"md5": "f014b1dd924f7af9583400aa2cad6269",
"sha256": "91c8c8e9727ebe70e28b79cd7c5b4be75f191a7a371afc54a5d268110aa72b6c"
},
"downloads": -1,
"filename": "asimtools-0.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f014b1dd924f7af9583400aa2cad6269",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 71929,
"upload_time": "2024-10-18T17:24:53",
"upload_time_iso_8601": "2024-10-18T17:24:53.984570Z",
"url": "https://files.pythonhosted.org/packages/a8/83/52652a2959dbe87a0fd5bc737d60deb7ff0cae6e2c443e484bf87d77e124/asimtools-0.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "384c0afff4f83f46713bdc053abb3c8d5e2533ba75ac6ac0c35f9f1069f5f631",
"md5": "cc2b693b13c6c73c4970cfe5b8295540",
"sha256": "75b386b7e2779cf6884280e2b415a7e11e38fbf6fee7d5506baf3b5cc54f5dd3"
},
"downloads": -1,
"filename": "asimtools-0.0.2.tar.gz",
"has_sig": false,
"md5_digest": "cc2b693b13c6c73c4970cfe5b8295540",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 52262,
"upload_time": "2024-10-18T17:24:55",
"upload_time_iso_8601": "2024-10-18T17:24:55.074063Z",
"url": "https://files.pythonhosted.org/packages/38/4c/0afff4f83f46713bdc053abb3c8d5e2533ba75ac6ac0c35f9f1069f5f631/asimtools-0.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-18 17:24:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "BattModels",
"github_project": "asimtools",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "ase",
"specs": [
[
">=",
"3.22.1"
]
]
},
{
"name": "colorama",
"specs": [
[
">=",
"0.4.6"
]
]
},
{
"name": "cycler",
"specs": [
[
">=",
"0.12.1"
]
]
},
{
"name": "docutils",
"specs": [
[
">=",
"0.20.1"
]
]
},
{
"name": "matplotlib",
"specs": [
[
">=",
"3.8.3"
]
]
},
{
"name": "myst-parser",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"1.26.4"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"2.2.1"
]
]
},
{
"name": "pycodestyle",
"specs": [
[
">=",
"2.8.0"
]
]
},
{
"name": "pydocstyle",
"specs": [
[
">=",
"6.3.0"
]
]
},
{
"name": "pymatgen",
"specs": [
[
">=",
"2024.3.1"
]
]
},
{
"name": "pytest",
"specs": [
[
">=",
"7.2.1"
]
]
},
{
"name": "PyYAML",
"specs": [
[
">=",
"6.0.1"
]
]
},
{
"name": "spglib",
"specs": [
[
">=",
"2.3.1"
]
]
},
{
"name": "phonopy",
"specs": []
},
{
"name": "seekpath",
"specs": []
}
],
"lcname": "asimtools"
}
JSON
