Add docs, examples and refactor scripts examples

Author: bastonero

README.md

@@ -24,6 +24,28 @@ or when installing from source:
     git clone https://github.com/bastonero/aiida-vibrosopy
     pip install .
 
+## Command line interface tool
+The plugin comes with a builtin CLI tool: `aiida-vibroscopy`.
+For example, the following command should print:
+
+```console
+> aiida-vibroscopy launch --help
+Usage: aiida-vibroscopy launch [OPTIONS] COMMAND [ARGS]...
+
+  Launch workflows.
+
+Options:
+  -v, --verbosity [notset|debug|info|report|warning|error|critical]
+                                  Set the verbosity of the output.
+  -h, --help                      Show this message and exit.
+
+Commands:
+  dielectric      Run an `DielectricWorkChain`.
+  harmonic        Run a `HarmonicWorkChain`.
+  iraman-spectra  Run an `IRamanSpectraWorkChain`.
+  phonon          Run an `PhononWorkChain`.
+```
+
 ## How to cite
 
 If you use this plugin for your research, please cite the following works:

docs/source/commands.md

@@ -0,0 +1,9 @@
+(commands)=
+
+# Commands (CLI)
+
+```{eval-rst}
+.. click:: aiida_vibroscopy.cli:cmd_root
+   :prog: aiida-vibroscopy
+   :show-nested:
+```

docs/source/conf.py

@@ -49,6 +49,7 @@
     'sphinx.ext.intersphinx',
     'sphinx.ext.viewcode',
     'sphinx_copybutton',
+    'sphinx_click.ext',
     'sphinx_togglebutton',
     'sphinx_design',
     'aiida.sphinxext',

docs/source/index.md

@@ -14,6 +14,7 @@ myst:
 
 installation/index
 tutorials/index
+commands
 ```
 
 ```{toctree}
@@ -38,7 +39,7 @@ topics/conventions
 :hidden: true
 :caption: Reference
 
-reference/index
+reference/api/index
 ```
 
 # AiiDA Vibroscopy

docs/source/reference/index.md docs/source/reference/api/index.mddocs/source/reference/index.md renamed to docs/source/reference/api/index.md

@@ -1,4 +1,4 @@
-(reference)=
+(reference-api)=
 
 # Python API
 
@@ -7,5 +7,5 @@ If you only want to get to know the input nested structure of the workflows, ple
 ```{toctree}
 :maxdepth: 4
 
-api/aiida_vibroscopy/index
+aiida_vibroscopy/index
 ```

examples/workflows/README.md examples/README.mdexamples/workflows/README.md renamed to examples/README.md

@@ -0,0 +1,77 @@
+# General information
+
+You need to install first a pseudpotential library via `aiida-pseudo` (see examples/README.md).
+
+You can run workflows using the command `aiida-vibroscopy launch WORKFLOW_NAME`.
+
+To know the available implemented workflows that can be used via CLI:
+
+```console
+> aiida-vibroscopy launch --help
+Usage: aiida-vibroscopy launch [OPTIONS] COMMAND [ARGS]...
+
+  Launch workflows.
+
+Options:
+  -v, --verbosity [notset|debug|info|report|warning|error|critical]
+                                  Set the verbosity of the output.
+  -h, --help                      Show this message and exit.
+
+Commands:
+  dielectric      Run an `DielectricWorkChain`.
+  harmonic        Run a `HarmonicWorkChain`.
+  iraman-spectra  Run an `IRamanSpectraWorkChain`.
+  phonon          Run an `PhononWorkChain`.
+```
+
+For furhter information, for instance:
+
+```console
+> aiida-vibroscopy launch dielectric --help
+Usage: aiida-vibroscopy launch dielectric [OPTIONS]
+
+  Run an `DielectricWorkChain`.
+
+  It computes dielectric, Born charges, Raman and non-linear optical
+  susceptibility tensors for a given structure.
+
+Options:
+  --pw CODE                       The code to use for the pw.x executable.
+                                  [required]
+  -S, --structure DATA            A StructureData node identified by its ID or
+                                  UUID.
+  -p, --protocol [fast|moderate|precise]
+                                  Select the protocol that defines the
+                                  accuracy of the calculation.  [default:
+                                  moderate]
+  -F, --pseudo-family GROUP       Select a pseudopotential family, identified
+                                  by its label.
+  -k, --kpoints-mesh <INTEGER INTEGER INTEGER FLOAT FLOAT FLOAT>...
+                                  The number of points in the kpoint mesh
+                                  along each basis vector and the offset.
+                                  Example: `-k 2 2 2 0 0 0`. Specify `0.5 0.5
+                                  0.5` for the offset if you want to result in
+                                  the equivalent Quantum ESPRESSO pw.x `1 1 1`
+                                  shift.
+  -o, --overrides FILENAME        The filename or filepath containing the
+                                  overrides, in YAML format.
+  -D, --daemon                    Submit the process to the daemon instead of
+                                  running it and waiting for it to finish.
+                                  [default: True]
+  -v, --verbosity [notset|debug|info|report|warning|error|critical]
+                                  Set the verbosity of the output.
+  -h, --help                      Show this message and exit.
+```
+
+## Example
+
+```console
+> aiida-vibroscopy launch dielectric \
+    --pw pw@localhost \ # change here with your installed code
+    -S 12345 \ # replace with you StructureData
+    --protocol moderate \ # (optional) choose between fast, moderate, precise
+    --pseudo-family SSSP/1.3/PBEsol/efficiency \ # (optional) change with your favorite
+    --kpoints-mesh 4 4 4 \ # (optional) it overrides the overrides, in particular removes kpoints_distance and kpoints_parallel_distance
+    --overrides overrides.yaml \ # (optional) filepath to overrides
+    --deamon True # (optional) submit to deamon
+```

examples/commands/README.md

@@ -0,0 +1,32 @@
+clean_workdir: false
+kpoints_parallel_distance: 0.2 # kpoints distance in Angstrom^-1 to sample the BZ parallel to the electric field. If used, it should help in converging faster the final results
+property: raman
+# central_difference: # if you know what you are doing, custom numerical derivatives with respect to electric field
+#   accuracy: 2
+#   electric_field_step: 0.0005
+scf:
+  kpoints_distance: 0.4 # kpoints distance in Angstrom^-1 to sample the BZ
+  kpoints_force_parity: false
+  max_iterations: 5
+  pw:
+    settings:
+      cmdline: ['-nd','1']
+    metadata:
+      options:
+        max_wallclock_seconds: 43200
+        resources:
+          num_machines: 1
+          num_mpiprocs_per_machine: 1
+        # queue_name: partition_name # for SLURM
+        # account: account_name # for SLURM, also for project etc
+        withmpi: true
+    parameters:
+      ELECTRONS:
+        conv_thr: 2.0e-12
+        electron_maxstep: 80
+        mixing_beta: 0.4
+      SYSTEM:
+        ecutrho: 240.0
+        ecutwfc: 30.0
+settings:
+  sleep_submission_time: 1.0