diff --git a/README.md b/README.md index f549cd03..b0a79490 100644 --- a/README.md +++ b/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`: diff --git a/docs/source/user_guide/command_line.rst b/docs/source/user_guide/command_line.rst index 03ee0e50..4a995821 100644 --- a/docs/source/user_guide/command_line.rst +++ b/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 `_ +Output files +------------ + +By default, calculations performed will modify the underlying `ase.Atoms `_ 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 ------------------------- diff --git a/docs/source/user_guide/python.rst b/docs/source/user_guide/python.rst index eac7760c..7e965737 100644 --- a/docs/source/user_guide/python.rst +++ b/docs/source/user_guide/python.rst @@ -9,3 +9,51 @@ Jupyter Notebook tutorials illustrating the use of currently available calculati - `Molecular Dynamics `_ - `Equation of State `_ - `Phonons `_ + + +Calculation outputs +=================== + +By default, calculations performed will modify the underlying `ase.Atoms `_ 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.