diff --git a/aiida_lammps/data/potential.py b/aiida_lammps/data/potential.py index 7fa09c14..40b4beec 100644 --- a/aiida_lammps/data/potential.py +++ b/aiida_lammps/data/potential.py @@ -2,7 +2,7 @@ Base class for the LAMMPS potentials. This class allows the storage/recovering of LAMMPS potentials, it allows -one to store any LAMMPS potential as a ``SinglefileData`` object, which can +one to store any LAMMPS potential as a :py:class:`~aiida.orm.nodes.data.singlefile.SinglefileData` object, which can then be either written to the LAMMPS input script and/or to a file, where it can be easily read by LAMMPS. This distinction depends on the assigned ``pair_style`` which require different ``pair_coeff`` entries in the input @@ -140,7 +140,7 @@ class LammpsPotentialData(orm.SinglefileData): Base class for the LAMMPS potentials. This class allows the storage/recovering of LAMMPS potentials, it allows - one to store any LAMMPS potential as a ``SinglefileData`` object, which can + one to store any LAMMPS potential as a :py:class:`~aiida.orm.nodes.data.singlefile.SinglefileData` object, which can then be either written to the LAMMPS input script and/or to a file, where it can be easily read by LAMMPS. This distinction depends on the assigned ``pair_style`` which require different ``pair_coeff`` entries in the input diff --git a/aiida_lammps/workflows/relax.py b/aiida_lammps/workflows/relax.py index 8f71cca0..3336f958 100644 --- a/aiida_lammps/workflows/relax.py +++ b/aiida_lammps/workflows/relax.py @@ -1,4 +1,4 @@ -"""Workflow for the relaxation of a structure using the minimization proceedure in LAMMPS.""" +"""Workflow for the relaxation of a structure using the minimization procedure in LAMMPS.""" from itertools import groupby import os from typing import Union @@ -36,7 +36,7 @@ def define(cls, spec): default=lambda: orm.Str("cg"), validator=cls._validate_relaxation_algorithms, help=""" - The algorithm to be used suring relaxation. + The algorithm to be used during relaxation. """, ) spec.input( diff --git a/docs/source/index.md b/docs/source/index.md index 1d1303f0..e4285bd4 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -1,10 +1,9 @@ --- 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)' + AiiDA: '[AiiDA](https://www.aiida.net/)' --- ```{toctree} @@ -38,7 +37,7 @@ 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/) to run {{ LAMMPS }} calculations. +{{ aiida_lammps }} is a Python package that allows the workflow management and data provenance tracking framework {{ AiiDA }} to 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. diff --git a/docs/source/topics/calculations/base.md b/docs/source/topics/calculations/base.md index 237f76b8..eb11e138 100644 --- a/docs/source/topics/calculations/base.md +++ b/docs/source/topics/calculations/base.md @@ -1,30 +1,37 @@ -# `LammpsBaseCalculation` +# ``LammpsBaseCalculation`` -The `LammpsBaseCalculation` performs a single stage LAMMPS calculation, the input is generated by a set of parameters passed as a dictionary. The inputs accepted are the following: +The {class}`~aiida_lammps.calculations.base.LammpsBaseCalculation` performs a single stage LAMMPS calculation, the input is generated by a set of parameters passed as a dictionary. The inputs accepted are the following: ## Inputs: -- **structure**, (`StructureData`) - Structure used in the ``LAMMPS`` calculation. -- **potential**, (`LammpsPotentialData`) - Potential used in the ``LAMMPS`` calculation. -- **parameters**, (`Dict`) - Parameters that control the input script generated for the ``LAMMPS`` calculation. -- **settings**, (`Dict`), *optional* - Additional settings that control the ``LAMMPS`` calculation. -- **input_restartfile** (`SinglefileData`), *optional* - Input restartfile to continue from a previous ``LAMMPS`` calculation. -- **parent_folder**, (`RemoteData`), *optional* - An optional working directory of a previously completed calculation to restart from. +- **structure**, ({class}`~aiida.orm.nodes.data.structure.StructureData`) - Structure used in the ``LAMMPS`` calculation. +- **potential**, ({class}`~aiida_lammps.data.potential.LammpsPotentialData`) - Potential used in the ``LAMMPS`` calculation. See [](#topics-data-potential). +- **parameters**, ({class}`~aiida.orm.nodes.data.dict.Dict`) - Parameters that control the input script generated for the ``LAMMPS`` calculation. See [](#topics-data-parameters). +- **settings**, ({class}`~aiida.orm.nodes.data.dict.Dict`), *optional* - Additional settings that control the ``LAMMPS`` calculation. +- **input_restartfile** ({class}`~aiida.orm.nodes.data.singlefile.SinglefileData`), *optional* - Input restart file to continue from a previous ``LAMMPS`` calculation. +- **parent_folder**, ({class}`~aiida.orm.nodes.data.remote.base.RemoteData`), *optional* - An optional working directory of a previously completed calculation to restart from. - **metadata.options.input_filename**, (`str`), *optional* - Name of the input file for the calculation. Defaults to `input.in`. - **metadata.options.structure_filename**, (`str`), *optional* - Name of the file where the structure is stored. Defaults to `structure.dat` - **metadata.options.output_filename**, (`str`). *optional* - Name of the main output file for LAMMPS. Defaults to `lammps.out`. - **metadata.options.variables_filename**, (`str`), *optional* - Name of the file where the final values of the thermodynamic variables are stored. Defaults to `aiida_lammps.yaml`. - **metadata.options.trajectory_filename**, (`str`), *optional* - Name of the file where the trajectories are stored. Defaults to `aiida_lammps.trajectory.dump`. -- **metadata.options.restart_filename**, (`str`), *optional* - Name of the restartfile to be written. Defaults to `lammps.restart`. +- **metadata.options.restart_filename**, (`str`), *optional* - Name of the restart file to be written. Defaults to `lammps.restart`. - **metadata.options.parser_name**, (`str`), *optional* - Name of the parser to be used for this calculation. Defaults to `lammps.base`. +:::{note} +LAMMPS can produce binary restart files which contain all the atomic positions, forces and other computed variables until when the are asked to be printed. One can control this by passing a dictionary called `restart` to the `settings` input. The available options for the `restart` are: +- `print_final`, (`bool`) - whether to print a restart file at the end of the calculation. Defaults to `False`. See [`write_restart`](https://docs.lammps.org/write_restart.html). +- `print intermediate`, (`bool`) - whether to print restart files periodically throughout the calculation. Defaults to `False`. See [`restart`](https://docs.lammps.org/restart.html). +- `num_steps`, (`int`) - how often is the intermediate restart file printed. Defaults to 10% of the total number of steps. +::: + ## Outputs: -- **results**, (`Dict`) - The parsed data extracted from the lammps output file. -- **trajectories** (`LammpsTrajectory`) - The data extracted from the lammps trajectory file, includes the atomic trajectories and the site and time dependent calculation parameters. -- **time_dependent_computes**, (`ArrayData`) - The data with the time dependent computes parsed from the lammps.out. -- **restartfile**, (`SinglefileData`), *optional* - The restartfile of a ``LAMMPS`` calculation. -- **structure**, (`StructureData`), *optional* - The output structure of the calculation. -- **remote_folder**, (`RemoteData`) - Folder in the remote machine where the calculation was performed. -- **remote_stash**, (`RemoteStashData`), *optional* – Contents of the stash.source_list option are stored in this remote folder after job completion. -- **retrieved**, (`FolderData`) - Files that are retrieved by the daemon will be stored in this node. By default the stdout and stderr of the scheduler will be added, but one can add more by specifying them in `CalcInfo.retrieve_list`. +- **results**, ({class}`~aiida.orm.nodes.data.dict.Dict`) - The parsed data extracted from the lammps output file. +- **trajectories** ({class}`~aiida_lammps.data.trajectory.LammpsTrajectory`) - The data extracted from the lammps trajectory file, includes the atomic trajectories and the site and time dependent calculation parameters. +- **time_dependent_computes**, ({class}`~aiida.orm.nodes.data.array.array.ArrayData`) - The data with the time dependent computes parsed from the lammps.out. +- **restartfile**, ({class}`~aiida.orm.nodes.data.singlefile.SinglefileData`), *optional* - The restart file of a ``LAMMPS`` calculation. +- **structure**, ({class}`~aiida.orm.nodes.data.structure.StructureData`), *optional* - The output structure of the calculation. +- **remote_folder**, ({class}`~aiida.orm.nodes.data.remote.base.RemoteData`) - Folder in the remote machine where the calculation was performed. +- **remote_stash**, ({class}`~aiida.orm.nodes.data.remote.stash.base.RemoteStashData`), *optional* – Contents of the stash.source_list option are stored in this remote folder after job completion. +- **retrieved**, ({class}`~aiida.orm.nodes.data.folder.FolderData`) - Files that are retrieved by the daemon will be stored in this node. By default the stdout and stderr of the scheduler will be added, but one can add more by specifying them in `CalcInfo.retrieve_list`. diff --git a/docs/source/topics/calculations/index.md b/docs/source/topics/calculations/index.md index 7fe57d37..176372cd 100644 --- a/docs/source/topics/calculations/index.md +++ b/docs/source/topics/calculations/index.md @@ -1,3 +1,14 @@ +--- +myst: + substitutions: + aiida_lammps: '`aiida-lammps`' + LAMMPS: '[LAMMPS](https://lammps.org)' + AiiDA: '[AiiDA](https://www.aiida.net/)' + LammpsBaseCalculation: '{class}`~aiida_lammps.calculations.base.LammpsBaseCalculation`' + LammpsRawCalculation: '{class}`~aiida_lammps.calculations.raw.LammpsRawCalculation`' +--- + + (topics-calculations)= # Calculations @@ -9,3 +20,5 @@ base raw ``` + +{{ aiida_lammps }} has two different types of calculations {{ LammpsBaseCalculation }} and {{ LammpsRawCalculation }}. The {{ LammpsBaseCalculation }} generates a {{ LAMMPS }} input script for a single stage calculation from a set of parameters passed as as dictionary to the calculation. However, to give more flexibility for cases not being tractable with a single stage calculation, or that require options not covered by the {{ LammpsBaseCalculation }} the {{ LammpsRawCalculation }} is designed to be able to accept any {{ LAMMPS }} script as an input. diff --git a/docs/source/topics/calculations/raw.md b/docs/source/topics/calculations/raw.md index 5885996b..dc93c096 100644 --- a/docs/source/topics/calculations/raw.md +++ b/docs/source/topics/calculations/raw.md @@ -1,19 +1,19 @@ -# `LammpsRawCalculation` +# ``LammpsRawCalculation`` -The `LammpsRawCalculation` performs a LAMMPS calculation from a given LAMMPS input script and a set of files. +The {class}`~aiida_lammps.calculations.raw.LammpsRawCalculation` performs a LAMMPS calculation from a given LAMMPS input script and a set of files. ## Inputs: -- **script**, (`SinglefileData`) - Complete input script to use. If specified, `structure`, `potential` and `parameters` are ignored. -- **files**, (Namespace of `SinglefileData`), *optional* - Optional files that should be written to the working directory. This is an -- **filenames**, (`Dict`), *optional* - Optional namespace to specify with which filenames the files of ``files`` input should be written. +- **script**, ({class}`~aiida.orm.nodes.data.singlefile.SinglefileData`) - Complete input script to use. If specified, `structure`, `potential` and `parameters` are ignored. +- **files**, (Namespace of {class}`~aiida.orm.nodes.data.singlefile.SinglefileData`), *optional* - Optional files that should be written to the working directory. This is an +- **filenames**, ({class}`~aiida.orm.nodes.data.dict.Dict`), *optional* - Optional namespace to specify with which filenames the files of ``files`` input should be written. - **metadata.options.input_filename**, (`str`), *optional* - Name of the input file for the calculation. Defaults to `input.in`. - **metadata.options.output_filename**, (`str`). *optional* - Name of the main output file for LAMMPS. Defaults to `lammps.out`. - **metadata.options.parser_name**, (`str`), *optional* - Name of the parser to be used for this calculation. Defaults to `lammps.raw`. ## Outputs: -- **results**, (`Dict`) - The parsed data extracted from the lammps output file. -- **remote_folder**, (`RemoteData`) - Folder in the remote machine where the calculation was performed. -- **remote_stash**, (`RemoteStashData`), *optional* – Contents of the stash.source_list option are stored in this remote folder after job completion. -- **retrieved**, (`FolderData`) - Files that are retrieved by the daemon will be stored in this node. By default the stdout and stderr of the scheduler will be added, but one can add more by specifying them in `CalcInfo.retrieve_list`. +- **results**, ({class}`~aiida.orm.nodes.data.dict.Dict`) - The parsed data extracted from the lammps output file. +- **remote_folder**, ({class}`~aiida.orm.nodes.data.remote.base.RemoteData`) - Folder in the remote machine where the calculation was performed. +- **remote_stash**, ({class}`~aiida.orm.nodes.data.remote.stash.base.RemoteStashData`), *optional* – Contents of the stash.source_list option are stored in this remote folder after job completion. +- **retrieved**, ({class}`~aiida.orm.nodes.data.folder.FolderData`) - Files that are retrieved by the daemon will be stored in this node. By default the stdout and stderr of the scheduler will be added, but one can add more by specifying them in `CalcInfo.retrieve_list`. diff --git a/docs/source/topics/data/parameters.md b/docs/source/topics/data/parameters.md index 9bf04082..8b538a86 100644 --- a/docs/source/topics/data/parameters.md +++ b/docs/source/topics/data/parameters.md @@ -1,6 +1,18 @@ +--- +myst: + substitutions: + aiida_lammps: '`aiida-lammps`' + LAMMPS: '[LAMMPS](https://lammps.org)' + AiiDA: '[AiiDA](https://www.aiida.net/)' + pair_style: '[pair-style](https://docs.lammps.org/pair_style.html)' +--- + + +(topics-data-parameters)= + # Parameters -The behavior of the ``aiida-lammps`` calculation can be controlled by collecting ``LAMMPS`` simulation parameters in a dictionary +The behavior of the {{ aiida_lammps }} calculation can be controlled by collecting {{ LAMMPS }} simulation parameters in a dictionary ```python parameters = { @@ -36,10 +48,10 @@ parameters = { } ``` -The dictionary is separated into several nested dictionaries that control different behaviors of the ``LAMMPS`` simulation: +The dictionary is separated into several nested dictionaries that control different behaviors of the {{ LAMMPS }} simulation: - ``control``: takes keywords specifying global simulation parameters: - * ``units``: ``LAMMPS`` [units](https://docs.lammps.org/units.html) used in the calculation (default: ``si``). - * ``timestep``: [time step](https://docs.lammps.org/timestep.html) used in the simulation, it depends on the units used (default: ``LAMMPS`` default dependent on units parameter). + * ``units``: {{ LAMMPS }} [units](https://docs.lammps.org/units.html) used in the calculation (default: ``si``). + * ``timestep``: [time step](https://docs.lammps.org/timestep.html) used in the simulation, it depends on the units used (default: {{ LAMMPS }} default dependent on units parameter). * ``newton``: it controls whether the Newton's third law is [turned on or off](https://docs.lammps.org/newton.html) for the calculation (default: ``on``). * ``processors``: specifies how [processors](https://docs.lammps.org/processors.html) are mapped to the simulation box (default: ignore the command). - ``structure``: variables controlling structure options: @@ -52,11 +64,11 @@ The dictionary is separated into several nested dictionaries that control differ * ``neighbor_modify``: set of options that [modify](https://docs.lammps.org/neigh_modify.html) the pairwise neighbor list generation (default: skip parameter). - ``dump``: controls parameters regarding the printing of the site dependent quantities: * ``dump_rate``: how often are the site dependent quantities printed to file (default: 10). -- ``compute``: set of lists containing information about which ``LAMMPS`` [computes](https://docs.lammps.org/compute.html) should be calculated. For each ``LAMMPS`` command one passes a list of dictionaries, each dictionary has a ``type`` key containing the options of the compute and ``group`` a key specifying over which group the compute is acting on. -- ``fix``: set of list containing information about which ``LAMMPS`` [fixes](https://docs.lammps.org/fix.html) should be calculated. For each ``LAMMPS`` command one passes a list of dictionaries, each dictionary has a ``type`` key containing the options of the fixes and ``group`` a key specifying over which group the fix is acting on. +- ``compute``: set of lists containing information about which {{ LAMMPS }} [computes](https://docs.lammps.org/compute.html) should be calculated. For each {{ LAMMPS }} command one passes a list of dictionaries, each dictionary has a ``type`` key containing the options of the compute and ``group`` a key specifying over which group the compute is acting on. +- ``fix``: set of list containing information about which {{ LAMMPS }} [fixes](https://docs.lammps.org/fix.html) should be calculated. For each {{ LAMMPS }} command one passes a list of dictionaries, each dictionary has a ``type`` key containing the options of the fixes and ``group`` a key specifying over which group the fix is acting on. - ``thermo``: set of variables indicating which global parameters (printed in the ``lammps.out``) should be printed: * ``printing_rate``: how often should the parameters be written to the ``lammps.out`` (default: 1000) - * ``thermo_printing``: dictionary containing which ``LAMMPS`` internal [variables](https://docs.lammps.org/thermo_style.html) are printed to the ``lammps.out``. The keys are the names of ``LAMMPS`` parameters and the value is a boolean on whether to print it or not. + * ``thermo_printing``: dictionary containing which {{ LAMMPS }} internal [variables](https://docs.lammps.org/thermo_style.html) are printed to the ``lammps.out``. The keys are the names of {{ LAMMPS }} parameters and the value is a boolean on whether to print it or not. - ``md``: set of variables controlling a molecular dynamics simulation (exclusionary with ``minimize`` key word): * ``max_number_steps``: maximum number of steps for the molecular dynamics simulation (default: 100) * ``run_style``: type of molecular dynamics algorithm (default: ``verlet``). @@ -70,9 +82,9 @@ The dictionary is separated into several nested dictionaries that control differ * ``force_tolerance``: tolerance for the force minimization (default: 1e-4). * ``max_iterations``: maximum number of iterations (default: 1000). * ``max_evaluations``: maximum number of evaluations (default: 1000). -- ``restart``: set of variables controlling the printing of the binary file to [restart](https://docs.lammps.org/Howto_restart.html) a ``LAMMPS`` calculation. +- ``restart``: set of variables controlling the printing of the binary file to [restart](https://docs.lammps.org/Howto_restart.html) a {{ LAMMPS }} calculation. * ``print_final``: whether or not to print a restart file at the end of the calculation, equivalent to setting [write_restart](https://docs.lammps.org/write_restart.html) at the end of the calculation (default: ``False``). - * ``print_intermediate``: whether or not to print restart files throughout the run at regular intervals, equivalent to the [restart](https://docs.lammps.org/restart.html) ``LAMMPS`` command (default: ``False``). + * ``print_intermediate``: whether or not to print restart files throughout the run at regular intervals, equivalent to the [restart](https://docs.lammps.org/restart.html) {{ LAMMPS }} command (default: ``False``). * ``num_steps``: however often the restart file is written if ``print_intermediate`` is used (default: ``max_number_steps*0.1``). :::{note} @@ -80,7 +92,7 @@ As the restart files can be very large, they are by default not printed, nor sto ::: ## 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. +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 -``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. +{{ 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 index 5b7200ec..5e426bf0 100644 --- a/docs/source/topics/data/potential.md +++ b/docs/source/topics/data/potential.md @@ -1,9 +1,20 @@ +--- +myst: + substitutions: + aiida_lammps: '`aiida-lammps`' + LAMMPS: '[LAMMPS](https://lammps.org)' + AiiDA: '[AiiDA](https://www.aiida.net/)' + pair_style: '[pair-style](https://docs.lammps.org/pair_style.html)' +--- + +(topics-data-potential)= + # ``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. +In {{ aiida_lammps }} the potential file is stored in the {class}`~aiida_lammps.data.potential.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. +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. ```python potential_parameters = { @@ -50,7 +61,7 @@ potential_parameters = { } } ``` -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. +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 ```python @@ -63,15 +74,15 @@ potential = LammpsPotentialData.get_or_create( ``` -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. +The {meth}`~aiida_lammps.data.potential.LammpsPotentialData.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``. +In {{ LAMMPS }} certain {{ pair_style }} 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. +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. diff --git a/docs/source/topics/data/trajectory.md b/docs/source/topics/data/trajectory.md index aacedfe0..a3a012fc 100644 --- a/docs/source/topics/data/trajectory.md +++ b/docs/source/topics/data/trajectory.md @@ -1 +1,16 @@ -# `LammpsTrajectory` +--- +myst: + substitutions: + aiida_lammps: '`aiida-lammps`' + LAMMPS: '[LAMMPS](https://lammps.org)' + AiiDA: '[AiiDA](https://www.aiida.net/)' +--- + +# ``LammpsTrajectory`` + +During the course of a {{ LAMMPS }} simulation large trajectory files are generated. However, these are text files that can be compressed greatly reducing the used space. Hence, storing them directly in the {{ AiiDA }} repository is not efficient. The {class}`~aiida_lammps.data.trajectory.LammpsTrajectory` data class takes care of this by storing each trajectory step is as a separate file, within a compressed zip folder. Thus reducing storage space, and allowing for fast access to each step. + +It is possible to access the data for each step using several methods: +- {meth}`~aiida_lammps.data.trajectory.LammpsTrajectory.get_step_string`: which returns the raw step string from the {{ LAMMPS }} output for a given step. +- {meth}`~aiida_lammps.data.trajectory.LammpsTrajectory.get_step_data`: which returns the parsed data for a given step. +- {meth}`~aiida_lammps.data.trajectory.LammpsTrajectory.get_step_structure`: which returns a {class}`~aiida.orm.nodes.data.structure.StructureData` instance for the crystal structure for a given step. diff --git a/docs/source/topics/workflows/base.md b/docs/source/topics/workflows/base.md index b8c1aa3d..5c231f29 100644 --- a/docs/source/topics/workflows/base.md +++ b/docs/source/topics/workflows/base.md @@ -1 +1,36 @@ -# `LammpsBaseWorkChain` +# ``LammpsBaseWorkChain`` + +The {class}`~aiida_lammps.workflows.base.LammpsBaseWorkChain` is a `WorkChain` wrapper for the {class}`~aiida_lammps.calculations.base.LammpsBaseCalculation` that includes the capabilities of the AiiDA [`BaseRestartWorkchain`](https://aiida.readthedocs.io/projects/aiida-core/en/latest/reference/apidoc/aiida.engine.processes.workchains.html#aiida.engine.processes.workchains.restart.BaseRestartWorkChain). That is it allows for automatic error handling and restarting of calculations if certain conditions are met. + +Right now the restart capabilities are limited to: +- Restarting an structural optimization from the last parsed structure if the minimization threshold was not reached. +- Restarting a calculation that ran out of walltime by attempting to start from the last stored structure, if no structure is found restart from scratch but with 50% more walltime. + +The inputs for the {class}`~aiida_lammps.workflows.base.LammpsBaseWorkChain` are quite similar to those from the {class}`~aiida_lammps.calculations.base.LammpsBaseCalculation`, with the only difference being, that for the Workchain the are encapsulated inside the `lammps` namespace. + +## Inputs: +- **lammps.structure**, ({class}`~aiida.orm.nodes.data.structure.StructureData`) - Structure used in the ``LAMMPS`` calculation. +- **lammps.potential**, ({class}`~aiida_lammps.data.potential.LammpsPotentialData`) - Potential used in the ``LAMMPS`` calculation. See [](#topics-data-potential). +- **lammps.parameters**, ({class}`~aiida.orm.nodes.data.dict.Dict`) - Parameters that control the input script generated for the ``LAMMPS`` calculation. See [](#topics-data-parameters). +- **lammps.settings**, ({class}`~aiida.orm.nodes.data.dict.Dict`), *optional* - Additional settings that control the ``LAMMPS`` calculation. +- **lammps.input_restartfile** ({class}`~aiida.orm.nodes.data.singlefile.SinglefileData`), *optional* - Input restart file to continue from a previous ``LAMMPS`` calculation. +- **lammps.parent_folder**, ({class}`~aiida.orm.nodes.data.remote.base.RemoteData`), *optional* - An optional working directory of a previously completed calculation to restart from. +- **store_restart**, ({class}`~aiida.orm.nodes.data.bool.Bool`), *optional* - Whether to store the restart file in the repository. Defaults to `False`. + +:::{note} +LAMMPS can produce binary restart files which contain all the atomic positions, forces and other computed variables until when the are asked to be printed. One can control this by passing a dictionary called `restart` to the `settings` input. The available options for the `restart` are: +- `print_final`, (`bool`) - whether to print a restart file at the end of the calculation. Defaults to `False`. See [`write_restart`](https://docs.lammps.org/write_restart.html). +- `print intermediate`, (`bool`) - whether to print restart files periodically throughout the calculation. Defaults to `False`. See [`restart`](https://docs.lammps.org/restart.html). +- `num_steps`, (`int`) - how often is the intermediate restart file printed. Defaults to 10% of the total number of steps. +::: + +## Outputs: + +- **results**, ({class}`~aiida.orm.nodes.data.dict.Dict`) - The parsed data extracted from the lammps output file. +- **trajectories** ({class}`~aiida_lammps.data.trajectory.LammpsTrajectory`) - The data extracted from the lammps trajectory file, includes the atomic trajectories and the site and time dependent calculation parameters. +- **time_dependent_computes**, ({class}`~aiida.orm.nodes.data.array.array.ArrayData`) - The data with the time dependent computes parsed from the lammps.out. +- **restartfile**, ({class}`~aiida.orm.nodes.data.singlefile.SinglefileData`), *optional* - The restart file of a ``LAMMPS`` calculation. +- **structure**, ({class}`~aiida.orm.nodes.data.structure.StructureData`), *optional* - The output structure of the calculation. +- **remote_folder**, ({class}`~aiida.orm.nodes.data.remote.base.RemoteData`) - Folder in the remote machine where the calculation was performed. +- **remote_stash**, ({class}`~aiida.orm.nodes.data.remote.stash.base.RemoteStashData`), *optional* – Contents of the stash.source_list option are stored in this remote folder after job completion. +- **retrieved**, ({class}`~aiida.orm.nodes.data.folder.FolderData`) - Files that are retrieved by the daemon will be stored in this node. By default the stdout and stderr of the scheduler will be added, but one can add more by specifying them in `CalcInfo.retrieve_list`. diff --git a/docs/source/topics/workflows/index.md b/docs/source/topics/workflows/index.md index b273758e..68fdb9da 100644 --- a/docs/source/topics/workflows/index.md +++ b/docs/source/topics/workflows/index.md @@ -1,3 +1,11 @@ +--- +myst: + substitutions: + aiida_lammps: '`aiida-lammps`' + LAMMPS: '[LAMMPS](https://lammps.org)' + AiiDA: '[AiiDA](https://www.aiida.net/)' +--- + (topics-workflows)= # Workflows @@ -9,3 +17,5 @@ base relax md ``` + +The workflows act as abstractions of the {class}`~aiida_lammps.calculations.base.LammpsBaseCalculation` focusing on being able to perform error correction as well as specific tasks. The idea is that these are used as building blocks for more complex calculations, offloading what is normally done inside by scripting in the {{ LAMMPS }} input to {{ AiiDA }}. The advantage of this is that each step of the complex workflow will be stored in the {{ AiiDA }} provenance graph, and will be able to be used for other calculations, data analysis or just as a way to effectively monitor what happens at each stage. The drawback with this approach is that each stage is a {{ LAMMPS }} calculation, which implies some overhead, as well as effort into rewriting the {{ LAMMPS }} script into an {{ AiiDA }} compliant workflow. diff --git a/docs/source/topics/workflows/md.md b/docs/source/topics/workflows/md.md index 08d948fb..568c7eaa 100644 --- a/docs/source/topics/workflows/md.md +++ b/docs/source/topics/workflows/md.md @@ -1 +1,52 @@ -# `LammpsMDWorkChain` +--- +myst: + substitutions: + aiida_lammps: '`aiida-lammps`' + LAMMPS: '[LAMMPS](https://lammps.org)' + AiiDA: '[AiiDA](https://www.aiida.net/)' + LammpsBaseCalculation: '{class}`~aiida_lammps.calculations.base.LammpsBaseCalculation`' + LammpsRawCalculation: '{class}`~aiida_lammps.calculations.raw.LammpsRawCalculation`' + Int: '{class}`~aiida.orm.nodes.data.int.Int`' + Str: '{class}`~aiida.orm.nodes.data.str.Str`' + Dict: '{class}`~aiida.orm.nodes.data.dict.Dict`' + List: '{class}`~aiida.orm.nodes.data.list.List`' +--- + +# ``LammpsMDWorkChain`` + +This is a subclass of the {class}`~aiida_lammps.workflows.base.LammpsBaseWorkChain` which focuses on MD simulations specifically. It overrides any set of parameters given in the md block (see [](#topics-data-parameters)) and instead directly exposes them to the user in the `md` input namespace. + + +## Inputs: + +- **lammps.structure**, ({class}`~aiida.orm.nodes.data.structure.StructureData`) - Structure used in the ``LAMMPS`` calculation. +- **lammps.potential**, ({class}`~aiida_lammps.data.potential.LammpsPotentialData`) - Potential used in the ``LAMMPS`` calculation. See [](#topics-data-potential). +- **lammps.parameters**, ({class}`~aiida.orm.nodes.data.dict.Dict`) - Parameters that control the input script generated for the ``LAMMPS`` calculation. See [](#topics-data-parameters). +- **lammps.settings**, ({class}`~aiida.orm.nodes.data.dict.Dict`), *optional* - Additional settings that control the ``LAMMPS`` calculation. +- **lammps.input_restartfile** ({class}`~aiida.orm.nodes.data.singlefile.SinglefileData`), *optional* - Input restart file to continue from a previous ``LAMMPS`` calculation. +- **lammps.parent_folder**, ({class}`~aiida.orm.nodes.data.remote.base.RemoteData`), *optional* - An optional working directory of a previously completed calculation to restart from. +- **store_restart**, ({class}`~aiida.orm.nodes.data.bool.Bool`), *optional* - Whether to store the restart file in the repository. Defaults to `False`. +- **md.steps**, ({{ Int }}), *optional* - Number of steps in the MD simulation. Defaults to `1000`. +- **md.algo**, {{ Str }}, *optional* - Type of time integrator used for MD simulations in LAMMPS ([run_style](https://docs.lammps.org/run_style.html)). Defaults to verlet. +- **md.integrator**, ({{ Str }}), *optional* - Type of thermostat used for the MD simulation in LAMMPS, e.g. ``fix npt``. Defaults to `npt`. +- **md.integrator_constraints**, ({{ Dict }}), *optional* - Set of constraints that are applied to the thermostat. Defaults to `{"temp":[300,300,100], "iso":[0.0, 0.0, 1000]}`. +- **md.velocity**, ({{ List }}), *optional* - List with the information describing how to generate the velocities for the initialization of the MD run. +- **md.respa_options**, ({{ List }}), *optional* - List with the information needed to setup the respa options. + +:::{note} +LAMMPS can produce binary restart files which contain all the atomic positions, forces and other computed variables until when the are asked to be printed. One can control this by passing a dictionary called `restart` to the `settings` input. The available options for the `restart` are: +- `print_final`, (`bool`) - whether to print a restart file at the end of the calculation. Defaults to `False`. See [`write_restart`](https://docs.lammps.org/write_restart.html). +- `print intermediate`, (`bool`) - whether to print restart files periodically throughout the calculation. Defaults to `False`. See [`restart`](https://docs.lammps.org/restart.html). +- `num_steps`, (`int`) - how often is the intermediate restart file printed. Defaults to 10% of the total number of steps. +::: + +## Outputs: + +- **results**, ({class}`~aiida.orm.nodes.data.dict.Dict`) - The parsed data extracted from the lammps output file. +- **trajectories** ({class}`~aiida_lammps.data.trajectory.LammpsTrajectory`) - The data extracted from the lammps trajectory file, includes the atomic trajectories and the site and time dependent calculation parameters. +- **time_dependent_computes**, ({class}`~aiida.orm.nodes.data.array.array.ArrayData`) - The data with the time dependent computes parsed from the lammps.out. +- **restartfile**, ({class}`~aiida.orm.nodes.data.singlefile.SinglefileData`), *optional* - The restart file of a ``LAMMPS`` calculation. +- **structure**, ({class}`~aiida.orm.nodes.data.structure.StructureData`), *optional* - The output structure of the calculation. +- **remote_folder**, ({class}`~aiida.orm.nodes.data.remote.base.RemoteData`) - Folder in the remote machine where the calculation was performed. +- **remote_stash**, ({class}`~aiida.orm.nodes.data.remote.stash.base.RemoteStashData`), *optional* – Contents of the stash.source_list option are stored in this remote folder after job completion. +- **retrieved**, ({class}`~aiida.orm.nodes.data.folder.FolderData`) - Files that are retrieved by the daemon will be stored in this node. By default the stdout and stderr of the scheduler will be added, but one can add more by specifying them in `CalcInfo.retrieve_list`. diff --git a/docs/source/topics/workflows/relax.md b/docs/source/topics/workflows/relax.md index 2d4c0467..3bae3cd5 100644 --- a/docs/source/topics/workflows/relax.md +++ b/docs/source/topics/workflows/relax.md @@ -1 +1,61 @@ -# `LammpsRelaxWorkChain` +--- +myst: + substitutions: + aiida_lammps: '`aiida-lammps`' + LAMMPS: '[LAMMPS](https://lammps.org)' + AiiDA: '[AiiDA](https://www.aiida.net/)' + LammpsBaseCalculation: '{class}`~aiida_lammps.calculations.base.LammpsBaseCalculation`' + LammpsRawCalculation: '{class}`~aiida_lammps.calculations.raw.LammpsRawCalculation`' + Int: '{class}`~aiida.orm.nodes.data.int.Int`' + Float: '{class}`~aiida.orm.nodes.data.float.Float`' + Str: '{class}`~aiida.orm.nodes.data.str.Str`' + Dict: '{class}`~aiida.orm.nodes.data.dict.Dict`' + List: '{class}`~aiida.orm.nodes.data.list.List`' + Bool: '{class}`~aiida.orm.nodes.data.bool.Bool`' +--- + +# ``LammpsRelaxWorkChain`` + +This is a subclass of the {class}`~aiida_lammps.workflows.base.LammpsBaseWorkChain` which focuses on minimization simulations specifically. It overrides any set of parameters given in the minimize block (see [](#topics-data-parameters)) and instead directly exposes them to the user in the `relax` input namespace. + +## Inputs: + +- **lammps.structure**, ({class}`~aiida.orm.nodes.data.structure.StructureData`) - Structure used in the ``LAMMPS`` calculation. +- **lammps.potential**, ({class}`~aiida_lammps.data.potential.LammpsPotentialData`) - Potential used in the ``LAMMPS`` calculation. See [](#topics-data-potential). +- **lammps.parameters**, ({class}`~aiida.orm.nodes.data.dict.Dict`) - Parameters that control the input script generated for the ``LAMMPS`` calculation. See [](#topics-data-parameters). +- **lammps.settings**, ({class}`~aiida.orm.nodes.data.dict.Dict`), *optional* - Additional settings that control the ``LAMMPS`` calculation. +- **lammps.input_restartfile** ({class}`~aiida.orm.nodes.data.singlefile.SinglefileData`), *optional* - Input restart file to continue from a previous ``LAMMPS`` calculation. +- **lammps.parent_folder**, ({class}`~aiida.orm.nodes.data.remote.base.RemoteData`), *optional* - An optional working directory of a previously completed calculation to restart from. +- **store_restart**, ({{ Bool }}), *optional* - Whether to store the restart file in the repository. Defaults to `False`. +- **relax.algo**, ({{ Str }}), *optional* - The algorithm to be used during relaxation. Defaults to cg. +- **relax.volume**, ({{ Bool }}), *optional* - Whether or not relaxation of the volume will be performed by using the [box/relax](https://docs.lammps.org/fix_box_relax.html) fix from LAMMPS. Defaults to `False`. +- **relax.shape**, ({{ Bool }}), *optional* - Whether or not the shape of the cell will be relaxed by using the [box/relax](https://docs.lammps.org/fix_box_relax.html) fix from LAMMPS. Defaults to `False` +- **relax.positions**, ({{ Bool }}), *optional* - Whether or not to allow the relaxation of the atomic positions. Defaults to `True`. +- **relax.steps**, ({{ Int }}), *optional* - Maximum number of steps during the relaxation. Defaults to `1000`. +- **relax.evaluations**, ({{ Int }}), *optional* - Maximum number of force/energy evaluations during the relaxation. Defaults to `10000`. +- **relax.energy_tolerance**, ({{ Float }}), *optional* - The tolerance that determined whether the relaxation procedure is stopped. In this case it stops when the relative change between outer iterations of the relaxation run is less than the given value. Defaults to 1e-4. +- **relax.force_tolerance**, ({{ Float }}), *optional* - The tolerance that determines whether the relaxation procedure is stopped. In this case it stops when the 2-norm of the global force vector is less than the given value. Defaults to `1e-4`. +- **relax.target_pressure**, ({{ Dict }}), *optional* - Dictionary containing the values for the target pressure tensor. See the [box/relax](https://docs.lammps.org/fix_box_relax.html) for more information. +- **relax.max_volume_change**, ({{ Float }}), *optional* - Maximum allowed change in one iteration (``vmax``). +- **relax.nreset**, ({{ Int }}), *optional* - Reset the reference cell every this many minimizer iterations. +- **relax.meta_convergence**, ({{ Bool }}), *optional* - If `True` the workchain will perform a meta-convergence on the cell volume. Defaults to `True`. +- **relax.max_meta_convergence_iterations**, ({{ Int}}), *optional* - The maximum number of variable cell relax iterations in the meta convergence cycle. Defaults to `5`. +- **relax.volume_convergence**, ({{ Float }}), *optional* - The volume difference threshold between two consecutive meta convergence iterations. Defaults to `0.1`. + +:::{note} +LAMMPS can produce binary restart files which contain all the atomic positions, forces and other computed variables until when the are asked to be printed. One can control this by passing a dictionary called `restart` to the `settings` input. The available options for the `restart` are: +- `print_final`, (`bool`) - whether to print a restart file at the end of the calculation. Defaults to `False`. See [`write_restart`](https://docs.lammps.org/write_restart.html). +- `print intermediate`, (`bool`) - whether to print restart files periodically throughout the calculation. Defaults to `False`. See [`restart`](https://docs.lammps.org/restart.html). +- `num_steps`, (`int`) - how often is the intermediate restart file printed. Defaults to 10% of the total number of steps. +::: + +## Outputs: + +- **results**, ({class}`~aiida.orm.nodes.data.dict.Dict`) - The parsed data extracted from the lammps output file. +- **trajectories** ({class}`~aiida_lammps.data.trajectory.LammpsTrajectory`) - The data extracted from the lammps trajectory file, includes the atomic trajectories and the site and time dependent calculation parameters. +- **time_dependent_computes**, ({class}`~aiida.orm.nodes.data.array.array.ArrayData`) - The data with the time dependent computes parsed from the lammps.out. +- **restartfile**, ({class}`~aiida.orm.nodes.data.singlefile.SinglefileData`), *optional* - The restart file of a ``LAMMPS`` calculation. +- **structure**, ({class}`~aiida.orm.nodes.data.structure.StructureData`), *optional* - The output structure of the calculation. +- **remote_folder**, ({class}`~aiida.orm.nodes.data.remote.base.RemoteData`) - Folder in the remote machine where the calculation was performed. +- **remote_stash**, ({class}`~aiida.orm.nodes.data.remote.stash.base.RemoteStashData`), *optional* – Contents of the stash.source_list option are stored in this remote folder after job completion. +- **retrieved**, ({class}`~aiida.orm.nodes.data.folder.FolderData`) - Files that are retrieved by the daemon will be stored in this node. By default the stdout and stderr of the scheduler will be added, but one can add more by specifying them in `CalcInfo.retrieve_list`. diff --git a/docs/source/tutorials/first_md.md b/docs/source/tutorials/first_md.md index a22070f9..d633c5c2 100644 --- a/docs/source/tutorials/first_md.md +++ b/docs/source/tutorials/first_md.md @@ -45,7 +45,7 @@ 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. +The ase structure is then passed to the {class}`~aiida.orm.nodes.data.structure.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. @@ -86,10 +86,10 @@ The potential is downloaded from the OpenKIM repository making use of the [reque 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. +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. For a more detailed explanation see the topic section [](#topics-data-potential). ::: -With the potential data and the metadata dictionary one can then generate a `LammpsPotentialData` node which can be assigned to the builder. +With the potential data and the metadata dictionary one can then generate a {class}`~aiida_lammps.data.potential.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: @@ -144,6 +144,11 @@ The parameters have several sections which control different behavior of the cal - `thermo`: controls which global thermodynamic information will be calculated and written to file ([see thermo command](https://docs.lammps.org/thermo.html)). - `md`: controls how the molecular dynamics calculations are performed. Controlling which type of ensemble will be used, eg. [npt](https://docs.lammps.org/fix_nh.html#fix-npt-command), [nvt](https://docs.lammps.org/fix_nh.html#fix-nvt-command), [nve](https://docs.lammps.org/fix_nve.html) as well as initial thermalization parameters such as the [velocities](https://docs.lammps.org/velocity.html) of the particles. +:::{note} +For a detailed explanation of the possible options in the parameters see the [](#topics-data-parameters) topic section. + +::: + 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. diff --git a/docs/source/tutorials/first_raw.md b/docs/source/tutorials/first_raw.md index 8af8a33c..82dd4764 100644 --- a/docs/source/tutorials/first_raw.md +++ b/docs/source/tutorials/first_raw.md @@ -10,10 +10,10 @@ myst: # Raw LAMMPS calculation -Sometimes transforming a {{ LAMMPS }} script into a set of parameters that can be passed as a dictionary to {{ aiida_lammps }} can be very complicated or impossible. That is why the `LammpsRawCalculation` is included, as it gives a way to pass a functioning {{ LAMMPS }} script to {{ aiida_lammps }} and run it via AiiDA. This will store the calculation in the AiiDA provenance graph and perform some basic parsing functions. However, as a great deal of the information needed to be able to parse the data is not present (due to the lack of parameters passed to the calculation engine) many of the automatic parsing done in the `LammpsBaseCalculation` is not performed in this case. +Sometimes transforming a {{ LAMMPS }} script into a set of parameters that can be passed as a dictionary to {{ aiida_lammps }} can be very complicated or impossible. That is why the {class}`~aiida_lammps.calculations.raw.LammpsRawCalculation` is included, as it gives a way to pass a functioning {{ LAMMPS }} script to {{ aiida_lammps }} and run it via AiiDA. This will store the calculation in the AiiDA provenance graph and perform some basic parsing functions. However, as a great deal of the information needed to be able to parse the data is not present (due to the lack of parameters passed to the calculation engine) many of the automatic parsing done in the {class}`~aiida_lammps.calculations.base.LammpsBaseCalculation` is not performed in this case. :::{note} -The usage of the `LammpsRawCalculation` also introduces difficulties with regards to the querying of results. With the `LammpsBaseCalculation` one passes several nodes, parameters, structure and potential which can be used in the AiiDA query engine to get specific calculations. As these do not exist for the `LammpsRawCalculation` the querying can be severely limited. +The usage of the {class}`~aiida_lammps.calculations.raw.LammpsRawCalculation` also introduces difficulties with regards to the querying of results. With the {class}`~aiida_lammps.calculations.base.LammpsBaseCalculation` one passes several nodes, parameters, structure and potential which can be used in the AiiDA query engine to get specific calculations. As these do not exist for the {class}`~aiida_lammps.calculations.raw.LammpsRawCalculation` the querying can be severely limited. ::: :::{tip} @@ -43,7 +43,7 @@ builder.code = code The process builder can be used to assign and automatically validate the inputs that will be used for the calculation. -For the raw calculation the most important piece is to pass the LAMMPS script that will be run. To be able to pass it to AiiDA one needs to store it as a `SinglefileData` node, which basically stores a file in the AiiDA provenance graph. When a `LammpsRawCalculation` is submitted this file will be copied **exactly** in the machine performing the calculation. +For the raw calculation the most important piece is to pass the LAMMPS script that will be run. To be able to pass it to AiiDA one needs to store it as a {class}`~aiida.orm.nodes.data.singlefile.SinglefileData` node, which basically stores a file in the AiiDA provenance graph. When a {class}`~aiida_lammps.calculations.raw.LammpsRawCalculation` is submitted this file will be copied **exactly** in the machine performing the calculation. ```python import io import textwrap @@ -86,7 +86,7 @@ script = SinglefileData( builder.script = script ``` -As one can notice the script wants to read a file named `data.rhodo` via the [`read_data`](https://docs.lammps.org/read_data.html) command. One can pass any set of files that the script might need, in this case a file stored in the lammps repository that is downloaded using the [requests library](https://docs.python-requests.org/en/latest/index.html), by first storing them as `SinglefileData` nodes and the passing them to the builder as follows: +As one can notice the script wants to read a file named `data.rhodo` via the [`read_data`](https://docs.lammps.org/read_data.html) command. One can pass any set of files that the script might need, in this case a file stored in the lammps repository that is downloaded using the [requests library](https://docs.python-requests.org/en/latest/index.html), by first storing them as {class}`~aiida.orm.nodes.data.singlefile.SinglefileData` nodes and the passing them to the builder as follows: ```python import requests diff --git a/docs/source/tutorials/first_relaxation.md b/docs/source/tutorials/first_relaxation.md index 99b36a81..daf777c1 100644 --- a/docs/source/tutorials/first_relaxation.md +++ b/docs/source/tutorials/first_relaxation.md @@ -45,7 +45,7 @@ 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. +The ase structure is then passed to the {class}`~aiida.orm.nodes.data.structure.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. @@ -86,10 +86,10 @@ The potential is downloaded from the OpenKIM repository making use of the [reque 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. +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. For a more detailed explanation see the topic section [](#topics-data-potential). ::: -With the potential data and the metadata dictionary one can then generate a `LammpsPotentialData` node which can be assigned to the builder. +With the potential data and the metadata dictionary one can then generate a {class}`~aiida_lammps.data.potential.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: @@ -140,6 +140,12 @@ The parameters have several sections which control different behavior of the cal - `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)). + +:::{note} +For a detailed explanation of the possible options in the parameters see the [](#topics-data-parameters) topic section. + +::: + 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. diff --git a/tests/calculations/test_raw.py b/tests/calculations/test_raw.py index 6d4a81fb..2458c64a 100644 --- a/tests/calculations/test_raw.py +++ b/tests/calculations/test_raw.py @@ -1,3 +1,4 @@ +"""Test the `LammpsRawCalculation`""" import io import textwrap @@ -26,12 +27,12 @@ def test_script(generate_calc_job, aiida_local_code_factory): "script": orm.SinglefileData(io.StringIO(content)), } - tmp_path, calc_info = generate_calc_job("lammps.raw", inputs) + tmp_path, _ = generate_calc_job("lammps.raw", inputs) assert (tmp_path / LammpsRawCalculation.FILENAME_INPUT).read_text() == content def test_files_invalid(generate_calc_job, aiida_local_code_factory): - """Test the ``files`` input valdiation. + """Test the ``files`` input validation. The list of filenames that will be used to write to the working directory needs to be unique. """ @@ -81,7 +82,7 @@ def test_files(generate_calc_job, aiida_local_code_factory): def test_filenames_invalid(generate_calc_job, aiida_local_code_factory): - """Test the ``filenames`` input valdiation. + """Test the ``filenames`` input validation. The list of filenames that will be used to write to the working directory needs to be unique. """