Merge ed27aac into 534fda5

README.md

@@ -3,100 +3,36 @@
 [![PyPI version](https://badge.fury.io/py/aiida-cp2k.svg)](https://badge.fury.io/py/aiida-cp2k)
 
 # AiiDA CP2K
-**The CP2K plugin for the AiiDA workflow and provenance engine.**
+AiiDA plugin for [CP2K](https://www.cp2k.org/).
 
 
-![logo](./aiida-cp2k_logo.png)
-
-# Installation
+## Installation
 
 If you use `pip`, you can install it as: 
 ```
 pip install aiida-cp2k
 ```
 
-
-# Features
-Following the philosophy to _''enable without getting in the way''_, this plugin provides access to all of CP2K's capabilities through a small set of well-tested features:
-
-- A full [CP2K input](https://manual.cp2k.org) has to be provided as a nested Python dictionary ([example](./test/test_dft.py)):
+To install the plugin in an editable mode, run:
 ```
-params = {'FORCE_EVAL': {'METHOD': 'Quickstep', 'DFT': { ... }}}
-calc.use_parameters(ParameterData(dict=params))
+git clone https://github.com/aiidateam/aiida-cp2k
+cd aiida-cp2k
+pip install -e .  # Also installs aiida, if missing (but not postgres/rabbitmq).
 ```
 
-- Section parameters are stored as key `_` in the dictionary:
-```
-xc_section = {'XC_FUNCTIONAL': {'_': 'LDA'}}
-```
+## Links
+[Documentation](https://aiida-cp2k.readthedocs.io/en/latest/) for the examples, features of the plugin.
+[Make an issue](https://github.com/aiidateam/aiida-cp2k/issues/new) for bug reports, questions and suggestions.
+[AiiDA](http://www.aiida.net/) to learn about AiiDA.
+[Cp2k](https://www.cp2k.org/) to learn about CP2K.
 
-- Repeated sections are stored as a list:
-```
-kind_section = [{'_': 'H', 'BASIS_SET': 'DZVP-MOLOPT-GTH', 'POTENTIAL': 'GTH-LDA'},
-                {'_': 'O', 'BASIS_SET': 'DZVP-MOLOPT-GTH', 'POTENTIAL': 'GTH-LDA'}]
-```
 
-- Most data files (basis sets, pseudo potentials, VdW, etc.) are auto-discovered from CP2K's [data directory](https://github.com/cp2k/cp2k/tree/master/cp2k/data).
-```
-dft_section = {'BASIS_SET_FILE_NAME': 'BASIS_MOLOPT', ...}
-```
+## License
+MIT
 
-- Additional data files can be added as AiiDA SinglefileData ([example](test/test_mm.py)):
-```
-water_pot = SinglefileData(file="/tmp/water.pot")
-calc.use_file(water_pot, linkname="water_pot")
-```
 
-- The start geometry can be provided as AiiDA StructureData ([example](./test/test_dft.py)):
-```
-atoms = ase.build.molecule('H2O', vacuum=2.0)
-calc.use_structure(StructureData(ase=atoms))
-```
-
-- Alternatively the start geometry can be contained in the CP2K input ([example](./test/test_no_struct.py)):
-```
-coord_section = {' ': ['H    2.0   2.0   2.737166',
-                       'H    2.0   2.0   2.000000']},
-```
-
-- For restarting a calculation a parent folder can be attached  ([example](./test/test_restart.py)):
-```
-calc2.use_parent_folder(calc1.out.remote_folder)
-```
-
-- By default only the output and restart file (if present) are retrieved. Additional files are retrieved upon request ([example](test/test_mm.py)):
-```
-settings = {'additional_retrieve_list': ["*.cube"]}
-calc.use_settings(ParameterData(dict=settings))
-```
-
-- The final geometry is extracted from the restart file (if present) and stored in AiiDA ([example](./test/test_geopt.py)):
-```
-print(calc.out.output_structure)
-```
-
-- From the CP2K output only the #warnings and final energy are parsed ([example](./test/test_mm.py)):
-```
-print(calc.res.nwarnings, calc.res.energy, calc.res.energy_units)
-```
-
-- The calculation is considered failed if #warnings can not be found ([example](./test/test_failure.py)).
-
-- The conversion of geometries between AiiDA and CP2K has a precision of at least 1e-10 Ångström ([example](./test/test_precision.py)).
-
-- The Python code complies with the [Flake8](http://flake8.pycqa.org) coding conventions.
-
-
-# Testing
-
-Every commit and pull request is automatically tested by [TravisCI](https://travis-ci.org/cp2k/aiida-cp2k/).
-
-To run the tests locally install [Docker](https://docs.docker.com/engine/installation/) and execute the following commands:
-```
-git clone https://github.com/cp2k/aiida-cp2k
-docker build -t aiida_cp2k_test aiida-cp2k
-docker run -it --init aiida_cp2k_test
-```
+## Contact
+yakutovicha@gmail.com
 
 
 ## Acknowledgements

docs/source/examples.rst

@@ -0,0 +1,24 @@
+Examples
+--------
+
+See `examples` folder for complete examples of setting up a calculation or a work chain.
+
+
+Simple calculation
+==================
+
+.. code-block:: bash
+
+    cd examples/single_calculations
+    verdi run example_dft.py <code_label>         # Submit example calculation.
+    verdi process list -a -p1                     # Check status of calculation.
+
+
+Work chain
+==========
+
+.. code-block:: bash
+
+    cd examples/workchains
+    verdi run example_base.py <code_label>       # Submit test calculation.
+    verdi process list -a -p1                     # Check status of the work chain.

docs/source/features.rst

@@ -0,0 +1,73 @@
+Features
+--------
+
+Following the philosophy to ''enable without getting in the way'', this plugin provides access to all of CP2K's capabilities through a small set of well-tested features:
+
+A full `CP2K input <https://manual.cp2k.org>`__ has to be provided as a nested Python dictionary `example <https://github.com/aiidateam/aiida-cp2k/blob/develop/examples/single_calculations/example_dft.py>`__:
+
+.. code-block:: python
+
+    params = {'FORCE_EVAL': {'METHOD': 'Quickstep', 'DFT': { ... }}}
+    builder.parameters = Dict(dict=params)
+
+
+Section parameters are stored as key `_` in the dictionary:
+
+.. code-block:: python
+
+    xc_section = {'XC_FUNCTIONAL': {'_': 'LDA'}}
+
+Repeated sections are stored as a list:
+
+.. code-block:: python
+
+    kind_section = [{'_': 'H', 'BASIS_SET': 'DZVP-MOLOPT-GTH', 'POTENTIAL': 'GTH-LDA'},
+                {'_': 'O', 'BASIS_SET': 'DZVP-MOLOPT-GTH', 'POTENTIAL': 'GTH-LDA'}]
+
+Most data files (basis sets, pseudo potentials, VdW, etc.) are auto-discovered from CP2K's `data directory <https://github.com/cp2k/cp2k/tree/master/data>`__.
+
+.. code-block:: python
+
+    dft_section = {'BASIS_SET_FILE_NAME': 'BASIS_MOLOPT', ...}
+
+
+Additional data files can be added as AiiDA SinglefileData (`example <https://github.com/aiidateam/aiida-cp2k/blob/develop/examples/single_calculations/example_mm.py>`__):
+
+.. code-block:: python
+
+    water_pot = SinglefileData(file=os.path.join("/tmp", "water.pot"))
+    builder.file = {"water_pot": water_pot}
+
+The start geometry can be provided as AiiDA StructureData (`example <https://github.com/aiidateam/aiida-cp2k/blob/develop/examples/single_calculations/example_dft.py>`__):
+
+.. code-block:: python
+
+    structure = StructureData(ase=ase.io.read(os.path.join(thisdir, '..', "files", 'h2o.xyz')))
+
+Alternatively the start geometry can be contained in the CP2K input (`example <https://github.com/aiidateam/aiida-cp2k/blob/develop/examples/single_calculations/example_no_struct.py>`_):
+
+.. code-block:: python
+
+   'COORD': {' ': ['H    2.0   2.0   2.737166', 'H    2.0   2.0   2.000000']}
+
+For restarting a calculation a parent folder can be attached  (`example <https://github.com/aiidateam/aiida-cp2k/blob/develop/examples/single_calculations/example_restart.py>`__):
+
+.. code-block:: python
+
+   builder.parent_calc_folder = calc1['remote_folder']
+
+By default only the output and restart file (if present) are retrieved. Additional files are retrieved upon request (`example <https://github.com/aiidateam/aiida-cp2k/blob/develop/examples/single_calculations/example_mm.py>`__):
+
+.. code-block:: python
+
+   settings = Dict(dict={'additional_retrieve_list': ["runtime.callgraph"]})
+   builder.settings = settings
+
+The final geometry is extracted from the restart file (if present) and stored in AiiDA (`example <https://github.com/aiidateam/aiida-cp2k/blob/develop/examples/single_calculations/example_geopt.py>`__):
+
+.. code-block:: python
+
+    dist = calc['output_structure'].get_ase().get_distance(0, 1)
+
+
+The conversion of geometries between AiiDA and CP2K has a precision of at least 1e-10 Ångström (`example <https://github.com/aiidateam/aiida-cp2k/blob/develop/examples/single_calculations/example_precision.py>`__).

docs/source/index.rst

@@ -11,6 +11,8 @@ The aiida-cp2k plugin for `AiiDA`_
 .. toctree::
    :maxdepth: 1
 
+   features
+   examples
    workflows
 
 

docs/source/workflows.rst

@@ -1,4 +1,4 @@
-workflows
+Workflows
 ---------
 
 .. aiida-workchain:: Cp2kBaseWorkChain