Describe output info

README.md

@@ -225,6 +225,55 @@ Jupyter Notebook tutorials illustrating the use of currently available calculati
 - [Phonons](https://colab.research.google.com/github/stfc/janus-tutorials/blob/main/phonons.ipynb)
 
 
+## Calculation outputs
+
+By default, calculations performed will modify the underlying [ase.Atoms](https://wiki.fysik.dtu.dk/ase/ase/atoms.html) object
+to store information in the `Atoms.info` and `Atoms.arrays` dictionaries about the MLIP used.
+
+Additional dictionary keys include `arch`, corresponding to the MLIP architecture used,
+and `model_path`, 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`.
+
+For example:
+
+```python
+from janus_core.calculations.single_point import SinglePoint
+
+single_point = SinglePoint(
+    struct_path="tests/data/NaCl.cif",
+    arch="mace_mp",
+    model_path="tests/models/mace_mp_small.model",
+)
+
+single_point.run()
+print(single_point.struct.info)
+```
+
+will return
+
+```python
+{
+  'spacegroup': Spacegroup(1, setting=1),
+  'unit_cell': 'conventional',
+  'occupancy': {'0': {'Na': 1.0}, '1': {'Cl': 1.0}, '2': {'Na': 1.0}, '3': {'Cl': 1.0}, '4': {'Na': 1.0}, '5': {'Cl': 1.0}, '6': {'Na': 1.0}, '7': {'Cl': 1.0}},
+  'model_path': 'tests/models/mace_mp_small.model',
+  'arch': 'mace_mp',
+  'mace_mp_energy': -27.035127799332745,
+  'mace_mp_stress': array([-4.78327600e-03, -4.78327600e-03, -4.78327600e-03,  1.08000967e-19, -2.74004242e-19, -2.04504710e-19]),
+  'system_name': 'NaCl',
+}
+```
+
+> [!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,
+> unless the same `arch` is chosen, in which case these values will also be overwritten.
+
+This is also the case the calculations performed using the CLI, with the same information written to extxyz output files.
+
+
 ## Development
 
 We recommend installing poetry for dependency management when developing for `janus-core`:

docs/source/user_guide/command_line.rst

@@ -118,6 +118,33 @@ This will run a singlepoint energy calculation on ``KCl.cif`` using the `MACE-MP
 Example configurations for all commands can be found in `janus-tutorials <https://github.com/stfc/janus-tutorials/tree/main/configs>`_
 
 
+Output files
+------------
+
+By default, calculations performed will modify the underlying `ase.Atoms <https://wiki.fysik.dtu.dk/ase/ase/atoms.html>`_ object
+to store information in the ``Atoms.info`` and ``Atoms.arrays`` dictionaries about the MLIP used.
+
+Additional dictionary keys include ``arch``, corresponding to the MLIP architecture used,
+and ``model_path``, 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``.
+
+This information is then saved when extxyz files are written. For example:
+
+.. code-block:: bash
+
+    janus singlepoint --struct tests/data/NaCl.cif --arch mace_mp --model-path /path/to/mace/model
+
+
+Generates an output file, ``NaCl-results.extxyz``, with ``arch``, ``model_path``, ``mace_mp_energy``, ``mace_mp_forces``, and ``mace_mp_stress``.
+
+.. 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,
+    unless the same ``arch`` is chosen, in which case these values will also be overwritten.
+
+
 Single point calculations
 -------------------------
 

docs/source/user_guide/python.rst

@@ -9,3 +9,51 @@ Jupyter Notebook tutorials illustrating the use of currently available calculati
 - `Molecular Dynamics <https://colab.research.google.com/github/stfc/janus-tutorials/blob/main/md.ipynb>`_
 - `Equation of State <https://colab.research.google.com/github/stfc/janus-tutorials/blob/main/eos.ipynb>`_
 - `Phonons <https://colab.research.google.com/github/stfc/janus-tutorials/blob/main/phonons.ipynb>`_
+
+
+Calculation outputs
+===================
+
+By default, calculations performed will modify the underlying `ase.Atoms <https://wiki.fysik.dtu.dk/ase/ase/atoms.html>`_ object
+to store information in the ``Atoms.info`` and ``Atoms.arrays`` dictionaries about the MLIP used.
+
+Additional dictionary keys include ``arch``, corresponding to the MLIP architecture used,
+and ``model_path``, 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``.
+
+For example:
+
+.. code-block:: python
+
+    from janus_core.calculations.single_point import SinglePoint
+
+    single_point = SinglePoint(
+        struct_path="tests/data/NaCl.cif",
+        arch="mace_mp",
+        model_path="tests/models/mace_mp_small.model",
+    )
+
+    single_point.run()
+    print(single_point.struct.info)
+
+will return
+
+.. code-block:: python
+
+    {
+        'spacegroup': Spacegroup(1, setting=1),
+        'unit_cell': 'conventional',
+        'occupancy': {'0': {'Na': 1.0}, '1': {'Cl': 1.0}, '2': {'Na': 1.0}, '3': {'Cl': 1.0}, '4': {'Na': 1.0}, '5': {'Cl': 1.0}, '6': {'Na': 1.0}, '7': {'Cl': 1.0}},
+        'model_path': 'tests/models/mace_mp_small.model',
+        'arch': 'mace_mp',
+        'mace_mp_energy': -27.035127799332745,
+        'mace_mp_stress': array([-4.78327600e-03, -4.78327600e-03, -4.78327600e-03,  1.08000967e-19, -2.74004242e-19, -2.04504710e-19]),
+        'system_name': 'NaCl',
+    }
+
+.. 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,
+    unless the same ``arch`` is chosen, in which case these values will also be overwritten.