(WIP) Documentation enhancement.

Adding an example for the raw tutorial.

docs/source/topics/data/parameters.md

@@ -2,7 +2,7 @@
 
 The behavior of the ``aiida-lammps`` calculation can be controlled by collecting ``LAMMPS`` simulation parameters in a dictionary
 
-```{code-block} python
+```python
 parameters = {
     'md': {
         'velocity': [{'group': 'all', 'create': {'temp': 300}}],
@@ -75,9 +75,10 @@ The dictionary is separated into several nested dictionaries that control differ
     * ``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}
+:::{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
 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.
 

docs/source/topics/data/potential.md

@@ -5,7 +5,7 @@ In ``aiida-lammps`` the potential file is stored in the `LammpsPotentialData` da
 
 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
+```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)
@@ -53,7 +53,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.
 
 Then the potential can be uploaded to the database
-```{code-block} python
+```python
 from aiida_lamps.data.potential import LammpsPotentialData
 
 potential = LammpsPotentialData.get_or_create(
@@ -65,9 +65,9 @@ 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.
 
-```{note}
+:::{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``.

docs/source/tutorials/first_raw.md

@@ -1,3 +1,144 @@
+---
+myst:
+  substitutions:
+    aiida_lammps: '`aiida-lammps`'
+    LAMMPS: '[LAMMPS](https://lammps.org)'
+    OpenKIM: '[OpenKIM](https://openkim.org/)'
+---
+
 (tutorials-raw)=
 
 # 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.
+
+:::{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.
+:::
+
+:::{tip}
+The code shown in the snippets below can be {download}`downloaded as a script <include/scripts/run_raw_basic.py>`,
+The script can be made executable and then run to execute the example calculation.
+:::
+
+
+
+First import the required classes and functions:
+
+```python
+from aiida.plugins import CalculationFactory
+from aiida.engine import run
+from aiida.orm import SinglefileData, load_code
+```
+
+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 = CalculationFactory("lammps.raw").get_builder()
+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.
+```python
+import io
+import textwrap
+
+script = SinglefileData(
+    io.StringIO(
+        textwrap.dedent(
+            """
+            # Rhodopsin model
+
+            units           real
+            neigh_modify    delay 5 every 1
+
+            atom_style      full
+            bond_style      harmonic
+            angle_style     charmm
+            dihedral_style  charmm
+            improper_style  harmonic
+            pair_style      lj/charmm/coul/long 8.0 10.0
+            pair_modify     mix arithmetic
+            kspace_style    pppm 1e-4
+
+            read_data       data.rhodo
+
+            fix             1 all shake 0.0001 5 0 m 1.0 a 232
+            fix             2 all npt temp 300.0 300.0 100.0 &
+                    z 0.0 0.0 1000.0 mtk no pchain 0 tchain 1
+
+            special_bonds   charmm
+
+            thermo          50
+            thermo_style    multi
+            timestep        2.0
+
+            run     100
+            """
+        )
+    )
+)
+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 by first storing them as `SinglefileData` nodes and the passing them to the builder as follows:
+
+```python
+data = orm.SinglefileData(
+    io.StringIO(
+        textwrap.dedent(
+            """
+            LAMMPS data file from restart file: timestep = 5000, procs = 1
+
+            32000 atoms
+            27723 bonds
+            40467 angles
+            56829 dihedrals
+            1034 impropers
+            ...
+            """
+        )
+    )
+)
+builder.files = {"data": data}
+builder.filenames = {"data": "data.rhodo"}
+```
+
+:::{important}
+Notice that one first passes the files in a dictionary with a key called `data`, the filename dictionary specifies the name that will be given to the file stored under the key `data` in the machine performing the calculation. One needs to ensure that this name, `data.rhodo` in this case, matches the expected name by the script.
+:::
+
+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.

docs/source/tutorials/include/scripts/run_raw_basic.py

@@ -0,0 +1,79 @@
+"""Run a LAMMPS calculation with additional input files
+
+The example input script is taken from https://www.lammps.org/inputs/in.rhodo.txt and is an example benchmark script for
+the official benchmarks of LAMMPS. It is a simple MD simulation of a protein. It requires an additional input file in
+the working directory ``data.rhodo``. This example shows how to add such additional input files.
+"""
+import io
+import textwrap
+
+
+from aiida.plugins import CalculationFactory
+from aiida.engine import run
+from aiida.orm import SinglefileData, load_code
+
+script = SinglefileData(
+    io.StringIO(
+        textwrap.dedent(
+            """
+            # Rhodopsin model
+
+            units           real
+            neigh_modify    delay 5 every 1
+
+            atom_style      full
+            bond_style      harmonic
+            angle_style     charmm
+            dihedral_style  charmm
+            improper_style  harmonic
+            pair_style      lj/charmm/coul/long 8.0 10.0
+            pair_modify     mix arithmetic
+            kspace_style    pppm 1e-4
+
+            read_data       data.rhodo
+
+            fix             1 all shake 0.0001 5 0 m 1.0 a 232
+            fix             2 all npt temp 300.0 300.0 100.0 &
+                    z 0.0 0.0 1000.0 mtk no pchain 0 tchain 1
+
+            special_bonds   charmm
+
+            thermo          50
+            thermo_style    multi
+            timestep        2.0
+
+            run     100
+            """
+        )
+    )
+)
+data = SinglefileData(
+    io.StringIO(
+        textwrap.dedent(
+            """
+            LAMMPS data file from restart file: timestep = 5000, procs = 1
+
+            32000 atoms
+            27723 bonds
+            40467 angles
+            56829 dihedrals
+            1034 impropers
+            ...
+            """
+        )
+    )
+)
+
+builder = CalculationFactory("lammps.raw").get_builder()
+builder.code = load_code("lammps@localhost")
+builder.script = script
+builder.files = {"data": data}
+builder.filenames = {"data": "data.rhodo"}
+builder.metadata.options = {"resources": {"num_machines": 1}}
+results, node = run.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}"

examples/launch_lammps_raw_script.py

@@ -69,4 +69,4 @@
 builder.metadata.options = {"resources": {"num_machines": 1}}
 _, node = engine.run_get_node(builder)
 
-print(f"Calculation node: {submission_node}")
+print(f"Calculation node: {node}")