Update documentation (#223)

Author: ElliottKasoar

README.md

@@ -122,7 +122,7 @@ See the [developer guide](https://stfc.github.io/aiida-mlip/developer_guide/inde
 Contributors to this project were funded by
 
 [![PSDI](https://raw.githubusercontent.com/stfc/aiida-mlip/main/docs/source/images/psdi-100.webp)](https://www.psdi.ac.uk/)
-[![ALC](https://raw.githubusercontent.com/stfc/aiida-mlip/main/docs/source/images/alc-100.webp)](https://adalovelacecentre.ac.uk/)
+[<img src="docs/source/images/alc.svg" width="200" height="100" />](https://adalovelacecentre.ac.uk/)
 [![CoSeC](https://raw.githubusercontent.com/stfc/aiida-mlip/main/docs/source/images/cosec-100.webp)](https://www.scd.stfc.ac.uk/Pages/CoSeC.aspx)
 
 

docs/source/conf.py

@@ -53,7 +53,7 @@
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
     "aiida": ("https://aiida.readthedocs.io/projects/aiida-core/en/latest", None),
-    "ase": ("https://wiki.fysik.dtu.dk/ase/", None),
+    "ase": ("https://ase-lib.org", None),
 }
 
 # Add any paths that contain templates here, relative to this directory.
@@ -200,6 +200,7 @@
     ("py:class", "Logger"),
     ("py:class", "QbFields"),
     ("py:class", "aiida_workgraph.workgraph.WorkGraph"),
+    ("py:class", "AiidaLoggerType"),
 ]
 
 

docs/source/images/alc-100.webp

@@ -1,11 +1,11 @@
 The aiida-mlip plugin for `AiiDA`_
-=====================================================
+==================================
 
-``aiida-mlip`` is available at http://github.com/aiidateam/aiida-mlip
+``aiida-mlip`` is available at http://github.com/stfc/aiida-mlip
 
 .. image::  images/aiida-mlip.png
    :height: 298px
-   :target: http://github.com/aiidateam/aiida-mlip
+   :target: http://github.com/stfc/aiida-mlip
 
 
 .. toctree::
@@ -16,10 +16,6 @@ The aiida-mlip plugin for `AiiDA`_
    API documentation <apidoc/aiida_mlip>
    AiiDA Documentation <https://aiida.readthedocs.io>
 
-If you use this plugin for your research, please cite the following work:
-
-.. highlights:: Author Name1, Author Name2, *Paper title*, Jornal Name XXX, YYYY (Year).
-
 If you use AiiDA for your research, please cite the following work:
 
 .. highlights:: Giovanni Pizzi, Andrea Cepellotti, Riccardo Sabatini, Nicola Marzari,
@@ -38,7 +34,7 @@ Contributors to ``aiida-mlip`` were supported by
    :height: 100px
    :target: https://www.psdi.ac.uk/
 
-.. image:: images/alc-100.webp
+.. image:: images/alc.svg
    :height: 100px
    :target: https://adalovelacecentre.ac.uk/
 

docs/source/images/alc.svg

@@ -1,27 +1,27 @@
-==============================
+============
 Calculations
-==============================
+============
 
-In these examples, we will assume that the `janus-core <https://github.com/stfc/janus-core>`_ package is installed and saved in the AiiDA database as an `InstalledCode` instance named 'janus@localhost'.
+In these examples, we will assume that the `janus-core <https://github.com/stfc/janus-core>`_ package is installed and saved in the AiiDA database as an ``InstalledCode`` instance named 'janus@localhost'.
 
-The structure should be a path to a file. Here, the structure file is specified as `path/to/structure`.
+The structure should be a path to a file. Here, the structure file is specified as ``path/to/structure``.
 
 .. note::
-   Any format that `ASE <https://wiki.fysik.dtu.dk/ase/>`_ can read is a valid structure file for a calculation.
+   Any format that `ASE <https://ase-lib.org>`_ can read is a valid structure file for a calculation.
 
-The model file determines the specific MLIP to be used. It can be a local file or a URI to a file to download. In these examples, it is assumed to be a local file located at `path/to/model`.
+The model file determines the specific MLIP to be used. It can be a local file or a URI to a file to download. In these examples, it is assumed to be a local file located at ``path/to/model``.
 
 
 SinglePoint Calculation
 -----------------------
 
-A `Singlepoint` Calculation represents a `Calcjob` object within the AiiDA framework.
+A ``Singlepoint`` Calculation represents a ``Calcjob`` object within the AiiDA framework.
 
 
 Usage
 ^^^^^
 
-This calculation can be executed using either the `run` or `submit` AiiDA commands.
+This calculation can be executed using either the ``run`` or ``submit`` AiiDA commands.
 Below is a usage example with the minimum required parameters. These parameters must be AiiDA data types.
 
 
@@ -86,7 +86,7 @@ And it is used as shown below. Note that some parameters, which are specific to
     )
 
 If a parameter is defined twice, in the config file and manually, the manually defined one will overwrite the config one.
-If for example the same config file as before is used, but this time the parameter "struct" is added to the launch function, the code would look like this:
+If for example the same config file as before is used, but this time the parameter ``struct`` is added to the launch function, the code would look like this:
 
 .. code-block:: python
 
@@ -99,11 +99,11 @@ If for example the same config file as before is used, but this time the paramet
         config=config,
     )
 
-In this case  the structure used is going to be "path/to/structure2.xyz" rather than ""path/to/structure.cif", which was defined in the config file.
+In this case  the structure used is going to be ``path/to/structure2.xyz`` rather than ``path/to/structure.cif``, which was defined in the config file.
 
 Refer to the API documentation for additional parameters that can be passed.
-Some parameters are not required and don't have a default value set in aiida-mlip. In that case the default values will be the same as `janus <https://stfc.github.io/janus-core/>`_
-The only default parameters defined in aiida-mlip are the names of the input and output files, as they do not affect the results of the calculation itself, and are needed in AiiDA to parse the results.
+Some parameters are not required and don't have a default value set in ``aiida-mlip``. In that case the default values will be the same as `janus-core <https://github.com/stfc/janus-core>`_
+The only default parameters defined in ``aiida-mlip`` are the names of the input and output files, as they do not affect the results of the calculation itself, and are needed in AiiDA to parse the results.
 
 
 Submission
@@ -112,29 +112,29 @@ Submission
 To facilitate the submission process and prepare inputs as AiiDA data types, example scripts are provided.
 The submit_singlepoint.py script can be used as is, submitted to verdi, and the parameters passed as strings to the CLI.
 They will be converted to AiiDA data types by the script itself.
-.. note::
 
+.. note::
 
     The example files are set up with default values, ensuring that calculations runs even if no input is provided via the cli.
-    However, the aiida-mlip code itself does require certain parameters, (e.g. the structure on which to perform the calculation).
+    However, the ``aiida-mlip`` code itself does require certain parameters, (e.g. the structure on which to perform the calculation).
 
 
 .. code-block:: python
 
     verdi run submit_singlepoint.py "janus@localhost" --structure "path/to/structure" --model "path/to/model" --device "cpu"
 
-The submit_using_config.py script can be used to facilitate submission using a config file.
+The ``submit_using_config.py`` script can be used to facilitate submission using a config file.
 
 Geometry Optimisation calculation
 ---------------------------------
 
-A `GeomOpt` Calculation represents a `Calcjob` object within the AiiDA framework.
+A ``GeomOpt`` Calculation represents a ``Calcjob`` object within the AiiDA framework.
 
 
 Usage
 ^^^^^
 
-This calculation can be executed using either the `run` or `submit` AiiDA commands.
+This calculation can be executed using either the ``run`` or ``submit`` AiiDA commands.
 Below is a usage example with some additional geometry optimisation parameters. These parameters must be AiiDA data types.
 
 
@@ -165,13 +165,13 @@ They will be converted to AiiDA data types by the script itself.
 Molecular Dynamics calculation
 ------------------------------
 
-An `MD` Calculation represents a `Calcjob` object within the AiiDA framework.
+An ``MD`` Calculation represents a ``Calcjob`` object within the AiiDA framework.
 
 
 Usage
 ^^^^^
 
-This calculation can be executed using either the `run` or `submit` AiiDA commands.
+This calculation can be executed using either the ``run`` or ``submit`` AiiDA commands.
 Below is a usage example with some additional geometry optimisation parameters. These parameters must be AiiDA data types.
 
 

docs/source/index.rst

@@ -4,88 +4,88 @@ Data types
 
 ModelData
 ---------
-Defines a custom data type called `ModelData` in AiiDA, which is a subclass of the `SinglefileData` type. `ModelData` is used to handle model files and provides functionalities for handling local files and downloading files from URIs.
-Additional features compared to `SinglefileData`:
+Defines a custom data type called ``ModelData`` in AiiDA, which is a subclass of the ``SinglefileData`` type. ``ModelData`` is used to handle model files and provides functionalities for handling local files and downloading files from URIs.
+Additional features compared to ``SinglefileData``:
 
 - It can take a relative path as an argument
 
-- It takes the argument "architecture" which is specifically related to the mlip model and it is added to the node attributes.
+- It takes the argument ``architecture`` which is specifically related to the MLIP model and it is added to the node attributes.
 
 - Download functionality:
-    - When provided with a URI, `ModelData` automatically downloads the file.
-    - Saves the downloaded file in a specified folder (default: `./cache/mlips`), creating a subfolder if the architecture, and stores it as an AiiDA data type.
-    - Handles duplicate files: if the file is downloaded twice, duplicates within the same folder are canceled, unless `force_download=True` is stated.
+    - When provided with a URI, ``ModelData`` automatically downloads the file.
+    - Saves the downloaded file in a specified folder (default: ``./cache/mlips``), creating a subfolder if the architecture, and stores it as an AiiDA data type.
+    - Handles duplicate files: if the file is downloaded twice, duplicates within the same folder are canceled, unless ``force_download=True`` is stated.
 
 Usage
 ^^^^^
 
-- To create a `ModelData` object from a local file:
+- To create a ``ModelData`` object from a local file:
 
 .. code-block:: python
 
     model = ModelData.from_local('/path/to/file', filename='model', architecture='mace')
 
-- To download a file and save it as a `ModelData` object:
+- To download a file and save it as a ``ModelData`` object:
 
 .. code-block:: python
 
     model = ModelData.from_uri('http://yoururl.test/model', architecture='mace', filename='model', cache_dir='/home/mlip/', force_download=False)
 
-- The architecture of the model file can be accessed using the `architecture` property:
+- The architecture of the model file can be accessed using the ``architecture`` property:
 
 .. code-block:: python
 
     model_arch = model.architecture
 
-As for a `SinglefileData`, the content of the model file can be accessed using the function `get_content()`
+As for a ``SinglefileData``, the content of the model file can be accessed using the function ``get_content()``
 
 
 JanusConfigfile
 ---------------
 
-The `JanusConfigfile` class is designed to handle config files written for janus-core in YAML format within the AiiDA framework.
-This class inherits from `SinglefileData` in the AiiDA, and extends it to support YAML config files.
+The ``JanusConfigfile`` class is designed to handle config files written for ``janus-core`` in YAML format within the AiiDA framework.
+This class inherits from ``SinglefileData`` in the AiiDA, and extends it to support YAML config files.
 It provides methods for reading, storing, and accessing the content of the config file.
 
 Usage
 ^^^^^
 
-- To create a `JanusConfigfile` object:
+- To create a ``JanusConfigfile`` object:
 
 .. code-block:: python
 
     config_file = JanusConfigfile('/path/to/config.yml')
 
 
-- To read the content of the config file as a dictionary, you can use the `read_yaml()` method:
+- To read the content of the config file as a dictionary, you can use the ``read_yaml()`` method:
 
 .. code-block:: python
 
     config_dict = config_file.read_yaml()
 
 
-- To store the content of the config file in the AiiDA database, you can use the `store_content()` method:
+- To store the content of the config file in the AiiDA database, you can use the ``store_content()`` method:
 
 .. code-block:: python
 
     config_file.store_content(store_all=False, skip=[])
 
-The `store_content()` method accepts the following parameters:
+The ``store_content()`` method accepts the following parameters:
 
-    - `store_all` (bool):
+    - ``store_all`` (bool):
         Determines whether to store all parameters or only specific ones.
-        By default, it's set to `False`.
-        When set to `False`, only the key parameters relevant for the provenance graph are stored: `code`, `structure`, `model`, `architecture`, `opt_cell_fully` (for GeomOpt), and `ensemble` (for MD).
+        By default, it's set to ``False``.
+        When set to ``False``, only the key parameters relevant for the provenance graph are stored: ``code``, ``structure``, ``model``, ``architecture``, ``opt_cell_fully`` (for GeomOpt), and ``ensemble`` (for MD).
         However, all inputs can be accessed in the config file at any time (just the config file will appear in the provenance graph as JanusConfigfile).
-        If `store_all` is set to `True`, all inputs are stored, either as specific data types (e.g. the input 'struct' is recognised as a StructureData type) or as Str.
+        If ``store_all`` is set to ``True``, all inputs are stored, either as specific data types (e.g. the input 'struct' is recognised as a StructureData type) or as Str.
 
-    - `skip` (list):
+    - ``skip`` (list):
         Specifies a list of parameters that should not be stored.
         In the source code of the calcjobs, when the same parameter is provided both as an AiiDA input and within the config file, the parameter from the config file is ignored and not stored.
-        These parameters are added to the `skip` list to ensure they are excluded from storage.
+        These parameters are added to the ``skip`` list to ensure they are excluded from storage.
 
 
-- The filepath of the config file can be accessed using the `filepath` property:
+- The filepath of the config file can be accessed using the ``filepath`` property:
 
 .. code-block:: python
 
@@ -99,7 +99,7 @@ The `store_content()` method accepts the following parameters:
     A more robust solution to this problem is going to be implemented.
 
 
-- The content of the config file can be accessed as a dictionary using the `as_dictionary` property:
+- The content of the config file can be accessed as a dictionary using the ``as_dictionary`` property:
 
 .. code-block:: python
 

docs/source/user_guide/calculations.rst

@@ -41,7 +41,7 @@ Once ``aiida-mlip`` and the desired MLIP calculators are installed, run::
     verdi plugin list aiida.calculations  # should now show your calculation plugins
 
 Then, use ``verdi code setup`` with the ``janus`` input plugin
-to set up an AiiDA code for aiida-mlip. The `aiida docs <https://aiida.readthedocs.io/projects/aiida-core/en/stable/howto/run_codes.html#how-to-create-a-code>`_ go over how to create a code.
+to set up an AiiDA code for ``aiida-mlip``. The `aiida docs <https://aiida.readthedocs.io/projects/aiida-core/en/stable/howto/run_codes.html#how-to-create-a-code>`_ go over how to create a code.
 
 
 

docs/source/user_guide/data.rst

@@ -2,12 +2,12 @@
 Training machine learning models
 ================================
 
-The `Train` class represents a `CalcJob` object within the AiiDA framework, designed for training machine learning models.
+The ``Train`` class represents a ``CalcJob`` object within the AiiDA framework, designed for training machine learning models.
 
 Usage
 ^^^^^
 
-This calculation can be executed using either the `run` or `submit` AiiDA commands.
+This calculation can be executed using either the ``run`` or ``submit`` AiiDA commands.
 Below is a usage example with some additional training parameters. These parameters must be AiiDA data types.
 
 .. code-block:: python
@@ -76,7 +76,7 @@ while the other parameters are optional. Here is an example (can be found in the
     keep_isolated_atoms: True
     save_cpu: True
 
-It is also possible to fine-tune models using the same type of `Calcjob`.
+It is also possible to fine-tune models using the same type of ``Calcjob``.
 In that case some additional parameters must be used: foundation_model and fine_tune.
 
 
@@ -93,8 +93,8 @@ In that case some additional parameters must be used: foundation_model and fine_
     TrainCalculation = CalculationFactory("mlip.train")
     submit(TrainCalculation,inputs)
 
-A model to fine-tune has to be provided as an input, either as a `ModelData` type (in which case it has to be a model file), or in the config file at the keyword `foundation_model`.
-If the keyword `fine_tune` is True but no model is given either way, it will return an error.
+A model to fine-tune has to be provided as an input, either as a ``ModelData`` type (in which case it has to be a model file), or in the config file at the keyword ``foundation_model``.
+If the keyword ``fine_tune`` is True but no model is given either way, it will return an error.
 
 .. note::
 
@@ -107,7 +107,7 @@ Submission
 ^^^^^^^^^^
 
 To facilitate the submission process and prepare inputs as AiiDA data types, an example script is provided.
-This script can be used as is or by changing, in the file, the path to the config file, then submitted to `verdi` as shown
+This script can be used as is or by changing, in the file, the path to the config file, then submitted to ``verdi`` as shown
 
 .. code-block:: python