Better documentation

TREX-CoE · Feb 27, 2022 · 0308e30 · 0308e30
1 parent 651b067
commit 0308e30
Show file tree

Hide file tree

Showing 4 changed files with 83 additions and 25 deletions.
diff --git a/docs/source/developer_guide/index.rst b/docs/source/developer_guide/index.rst
@@ -5,11 +5,6 @@ Developer guide
 Running the tests
 +++++++++++++++++
 
-The following will discover and run all unit test::
-
-    pip install -e .[testing]
-    pytest -v
-
 Automatic coding style checks
 +++++++++++++++++++++++++++++
 
@@ -33,7 +28,6 @@ Continuous integration
 
 ``aiida_qp2`` comes with a ``.github`` folder that contains continuous integration tests on every commit using `GitHub Actions <https://github.com/features/actions>`_. It will:
 
-#. run all tests for the ``django`` ORM
 #. build the documentation
 #. check coding style and version number (not required to pass by default)
 

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -15,10 +15,6 @@ The aiida-qp2 plugin for `AiiDA`_
    developer_guide/index
    API documentation <apidoc/aiida_qp2>
 
-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,

diff --git a/docs/source/user_guide/get_started.rst b/docs/source/user_guide/get_started.rst
@@ -2,7 +2,7 @@
 Getting started
 ===============
 
-This page should contain a short guide on what the plugin does and
+This page contains a short guide on what the plugin does and
 a short example on how to use the plugin.
 
 Installation
@@ -13,12 +13,12 @@ Use the following commands to install the plugin::
     git clone https://github.com/TREX-CoE/aiida-qp2 .
     cd aiida-qp2
     pip install -e .  # also installs aiida, if missing (but not postgres)
-    #pip install -e .[pre-commit,testing] # install extras for more features
+    #pip install -e .[pre-commit,testing]  # install extras for more features
+    #pre-commit install  # install pre-commit hooks
     verdi quicksetup  # better to set up a new profile
-    verdi calculation plugins  # should now show your calclulation plugins
+    verdi plugin list aiida.calculations  # should now show your calclulation plugins
 
-Then use ``verdi code setup`` with the ``qp2`` input plugin
-to set up an AiiDA code for qp2.
+Then use ``verdi code setup`` to set up an AiiDA code for qp2.
 
 Usage
 +++++
@@ -27,8 +27,8 @@ A quick demo of how to submit a calculation::
 
     verdi daemon start         # make sure the daemon is running
     cd examples
-    verdi run test_submit.py        # submit test calculation
-    verdi calculation list -a  # check status of calculation
+    verdi run example_ezfio_from_gdt.py        # submit an example calculation
+    verdi process list -a  # check status of the calculation
 
 Available calculations
 ++++++++++++++++++++++

diff --git a/docs/source/user_guide/tutorial.rst b/docs/source/user_guide/tutorial.rst
@@ -2,22 +2,90 @@
 Tutorial
 ========
 
-This page can contain a simple tutorial for your code.
+This page contains a simple tutorial for ``aiida-qp2`` plugin.
 
 What we want to achieve
 +++++++++++++++++++++++
 
-Step 1
-------
+Initialize the wave function file
+---------------------------------
 
-Some text
+Create an EZFIO ``SinglefileData`` node from the existing ``StructureData`` instance using ``qp_create_ezfio`` dictionary::
 
-Step 2
-------
 
-Some other text
+        # Load the required AiiDA modules
+        from aiida import orm, engine
+        from aiida.common.exceptions import NotExistent
+
+        # QP-related parameters
+        ezfio_basename = 'hcn.ezfio'
+        create_parameters = {
+            'qp_create_ezfio': {
+                'basis'  : '"6-31g"',      # QP-native basis set
+                'charge' : '0',
+                'output' : ezfio_basename
+            }
+        }
+
+        # AiiDA-related parameters
+
+        # Load the code
+        try:
+            code = orm.load_code('qp@localost')
+        except:
+            raise Exception(f'Create the qp2 code') from NotExistent
+
+        # Build the calculation
+        builder = code.get_builder()
+
+        # Replace <StructureData_name> with the name of your StructureData object
+        structure = load_node(pk=<StructureData_name>.pk)
+        builder.structure = structure
+        builder.parameters = orm.Dict(dict=create_parameters)
+        # EZFIO directory name (to be tar.gz-ed)
+        builder.metadata.options.output_wf_basename = ezfio_basename
+
+        # Run the calculation & parse the results
+        result = engine.run(builder)
+
+        # Print the name of the output wave function (EZFIO) file
+        print('EZFIO SinglefileData name   : ', result['output_wavefunction'].filename)
+
+
+Note: it is possible to create a ``StructureData`` node from the XYZ atomic configuration file. For example, using the ``Molecule`` class of the ``pymatgen`` package::
+
+        from pymatgen.core import Molecule
+        mol = Molecule.from_file('hcn.xyz')
+        structure = orm.StructureData(pymatgen_molecule=mol)
+
+Perform calculations
+--------------------
+
+Use the previously created wave function file to run SCF (or any other type of QP-supported) calculation according to the ``qp_commands`` list::
+
+        # QP-related parameters
+        calc_parameters = {
+            'qp_commands': [
+                f'set_file {ezfio_basename}',
+                'run scf'
+                ]
+        }
+
+        # AiiDA-related parameters
+        builder_scf = code.get_builder()
+
+        builder_scf.parameters = orm.Dict(dict=calc_parameters)
+        builder_scf.wavefunction = result['output_wavefunction']
+        builder_scf.metadata.options.output_wf_basename = ezfio_basename
+
+        # Run the calculation & parse the results
+        result_scf = engine.run(builder_scf)
+
+        # Print the computed SCF energy
+        print('SCF energy (Hartree)        : ', result_scf['output_energy'])
+
 
 The final result
 +++++++++++++++++++++++
 
-Some text
+You have created a wave function file using parameters provided in ``qp_create_ezfio`` dict. You have then computed the SCF energy with Quantum Package via the ``aiida-qp2`` plugin using the ``qp_commands`` list. All input and output nodes have been stored in the data provenance and can be queried for.