An AiiDA plugin is an extension of AiiDA, announcing itself to
aiida-core by means of a new entry point.
AiiDA plugins can be bundled and distributed in a python package that provides a set of extensions to AiiDA.
The python community uses the term ‘package’ rather loosely. Depending on context, it can refer to a collection of python modules or it may, in addition, include the files necessary for building and installing the package.
What a plugin can do¶
Add a new class to AiiDA’s entry point groups, including:: calculations, parsers, workflows, data types, verdi commands, schedulers, transports and importers/exporters from external databases. This typically involves subclassing the respective base class AiiDA provides for that purpose.
Install new commandline and/or GUI executables
Depend on, and build on top of any number of other plugins (as long as their requirements do not clash)
What a plugin should not do¶
An AiiDA plugin should not:
Change the database schema AiiDA uses
Use protected functions, methods or classes of AiiDA (those starting with an underscore
Monkey patch anything within the
aiidanamespace (or the namespace itself)
Failure to comply will likely prevent your plugin from being listed on the official AiiDA plugin registry.
If you find yourself tempted to do any of the above, please open an issue on the AiiDA repository and explain why. We will advise on how to proceed.
Wrapping an external code¶
In order to wrap an external simulation code for use in AiiDA, you will need to write a calculation input plugin (subclassing the
CalcJob class) and an output parser plugin (subclassing the
- Don’t break data provenance.Store at least what is needed for full reproducibility.
- Parse what you want to query for.Make a list of which information to:
- Expose the full functionality.Standardization is good but don’t artificially limit the power of a code you are wrapping - or your users will get frustrated.If the code can do it, there should be some way to do it with your plugin.
- Don’t rely on AiiDA internals.AiiDA’s public python API includes anything that you can import via
from aiida.module import thing.Functionality at deeper nesting levels is not considered part of the public API and may change between minor AiiDA releases, forcing you to update your plugin.
While it is up to you to decide the folder structure for your plugin, here is how a typical AiiDA plugin package may look like (see also the aiida-diff demo plugin):
aiida-mycode/ - distribution folder aiida_mycode/ - toplevel package (from aiida_mycode import ..) __init__.py calculations/ __init__.py mycode.py - contains MycodeCalculation parsers/ __init__.py mycode.py - contains MycodeParser data/ __init__.py mydat.py - contains MyData (supports code specific format) commands/ __init__.py mydat.py - contains visualization subcommand for MyData workflows/ __init__.py mywf.py - contains a basic workflow using mycode ... setup.py - install script setup.json - install configuration ...
A minimal plugin package instead might look like:
aiida-minimal/ aiida_minimal/ __init__.py simpledata.py setup.py setup.json