Update documentation

README.md

@@ -136,13 +136,22 @@ print(results)
 
 will read the NaCl structure file and attach the MACE-MP (medium) calculator, before calculating and printing the energy, forces, and stress.
 
-Jupyter Notebook tutorials illustrating the use of currently available calculations can be found in the [tutorials](https://github.com/stfc/janus-core/tree/main/docs/source/tutorials) documentation directory. This currently includes examples for:
+### Tutorials
+
+Jupyter Notebook tutorials illustrating the use of currently available calculations can
+be found in the [Python tutorials](docs/source/tutorials/python) documentation
+directory. This currently includes examples for:
 
 - [Single Point](docs/source/tutorials/python/single_point.ipynb) [![badge](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/stfc/janus-core/blob/main/docs/source/tutorials/python/single_point.ipynb)
+
 - [Geometry Optimization](docs/source/tutorials/python/geom_opt.ipynb) [![badge](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/stfc/janus-core/blob/main/docs/source/tutorials/python/geom_opt.ipynb)
+
 - [Molecular Dynamics](docs/source/tutorials/python/md.ipynb) [![badge](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/stfc/janus-core/blob/main/docs/source/tutorials/python/md.ipynb)
+
 - [Equation of State](docs/source/tutorials/python/eos.ipynb) [![badge](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/stfc/janus-core/blob/main/docs/source/tutorials/python/eos.ipynb)
+
 - [Phonons](docs/source/tutorials/python/phonons.ipynb) [![badge](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/stfc/janus-core/blob/main/docs/source/tutorials/python/phonons.ipynb)
+
 - [Nudged Elastic Band](docs/source/tutorials/python/neb.ipynb) [![badge](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/stfc/janus-core/blob/main/docs/source/tutorials/python/neb.ipynb)
 
 
@@ -265,6 +274,23 @@ Options:
 
 Please see the [user guide](https://stfc.github.io/janus-core/user_guide/command_line.html) for examples of each subcommand.
 
+### Tutorials
+
+Jupyter Notebook tutorials illustrating the use of currently available calculations can
+be found in the [CLI tutorials](docs/source/tutorials/cli) documentation directory.
+This currently includes examples for:
+
+- [Single Point](docs/source/tutorials/cli/singlepoint.ipynb) [![badge](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/stfc/janus-core/blob/main/docs/source/tutorials/cli/singlepoint.ipynb)
+
+- [Geometry Optimization](docs/source/tutorials/cli/geomopt.ipynb) [![badge](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/stfc/janus-core/blob/main/docs/source/tutorials/cli/geomopt.ipynb)
+
+- [Molecular Dynamics](docs/source/tutorials/cli/md.ipynb) [![badge](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/stfc/janus-core/blob/main/docs/source/tutorials/cli/md.ipynb)
+
+- [Phonons](docs/source/tutorials/cli/phonons.ipynb) [![badge](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/stfc/janus-core/blob/main/docs/source/tutorials/cli/phonons.ipynb)
+
+- [Nudged Elastic Band](docs/source/tutorials/cli/neb.ipynb) [![badge](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/stfc/janus-core/blob/main/docs/source/tutorials/cli/neb.ipynb)
+
+
 
 ### Using configuration files
 

docs/source/developer_guide/get_started.rst

@@ -73,7 +73,12 @@ Packages in the ``dev`` dependency group allow tests to be run locally using ``p
 
 .. note::
 
-    MACE must be installed for tests to run successfully. All other MLIPs are optional.
+    Since many tests check against specific calculation outputs, the ``mace`` extra is
+    required for most tests to run successfully. ``chgnet`` is also required for
+    ``test_descriptors.py``.
+
+    All other extras are optional, as tests that depend on these will be skipped if the
+    import fails.
 
 
 Alternatively, tests can be run in separate virtual environments using ``tox``::

docs/source/user_guide/python.rst

@@ -62,6 +62,10 @@ and ``model``, corresponding to the model path, name or label.
 Results from the MLIP calculator, which are typically stored in ``Atoms.calc.results``, will also,
 by default, be copied to these dictionaries, prefixed by the MLIP ``arch``.
 
+The ``model`` and version of the MLIP package will also be saved to the calculator that
+is attached to the structure in the ``Atoms.calc.parameters`` dictionary.
+
+
 For example:
 
 .. code-block:: python
@@ -76,6 +80,7 @@ For example:
 
     single_point.run()
     print(single_point.struct.info)
+    print(single_point.struct.calc.parameters)
 
 will return
 
@@ -92,6 +97,9 @@ will return
         'system_name': 'NaCl',
     }
 
+    {'version': '0.3.14', 'arch': 'mace_mp', 'model': 'tests/models/mace_mp_small.model'}
+
+
 .. note::
     If running calculations with multiple MLIPs, ``arch`` and ``mlip_model`` will be overwritten with the most recent MLIP information.
     Results labelled by the architecture (e.g. ``mace_mp_energy``) will be saved between MLIPs,
@@ -144,12 +152,20 @@ The ``TorchDFTD3Calculator`` can also be added to any existing calculator if req
 .. code-block:: python
 
     from ase import units
+    from ase.io import read
 
+    from janus_core.calculations.single_point import SinglePoint
     from janus_core.helpers.mlip_calculators import add_dispersion, choose_calculator
 
+    struct = read("tests/data/NaCl-deformed.cif")
+
     mace_calc = choose_calculator("mace_mp")
     calc = add_dispersion(mace_calc, device="cpu", cutoff=95 * units.Bohr)
 
+    struct.calc = calc
+
+    single_point = SinglePoint(struct=struct)
+    single_point.run()
 
 
 Additional Calculators
@@ -165,10 +181,11 @@ For example, performing geometry optimisation using the (`ASE built-in <https://
 
 .. code-block:: python
 
-    from janus_core.calculations.geom_opt import GeomOpt
     from ase.calculators.lj import LennardJones
     from ase.io import read
 
+    from janus_core.calculations.geom_opt import GeomOpt
+
     struct = read("tests/data/NaCl-deformed.cif")
     struct.calc = LennardJones()
 
@@ -177,3 +194,28 @@ For example, performing geometry optimisation using the (`ASE built-in <https://
         fmax=0.001,
     )
     geom_opt.run()
+
+
+Similarly, if you have any issues setting up a calculator from a supported MLIP, these
+can still be set up manually:
+
+.. code-block:: python
+
+    from ase.io import read
+    from mace.calculators import mace_mp
+
+    from janus_core.calculations.geom_opt import GeomOpt
+
+    struct = read("tests/data/NaCl-deformed.cif")
+    struct.calc = mace_mp()
+
+    geom_opt = GeomOpt(
+        struct=struct,
+        fmax=0.001,
+    )
+    geom_opt.run()
+
+.. note::
+    Setting up a calculator this way means that we are unable to set the ``Atoms.info``
+    details about the calculator, such as ``model`` and ``arch``, or
+    ``Atoms.calc.parameters``, described in `Calculation outputs`_.