From 076ca750267538b78b878889b26fa815dfed100a Mon Sep 17 00:00:00 2001 From: Jonathan Chico Date: Fri, 17 Nov 2023 20:29:11 +0100 Subject: [PATCH] (WIP) Documentation improvements related to #77 Changing the theme of the documentation to make it more similar to the qe theme. Adding a tutorial for the minimization calculation. General improvements to the documentation. --- .gitignore | 2 +- README.md | 15 +- aiida_lammps/parsers/inputfile.py | 8 +- docs/Makefile | 39 ++++ docs/source/_static/aiida-custom.css | 130 +++++++++++ docs/source/_static/aiida-lammps-custom.css | 58 +++++ docs/source/{static => _static}/logo.png | Bin docs/source/{static => _static}/logo.pptx | Bin docs/source/_static/logo_aiida.svg | 5 + docs/source/_templates/icon-links.html | 40 ++++ docs/source/_templates/sbt-sidebar-nav.html | 24 ++ docs/source/conf.py | 153 +++++++------ docs/source/getting_started/index.md | 68 +++++- docs/source/index.md | 105 +++++++-- docs/source/topics/calculations/base.md | 1 + docs/source/topics/calculations/index.md | 11 + docs/source/topics/calculations/raw.md | 1 + docs/source/topics/data/index.md | 9 + docs/source/topics/data/potential.md | 1 + docs/source/topics/data/trajectory.md | 1 + docs/source/topics/workflows/base.md | 1 + docs/source/topics/workflows/index.md | 11 + docs/source/topics/workflows/md.md | 1 + docs/source/topics/workflows/relax.md | 1 + docs/source/tutorials/first_md.md | 3 + docs/source/tutorials/first_raw.md | 3 + docs/source/tutorials/first_relaxation.md | 207 ++++++++++++++++++ .../include/scripts/run_minimization_basic.py | 92 ++++++++ docs/source/tutorials/index.md | 76 +++++++ pyproject.toml | 26 ++- 30 files changed, 972 insertions(+), 120 deletions(-) create mode 100644 docs/Makefile create mode 100644 docs/source/_static/aiida-custom.css create mode 100644 docs/source/_static/aiida-lammps-custom.css rename docs/source/{static => _static}/logo.png (100%) rename docs/source/{static => _static}/logo.pptx (100%) create mode 100644 docs/source/_static/logo_aiida.svg create mode 100644 docs/source/_templates/icon-links.html create mode 100644 docs/source/_templates/sbt-sidebar-nav.html create mode 100644 docs/source/topics/calculations/base.md create mode 100644 docs/source/topics/calculations/index.md create mode 100644 docs/source/topics/calculations/raw.md create mode 100644 docs/source/topics/data/index.md create mode 100644 docs/source/topics/data/potential.md create mode 100644 docs/source/topics/data/trajectory.md create mode 100644 docs/source/topics/workflows/base.md create mode 100644 docs/source/topics/workflows/index.md create mode 100644 docs/source/topics/workflows/md.md create mode 100644 docs/source/topics/workflows/relax.md create mode 100644 docs/source/tutorials/first_md.md create mode 100644 docs/source/tutorials/first_raw.md create mode 100644 docs/source/tutorials/first_relaxation.md create mode 100755 docs/source/tutorials/include/scripts/run_minimization_basic.py create mode 100644 docs/source/tutorials/index.md diff --git a/.gitignore b/.gitignore index 99c98074..3e725ab0 100644 --- a/.gitignore +++ b/.gitignore @@ -44,4 +44,4 @@ pip-wheel-metadata # Docs docs/_build/ docs/build -docs/source/reference/apidoc +docs/source/reference/api diff --git a/README.md b/README.md index e28f6c02..a2867c76 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,12 @@ [![Coverage Status](https://codecov.io/gh/aiidaplugins/aiida-lammps/branch/master/graph/badge.svg)](https://codecov.io/gh/aiidaplugins/aiida-lammps) [![PyPI](https://img.shields.io/pypi/v/aiida-lammps.svg)](https://pypi.python.org/pypi/aiida-lammps/) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black) +[![Docs status](https://readthedocs.org/projects/aiida-lammps/badge)](http://aiida-lammps.readthedocs.io/) # AiiDA LAMMPS plugin -A LAMMPS plugin for the [AiiDA](http://aiida-core.readthedocs.io/) framework. +An [AiiDA](http://aiida-core.readthedocs.io/) plugin for the classical molecular dynamics code [LAMMPS](https://www.lammps.org). + This plugin contains 2 types of calculations: - `lammps.base`: Calculation making use of parameter based input generation for single stage LAMMPS calculations. @@ -48,9 +50,9 @@ pip install -e aiida-lammps ## Built-in Potential Support -The `lammps.base` calculation and associated workflows make use of the ``LammpsPotentialData`` data structure which is created by passing apotential file, plus some labelling parameters to it. +The `lammps.base` calculation and associated workflows make use of the ``LammpsPotentialData`` data structure which is created by passing a potential file, plus some labelling parameters to it. -This data strcuture can be used to handle the following potential types: +This data structure can be used to handle the following potential types: - Single file potentials: Any potential that can be stored in a single file, e.g. [EAM](https://docs.lammps.org/pair_eam.html), [MEAM](https://docs.lammps.org/pair_meam.html), [Tersoff](https://docs.lammps.org/pair_tersoff.html) and [ReaxFF](https://docs.lammps.org/pair_reaxff.html). - Directly parametrized potentials: Potentials whose parameters are directly given via ``pair_coeff`` in the input file, e.g [Born](https://docs.lammps.org/pair_born_gauss.html), [Lennard-Jones](https://docs.lammps.org/pair_line_lj.html) and [Yukawa](https://docs.lammps.org/pair_yukawa.html). These parameters should be written into a file that is then stored into a ``LammpsPotentialData`` node. @@ -105,7 +107,7 @@ pytest --lammps-workdir "test_workdir" ### Pre-commit -The code is formatted and linted using [pre-commit](https://pre-commit.com/), so that the code conform to the standars. One must simply install the repository with the `pre-commit` extra dependencies: +The code is formatted and linted using [pre-commit](https://pre-commit.com/), so that the code conform to the standard. One must simply install the repository with the `pre-commit` extra dependencies: ```shell cd aiida-lammps @@ -118,8 +120,11 @@ or to automate runs, triggered before each commit: pre-commit install ``` -The pre-commit can also be run in an isolated enviroment via `tox` with: +The pre-commit can also be run in an isolated environment via `tox` with: ```shell tox -e pre-commit ``` + +## License +The `aiida-lammps` plugin package is released under the MIT license. See the `LICENSE.txt` file for more details. diff --git a/aiida_lammps/parsers/inputfile.py b/aiida_lammps/parsers/inputfile.py index 338f197a..78d09279 100644 --- a/aiida_lammps/parsers/inputfile.py +++ b/aiida_lammps/parsers/inputfile.py @@ -27,7 +27,7 @@ def generate_input_file( parameters: dict, potential: LammpsPotentialData, structure: orm.StructureData, - trajectory_filename: str = "aiida_lampps.trajectory.dump", + trajectory_filename: str = "aiida_lammps.trajectory.dump", restart_filename: str = "lammps.restart", potential_filename: str = "potential.dat", structure_filename: str = "structure.dat", @@ -45,14 +45,14 @@ def generate_input_file( command is used to overwrite the structure and set the velocity and other parameters from a previous calculation. - :param parameters: calculation paramters used to control the LAMMPS calculation + :param parameters: calculation parameters used to control the LAMMPS calculation :type parameters: dict :param potential: potential used during the LAMMPS calculation :type potential: LammpsPotentialData :param structure: structure used during the LAMMPS calculation :type structure: orm.StructureData :param trajectory_filename: filename used to write the trajectory information, - defaults to 'aiida_lampps.trajectory.dump' + defaults to 'aiida_lammps.trajectory.dump' :type trajectory_filename: str, optional :param restart_filename: filename used to write the restart information, defaults to 'restart.aiida' @@ -973,7 +973,7 @@ def generate_id_tag(name: str = None, group: str = None) -> str: """Generate an id tag for fixes and/or computes. To standardize the naming of computes and/or fixes and to ensure that one - can programatically recreate them their name will consist of the name of the fix/compute + can programmatically recreate them their name will consist of the name of the fix/compute with the group at which is applied appended plus the aiida keyword. Of this way one can always regenerate these tags by knowing which fix/computes were asked of the calculation. diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..6b0e93df --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,39 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = build + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -n -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source + +.PHONY: all help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext customdefault + +customdefault: + $(SPHINXBUILD) -b html -nW --keep-going $(ALLSPHINXOPTS) $(BUILDDIR)/html + +all: clean html view + +clean: + rm -rf $(BUILDDIR) + rm -rf $(shell find . -type d -wholename "*/reference/api/auto") + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +view: + open $(BUILDDIR)/html/index.html diff --git a/docs/source/_static/aiida-custom.css b/docs/source/_static/aiida-custom.css new file mode 100644 index 00000000..42d2fa2d --- /dev/null +++ b/docs/source/_static/aiida-custom.css @@ -0,0 +1,130 @@ +/* Fix CSS of top bar link icons */ +a.nav-link.nav-external i { + padding-left: 0.3em !important; + font-size: inherit !important; + vertical-align: inherit !important; +} +/* Current fix for https://github.com/pandas-dev/pydata-sphinx-theme/issues/193 */ +dl.field-list { + display: grid; + grid-template-columns: fit-content(30%) minmax(0, 1fr); +} +/* For icon unicodes see https://fontawesome.com/v4.7.0/icons/ */ +.title-icon-rocket .admonition-title:before { + margin-right:.5rem; + content: "\f135" +} +.title-icon-info-circle .admonition-title:before { + margin-right:.5rem; + content: "\f05a" +} +.title-icon-question-circle .admonition-title:before { + margin-right:.5rem; + content: "\f059" +} +.title-icon-download .admonition-title:before { + margin-right:.5rem; + content: "\f019" +} +.title-icon-external-link .admonition-title:before { + margin-right:.5rem; + content: "\f08e" +} +.title-icon-lightbulb .admonition-title:before { + margin-right:.5rem; + content: "\f0eb" +} +.title-icon-wrench .admonition-title:before { + margin-right:.5rem; + content: "\f0ad" +} +.title-icon-cog .admonition-title:before { + margin-right:.5rem; + content: "\f013" +} +.title-icon-cogs .admonition-title:before { + margin-right:.5rem; + content: "\f085" +} +.title-icon-code-fork .admonition-title:before { + margin-right:.5rem; + content: "\f126" +} +/* Semantic icon names */ +.title-icon-launch-software .admonition-title:before { + margin-right:.5rem; + content: "\f135" /* rocket */ +} +.title-icon-install-software .admonition-title:before { + margin-right:.5rem; + content: "\f019" /* download */ +} +.title-icon-information .admonition-title:before { + margin-right:.5rem; + content: "\f05a" /* info-circle */ +} +.title-icon-tip .admonition-title:before { + margin-right:.5rem; + content: "\f0eb" /* lightbulb */ +} +.title-icon-important .admonition-title:before { + margin-right:.5rem; + content: "\f06a" /* exclamation-circle */ +} +.title-icon-warning .admonition-title:before { + margin-right:.5rem; + content: "\f071" /* exclamation-triangle */ +} +.title-icon-troubleshoot .admonition-title:before { + margin-right:.5rem; + content: "\f0ad" /* wrench */ +} +.title-icon-read-more .admonition-title:before { + margin-right:.5rem; + content: "\f518" /* external-link */ +} + +.dropdown-group .dropdown .summary-title { + border-bottom: 0 !important; + font-weight:700 !important; +} +.dropdown-group .dropdown:not(:last-child) { + margin-bottom: 0 !important; + border-radius: 0 !important; +} +.dropdown-group .dropdown:first-child, +.dropdown-group .dropdown:first-child .summary-title { + border-radius: 1rem 1rem 0rem 0rem !important; +} +.dropdown-group .dropdown:last-child, +.dropdown-group .dropdown:last-child .summary-title { + border-radius: 0rem 0rem 1rem 1rem !important; +} + +.dropdown-group .dropdown:last-child { + margin-bottom: 24px !important; +} + +div.admonition :last-child { + margin-bottom: 0 +} + +div.highlight-bash div.highlight { + background-color: aliceblue; +} + +div.highlight-console div.highlight { + background-color: aliceblue; +} + +.aiida-green { + color: #32B805; +} + +.aiida-blue { + color: #0496DE; +} + +.aiida-orange { + color: #FF7D16; +} diff --git a/docs/source/_static/aiida-lammps-custom.css b/docs/source/_static/aiida-lammps-custom.css new file mode 100644 index 00000000..8ebb4c26 --- /dev/null +++ b/docs/source/_static/aiida-lammps-custom.css @@ -0,0 +1,58 @@ +.logo-table td { + padding: 20px 10px; +} + +.center { + text-align: center; + max-width: 90%; +} + +.bigfont { + font-size: 140%; +} + +.navbar-brand { + padding: 0; + padding-top: 0.5rem; +} + +img.logo__image { + max-height: 180px; + padding-left: 1.5rem; + padding-bottom: 1rem; +} + +.navbar-icon-links i.fa-brands { + font-size: 40px!important; +} + +img.aiida-sidebar-logo { + height: 40px!important; +} + +img.aiida-logo { + width: 20px; + padding-bottom: 3px; +} + +.fa { + color: var(--pst-color-primary); +} + +.bd-search { + padding: 0 1rem; +} + +.tutor-footer { + padding-top: 0rem; + border-top: none!important; +} + +.footer-table { + margin-bottom: 0rem; + border-color: transparent; +} + +.footer-table td:last-child { + text-align: right; +} diff --git a/docs/source/static/logo.png b/docs/source/_static/logo.png similarity index 100% rename from docs/source/static/logo.png rename to docs/source/_static/logo.png diff --git a/docs/source/static/logo.pptx b/docs/source/_static/logo.pptx similarity index 100% rename from docs/source/static/logo.pptx rename to docs/source/_static/logo.pptx diff --git a/docs/source/_static/logo_aiida.svg b/docs/source/_static/logo_aiida.svg new file mode 100644 index 00000000..f28d9625 --- /dev/null +++ b/docs/source/_static/logo_aiida.svg @@ -0,0 +1,5 @@ + + + + + diff --git a/docs/source/_templates/icon-links.html b/docs/source/_templates/icon-links.html new file mode 100644 index 00000000..356c4f73 --- /dev/null +++ b/docs/source/_templates/icon-links.html @@ -0,0 +1,40 @@ +{%- macro icon_link_nav_item(url, icon, name, type, attributes='') -%} + {%- if url | length > 2 %} +
  • + {%- set attributesDefault = { "href": url, "title": name, "class": "nav-link", "rel": "noopener", "target": "_blank", "data-bs-toggle": "tooltip", "data-bs-placement": "bottom"} %} + {%- if attributes %}{% for key, val in attributes.items() %} + {% set _ = attributesDefault.update(attributes) %} + {% endfor %}{% endif -%} + {% set attributeString = [] %} + {% for key, val in attributesDefault.items() %} + {%- set _ = attributeString.append('%s="%s"' % (key, val)) %} + {% endfor %} + {% set attributeString = attributeString | join(" ") -%} + + {%- if type == "fontawesome" -%} + + {{ name }} + {%- elif type == "local" -%} + {{ name }} + {%- elif type == "url" -%} + {{ name }} + {%- else %} + Incorrectly configured icon link. Type must be `fontawesome`, `url` or `local`. + {%- endif -%} + +
    • + {%- endif -%} +{%- endmacro -%} +{%- if theme_icon_links -%} + +{%- endif -%} diff --git a/docs/source/_templates/sbt-sidebar-nav.html b/docs/source/_templates/sbt-sidebar-nav.html new file mode 100644 index 00000000..e9bbe7b6 --- /dev/null +++ b/docs/source/_templates/sbt-sidebar-nav.html @@ -0,0 +1,24 @@ + diff --git a/docs/source/conf.py b/docs/source/conf.py index 9093276d..7e9c5a15 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -4,9 +4,8 @@ `tox -e docs-clean` and `tox -e docs-update`, or directly: `sphinx-build -n -W --keep-going docs/source docs/_build` """ -import os -import subprocess -import sys +import pathlib +import time from aiida.manage.configuration import load_documentation_profile @@ -19,98 +18,108 @@ # default profile of the AiiDA installation does not use a Django backend. load_documentation_profile() -PROJECT = "AiiDA LAMMPS" -COPYRIGHT = "2021, AiiDA Team" +project = "AiiDA LAMMPS" +copyright = f"2021-{time.localtime().tm_year}, AiiDA Team. All rights reserved" AUTHOR = "AiiDA Team" VERSION = __version__ extensions = [ - # read Markdown files - "myst_parser", - # specify sitemap in single file (not toctrees) - "sphinx_external_toc", + "sphinx.ext.mathjax", "sphinx.ext.intersphinx", - "sphinx.ext.autodoc", "sphinx.ext.viewcode", "sphinx_copybutton", + "sphinx_click.ext", + "sphinx_design", + "myst_parser", + "aiida.sphinxext", + "autoapi.extension", ] intersphinx_mapping = { - "python": ("https://docs.python.org/3", None), + "python": ("https://docs.python.org/3.9", None), "aiida": ("https://aiida-core.readthedocs.io/en/latest", None), "click": ("https://click.palletsprojects.com/", None), - "flask": ("http://flask.pocoo.org/docs/latest/", None), - "flask_restful": ("https://flask-restful.readthedocs.io/en/latest/", None), - "kiwipy": ("https://kiwipy.readthedocs.io/en/latest/", None), - "pandas": ("https://pandas.pydata.org/docs/", None), - "plumpy": ("https://plumpy.readthedocs.io/en/latest/", None), "pymatgen": ("https://pymatgen.org/", None), } -suppress_warnings = ["etoc.toctree"] -html_theme = "furo" # pylint: disable=invalid-name +# Settings for the `autoapi.extenstion` automatically generating API docs +filepath_docs = pathlib.Path(__file__).parent.parent +filepath_src = filepath_docs.parent / "aiida_lammps" +autoapi_type = "python" +autoapi_dirs = [filepath_src] +autoapi_ignore = [filepath_src / "*cli*"] +autoapi_root = str(filepath_docs / "source" / "reference" / "api" / "auto") +autoapi_keep_files = True +autoapi_add_toctree_entry = False + +# Settings for the `sphinx_copybutton` extension +copybutton_selector = "div:not(.no-copy)>div.highlight pre" +copybutton_prompt_text = ( + r">>> |\.\.\. |(?:\(.*\) )?\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: " +) +copybutton_prompt_is_regexp = True + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = "en" + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ["**.ipynb_checkpoints", "reference/api/auto/aiida_lammps/index.rst"] + +# -- MyST options + +myst_enable_extensions = [ + "deflist", + "colon_fence", + "substitution", + "attrs_inline", + "substitution", +] +myst_substitutions = { + "aiida_logo": '', +} + +html_theme = "sphinx_book_theme" # pylint: disable=invalid-name html_title = f"v{__version__}" # pylint: disable=invalid-name -html_logo = "static/logo.png" # pylint: disable=invalid-name html_theme_options = { "announcement": "This documentation is in development!", + "repository_url": "https://github.com/aiidaplugins/aiida-lammps", + "github_url": "https://github.com/aiidaplugins/aiida-lammps", + "use_edit_page_button": True, + "navigation_with_keys": False, + "logo": { + "text": "AiiDA LAMMPS", + "image_light": "_static/logo.png", + "image_dark": "_static/logo.png", + }, +} +html_static_path = ["_static"] +html_context = { + "github_user": "aiidaplugins", + "github_repo": "aiida-lammps", + "github_version": "main", + "doc_path": "docs/source", + "default_mode": "dark", } - -def run_apidoc(_): - """Runs sphinx-apidoc when building the documentation. - - Needs to be done in conf.py in order to include the APIdoc in the - build on readthedocs. - - See also https://github.com/rtfd/readthedocs.org/issues/1139 - """ - source_dir = os.path.abspath(os.path.dirname(__file__)) - apidoc_dir = os.path.join(source_dir, "reference", "apidoc") - package_dir = os.path.join(source_dir, os.pardir, os.pardir, "aiida_lammps") - - # In #1139, they suggest the route below, but this ended up - # calling sphinx-build, not sphinx-apidoc - # from sphinx.apidoc import main - # main([None, '-e', '-o', apidoc_dir, package_dir, '--force']) - - cmd_path = "sphinx-apidoc" - if hasattr(sys, "real_prefix"): # Check to see if we are in a virtualenv - # If we are, assemble the path manually - cmd_path = os.path.abspath( - os.path.join( - sys.prefix, - "bin", - "sphinx-apidoc", - ) - ) - - options = [ - "-o", - apidoc_dir, - package_dir, - "--private", - "--force", - "--no-headings", - "--module-first", - "--no-toc", - "--maxdepth", - "4", +html_sidebars = { + "**": [ + "navbar-logo.html", + "navbar-icon-links.html", + "sbt-sidebar-nav.html", + "search-field.html", ] +} - # See https://stackoverflow.com/a/30144019 - env = os.environ.copy() - env[ - "SPHINX_APIDOC_OPTIONS" - ] = "members,special-members,private-members,undoc-members,show-inheritance" - subprocess.check_call([cmd_path] + options, env=env) - - -def setup(app): - """Run the apidoc.""" - if os.environ.get("RUN_APIDOC", None) != "False": - app.connect("builder-inited", run_apidoc) - +html_css_files = ["aiida-custom.css", "aiida-lammps-custom.css"] autodoc_mock_imports = ["pytest"] # We should ignore any python built-in exception, for instance diff --git a/docs/source/getting_started/index.md b/docs/source/getting_started/index.md index d2be2d92..5714a553 100644 --- a/docs/source/getting_started/index.md +++ b/docs/source/getting_started/index.md @@ -1,5 +1,14 @@ +--- +myst: + substitutions: + pip: '[`pip`](https://pip.pypa.io/en/stable/index.html)' + PyPI: '[PyPI](https://pypi.org/)' +--- + # Get started +(getting_started-requirements)= + ## Requirements To use `aiida-lammps` one should have already: @@ -9,19 +18,26 @@ To use `aiida-lammps` one should have already: Information about how to perform these steps can be found in the `aiida-core` [documentation](https://aiida.readthedocs.io/projects/aiida-core/en/latest/intro/get_started.html) +(getting_started-installation)= + ## Installation -The package can be installed either from the Python Package Index [PyPI](https://pypi.org/) or from the source. +The package can be installed either from the Python Package Index {{ PyPI }} or from the source. + +::::{tab-set} -Installgin via [PyPI](https://pypi.org/) can be done making use of the Python package manager [pip](https://pip.pypa.io/en/stable/): +:::{tab-item} PyPI +Installing via {{ PyPI }} can be done making use of the Python package manager {{ pip }}: ```shell pip install aiida-lammps ``` -This will install the latest release version available in [PyPI](https://pypi.org/). Other releases can be installed vy explicitly passing the release version number in the installation command. +This will install the latest release version available in {{ PyPI }}. Other releases can be installed vy explicitly passing the release version number in the installation command. +::: -To install from source one needs to clone the repository and then install the package making use of [pip](https://pip.pypa.io/en/stable/): +:::{tab-item} Source +To install from source one needs to clone the repository and then install the package making use of {{ pip }}: ```shell git clone https://github.com/aiidaplugins/aiida-lammps.git @@ -29,15 +45,23 @@ pip install -e aiida-lammps ``` Notice that the flag ``-e`` means that the package is installed in editable mode, meaning that any changes to the source code will be automatically picked up. +::: + +:::: :::{note} -Installing from source in the editable mode is recommended when developing as one would not need to re-install the package everytime that a change has been made. +Installing from source in the editable mode is recommended when developing as one would not need to re-install the package every time that a change has been made. ::: + +(getting_started-setup)= + ## Setup Setting up `aiida-lammps` to run a [LAMMPS](https://www.lammps.org/#gsc.tab=0) job is done in a similar way as any other [AiiDA plugin](https://aiida.readthedocs.io/projects/aiida-core/en/latest/topics/plugins.html). That is a [Computer](https://aiida.readthedocs.io/projects/aiida-core/en/latest/howto/run_codes.html#how-to-set-up-a-computer) and a [Code](https://aiida.readthedocs.io/projects/aiida-core/en/latest/howto/run_codes.html#how-to-create-a-code) need to be setup for the current profile. +(getting_started-setup-computer)= + ### Computer A [Computer](https://aiida.readthedocs.io/projects/aiida-core/en/latest/reference/apidoc/aiida.orm.html#aiida.orm.computers.Computer) is an aiida data type that contains the information about a compute resource, this could be a local machine, a remote personal computer, an HPC center, etc. Basically it is the machine where [LAMMPS](https://www.lammps.org/#gsc.tab=0) is installed and it will be run. @@ -46,9 +70,12 @@ For the following it will be considered that [LAMMPS](https://www.lammps.org/#gs The computer setup can be done either via the [AiiDA](https://aiida.net/) command line interface (CLI), [verdi](https://aiida.readthedocs.io/projects/aiida-core/en/latest/reference/command_line.html), or the Python application programming interface (API). +::::{tab-set} + +:::{tab-item} bash To define the computer via the CLI one needs to run the following command: -```shell +```console verdi computer setup -n --label localhost --hostname localhost --transport core.local --scheduler core.direct --work-dir /home/my_username/aiida_workspace ``` @@ -56,10 +83,13 @@ This command will create a [Computer](https://aiida.readthedocs.io/projects/aiid After this its is still necessary to configure the `core.local` transport: -```shell +```console verdi computer configure core.local localhost -n --safe-interval 0 --user my_email@provider.com ``` This configures that the computer will wait 0 seconds between connections attempts (one can increase this to avoid putting pressure in a network) for the user with email `my_email@provider.com` +::: + +:::{tab-item} API Using the Python API one can create a [Computer](https://aiida.readthedocs.io/projects/aiida-core/en/latest/reference/apidoc/aiida.orm.html#aiida.orm.computers.Computer) by running the following code either in the `verdi shell` or using `verdi run` in a script that contains the code @@ -80,23 +110,34 @@ computer.store() # Configure the core.local transport computer.configure() ``` +::: +:::: + +For more detailed information, please refer to the documentation [on setting up compute resources](https://aiida.readthedocs.io/projects/aiida-core/en/latest/howto/run_codes.html#how-to-set-up-a-computer). + +(getting_started-setup-code)= ### Code -Since LAMMPS is a piece of software that is installed in a machine we have to create a [InstalledCode](https://aiida.readthedocs.io/projects/aiida-core/en/latest/reference/apidoc/aiida.orm.nodes.data.code.html#aiida.orm.nodes.data.code.installed.InstalledCode) node in the database which containts the information about this program. As with the [Computer](https://aiida.readthedocs.io/projects/aiida-core/en/latest/reference/apidoc/aiida.orm.html#aiida.orm.computers.Computer) it is possible to define this both via the [AiiDA](https://aiida.net/) command line interface (CLI), [verdi](https://aiida.readthedocs.io/projects/aiida-core/en/latest/reference/command_line.html), or the Python application programming interface (API). +Since LAMMPS is a piece of software that is installed in a machine we have to create a [InstalledCode](https://aiida.readthedocs.io/projects/aiida-core/en/latest/reference/apidoc/aiida.orm.nodes.data.code.html#aiida.orm.nodes.data.code.installed.InstalledCode) node in the database which contains the information about this program. As with the [Computer](https://aiida.readthedocs.io/projects/aiida-core/en/latest/reference/apidoc/aiida.orm.html#aiida.orm.computers.Computer) it is possible to define this both via the [AiiDA](https://aiida.net/) command line interface (CLI), [verdi](https://aiida.readthedocs.io/projects/aiida-core/en/latest/reference/command_line.html), or the Python application programming interface (API). In the following it will be assumed that [LAMMPS](https://www.lammps.org/#gsc.tab=0) is installed in the same machine that is running [AiiDA](https://aiida.net/), `localhost`, that the executable is called `lmp` and that there is already a [Computer](https://aiida.readthedocs.io/projects/aiida-core/en/latest/reference/apidoc/aiida.orm.html#aiida.orm.computers.Computer) named `localhost` setup in the database. +::::{tab-set} + +:::{tab-item} CLI + To define the [InstalledCode](https://aiida.readthedocs.io/projects/aiida-core/en/latest/reference/apidoc/aiida.orm.nodes.data.code.html#aiida.orm.nodes.data.code.installed.InstalledCode) which refers to the [LAMMPS](https://www.lammps.org/#gsc.tab=0) installation via the CLI one runs the command: -```shell +```console verdi code create core.code.installed --label lammps --computer localhost --default-calc-job-plugin lammps.base --filepath-executable /path/to/lammps/lmp ``` This will create an [InstalledCode](https://aiida.readthedocs.io/projects/aiida-core/en/latest/reference/apidoc/aiida.orm.nodes.data.code.html#aiida.orm.nodes.data.code.installed.InstalledCode) with the name `lammps` associated to the [Computer](https://aiida.readthedocs.io/projects/aiida-core/en/latest/reference/apidoc/aiida.orm.html#aiida.orm.computers.Computer) named `localhost` whose executable absolute path is `/path/to/lammps/lmp` +::: - -To define the [InstalledCode](https://aiida.readthedocs.io/projects/aiida-core/en/latest/reference/apidoc/aiida.orm.nodes.data.code.html#aiida.orm.nodes.data.code.installed.InstalledCode) which refers to the [LAMMPS](https://www.lammps.org/#gsc.tab=0) installation via the Python API one can use the follwoing code in either the `verdi shell` or by running a script which constains it via `verdi run`: +:::{tab-item} API +To define the [InstalledCode](https://aiida.readthedocs.io/projects/aiida-core/en/latest/reference/apidoc/aiida.orm.nodes.data.code.html#aiida.orm.nodes.data.code.installed.InstalledCode) which refers to the [LAMMPS](https://www.lammps.org/#gsc.tab=0) installation via the Python API one can use the following code in either the `verdi shell` or by running a script which contains it via `verdi run`: ```python from aiida.orm import InstalledCode @@ -115,3 +156,8 @@ code = InstalledCode( # Store the code node in the database code.store() ``` +::: + +:::: + +For more detailed information, please refer to the documentation [on setting up codes](https://aiida.readthedocs.io/projects/aiida-core/en/latest/howto/run_codes.html#how-to-setup-a-code). diff --git a/docs/source/index.md b/docs/source/index.md index 39c68fb2..2953c6e2 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -1,37 +1,108 @@ +--- +myst: + substitutions: + README.md of the repository: '`README.md` of the repository' + aiida-core documentation: '`aiida-core` documentation' + aiida_lammps: '`aiida-lammps`' + LAMMPS: '[LAMMPS](https://lammps.org)' +--- + +```{toctree} +:hidden: true + +getting_started/index +tutorials/index +``` + +```{toctree} +:hidden: true +:caption: Topic guides +topics/data/index +topics/calculations/index +topics/workflows/index +``` + +```{toctree} +:hidden: true +:caption: Reference +reference/api/index +``` + + + # AiiDA LAMMPS Plugin -``aiida-lammps`` is a Python package that allows the workflow management and data provenance tracking framework [AiiDA](http://aiida-core.readthedocs.io/) run [LAMMPS](https://www.lammps.org/) calculations. -``LAMMPS`` is a classical molecular dynamics (MD) code with a focus on materials modeling, it is used broadly inside the MD community due to its flexibility, and in-built capability to generate complex workflows in its input script. +{{ aiida_lammps }} is a Python package that allows the workflow management and data provenance tracking framework [AiiDA](http://aiida-core.readthedocs.io/) run {{ LAMMPS }} calculations. + +{{ LAMMPS }} is a classical molecular dynamics (MD) code with a focus on materials modeling, it is used broadly inside the MD community due to its flexibility, and in-built capability to generate complex workflows in its input script. + +[![PyPI version](https://badge.fury.io/py/aiida-lammps.svg)](https://badge.fury.io/py/aiida-lammps) +[![PyPI pyversions](https://img.shields.io/pypi/pyversions/aiida-lammps.svg)](https://pypi.python.org/pypi/aiida-lammps) +[![Build Status](https://github.com/aiidaplugins/aiida-lammps/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/aiidateam/aiida-lammps/actions) +[![Docs status](https://readthedocs.org/projects/aiida-lammps/badge)](http://aiida-lammps.readthedocs.io/) + +______________________________________________________________________ -## Installation -One can install ``aiida-lammps`` in a Python environment using ``pip``: +::::{grid} 1 2 2 2 +:gutter: 3 -```{code-block} console -pip install aiida-lammps +:::{grid-item-card} {fa}`rocket;mr-1` Get started +:text-align: center +:shadow: md + +Instructions to install, configure and setup the plugin package. + ++++ + +```{button-ref} getting_started/index +:ref-type: doc +:click-parent: +:expand: +:color: primary +:outline: + +To the installation guides +``` +::: + +:::{grid-item-card} {fa}`info-circle;mr-1` Tutorials +:text-align: center +:shadow: md + +Easy examples to take the first steps with the plugin package. + ++++ + +```{button-ref} tutorials/index +:ref-type: doc +:click-parent: +:expand: +:color: primary +:outline: + +To the tutorials ``` +::: +:::: -``aiida-lammps`` will install ``aiida-core`` if it is not already installed in your system, as it is a pre-requisite of the package. Information on the requirements of ``aiida-core``, and steps needed to configure it to be able to perform calculations can be found in the [AiiDA documentation](http://aiida-core.readthedocs.io/). ## Compatibility -``aiida-lammps`` has been developed to work with [aiida-core v2.x](https://www.aiida.net/news/posts/2022-04-27-aiida-2-release.html) and tested with the ``LAMMPS`` releases [19Jul2019](https://github.com/lammps/lammps/releases/tag/patch_19Jul2019) and [29Oct2020](https://github.com/lammps/lammps/releases/tag/stable_29Oct2020). It is important to notice that older versions of ``LAMMPS`` can have different formats which means that the plugin is not guaranteed to be able to properly produce input files and/or parse the output generated by the program. If there are any compatibility problems with the plugin, please open an [issue](https://github.com/aiidaplugins/aiida-lammps/issues) so that it can be addressed. +{{ aiida_lammps }} has been developed to work with [aiida-core v2.x](https://www.aiida.net/news/posts/2022-04-27-aiida-2-release.html) and tested with the {{ LAMMPS }} releases [19Jul2019](https://github.com/lammps/lammps/releases/tag/patch_19Jul2019) and [29Oct2020](https://github.com/lammps/lammps/releases/tag/stable_29Oct2020). It is important to notice that older versions of {{ LAMMPS }} can have different formats which means that the plugin is not guaranteed to be able to properly produce input files and/or parse the output generated by the program. If there are any compatibility problems with the plugin, please open an [issue](https://github.com/aiidaplugins/aiida-lammps/issues) so that it can be addressed. -```{warning} -In this version a major refactoring of the entrie plugin has been done so that render it backwards incompatible with older versions. +:::{warning} +In this version a major refactoring of the entire plugin has been done so that render it backwards incompatible with older versions. -New potential datastructures and calculations have been introduced with the aim of improving the flexibility of the plugin. +New potential data structures and calculations have been introduced with the aim of improving the flexibility of the plugin. The same basic types of calculations than were previously supported (optimization and molecular dynamics) are still possible with examples for [optimization](users/example_minimize.md) and [molecular dynamics](users/example_md.md) being given in the documentation. -``` -## Getting Started - -The ``aiida-lammps`` package includes a series of examples in the ``examples/`` folder, with those a user can learn how to perform simple ``LAMMPS`` calculations using ``aiida-lammps``. +::: ## Capabilities -``aiida-lammps`` has been designed in such a way that the base ``Calculation`` method can run a single-phase ``LAMMPS`` calculation with as much flexibility as possible, with multi-stage runs being handled by specially designed ``WorkChains`` instead. +{{ aiida_lammps }} has been designed in such a way that the base ``Calculation`` method can run a single-phase LAMMPS calculation with as much flexibility as possible, with multi-stage runs being handled by specially designed ``WorkChains`` instead. ### What does this implies? -Instead of relying on the internal ``LAMMPS`` scripting language to treat loops, multiple phases, definition of custom variables, etc., those tasks are off loaded to the AiiDA worchains, allowing one to make use of the provenance tracking, automated data storage and caching capabilities of AiiDA. +Instead of relying on the internal {{ LAMMPS }} scripting language to treat loops, multiple phases, definition of custom variables, etc., those tasks are off loaded to the AiiDA workchains, allowing one to make use of the provenance tracking, automated data storage and caching capabilities of AiiDA. diff --git a/docs/source/topics/calculations/base.md b/docs/source/topics/calculations/base.md new file mode 100644 index 00000000..7e8c7fa8 --- /dev/null +++ b/docs/source/topics/calculations/base.md @@ -0,0 +1 @@ +# `LammpsBaseCalculation` diff --git a/docs/source/topics/calculations/index.md b/docs/source/topics/calculations/index.md new file mode 100644 index 00000000..7fe57d37 --- /dev/null +++ b/docs/source/topics/calculations/index.md @@ -0,0 +1,11 @@ +(topics-calculations)= + +# Calculations + +```{toctree} +:maxdepth: 1 + +base +raw + +``` diff --git a/docs/source/topics/calculations/raw.md b/docs/source/topics/calculations/raw.md new file mode 100644 index 00000000..ec839c14 --- /dev/null +++ b/docs/source/topics/calculations/raw.md @@ -0,0 +1 @@ +# `LammpsRawCalculation` diff --git a/docs/source/topics/data/index.md b/docs/source/topics/data/index.md new file mode 100644 index 00000000..69acd8df --- /dev/null +++ b/docs/source/topics/data/index.md @@ -0,0 +1,9 @@ +# Data + +```{toctree} +:maxdepth: 1 + +potential +trajectory + +``` diff --git a/docs/source/topics/data/potential.md b/docs/source/topics/data/potential.md new file mode 100644 index 00000000..482a45f9 --- /dev/null +++ b/docs/source/topics/data/potential.md @@ -0,0 +1 @@ +# `LammpsPotentialData` diff --git a/docs/source/topics/data/trajectory.md b/docs/source/topics/data/trajectory.md new file mode 100644 index 00000000..aacedfe0 --- /dev/null +++ b/docs/source/topics/data/trajectory.md @@ -0,0 +1 @@ +# `LammpsTrajectory` diff --git a/docs/source/topics/workflows/base.md b/docs/source/topics/workflows/base.md new file mode 100644 index 00000000..b8c1aa3d --- /dev/null +++ b/docs/source/topics/workflows/base.md @@ -0,0 +1 @@ +# `LammpsBaseWorkChain` diff --git a/docs/source/topics/workflows/index.md b/docs/source/topics/workflows/index.md new file mode 100644 index 00000000..b273758e --- /dev/null +++ b/docs/source/topics/workflows/index.md @@ -0,0 +1,11 @@ +(topics-workflows)= + +# Workflows + +```{toctree} +:maxdepth: 1 + +base +relax +md +``` diff --git a/docs/source/topics/workflows/md.md b/docs/source/topics/workflows/md.md new file mode 100644 index 00000000..08d948fb --- /dev/null +++ b/docs/source/topics/workflows/md.md @@ -0,0 +1 @@ +# `LammpsMDWorkChain` diff --git a/docs/source/topics/workflows/relax.md b/docs/source/topics/workflows/relax.md new file mode 100644 index 00000000..2d4c0467 --- /dev/null +++ b/docs/source/topics/workflows/relax.md @@ -0,0 +1 @@ +# `LammpsRelaxWorkChain` diff --git a/docs/source/tutorials/first_md.md b/docs/source/tutorials/first_md.md new file mode 100644 index 00000000..de9def23 --- /dev/null +++ b/docs/source/tutorials/first_md.md @@ -0,0 +1,3 @@ +(tutorials-md)= + +# Molecular dynamics in LAMMPS diff --git a/docs/source/tutorials/first_raw.md b/docs/source/tutorials/first_raw.md new file mode 100644 index 00000000..7caf4655 --- /dev/null +++ b/docs/source/tutorials/first_raw.md @@ -0,0 +1,3 @@ +(tutorials-raw)= + +# Raw LAMMPS calculation diff --git a/docs/source/tutorials/first_relaxation.md b/docs/source/tutorials/first_relaxation.md new file mode 100644 index 00000000..734371a8 --- /dev/null +++ b/docs/source/tutorials/first_relaxation.md @@ -0,0 +1,207 @@ +--- +myst: + substitutions: + aiida_lammps: '`aiida-lammps`' + LAMMPS: '[LAMMPS](https://lammps.org)' + OpenKIM: '[OpenKIM](https://openkim.org/)' +--- + +(tutorials-minimization)= + +# Minimization in LAMMPS + +The following example will show how one performs a [LAMMPS minimization](https://docs.lammps.org/minimize.html) calculation through AiiDA's Python API. +For the purpose of this demonstration, the optimal structure for bcc iron will is computed. + +:::{tip} +The code shown in the snippets below can be {download}`downloaded as a script `, +The script can be made executable and then run to execute the example calculation. +::: + +First import the required classes and functions: + +```python +from aiida.engine import run +from aiida.orm import Dict, StructureData, load_code +from aiida_lammps.data.potential import LammpsPotentialData +``` + +Then, load the code that was setup in AiiDA for `lmp` and get an instance of the [process builder](https://aiida.readthedocs.io/projects/aiida-core/en/latest/topics/processes/usage.html#process-builder): + +```python +# Load the code configured for ``lmp``. Make sure to replace +# this string with the label used in the code setup. +code = load_code('lammps@localhost') +builder = code.get_builder() +``` + +The process builder can be used to assign and automatically validate the inputs that will be used for the calculation. +One can start by defining and assigning the structure to the builder: + +```python +from ase.build import bulk +structure = StructureData(ase=bulk('Fe', 'bcc', 2.87, cubic=True)) +builder.structure = structure +``` + +The crystal structure is generated by making use of the `bulk` method of the [ASE library](https://wiki.fysik.dtu.dk/ase/ase/build/build.html#ase.build.bulk). +The ase structure is then passed to the `StructureData`, which generates a node that is stored in AiiDA's provenance graph, and then passed to the builder. + +:::{note} +The structure is constructed in such as way as to have a cubic cell with orthogonal axis as {{ LAMMPS }} prefers this kind of setup. +::: + +The next step is to define the interatomic potential that will be used for this system. +The interatomic potentials can be found in many repositories such as the ones from [NIST](https://www.ctcms.nist.gov/potentials/) and OpenKIM. +In the following a potential from the OpenKIM repository will be used. + +```python +import requests +import io + +# Download the potential from the repository and store it as a BytesIO object +_stream = io.BytesIO(requests.get('https://openkim.org/files/MO_546673549085_000/Fe_2.eam.fs').text.encode('ascii')) + +# Set the metadata for the potential +potential_parameters = { + 'species': ['Fe'], + 'atom_style': 'atomic', + 'pair_style': 'eam/fs', + 'units': 'metal', + 'extra_tags': { + 'title': 'EAM potential (LAMMPS cubic hermite tabulation) for Fe developed by Mendelev et al. (2003) v000', + 'content_origin': 'NIST IPRP: https: // www.ctcms.nist.gov/potentials/Fe.html', + 'developer': ['Ronald E. Miller'], + 'publication_year': 2018, + } +} + +# Store the potential in an AiiDA node +potential = LammpsPotentialData.get_or_create(source=_stream,**potential_parameters) + +builder.potential = potential +``` + +The potential is downloaded from the OpenKIM repository making use of the [requests library](https://docs.python-requests.org/en/latest/index.html) and then transformed into a bytes stream via the `BytesIO` class from the [core io library](https://docs.python.org/3/library/io.html). +After that one needs to define the metadata for the potential, this is necessary to be able to make sure that the potential is used only on appropriate systems and that it can be easily tracked. + +:::{note} +All the parameters in the `extra_tags` are not necessary to define a potential node, but they will improve the querying and tracking of the potential. +::: + +With the potential data and the metadata dictionary one can then generate a `LammpsPotentialData` node which can be assigned to the builder. + +Then one needs to define the parameters which control how the input file for the {{ LAMMPS }} calculation is generated. +For a structural minimization the minimal set of parameters is the following: + +```python + +# Parameters to control the input file generation +parameters = Dict({ + "control": { + "units": "metal", + "timestep": 1e-5 + }, + "compute":{ + "pe/atom": [{"type": [{"keyword": " ", "value": " "}], "group": "all"}], + "ke/atom": [{"type": [{"keyword": " ", "value": " "}], "group": "all"}], + "stress/atom": [{"type": ["NULL"], "group": "all"}], + "pressure": [{"type": ["thermo_temp"], "group": "all"}], + }, + + "structure":{"atom_style": "atomic"}, + "thermo":{ + "printing_rate": 100, + "thermo_printing": { + "step": True, + "pe": True, + "ke": True, + "press": True, + "pxx": True, + "pyy": True, + "pzz": True, + } + }, + "minimize":{ + "style": "cg", + "energy_tolerance": 1e-4, + "force_tolerance": 1e-4, + "max_iterations": 1000, + "max_evaluations": 1000, + }, +}) +builder.parameters = parameters +``` +The parameters have several sections which control different behavior of the calculation: + +- `control` section handles global parameters for the simulation, such as the units and time step. +- `compute` section specifies which parameters will be calculated and printed to file during the LAMMPS simulation ([see compute command](https://docs.lammps.org/compute.html)). +- `structure`: controls aspects related to the structure handling in {{ LAMMPS }}. +- `thermo`: controls which global thermodynamic information will be calculated and written to file ([see thermo command](https://docs.lammps.org/thermo.html)). +- `minimize`: controls the structural minimization algorithm used ([see minimize command](https://docs.lammps.org/minimize.html)). + +Lastly one needs to define the computational resources needed to perform the calculation +```python +# Run the calculation on 1 CPU and kill it if it runs longer than 1800 seconds. +# Set ``withmpi`` to ``False`` if ``pw.x`` was compiled without MPI support. +builder.metadata.options = { + 'resources': { + 'num_machines': 1, + }, + 'max_wallclock_seconds': 1800, + 'withmpi': False, +} +``` + +Now as all the needed parameters have been defined the calculation can bse launched using the process builder: + +```python +outputs, node = run.get_node(builder) +``` + +Once the calculation is finished `run.get_node` will return the outputs produced and the calculation node, `outputs` and `node` respectively. + +The `node` is the entry that contains the information pertaining the calculation. +It is possible to check if the calculation finished successfully (processes that return `0` are considered to be successful) by looking at its exit status: + +```python +node.exit_status +``` + +If the result is different from zero it means that a problem was encountered in the calculation. This might indicate that some output is not present, that the calculation failed due to a transitory issue, an input problem, etc. + +The `outputs` is a dictionary containing the output nodes produced by the calculation: + +```python +print(outputs) +{ + 'results': , + 'time_dependent_computes': , + 'trajectories': , + 'structure': , + 'remote_folder': , + 'retrieved': +} +``` + +The `results` node is a dictionary that will contain the final result of the calculated thermodynamic variables as well as general information about the calculation status + +```python +print(results.get_dict()) +{ + 'final_ke': 0, + 'final_pe': -8.2418066986197, + 'final_pxx': -27037.610112703, + 'final_pyy': -27037.610112703, + 'final_pzz': -27037.610112703, + ... +} +``` + +The `time_dependent_computes` contains a series of numpy arrays each one representing the values the global variables as a function of time. One can get the names of the arrays by making use of the `.get_arraynames()` method and an individual array can be accesses by making use of `.get_array('array_name')` where `'array_name'` is one of the strings found with the previous command. + +The complete output that was written by {{ LAMMPS }} to stdout, can be retrieved as follows: + +```python +results['retrieved'].base.repository.get_object_content('aiida_lammps.out') +``` diff --git a/docs/source/tutorials/include/scripts/run_minimization_basic.py b/docs/source/tutorials/include/scripts/run_minimization_basic.py new file mode 100755 index 00000000..79a3b0ae --- /dev/null +++ b/docs/source/tutorials/include/scripts/run_minimization_basic.py @@ -0,0 +1,92 @@ +#!/usr/bin/env runaiida +import io + +from aiida.engine import run +from aiida.orm import Dict, StructureData, load_code +from ase.build import bulk +import requests + +from aiida_lammps.data.potential import LammpsPotentialData + +# Load the code configured for ``lmp``. Make sure to replace +# this string with the label used in the code setup. +code = load_code("lammps@localhost") +builder = code.get_builder() + +structure = StructureData(ase=bulk("Fe", "bcc", 2.87, cubic=True)) +builder.structure = structure + +# Download the potential from the repository and store it as a BytesIO object +_stream = io.BytesIO( + requests.get( + "https://openkim.org/files/MO_546673549085_000/Fe_2.eam.fs", timeout=20 + ).text.encode("ascii") +) + +# Set the metadata for the potential +potential_parameters = { + "species": ["Fe"], + "atom_style": "atomic", + "pair_style": "eam/fs", + "units": "metal", + "extra_tags": { + "title": "EAM potential (LAMMPS cubic hermite tabulation) for Fe developed by Mendelev et al. (2003) v000", + "content_origin": "NIST IPRP: https: // www.ctcms.nist.gov/potentials/Fe.html", + "developer": ["Ronald E. Miller"], + "publication_year": 2018, + }, +} + +# Store the potential in an AiiDA node +potential = LammpsPotentialData.get_or_create(source=_stream, **potential_parameters) + +builder.potential = potential + +parameters = Dict( + { + "control": {"units": "metal", "timestep": 1e-5}, + "compute": { + "pe/atom": [{"type": [{"keyword": " ", "value": " "}], "group": "all"}], + "ke/atom": [{"type": [{"keyword": " ", "value": " "}], "group": "all"}], + "stress/atom": [{"type": ["NULL"], "group": "all"}], + "pressure": [{"type": ["thermo_temp"], "group": "all"}], + }, + "structure": {"atom_style": "atomic"}, + "thermo": { + "printing_rate": 100, + "thermo_printing": { + "step": True, + "pe": True, + "ke": True, + "press": True, + "pxx": True, + "pyy": True, + "pzz": True, + }, + }, + "minimize": { + "style": "cg", + "energy_tolerance": 1e-4, + "force_tolerance": 1e-4, + "max_iterations": 1000, + "max_evaluations": 1000, + }, + } +) +builder.parameters = parameters + +builder.metadata.options = { + "resources": { + "num_machines": 1, + }, + "max_wallclock_seconds": 1800, + "withmpi": False, +} + +results, node = run.get_node(builder) + +print( + f"Calculation: {node.process_class}<{node.pk}> {node.process_state.value} [{node.exit_status}]" +) +print(f"Results: {results}") +assert node.is_finished_ok, f"{node} failed: [{node.exit_status}] {node.exit_message}" diff --git a/docs/source/tutorials/index.md b/docs/source/tutorials/index.md new file mode 100644 index 00000000..d384982d --- /dev/null +++ b/docs/source/tutorials/index.md @@ -0,0 +1,76 @@ +(tutorials)= +# Tutorials + +:::{important} +Before working with the tutorial, the following steps need to have been performed: + +- installation of the `aiida-lammps` plugin ([see the instructions](#getting_started-installation)) +- configure the `LAMMPS` code ([see the instructions](#getting_started-setup-code)) +::: +```{toctree} +:hidden: true +:maxdepth: 1 + +first_relaxation +first_md +first_raw +``` + +:::{card} +:class-header: panel-header-text +:class-footer: tutor-footer +:link: tutorials-minimization +:link-type: ref +:margin: 4 + +{fa}`fa-regular fa-rocket` Running your first minimization calculation. +^^^ +Learn how to run a LAMMPS minimization with AiiDA, using the Python API. ++++ +::::{list-table} +:class: footer-table +:widths: 50 50 +* - {fa}`fa-sharp fa-regular fa-clock` 30 min + - {{ aiida_logo }} [Beginner]{.aiida-green} +:::: +::: + + +:::{card} +:class-header: panel-header-text +:class-footer: tutor-footer +:link: tutorials-md +:link-type: ref +:margin: 4 + +{fa}`fa-solid fa-atom` Molecular dynamics +^^^ +Learn how to run a LAMMPS molecular dynamics calculation. ++++ +::::{list-table} +:class: footer-table +:widths: 50 50 +* - {fa}`fa-sharp fa-regular fa-clock` 20 min + - {{ aiida_logo }} [Beginner]{.aiida-green} +:::: +::: + + +:::{card} +:class-header: panel-header-text +:class-footer: tutor-footer +:link: tutorials-raw +:link-type: ref +:margin: 4 + +{fa}`fa-solid fa-file-lines` Raw calculation +^^^ +Learn how to run a raw LAMMPS calculation based on an input file. ++++ +::::{list-table} +:class: footer-table +:widths: 50 50 +* - {fa}`fa-sharp fa-regular fa-clock` 20 min + - {{ aiida_logo }} [Beginner]{.aiida-green} +:::: +::: diff --git a/pyproject.toml b/pyproject.toml index 4186731e..eb3f890d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -36,10 +36,10 @@ Documentation = "https://aiida-lammps.readthedocs.io" Source = "https://github.com/aiidaplugins/aiida-lammps" [project.optional-dependencies] -testing = [ - "attrs>=17.4.0", - "pgtest", - "pytest", +tests = [ + 'pgtest~=1.3', + 'pytest~=6.0', + 'pytest-regressions~=2.3', "pytest-cov", "coverage", "pytest-timeout", @@ -47,15 +47,21 @@ testing = [ ] pre-commit = [ - "aiida-core[pre-commit]~=2.2", - "tox>=3.23.0", - "virtualenv>20" + 'pre-commit~=2.17', + 'pylint~=2.17.2', + 'pylint-aiida~=0.1.1', + 'toml', ] docs = [ - "myst-parser~=0.15.0", - "sphinx-external-toc", - "sphinx-copybutton", + 'sphinx~=6.2.1', + 'sphinx-copybutton~=0.5.2', + 'sphinx-book-theme~=1.0.1', + 'sphinx-click~=4.4.0', + 'sphinx-design~=0.4.1', + 'sphinxcontrib-details-directive~=0.1.0', + 'sphinx-autoapi~=3.0', + 'myst_parser~=1.0.0', "furo" ]