The term transport in AiiDA refers to a class that the engine uses to perform operations on local or remote machines where its CalcJob are submitted. The base class Transport defines an interface for these operations, such as copying files and executing commands. A transport plugin is a class that implements this base class for a specific connection method. The aiida-core package ships with two transport plugins: the LocalTransport and SshTransport classes. The local transport can be used to connect with the localhost and makes use only of some standard python modules like os and shutil. The ssh transport, which can be used for machines that can be connected to over ssh, is simply a wrapper around the library paramiko that is installed as a required dependency of aiida-core.
CalcJob
Transport
aiida-core
LocalTransport
SshTransport
local
os
shutil
ssh
The transport class is actually almost never used directly by the user. It is mostly utilized by the engine that uses the transport plugin to connect to the machine where the calculation job, that it is managing, is running. The engine has to be able to use always the same methods regardless of which kind of transport is required to connect to the computer in question.
The generic transport class contains a set of minimal methods that an implementation must support in order to be fully compatible with the other plugins. If not, a NotImplementedError will be raised, interrupting the managing of the calculation or whatever is using the transport plugin.
NotImplementedError
As for the general functioning of the plugin, the __init__() method is used only to initialize the class instance, without actually opening the transport channel. The connection must be opened only by the __enter__() method, (and closed by __exit__()). The __enter__() method lets you use the transport class using the with statement (see python docs), in a way similar to the following:
__init__()
__enter__()
__exit__()
with
with TransportPlugin() as transport: transport.some_method()
To ensure this, for example, the local plugin uses a hidden boolean variable _is_open that is set when the __enter__() and __exit__() methods are called. The ssh logic is instead given by the property sftp.
_is_open
The other functions that require some care are the copying functions, called using the following terminology:
put: from local source to remote destination get: from remote source to local destination copy: copying files from remote source to remote destination
put: from local source to remote destination
put
get: from remote source to local destination
get
copy: copying files from remote source to remote destination
copy
Note that these functions must accept both files and folders and internally they will fallback to functions like putfile or puttree.
putfile
puttree
The last function requiring care is exec_command_wait(), which is an analogue to the subprocess python module. The function gives the freedom to execute a string as a remote command, thus it could produce nasty effects if not written with care.
exec_command_wait()
Warning
Be sure to escape any strings for bash!
Download this template as a starting point to implementing a new transport plugin. It contains the interface with all the methods that need to be implemented, including docstrings that will work with Sphinx documentation.
this template
Note
To inform AiiDA about your new transport plugin you must register an entry point in the aiida.transports entry point group. Please visit the AiiDA registry to see an example of how this can be done.
aiida.transports