(WIP) Fixing an issue with the building of the documentation via tox.

Adding a tutorial for the md and an example. Moving information to the topics related to the data.
aiidaplugins · Nov 20, 2023 · c5c1cb7 · c5c1cb7
1 parent 87079c0
commit c5c1cb7
Show file tree

Hide file tree

Showing 13 changed files with 421 additions and 474 deletions.
diff --git a/.github/workflows/cd.yml b/.github/workflows/cd.yml
@@ -16,7 +16,7 @@ jobs:
         with:
           python-version: "3.8"
       - name: Make sure virtualevn>20 is installed, which will yield newer pip and possibility to pin pip version.
-        run: pip install virtualenv>20
+        run: pip install "virtualenv>20"
       - name: Install Tox
         run: pip install tox
       - name: Run pre-commit in Tox
@@ -77,7 +77,7 @@ jobs:
         run: conda install -y lammps==${{ matrix.lammps-version }}
 
       - name: Make sure virtualevn>20 is installed, which will yield newer pip and possibility to pin pip version.
-        run: pip install virtualenv>20
+        run: pip install "virtualenv>20"
       - name: Install Tox
         run: pip install tox
 

diff --git a/docs/Makefile b/docs/Makefile
@@ -19,9 +19,13 @@ ALLSPHINXOPTS   = -n -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS)
 # 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
+.PHONY: all help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext default
 
-customdefault:
+default:
+	$(SPHINXBUILD) -b html -nW $(ALLSPHINXOPTS) $(BUILDDIR)/html
+
+# Same as 'default' but does not exit at the first warning
+debug:
 	$(SPHINXBUILD) -b html -nW --keep-going $(ALLSPHINXOPTS) $(BUILDDIR)/html
 
 all: clean html view

diff --git a/docs/source/developers/intro.md → docs/source/developers/index.md b/docs/source/developers/intro.md → docs/source/developers/index.md
diff --git a/docs/source/index.md b/docs/source/index.md
@@ -22,6 +22,12 @@ topics/calculations/index
 topics/workflows/index
 ```
 
+```{toctree}
+:hidden: true
+:caption: Development information
+developers/index
+```
+
 ```{toctree}
 :hidden: true
 :caption: Reference
@@ -96,7 +102,7 @@ In this version a major refactoring of the entire plugin has been done so that r
 
 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.
+The same basic types of calculations than were previously supported (optimization and molecular dynamics) are still possible with examples for [optimization](tutorials/first_relaxation.md) and [molecular dynamics](tutorials/first_md.md) being given in the documentation.
 :::
 
 ## Capabilities

diff --git a/docs/source/reference/api/index.md b/docs/source/reference/api/index.md
@@ -0,0 +1,11 @@
+# Python API
+
+```{toctree}
+:maxdepth: 3
+auto/aiida_lammps/utils/index
+auto/aiida_lammps/calculations/index
+auto/aiida_lammps/data/index
+auto/aiida_lammps/parsers/index
+auto/aiida_lammps/validation/index
+auto/aiida_lammps/workflows/index
+```
diff --git a/docs/source/topics/data/index.md b/docs/source/topics/data/index.md
@@ -3,6 +3,7 @@
 ```{toctree}
 :maxdepth: 1
 
+parameters
 potential
 trajectory
 

diff --git a/docs/source/users/get_started.md → docs/source/topics/data/parameters.md b/docs/source/users/get_started.md → docs/source/topics/data/parameters.md
@@ -1,100 +1,5 @@
-# Getting started
+# Parameters
 
-In a traditional ``LAMMPS`` calculation a user has an input file which is sequentially read by the executable, each line has a command specifying what actions will be taken, usually the potential is kept as a separate file which is then referred to in the input file.
-
-``aiida-lammps`` generates the necessary inputs by taking three principal data types, namely the ``structure``, the ``potential`` and the ``parameters``, which decribe the simulation box, the interaction parameters between the atoms and the parameters needed to construct the input file (which kind of simulation, which computes/fixes, etc.) respectively.
-
-## Structure
-
-The structure is the simulation box that will be used for the simulation. The data structure must be of an `~:code:aiida.orm.StructureData` type.
-
-```{note}
-``LAMMPS`` can in principle generate the structure internally, but this is not supported by the input generator that is shipped with the plugin. One can instead if necessary run the entire calculation only giving a ``LAMMPS`` input file.
-```
-
-```{note}
-    LAMMPS requires the simulation cell to be in the format of a lower triangular matrix (right-handed basis). Therefore the cell and positions may require [rotation and inversion](https://lammps.sandia.gov/doc/Howto_triclinic.html). This is **automatically** done to **every structure** at the calculation level, so it might be that the cell that is provided is modified so that it follows this convention. However, this is just a different representation of the cell, its symmetry group, should remain unchanged in this process.
-```
-
-## Potential
-
-The potential is one of the most important pieces of data in a MD simulation, since it controls how the atoms interact with each other.
-In ``aiida-lammps`` the potential file is stored in the `LammpsPotentialData` data type, which will store the entire potential file in the database, and add certain attributes so that the data node is easily queryable for later usage. These attributes have been chosen so that they resemble the [OpenKIM](https://openkim.org/doc/schema/kimspec/) standard as much as possible.
-
-To demonstrate how this works one can [download](https://openkim.org/id/EAM_Dynamo_Mendelev_2003_Fe__MO_546673549085_000) a potential from the OpenKIM database, after the file has been downloaded one can generate a dictionary with the metadata of the potential to tag it in the ``AiiDA`` database.
-
-```{code-block} python
-potential_parameters = {
-    'species': ['Fe'],  # Which species can be treated by this potential (required)
-    'atom_style': 'atomic', # Which kind of atomic style is associated with this potential (required)
-    'pair_style': 'eam/fs', # LAMMPS pair style (required)
-    'units': 'metal', # Default units of this potential (required)
-    'extra_tags': {
-        'content_origin': 'NIST IPRP: https: // www.ctcms.nist.gov/potentials/Fe.html', # Where the file was original found
-        'content_other_locations': None, # If the file can be found somewhere else
-        'data_method': 'unknown', # How was the data generated
-        'description': """
-        This Fe EAM potential parameter file is from the NIST repository, \"Fe_2.eam.fs\" as of the March 9, 2009 update.
-        It is similar to \"Fe_mm.eam.fs\" in the LAMMPS distribution dated 2007-06-11,
-        but gives different results for very small interatomic distances
-        (The LAMMPS potential is in fact the deprecated potential referred to in the March 9, 2009 update on the NIST repository).
-        The file header includes a note from the NIST contributor:
-        \"The potential was taken from v9_4_bcc (in C:\\SIMULATION.MD\\Fe\\Results\\ab_initio+Interstitials)\"
-        """, # Short description of the potential
-        'developer': ['Ronald E. Miller'], # Name of the developer that uploaded it to OpenKIM
-        'disclaimer': """
-        According to the developer Giovanni Bonny (as reported by the NIST IPRP),
-        this potential was not stiffened and cannot be used in its present form for collision cascades.
-        """, # Any known issues with the potential
-        'properties': None, # If any specific properties are associated to the potential
-        'publication_year': 2018, # Year of publication to OpenKIM
-        'source_citations': [{
-            'abstract': None,
-            'author':
-            'Mendelev, MI and Han, S and Srolovitz, DJ and Ackland, GJ and Sun, DY and Asta, M',
-            'doi': '10.1080/14786430310001613264',
-            'journal': '{Phil. Mag.}',
-            'number': '{35}',
-            'pages': '{3977-3994}',
-            'recordkey': 'MO_546673549085_000a',
-            'recordprimary': 'recordprimary',
-            'recordtype': 'article',
-            'title':
-            '{Development of new interatomic potentials appropriate for crystalline and liquid iron}',
-            'volume': '{83}',
-            'year': '{2003}'
-        }],
-        'title': 'EAM potential (LAMMPS cubic hermite tabulation) for Fe developed by Mendelev et al. (2003) v000' # Title of the potential
-    }
-}
-```
-Certain tags are required, and must be provided to be able to upload the potential to the database. This is because they identify which ``pair_style`` is associated with the potential, which atomic species can be treated with it, etc. The rest of the tags, in this example are filled so that they follow the [OpenKIM](https://openkim.org/doc/schema/kimspec/) standard as that is the place where the potential was obtained. If another database is used or if it is a homemade potential, these tags can be used to facilitate the querying of the potential.
-
-Then the potential can be uploaded to the database
-```{code-block} python
-from aiida_lamps.data.potential import LammpsPotentialData
-
-potential = LammpsPotentialData.get_or_create(
-    source='Fe_2.eam.fs', # Relative path to the potential file
-    **potential_parameters, # Parameters to tag the potential
-)
-
-```
-
-The ``get_or_create`` method is based on the one by [aiida-pseudo](https://github.com/aiidateam/aiida-pseudo/blob/master/aiida_pseudo/data/pseudo/pseudo.py), which will calculate the md5 sum of the file and check the database for another file with the same [md5 hash](https://en.wikipedia.org/wiki/MD5), if such entry is found, that potential is used instead. This avoids the unnecessary replication of potential data nodes whenever one tries to upload a previously uploaded potential.
-
-```{note}
-When calculating the md5 hash the program will look at the contents of the file, so that even if a minor change is done (that should not affect the result of a calculation), the checksum will be different and hence a new potential node will be created.
-```
-
-### Potentials without files
-In ``LAMMPS`` certain [pair_style](https://docs.lammps.org/pair_style.html) such as the Lenard-Johns potential do not read their parameters from an auxiliary file, if not they are directly written to the main input file. In ``aiida-lammps`` to standardize the potential storage in the database these kinds of potentials are expected to be also be stored as a file. The format expected for these kinds of potentials is simply the coefficients that one would normally write the in the ``LAMMPS`` input file. The input file generator will then generate the necessary lines for the input file depending on the potential ``pair_style``.
-
-
-### Potentials with multiple files
-In ``LAMMPS`` it is in principle possible to give several potential files to treat different atoms. Currently this is **not** supported in the plugin. As only one potential file can be give as to treat the entire system. This is a situation that is aimed to be solved in future releases.
-
-## Parameters
 The behavior of the ``aiida-lammps`` calculation can be controlled by collecting ``LAMMPS`` simulation parameters in a dictionary
 
 ```{code-block} python
@@ -173,8 +78,8 @@ The dictionary is separated into several nested dictionaries that control differ
 ```{note}
 As the restart files can be very large, they are by default not printed, nor stored in the database. Even when one prints them with the ``print_final`` and/or ``print_intermediate`` they are not retrieved and are only kept in the remote folder. The storage of the restart file can be controlled via the ``store_restart=True``(``store_restart=False``) to store(not-store) option in the ``settings`` dictionary.
 ```
-### Compute parameters
+## Compute parameters
 When asking ``aiida-lammps`` to calculate a certain ``compute`` its ``LAMMPS`` name will be automatically generated following the pattern ``compute_name_group_name_aiida`` where ``compute_name`` is the ``LAMMPS`` name of the compute, e.g. ``pe/atom`` with the difference than the ``/`` character is replaced by ``_`` and ``group_name`` is the name of the group to which the compute is applied. All global computes are printed to the ``lammps.out`` and all site dependent quantities are printed to the trajectory file. These computes can then be accessed as outputs of the simulation.
 
-### Input validation
+## Input validation
 ``LAMMPS`` has a quite large amount of possible parameters which can be passed into it to control its behavior. Many of these options are incompatible which can cause the ``LAMMPS`` simulation to fail. To try to catch as many as possible of these possible conflicts the ``aiida-lammps`` input is validated against a [JSON schema](https://json-schema.org/understanding-json-schema/index.html), that checks that the provided input parameters fulfill this schema as much as possible, e.g. it checks that only ``LAMMPS`` computes can be passed to the ``compute`` block, etc. Due to the large amount and variety of options for each compute/fixes these options are not thoroughly checked, only the name of the compute itself is checked.
diff --git a/docs/source/topics/data/potential.md b/docs/source/topics/data/potential.md
@@ -1 +1,77 @@
 # `LammpsPotentialData`
+
+The potential is one of the most important pieces of data in a MD simulation, since it controls how the atoms interact with each other.
+In ``aiida-lammps`` the potential file is stored in the `LammpsPotentialData` data type, which will store the entire potential file in the database, and add certain attributes so that the data node is easily queryable for later usage. These attributes have been chosen so that they resemble the [OpenKIM](https://openkim.org/doc/schema/kimspec/) standard as much as possible.
+
+To demonstrate how this works one can [download](https://openkim.org/id/EAM_Dynamo_Mendelev_2003_Fe__MO_546673549085_000) a potential from the OpenKIM database, after the file has been downloaded one can generate a dictionary with the metadata of the potential to tag it in the ``AiiDA`` database.
+
+```{code-block} python
+potential_parameters = {
+    'species': ['Fe'],  # Which species can be treated by this potential (required)
+    'atom_style': 'atomic', # Which kind of atomic style is associated with this potential (required)
+    'pair_style': 'eam/fs', # LAMMPS pair style (required)
+    'units': 'metal', # Default units of this potential (required)
+    'extra_tags': {
+        'content_origin': 'NIST IPRP: https: // www.ctcms.nist.gov/potentials/Fe.html', # Where the file was original found
+        'content_other_locations': None, # If the file can be found somewhere else
+        'data_method': 'unknown', # How was the data generated
+        'description': """
+        This Fe EAM potential parameter file is from the NIST repository, \"Fe_2.eam.fs\" as of the March 9, 2009 update.
+        It is similar to \"Fe_mm.eam.fs\" in the LAMMPS distribution dated 2007-06-11,
+        but gives different results for very small interatomic distances
+        (The LAMMPS potential is in fact the deprecated potential referred to in the March 9, 2009 update on the NIST repository).
+        The file header includes a note from the NIST contributor:
+        \"The potential was taken from v9_4_bcc (in C:\\SIMULATION.MD\\Fe\\Results\\ab_initio+Interstitials)\"
+        """, # Short description of the potential
+        'developer': ['Ronald E. Miller'], # Name of the developer that uploaded it to OpenKIM
+        'disclaimer': """
+        According to the developer Giovanni Bonny (as reported by the NIST IPRP),
+        this potential was not stiffened and cannot be used in its present form for collision cascades.
+        """, # Any known issues with the potential
+        'properties': None, # If any specific properties are associated to the potential
+        'publication_year': 2018, # Year of publication to OpenKIM
+        'source_citations': [{
+            'abstract': None,
+            'author':
+            'Mendelev, MI and Han, S and Srolovitz, DJ and Ackland, GJ and Sun, DY and Asta, M',
+            'doi': '10.1080/14786430310001613264',
+            'journal': '{Phil. Mag.}',
+            'number': '{35}',
+            'pages': '{3977-3994}',
+            'recordkey': 'MO_546673549085_000a',
+            'recordprimary': 'recordprimary',
+            'recordtype': 'article',
+            'title':
+            '{Development of new interatomic potentials appropriate for crystalline and liquid iron}',
+            'volume': '{83}',
+            'year': '{2003}'
+        }],
+        'title': 'EAM potential (LAMMPS cubic hermite tabulation) for Fe developed by Mendelev et al. (2003) v000' # Title of the potential
+    }
+}
+```
+Certain tags are required, and must be provided to be able to upload the potential to the database. This is because they identify which ``pair_style`` is associated with the potential, which atomic species can be treated with it, etc. The rest of the tags, in this example are filled so that they follow the [OpenKIM](https://openkim.org/doc/schema/kimspec/) standard as that is the place where the potential was obtained. If another database is used or if it is a homemade potential, these tags can be used to facilitate the querying of the potential.
+
+Then the potential can be uploaded to the database
+```{code-block} python
+from aiida_lamps.data.potential import LammpsPotentialData
+
+potential = LammpsPotentialData.get_or_create(
+    source='Fe_2.eam.fs', # Relative path to the potential file
+    **potential_parameters, # Parameters to tag the potential
+)
+
+```
+
+The ``get_or_create`` method is based on the one by [aiida-pseudo](https://github.com/aiidateam/aiida-pseudo/blob/master/aiida_pseudo/data/pseudo/pseudo.py), which will calculate the md5 sum of the file and check the database for another file with the same [md5 hash](https://en.wikipedia.org/wiki/MD5), if such entry is found, that potential is used instead. This avoids the unnecessary replication of potential data nodes whenever one tries to upload a previously uploaded potential.
+
+```{note}
+When calculating the md5 hash the program will look at the contents of the file, so that even if a minor change is done (that should not affect the result of a calculation), the checksum will be different and hence a new potential node will be created.
+```
+
+## Potentials without files
+In ``LAMMPS`` certain [pair_style](https://docs.lammps.org/pair_style.html) such as the Lenard-Johns potential do not read their parameters from an auxiliary file, if not they are directly written to the main input file. In ``aiida-lammps`` to standardize the potential storage in the database these kinds of potentials are expected to be also be stored as a file. The format expected for these kinds of potentials is simply the coefficients that one would normally write the in the ``LAMMPS`` input file. The input file generator will then generate the necessary lines for the input file depending on the potential ``pair_style``.
+
+
+## Potentials with multiple files
+In ``LAMMPS`` it is in principle possible to give several potential files to treat different atoms. Currently this is **not** supported in the plugin. As only one potential file can be give as to treat the entire system. This is a situation that is aimed to be solved in future releases.