Skip to content

Tools for simplifying daily work with the AiiDA workflow engine

License

Notifications You must be signed in to change notification settings

JuDFTteam/aiida-jutools

Repository files navigation

Documentation Status Build Status codecov MIT license GitHub version PyPI version DOI

aiida-jutools

This package offers

  1. For users: Tools for simplifying daily work with the AiiDA workflow engine, especically with respect to data management and high-throughput computing.
  2. For developers: Common utilities for AiiDA plugins, such as the JuDFTteam AiiDA plugins. These utitlities in turn make use of the common underlying Python layer masci-tools.

Just import with import aiida_jutools as jutools. Then you can call all tools like so: jutools.subpackage.tool (). All tools have comprehensive docstrings.

Installation

git clone git@github.com:JuDFTteam/aiida-jutools.git
cd aiida-jutools
# user install
pip install .
# developer install
pip install -e .

Documentation

Under construction. However, all classes and methods have comprehensive docstrings.

For developers

You have made some AiiDA code that may be useful to others? Consider adding it to jutools! Make a pull request, or ask @Irratzo to be added as developer.

Please adhere to the developer coding conventions:

  • Place larger classes in a subpackage (subfolder) in a separate module (file). Smaller stuff like functions go in the respective subpackage's subpackage/util.py.
  • Make all tools available at subpackage level via import in subpackage/__init__.py. See existing files for how to do that. Also import each new subpackage in the package's top-level __init__.py. Together, this enables to access all tools with tab completion like jutools.subpackage.tool() instead of needing to import single modules. The former is better practice. For that purpose, keep subpackage and module names short but clear, preferably one word only, as opposed to tool names which should be as long as needed to be self-explanatory.
  • Prefix non-user tools with _ to keep user namespace clean and organized.
  • Prefix all imports inside modules with _ to keep user namespace clean and organized. Prefer top namespace imports to avoid name conflicts and ambiguities. See existing modules for conventions, e.g. with respect to AiiDA imports.
  • Add docstring for every added tool. Add typing hints wherever possible and sensible. See existing modules for examples.
  • When manipulating AiiDA nodes, implement with 'load or create' pattern: load nodes if already exist, otherwise create. Provide a dry_run:bool=True and verbosity options (verbosity:int, verbose:bool, or silent:bool).
  • If you use cross-references in docstrings, do cross-referencing relative to the current location (i.e., prefixed by a dot .). Example: :py:func:`~.query_processes` instead of :py:func:`~aiida_jutools.process.query_processes`, when in module aiida_jutools.process.