Merge branch 'develop'

CHANGELOG.md

@@ -0,0 +1,57 @@
+## v0.3.0 
+
+### Merge with workflows repo
+- the second repository with basic workflows was merged into the plugin repostitory.
+- Afterwards the repo was renamed from aiida_fleur_plugin to aiida-fleur
+
+### Installation (new aiida plugin system):
+- everything is now pip installable (pip install -e .) (not yet on pypi)
+Therefore the files do not have to be copied anymore into the aiida_core source folder
+(make sure to add the aiida-fleur folder to your PYTHONPATH variable)
+- all modules are now importet from the aiida_fleur folder
+ (example 'from aiida.tools.codespecific.fleur.convergence import fleur_convergence' -> 'from aiida_fleur.workflows.scf import fleur_scf_wc)
+
+### Renaming
+- In the process (and due to the entry points some things have to be renamed)
+  The plugin in aiida (fleur_inp.fleur -> fleur.fleur; fleur_inp.fleurinp -> fleur.fleurinp; fleur_inp.fleurinputgen -> fleur.inpgen)
+
+### Workflows
+- some fine tuning of workflows. Naming scheme was introduced.
+- Some first error catching and controlled shutdown (because of new AiiDA features).
+- added consistent through all workflows the 'serial' key in wf_parameter nodes, which will turn of mpi.
+
+### Dokumentation
+- Due to the new plugin system of AiiDA the Dokumentation is now online on read-the-docs. 
+(so far incomplete because of old AiiDA version on pypi) We still recommend to take a look at the docs in the repo itself (ggf build it)
+
+
+
+## v0.2.0 tutorial version
+
+Version for used at the MAX AiiDA-fleur tutorial in May 2017
+
+### Dokumentation
+- added some basic explainations pages beyond the pure in code docs
+
+
+### Tests
+- added basic tests of Fleur itself and tests for submission
+
+### Ploting
+- There is a plot_methods repo on bitbucket which has methods to visualize common workflow output nodes.
+
+
+
+
+## v0.1 Base commit
+
+### Moved everything von bitbucket to github
+
+### Dokumentation
+-Basic docs available locally
+
+### Installation
+- provided copy_files script to copy the plugin files into AiiDA folder
+
+### Workflows
+- Some basic sketches of basic workflows available (working AiiDa workflow system just released)

README.md

@@ -1,100 +1,192 @@
-FLEUR AiiDA plug-in
-===================
-**Enables the usage of the [FLEUR code](http://www.flapw.de) with the [AiiDA framework](http://www.aiida.net)**  
-Developed at the Forschungszentrum Jülich GmbH  
+# FLEUR with AiiDA
+
+[![MIT license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
+[![GitHub tag](https://img.shields.io/github/tag/broeder-j/aiida-fleur.svg)](https://github.com/broeder-j/)
+[![PyPI version](https://img.shields.io/pypi/v/aiida-fleur.svg)](https://pypi.python.org/pypi/aiida-fleur)
+
+This software contains a plugin that enables the usage of the all-electron DFT [FLEUR code](http://www.flapw.de) with the [AiiDA framework](http://www.aiida.net). Further this package contains common workflows and some utility.
+
+Developed at [Forschungszentrum Jülich GmbH](http://www.fz-juelich.de/pgi/pgi-1/DE/Home/home_node.html)  
+
+
+### Documentation
+
+Hosted at http://aiida-fleur.readthedocs.io/en/develop/index.html.
+For other information checkout the AiiDA docs or http://www.flapw.de.
+
+### License:
 
-License:
---------
 MIT license.
 See license file.
 
 
-Comments/Disclaimer:
---------------------
-The plug-in will only work with a Fleur version using xml files as I/O.  
-For example check out the Fleur version released withing MAX. 
+### Comments/Disclaimer:
+
+The plug-in and the workflows will only work with a Fleur version using xml files as I/O.  
+For example check out the Fleur version released withing MAX.
 
-WARNING: This is a beta version, which runs, but is still under development.  
-For anything contact j.broeder@fz-juelich.de
+**WARNING:** This is a beta version, which runs, but is still under development.  
+For anything contact j.broeder@fz-juelich.de and feel free to write issues and contribute.
 
 
-Contents
---------
+### Contents
+
 1. [Introduction](#Introduction)
 2. [Installation Instructions](#Installation)
 3. [Code Dependencies](#Dependencies)
 4. [Further Information](#FurtherInfo)
 
-Introduction <a name="Introduction"></a>
-========================================
+## Introduction <a name="Introduction"></a>
+
+This is the basic package (plugin plus workflows) to use the FLEUR-code with the AiiDA Framework.
+The FLEUR-code is an all-electron DFT code using the FLAPW method,
+and widely applied in the material science and physics community.  
 
-This is an AiiDA plug-in for the Fleur code.  
+### The plugin :
 
 The Fleur plug-in consists of a datastructure called FleurinpData and two plug-ins,  
 one for the Fleur inputgenerator (inpgen) and one for a Fleur calculation itself.
 
-Every plug-in has an input part and an output parser, see the AiiDA documentation for general info.
+Every plug-in has an input part (defines the calculation) and an output parser, see the AiiDA documentation for general info.
 
-Further there is also some useful utility found under 'aiida_fleur/tools'
 
-Structure_util.py : constains some methods to handle AiiDA structures 
-(some of them might now be methods of the AiiDA structureData, if so use them from there!)
+### Workflows in this package:
 
-merge_parameter.py : methods to handle parameterData nodes, i.e merge them. Which is very useful for all-electron codes, because instead of pseudo potentialsfamilies you can create now families of parameter nodes for the periodic table.
+workflow name | Description
+--------------|------------
+scf | SCF-cycle of Fleur. Converge the charge density and the Total energy with multiple FLEUR runs
+eos | Calculate and Equation of States (Lattice constant) with FLEUR
+dos | Calculate a Density of States (DOS) with FLEUR
+bands | Calculate a Band structure with FLEUR
+relax | Relaxation of a crystal structure with FLEUR
 
-xml_util.py : all xml functions that are used, by parsers and other tools are in here. Some are 'general' some a very specific to Fleur.
+See the AiiDA documentation for general info about the AiiDA workflow system or how to write workflows.
 
-read_cif.py : this can be used as stand-alone to create StructureData nodes from .cif files from an directory tree. 
 
-Installation Instructions <a name="Installation"></a>
-=====================================================
+### Utility/tools:
 
-today:
-The python source files of the plug-in have to be placed in the AiiDA source code in certain places. 
-You might use the copy_plugin_files.sh script to do so.
-
-in the near future:
-pip install aiida_fleur
+filename | Description
+---------|------------
+Structure_util.py | Constains some methods to handle AiiDA structures (some of them might now be methods of the AiiDA structureData, if so use them from there!)
+merge_parameter.py | Methods to handle parameterData nodes, i.e merge them. Which is very useful for all-electron codes, because instead of pseudo potentialsfamilies you can create now families of parameter nodes for the periodic table.
+xml_util.py | All xml functions that are used, by parsers and other tools are in here. Some are 'general' some a very specific to Fleur.
+read_cif.py | This can be used as stand-alone to create StructureData nodes from .cif files from an directory tree. 
 
+## Installation Instructions <a name="Installation"></a>
 
-Files
------
+From the aiida-fleur folder use:
 
-#fleurinpData : aiida.orm.data.fleurinp.fleurinp.py   
-fleurinpData : aiida.orm.data.fleurinp.__init__.py
-fleurinpModifier : aiida.orm.data.fleurinp.fleurinpmodifier.py
+    $ pip install .
+    # or which is very useful to keep track of the changes (developers)
+    $ pip install -e . 
 
-fleurinpgen calculation: aiida.orm.calculation.job.fleur_inp.fleurinputgen.py  
-fleurinpgen output parser: aiida.parsers.plugins.fleur_inp.fleur_inputgen.py  
+To uninstall use:
 
-fleur calculation: aiida.orm.calculation.job.fleur_inp.fleur.py  
-fleur output parser: aiida.parsers.plugins.fleur_inp.fleur.py   
+    $ pip uninstall aiida-fleur
 
-The Fleur code needs a XMLSchema file, place them under, the plugin searches them in your pythonpath, it assumes also that your aiida_core code is in your pythonpath. Checkout search_path in fleurinp.py, in case need ad your path there:  
-aiida.orm.calculation.job.fleur_inp.fleur_schema
+Soon (When package on pypi):
 
-Also some common routines '/aiida_fleur/tools/' used by some classes have to be placed currently under:
-aiida.tools.codespecific.fleur 
+    $ pip install aiida-fleur
 
-Utility:
+Alternative (old):
+The python source files of the plug-in have to be placed in the AiiDA source code in certain places. 
+You might use the copy_plugin_files.sh script to do so.
 
-Structure_util.py
-merge_parameter.py
-read_cif.py
+To test wether the installation was successful use:
+```bash
+$ verdi calculation plugins
+```
+```bash
+   # example output:
+
+   ## Pass as a further parameter one (or more) plugin names
+   ## to get more details on a given plugin.
+   * codtools.cifcellcontents
+   * codtools.cifcodcheck
+   * codtools.cifcodnumbers
+   * codtools.ciffilter
+   * codtools.cifsplitprimitive
+   * quantumespresso.cp
+   * quantumespresso.pw
+   * quantumespresso.pwimmigrant
+   * simpleplugins.templatereplace
+   ...
+   * fleur.fleur
+   * fleur.inpgen
+   * fleur.scf
+   * fleur.eos
+   * fleur.band
+   * fleur.dos
+```
+You should see fleur.* in the list
+
+
+## Files/Contents
+A short sum up of the most important classes and where to find them, how to import them.
+
+___
+### Plugin files:
+
+#### Data:
+fleurinpData : aiida_fleur.data.fleurinp.py  
+fleurinpModifier : aiida_fleur.data.fleurinpmodifier.py  
+
+#### Calculations:
+FleurinputgenCalculation : aiida_fleur.calculation.fleurinputgen.py    
+FleurCalculation : aiida_fleur.calculation.fleur.py   
+
+#### Parsers:
+FleurinpgenParser: aiida_fleur.parsers.fleur_inputgen.py  
+FleurParser: aiida_fleur.parsers.fleur.py   
+
+#### XML Schema Files:
+in fleur_schema folder
+
+The Fleur code needs a XMLSchema file, the plugin searches (walks) for them in your PYTHONPATH.  
+Therefore **make sure that the plugin folder is under your PYTHONPATH env variable.**   
+If nothing works add a path to search_path in fleurinp.py (hack).
+
+___
+### Workflows/workchains:
+
+Class name | file name
+-----------|----------
+fleur_scf_wc | aiida_fleur.workflows.scf.py
+fleur_eos_wc | aiida_fleur.workflows.eos.py
+fleur_dos_wc | aiida_fleur.workflows.dos.py
+fleur_band_wc | aiida_fleur.workflows.band.py
+fleur_relax_wc | aiida_fleur.workflows.relax.py
+
+
+### Utility under '/aiida_fleur/tools/':
+
+Structure_util.py  
+merge_parameter.py  
+read_cif.py  
 ...
 
-
-Code Dependencies <a name="Dependencies"></a>
-=============================================
+___
+## Code Dependencies <a name="Dependencies"></a>
 
 Requirements are listed in 'requirements.txt'.
 
-Further Information <a name="FurtherInfo"></a>
-=============================================
+* aiida_core  
+* lxml  
+* ase  
+
+Mainly AiiDA:
+
+1. Download from [www.aiida.net/?page_id=264](www.aiida.net -> Download)
+2. install and setup -> [http://aiida-core.readthedocs.org/en/stable/](aiida's documentation)
+
+For easy ploting we recommend installing 'plot_methods':
+https://bitbucket.org/broeder-j/plot_methods
+
+## Further Information <a name="FurtherInfo"></a>
 
-The plug-in source code documentation is here (will be on read_the_docs soon).  
+The plug-in source code documentation is [here](http://aiida-fleur.readthedocs.io/en/develop/index.html).  
 also some documentation of the plug-in, further things can be found at www.flapw.de.   
-Two usage examples are shown in 'examples'.
+Usage examples are shown in 'examples'.
 
 
 

WF_STYLE_CONVENTION.txt

@@ -0,0 +1,66 @@
+__author__: Jens Broeder (j.broeder@fz-juelich.de)
+
+Here are some guidlines for writting FLEUR workflows/workchains and AiiDA in general.
+Keep in mind that a workflow is REAL SOFTWARE which will be used by others and build ontop and NOT a script.
+
+
+########################
+
+GENERAL:
+
+1. Every Workflow needs a clear documentation of input, output! Think this through and do not change it later on, bcause you will break the code of others! Therefore thinking about good names (see below) is not wasted time.
+
+2. reuse as much of previous workflows as possible, use subworkflows.
+(otherwise your code exploded, is hard to understand again und not reusable)
+
+3. If you think somthing processing is common or might be useful for something else,
+make it modular, and import the method (goes along with point 2.).
+
+4. Try to keep the workflow context clean! (this part will always be saved and visible, there people track what is going on.
+
+5. Write clear report statements in the worklow report.
+
+6. ggf one has to think about resource managment.
+i.e if a big system needs to be calculated and the user says use x hundred cores,
+and in the workflow simulations on very small systems need to be done, it makes no
+sense to submit a job with the same huge amount
+(use a default amount of resources, or the given ones if they are less, for small calculations)
+
+7. ERROR handling:
+
+Error handling is very important and might take a lot of effort. Write at least an outline (named: inspect_xx, handle_xx), which skeleton for all the errors (treated or not). (look at the aiida QE workflows as example)
+Now iterative put every time you ancounter a 'crash' because something failed (usually variable/node acess stuff), the corresponding code in a try block and call your handler.
+Use self.abort('message') to clearly terminate the workflow in the case something went wrong and it makes no sense to continue.
+
+Keep in mind, your workflow should never:
+
+7.1 end up in a while true (because of a calculation or subworkflow failure)
+7.2 crash with at a later point because a calculation or subworkflow failed.
+(The user won't understand so easly what append, also this makes it impossible to build useful error handling of your workflow ontop (when using your workflow as a subworkflow))
+....
+
+
+
+
+##########################
+
+FLEUR Specific:
+
+1. Output nodes of a workflow has the nameing convention 'output_name_description'
+   i.e 'output_scf_wc_para'
+
+2. Every workflow should give back one parameter output node named 'output_wfname_para'
+   which contains all the 'physical results' the workflow is designd to provide,
+   or at least information to acces these results direclty (if stored in files and so on)
+   further the node should contain valuable information to make sense/judge the quality of the data.
+
+   Try to design this node in a way that if you take a look at it, you understand
+   the following questions:
+
+   which workflow was run, what version?
+   what came out?  What was put in, how can I see what was put in?
+   Is this valueable or garbage?
+
+3. so far name Fleur workflows/workchains name: fleur_name_wc
+
+4. (advanced) group workflow internal(between) calculations and add extras to calcualtion. (that way one can extract them from global querries, if need.

aiida_fleur/__init__.py

@@ -1,9 +1,9 @@
 # -*- coding: utf-8 -*-
 '''
-FLEUR plug-in
+AiiDA-FLEUR
 '''
 
-__copyright__ = u"Copyright (c), 2016, Forschungszentrum Juelich, Germany. All rights reserved."
+__copyright__ = u"Copyright (c), 2015-2017, Forschungszentrum Juelich GmbH, Germany. All rights reserved."
 __license__ = "MIT license, see LICENSE.txt file."
 __version__ = "0.3.0"
 __contributors__ = "Jens Broeder"