From 2d3cf681c2f71e59b3894449210461e94c3e199b Mon Sep 17 00:00:00 2001 From: Sebastiaan Huber Date: Tue, 17 May 2022 12:40:01 +0200 Subject: [PATCH] Docs: add documentation on new `InstalledCode` and `PortableCode` It also provides some historical context as to why it replaces the old `Code` and when that will be removed. --- docs/source/topics/data_types.rst | 151 +++++++++++++++++++++++------- 1 file changed, 119 insertions(+), 32 deletions(-) diff --git a/docs/source/topics/data_types.rst b/docs/source/topics/data_types.rst index 2beb07147d..860db0dcad 100644 --- a/docs/source/topics/data_types.rst +++ b/docs/source/topics/data_types.rst @@ -40,35 +40,43 @@ Below is a list of the core data types already provided with AiiDA, along with t .. table:: :widths: 20 20 45 45 - +-----------------------------------------------------------+------------------------+---------------------------------------------------+-----------------------------------+ - | **Class** | **Entry point** | **Stored in database** | **Stored in repository** | - +===========================================================+========================+===================================================+===================================+ - | :ref:`Int ` | ``core.int`` | The integer value | \\- | - +-----------------------------------------------------------+------------------------+---------------------------------------------------+-----------------------------------+ - | :ref:`Float ` | ``core.float`` | The float value | \\- | - +-----------------------------------------------------------+------------------------+---------------------------------------------------+-----------------------------------+ - | :ref:`Str ` | ``core.str`` | The string | \\- | - +-----------------------------------------------------------+------------------------+---------------------------------------------------+-----------------------------------+ - | :ref:`Bool ` | ``core.bool`` | The boolean value | \\- | - +-----------------------------------------------------------+------------------------+---------------------------------------------------+-----------------------------------+ - | :ref:`List ` | ``core.list`` | The complete list | \\- | - +-----------------------------------------------------------+------------------------+---------------------------------------------------+-----------------------------------+ - | :ref:`Dict ` | ``core.dict`` | The complete dictionary | \\- | - +-----------------------------------------------------------+------------------------+---------------------------------------------------+-----------------------------------+ - | :ref:`EnumData ` | ``core.enum`` | The value, name and the class identifier | \\- | - +-----------------------------------------------------------+------------------------+---------------------------------------------------+-----------------------------------+ - | :ref:`JsonableData ` | ``core.jsonable`` | The JSON data and the class identifier | \\- | - +-----------------------------------------------------------+------------------------+---------------------------------------------------+-----------------------------------+ - | :ref:`ArrayData ` | ``core.array`` | The array names and corresponding shapes | The array data in ``.npy`` format | - +-----------------------------------------------------------+------------------------+---------------------------------------------------+-----------------------------------+ - | :ref:`XyData ` | ``core.array.xy`` | The array names and corresponding shapes | The array data in ``.npy`` format | - +-----------------------------------------------------------+------------------------+---------------------------------------------------+-----------------------------------+ - | :ref:`SinglefileData ` | ``core.singlefile`` | The filename | The file | - +-----------------------------------------------------------+------------------------+---------------------------------------------------+-----------------------------------+ - | :ref:`FolderData ` | ``core.folder`` | \\- | All files and folders | - +-----------------------------------------------------------+------------------------+---------------------------------------------------+-----------------------------------+ - | :ref:`RemoteData ` | ``core.remote`` | The computer and the absolute path to the folder | All files and folders | - +-----------------------------------------------------------+------------------------+---------------------------------------------------+-----------------------------------+ + +--------------------------------------------------------------+------------------------+---------------------------------------------------+-----------------------------------+ + | **Class** | **Entry point** | **Stored in database** | **Stored in repository** | + +==============================================================+========================+===================================================+===================================+ + | :ref:`Int ` | ``core.int`` | The integer value | ``-`` | + +--------------------------------------------------------------+------------------------+---------------------------------------------------+-----------------------------------+ + | :ref:`Float ` | ``core.float`` | The float value | ``-`` | + +--------------------------------------------------------------+------------------------+---------------------------------------------------+-----------------------------------+ + | :ref:`Str ` | ``core.str`` | The string | ``-`` | + +--------------------------------------------------------------+------------------------+---------------------------------------------------+-----------------------------------+ + | :ref:`Bool ` | ``core.bool`` | The boolean value | ``-`` | + +--------------------------------------------------------------+------------------------+---------------------------------------------------+-----------------------------------+ + | :ref:`List ` | ``core.list`` | The complete list | ``-`` | + +--------------------------------------------------------------+------------------------+---------------------------------------------------+-----------------------------------+ + | :ref:`Dict ` | ``core.dict`` | The complete dictionary | ``-`` | + +--------------------------------------------------------------+------------------------+---------------------------------------------------+-----------------------------------+ + | :ref:`EnumData ` | ``core.enum`` | The value, name and the class identifier | ``-`` | + +--------------------------------------------------------------+------------------------+---------------------------------------------------+-----------------------------------+ + | :ref:`JsonableData ` | ``core.jsonable`` | The JSON data and the class identifier | ``-`` | + +--------------------------------------------------------------+------------------------+---------------------------------------------------+-----------------------------------+ + | :ref:`ArrayData ` | ``core.array`` | The array names and corresponding shapes | The array data in ``.npy`` format | + +--------------------------------------------------------------+------------------------+---------------------------------------------------+-----------------------------------+ + | :ref:`XyData ` | ``core.array.xy`` | The array names and corresponding shapes | The array data in ``.npy`` format | + +--------------------------------------------------------------+------------------------+---------------------------------------------------+-----------------------------------+ + | :ref:`SinglefileData ` | ``core.singlefile`` | The filename | The file | + +--------------------------------------------------------------+------------------------+---------------------------------------------------+-----------------------------------+ + | :ref:`FolderData ` | ``core.folder`` | ``-`` | All files and folders | + +--------------------------------------------------------------+------------------------+---------------------------------------------------+-----------------------------------+ + | :ref:`RemoteData ` | ``core.remote`` | The computer and the absolute path to the folder | All files and folders | + +--------------------------------------------------------------+------------------------+---------------------------------------------------+-----------------------------------+ + | :ref:`AbstractCode ` | ``-`` | Default plugin, append/prepend text | ``-`` | + +--------------------------------------------------------------+------------------------+---------------------------------------------------+-----------------------------------+ + | :ref:`Code ` | ``core.code`` | The computer and the executable path | All files and folders | + +--------------------------------------------------------------+------------------------+---------------------------------------------------+-----------------------------------+ + | :ref:`InstalledCode ` | ``core.code.installed``| The computer and the executable path | ``-`` | + +--------------------------------------------------------------+------------------------+---------------------------------------------------+-----------------------------------+ + | :ref:`PortableCode ` | ``core.code.portable`` | The relative path of the executable | All files and folders of the code | + +--------------------------------------------------------------+------------------------+---------------------------------------------------+-----------------------------------+ .. _topics:data_types:core:base: @@ -400,11 +408,90 @@ To see the contents of a subdirectory, pass the relative path to the :py:meth:`~ Using the :py:meth:`~aiida.orm.RemoteData.listdir()` method, or any method that retrieves information from the remote computer, opens a connection to the remote computer using its transport type. Their use is strongly discouraged when writing scripts and/or workflows. -.. todo:: - .. _topics:data_types:core:code: +.. _topics:data_types:core:code: + +AbstractCode +------------ + +.. versionadded:: 2.1 + +The :class:`aiida.orm.nodes.data.code.abstract.AbstractCode` class provides the abstract class for objects that represent a "code" that can be executed through a :class:`aiida.engine.processes.calcjobs.calcjob.CalcJob` plugin. +There are currently three implementations of this abstract class: + + * :class:`~aiida.orm.nodes.data.code.legacy.Code` (see :ref:`Code `) + * :class:`~aiida.orm.nodes.data.code.installed.InstalledCode` (see :ref:`InstalledCode `) + * :class:`~aiida.orm.nodes.data.code.portable.PortableCode` (see :ref:`PortableCode `) + + +.. _topics:data_types:core:code:legacy: + +Code +---- + +.. deprecated:: 2.1 + +Historically, there was only one code implementation, the :class:`~aiida.orm.nodes.data.code.legacy.Code`, which implemented two different types of code: + + * An executable pre-installed on a computer, represented by a :class:`~aiida.orm.computers.Computer`. + * A directory containing all code files including an executable which would be uploaded to + +These two types were referred to as "remote" and "local" codes. +However, this nomenclature would lead to confusion as a "remote" code could also refer to an executable on the localhost, i.e., the machine where AiiDA itself runs. +In addition, having two different concepts implemented by a single class led to a unintuitive interface. +Therefore, the ``Code`` class was deprecated in ``aiida-core==2.1`` and replaced by the :ref:`InstallCode ` and :ref:`InstallCode `, respectively. +The ``Code`` class is now deprecated and will be removed in ``aiida-core==3.0``. + + +.. _topics:data_types:core:code:installed: + +InstalledCode +------------- + +.. versionadded:: 2.1 + +The :class:`~aiida.orm.nodes.data.code.installed.InstalledCode` class is an implementation of the :class:`~aiida.orm.nodes.data.code.abstract.AbstractCode` class that represents an executable code on a remote computer. +This plugin should be used if an executable is pre-installed on a computer. +The ``InstalledCode`` represents the code by storing the absolute filepath of the relevant executable and the computer on which it is installed. +The computer is represented by an instance of :class:`~aiida.orm.computers.Computer`. +Each time a :class:`~aiida.engine.CalcJob` is run using an ``InstalledCode``, it will run its executable on the associated computer. +Example of creating an ``InstalledCode``: + +.. code:: python + + from aiida.orm import InstalledCode + code = InstalledCode( + label='some-label', + computer=load_computer('localhost'), + filepath_executable='/usr/bin/bash' + ) + + +.. _topics:data_types:core:code:portable: + +PortableCode +------------ + +.. versionadded:: 2.1 + +The :class:`~aiida.orm.nodes.data.code.portable.PortableCode` class is an implementation of the :class:`~aiida.orm.nodes.data.code.abstract.AbstractCode` class that represents an executable code stored in AiiDA's storage. +This plugin should be used for executables that are not already installed on the target computer, but instead are available on the machine where AiiDA is running. +The plugin assumes that the code is self-contained by a single directory containing all the necessary files, including a main executable. +When constructing a ``PortableCode``, passing the absolute filepath as ``filepath_files`` will make sure that all the files contained within are uploaded to AiiDA's storage. +The ``filepath_executable`` should indicate the filename of the executable within that directory. +Each time a :class:`~aiida.engine.CalcJob` is run using a ``PortableCode``, the uploaded files will be automatically copied to the working directory on the selected computer and the executable will be run there. +Example of creating an ``PortableCode``: + +.. code:: python + + from pathlib import Path + from aiida.orm import PortableCode + code = PortableCode( + label='some-label', + filepath_files=Path('/some/path/code'), + filepath_executable='executable.exe' + ) - title: Code .. _topics:data_types:materials: