diff --git a/README.md b/README.md index c48dd9f5..824da288 100644 --- a/README.md +++ b/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 diff --git a/docs/source/developer_guide/get_started.rst b/docs/source/developer_guide/get_started.rst index bd7d7b79..9e5425df 100644 --- a/docs/source/developer_guide/get_started.rst +++ b/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``:: diff --git a/docs/source/user_guide/python.rst b/docs/source/user_guide/python.rst index 3bf3b545..1c3b7545 100644 --- a/docs/source/user_guide/python.rst +++ b/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