diff --git a/docs/source/developer_guide/devel_tutorial/code_plugin_float_sum.rst b/docs/source/developer_guide/devel_tutorial/code_plugin_float_sum.rst index f11d48a11..1110836ce 100644 --- a/docs/source/developer_guide/devel_tutorial/code_plugin_float_sum.rst +++ b/docs/source/developer_guide/devel_tutorial/code_plugin_float_sum.rst @@ -58,22 +58,56 @@ implementation can look like this:: """ self._set_attr('number', float(value)) - +The definition of this new data type should reside below a ``data`` sub package in your +plugin package, with directory structure like:: + + + aiida-yourplugin/ + aiida_yourplugin/ + __init__.py + calcs/ + __init__.py + sum.py + parsers/ + __init__.py + sum_parser.py + data/ + __init__.py + float.py <-- Put the code here + setup.py + setup.json + + +And following lines should be there in the ``setup.json`` file:: + + { + ... + "entry_points": { + "aiida.data": { + "yourplugin.float = aiida_yourplugin.data.float:FloatData" + }, + ... + } + ... + } + +.. seealso:: + Please see the documentation about the :ref:`entry points` to learn more about the plugin system. Exercise: Modifying the calculation plugin ------------------------------------------ -Your exercise consists in creating a new code plugin (let's call it for instance -``floatsum``) that will also perform the sum, but accept as input two ``FloatData`` +Your exercise consists in creating a new calculation plugin (let's call it for instance +``SumFloatCalculation``) that will also perform the sum, but accept as input two ``FloatData`` node and return also a ``FloatData`` node containing the sum. Below, you will find some hints on the parts you need to modify with respect to the :doc:`previous tutorial` using instead ``ParameterData`` both as inputs and outputs. -.. note:: remember to create copies of your files with a new name - ``floatsum.py`` instead of ``sum.py``, and to change the class - name accordingly. +.. note:: Remember to add an entry point for the ``SumFloatCalculation`` in the ``setup.json`` file and re-install the package and refresh entry points. + It is up to you to either put the new class in the same ``sum.py`` or create a new ``floatsum.py``. + The same also applies to the new parser class. Changes to the parser ///////////////////// @@ -92,7 +126,7 @@ To be able to run your new ``FloatsumParser``, you will need the corresponding input plugin (``FloatsumCalculation``). The first modification is then to link to the correct parser class:: - self._default_parser = 'floatsum' + self._default_parser = 'sum.floatsum' # Name of the entry point For consistency, we also want that the input plugin accepts two ``FloatData`` instead of a single ``ParameterData``. @@ -133,7 +167,7 @@ Code //// The python code that actually performs the calculation does not need to be modified. We can reuse the same file, but we suggest to setup a new code -in AiiDA, with a different name, using as default plugin the ``floatsum`` +in AiiDA, with a different name, using as default plugin the ``sum.floatsum`` plugin. Submission script diff --git a/docs/source/developer_guide/devel_tutorial/code_plugin_int_sum.rst b/docs/source/developer_guide/devel_tutorial/code_plugin_int_sum.rst index c6179e078..3263bb7ca 100644 --- a/docs/source/developer_guide/devel_tutorial/code_plugin_int_sum.rst +++ b/docs/source/developer_guide/devel_tutorial/code_plugin_int_sum.rst @@ -1,3 +1,5 @@ +.. _DevelopDataPluginTutorialInt: + Calculation plugin - Integer Summation ====================================== @@ -47,7 +49,54 @@ codes and it needs to know: It is also useful, but not necessary, to have a script that prepares the calculation for AiiDA with the necessary parameters and submits it. -Let's start to see how to prepare these components. + +Before we start to see how to prepare these components, let's have a look of an +example directory structure for your plugin project. +Different components should be includeded in a single installable python package. +This is important as it allows the entry points to be registered when the plugin +gets installed, otherwise ``aiida_core`` would not know where to look for these +codes. +Below is an example of the directory structure of our new plugin:: + + aiida-yourplugin/ + aiida_yourplugin/ + __init__.py + calcs/ + __init__.py + sum.py + parsers/ + __init__.py + sum_parser.py + setup.py + setup.json + +The code of the input plugin should be placed inside ``sum.py`` and the parser +for the outputs are located in ``sum_parser.py``. You also have to declear the +entry points in the ``setup.json``:: + + { + ... + "entry_points": { + "aiida.calculations": [ + "yourplugin.sum = aiida_yourplugin.calcs.SumCalculation:" + ], + "aiida.parsers": [ + "yourplugin.sum = aiida_yourplugin.parsers.SumParser" + + ], + ... + } + ... + } + +You need to install your pacakge and refresh the entry points in order to make it avaliable to ``aiida_core``. +The following commands can be used for this:: + + pip install -e . + reentry scan -r aiida + +.. seealso:: + Please see the documentation about the :ref:`entry points` to learn more about the plugin system. Code ---- @@ -81,6 +130,7 @@ as parameter. The resulting file from the script will be handled by AiiDA. The code can be downloaded from :download:`here `. We will now proceed to prepare an AiiDA input plugin for this code. + Input plugin ------------ In abstract term, this plugin must contain the following two pieces of @@ -190,17 +240,19 @@ summation code (a detailed description of the different sections follows):: The above input plugin can be downloaded from (:download:`here `). -In order the plugin to be automatically discoverable by AiiDA, it needs to be -registered using the :ref:`entry point system `. +In order the plugin to be automatically discoverable by AiiDA, a entry point needs to be +registered following the guide described in the :ref:`entry point system ` section. After proper installation, your plugin will be discoverable and loadable -using ``CalculationFactory``. +using:: + + SumCalculation = CalculationsFactory("myplugin.sum") When developing your calculation plugin, you should name the class inside the plugin as -PluginnameCalculation. For example, the class name of the summation input plugin is, -as you see above, ``SumCalculation``. The first letter must be capitalized, -the other letters must be lowercase. Also you, make sure your calculation plugin -inherit the class from ``JobCalculation``. At the end, you will be able -to load your plugin using ``CalculationFactory``. +*PluginnameCalculation*. +For example, the class name of the summation input plugin is, +as you see above, ``SumCalculation``. +The first letter should be capitalized, the other letters should be lowercase. +Also you should make sure your calculation plugin inherit the class from ``JobCalculation``. .. note:: The base ``Calculation`` class should only be used as the abstract @@ -297,6 +349,7 @@ external code, creating a suitable JSON file:: with open(input_filename, 'w') as infile: json.dump(input_json, infile) + The last step: the calcinfo /////////////////////////// @@ -391,7 +444,7 @@ For the time being, just define also the following variables as empty lists -Finally, you need to specify which code executable(s) need to be called +Finally, you need to specify which code executable(s) need to be called and link the code to the ``codeinfo`` object. For each code, you need to create a ``CodeInfo`` object, specify the code UUID, and define the command line parameters that should be passed to the code as a @@ -400,7 +453,7 @@ Moreover, AiiDA takes care of escaping spaces and other symbols). In our case, our code requires the name of the input file, followed by the name of the output file, so we write:: - codeinfo.cmdline_params = [self._DEFAULT_INPUT_FILE,self._DEFAULT_OUTPUT_FILE] + codeinfo.cmdline_params = [self._DEFAULT_INPUT_FILE, self._DEFAULT_OUTPUT_FILE] Finally, we link the just created ``codeinfo`` to the ``calcinfo``, and return it:: @@ -432,8 +485,7 @@ is ready! huge files, you should carefully think at how to design your plugin interface. The same applies for ``calcinfo.retrieve_list``. -As a final step, after copying the file in the location specified above, we -can check if AiiDA recognised the plugin, by running the command +As a final step, we can check if AiiDA recognised the plugin, by running the command ``verdi calculation plugins`` and verifying that our new ``sum`` plugin is now listed. @@ -606,8 +658,9 @@ in the database:: with the ``calc.res`` interface (for instance, later we will be able to get the results using ``print calc.res.sum``. -The above `output plugin` can be downloaded from :download:`here ` -and should be placed at ``aiida/parsers/plugins/sum.py``. +The above `output plugin` can be downloaded from :download:`here `. +You will need to register the `SumParser class to an entry point using the methods described +:ref:`here `. .. note:: Before continuing, it is important to restart the daemon, so that it can recognize the new files added into the aiida code and use the new