API

Rules and sessions

class mona.Rule(corofunc)

Decorator that turns a coroutine function into a rule.

A rule is a callable that generates a task instead of actually calling the coroutine.

Parameters:corofunc – a coroutine function

__call__(*args, **kwargs)

Create a task.

All arguments are passed to Task.

add_extra_arg(factory)

Register an extra argument factory.

Parameters:factory – callable that returns an extra argument that will be appended to the arguments passed when creating a task.

corofunc

Coroutine function associated with the rule.

coroutine mona.run_process(*args, ncores=None, **kwargs)

Create a subprocess.

Wrapper around asyncio.create_subprocess_exec() that handles errors and whose behavior can be modified by session plugins.

Parameters:

• args (str) – arguments of the subprocess
• ncores (int) – number of cores that should be taken by the process
• kwargs – all other keyword arguments are passed to create_subprocess_exec(). PIPE is passed to stdin and stdout keyword arguments by default.

Return the standard output as bytes if no error output was generated or a tuple of bytes containing standard and error outputs.

coroutine mona.run_shell(cmd, ncores=None, **kwargs)

Execute a command in a shell.

Wrapper around asyncio.create_subprocess_shell() that handles errors and whose behavior can be modified by session plugins.

Parameters:

• cmd (str) – a shell command to be executed
• ncores (int) – number of cores that should be taken by the process
• kwargs – all other keyword arguments are passed to create_subprocess_shell(). PIPE is passed to stdin and stdout keyword arguments by default.

Return the standard output as bytes if no error output was generated or a tuple of bytes containing standard and error outputs.

coroutine mona.run_thread(func, *args)

Run a callable in a new thread.

Wrapper around asyncio.AbstractEventLoop.run_in_executor() whose behavior can be modified by session plugins.

Parameters:

• func – a callable
• args – positional arguments to the callable.

Return the result of the callable.

class mona.Session(plugins=None, warn=True)

A context manager in which tasks can be created.

Parameters:

• plugins – session plugins to load. This is equivalent to calling each plugin with the created session as an argument
• warn (bool) – warn at the end of session if some created tasks were not executed and no tasks were explicitly filtered

classmethod active()

Return a currently active session.

add_side_effect_of(caller, callee)

Register a task created by a task.

all_tasks()

Return all tasks created in session.

create_task(corofunc, *args, **kwargs)

Create a new task.

Parameters:

• corofunc – a coroutine function to be executed
• args – arguments to the coroutine
• kwargs – keyword arguments passed to Task

dot_graph(*args, **kwargs)

Generate Digraph for the task DAG.

eval(*args, **kwargs)

Blocking version of eval_async().

coroutine eval_async(obj, depth=False, priority=(RESULTS, EXECUTE, TRAVERSE), exception_handler=None, task_filter=None, limit=None)

Evaluate an object by running all tasks it references.

This includes all newly created tasks that are referenced indirectly.

Parameters:

• obj – any hashable object
• depth (bool) – traverse DAG depth-first if true, breadth-first otherwise
• priority (tuple) – prioritize steps in DAG traversal in order
• exception_handler – callable that accepts a task and an exception it raised and returns True if the exception should be ignored
• task_filter – callable that accepts a task and returns True if the task should be executed
• limit (int) – limit of the number of executed task

Return the evaluated object.

register_task(task)

Register a task in a session.

run_task(task)

Run a task.

Parameters:task – task to run

Return the result of the task’s coroutine function or it’s hashed instance if hashable.

coroutine run_task_async(task)

Run a task asynchronously.

running_task

Currently running task.

set_result(task, result)

Attach a result to a task.

side_effects_of(task)

Return tasks created by a given task.

storage

General-purpose dictionary-based storage.

Session plugins

class mona.plugins.Parallel(ncores=None)

Plugin that enables running tasks in parallel.

class mona.plugins.Cache(db, write='eager', full_restore=False)

Plugin that caches tasks and objects in a session to an SQLite database.

db

Database connection.

classmethod from_path(path, **kwargs)

Create a cache with a database at the given path.

class mona.plugins.FileManager(root, eager=True)

Plugin that manages storage of abstract task files in a file system.

class mona.plugins.TmpdirManager(root)

Plugin that manages temporary directories.

Files

class mona.files.File(path, content)

Represents a file located at an abstract relative path.

Users should create instances by one of the classmethod constructors documented below rather than directly.

content

Content as bytes or its hash.

classmethod from_path(path, root=None, *, keep=True)

Create a file from a physical file.

Parameters:

• path – the path of the physical file. Also a basis for the abstract path of the file instance.
• root – If given, the abstract path will be created from the physical path taken relative to the root. If not given, the path argument must be relative.
• keep (bool) – whether the physical file should kept or destroyed

classmethod from_str(path, content)

Create a file from a string or bytes.

Parameters:

• path – the abstract path of the created file instance
• content – the content of the file

name

Equivalent to path.name.

path

Abstract path to the file.

read_bytes()

Return content of the file as bytes.

read_text()

Return content of the file as string.

stem

Equivalent to path.stem.

target_in(path, *, mutable=False)

Create an actual file or a symlink at the given location.

Parameters:

• path (Path) – where the file should be created
• mutable (bool) – whether the created file will be mutable

Directory tasks

class mona.dirtask.DirtaskTmpdir(output_filter=None)

Context manager of a temporary directory that collects created files.

Parameters:output_filter – true for files to be collected

has_tmpdir_manager()

Is the temporary directory managed.

result()

Return a collection of files created in the temporary directory.

This is available only after leaving the context.

mona.dirtask.dir_task(*args, **kwargs)

Create a rule with an executable and a files as inputs.

The result of the task is a dictionary of all new files created by running the executable.

Scientific calculations

Molecular and crystal geometries

class mona.sci.geomlib.Atom(species, coord, **flags)

Represents a single atom.

Parameters:

• species – atom type
• coord – atom coordinate

copy()

Create a copy.

covalent_radius

Covalent radius.

mass

Atom mass.

number

Atom number.

class mona.sci.geomlib.Molecule(atoms, **flags)

Represents a molecule.

Parameters:atoms – atoms

bondmatrix(scale)

Return a connectivity matrix.

centered()

Return a new molecule with a center of mass at origin.

centers

Iterate over atoms.

cms

Center of mass.

coords

Coordinates.

copy()

Create a cpoy.

dump(f, fmt)

Write a molecule to a file.

Supported formats: ‘xyz’, ‘aims’, ‘mopac’.

dumps(fmt)

Default object formatter.

formula

Formula.

classmethod from_coords(species, coords, **flags)

Alternative constructor.

Parameters:

• species – atom types
• coords – coordinates

get_fragments(scale=1.3)

Return a list of clusters of connected atoms.

ghost()

Create a copy with all atoms as ghost atoms.

hash()

Hash of a molecule from rounded moments of inertia.

inertia

Inertia tensor.

items()

Iterate over tuples of atom type and coordinate.

mass

Molecular mass.

numbers

Atom numbers.

rotated(axis=None, phi=None, center=None, rotmat=None)

Return a new rotated molecule.

shifted(delta)

Return a new molecule shifted in space.

species

Atom types.

write(filename)

Write to a file.

xyz

Coordinates as a numpy array.

class mona.sci.geomlib.Crystal(atoms, lattice, **flags)

Represents a crystal. Inherits from Molecule.

Parameters:

• atoms – atoms
• lattice – lattice vectors

abc

Latice vectors as a numpy array.

copy()

Create a copy.

dump(f, fmt)

Write a crystal to a file.

Supported formats: ‘aims’, ‘vasp’.

classmethod from_coords(species, coords, lattice, **flags)

Alternative constructor.

Parameters:

• species – atom types
• coords – coordinates
• lattice – lattice vectors

get_kgrid(density=0.06)

Return a k-point grid with a given density.

normalized()

Create a copy with atoms on unit cell faces normalized.

rotated(axis=None, phi=None, center=None, rotmat=None)

Return a new crystal with rotated unit cell and lattice vectors.

supercell(ns)

Create a supercell.

mona.sci.geomlib.readfile(path, fmt=None)

Read a molecule or a crystal from a path.

mona.sci.geomlib.load(fp, fmt)

Read a molecule or a crystal from a file object.

mona.sci.geomlib.loads(s, fmt)

Read a molecule or a crystal from a string.

FHI-aims

class mona.sci.aims.Aims

Task factory that creates an FHI-aims directory task.

The creation of a task is handeld by a series of plugins that process keyword arguments passed to the instance of Aims to generate control.in and geometry.in. The default plugins are created with no extra arguments. Custom plugins can be registered by calling them with the Aims instance as an argument.

Aims tasks require two prerequisites to function:

• mona_aims executable in PATH, which runs Aims and accepts these environment variables:
  • MONA_AIMS specifies the Aims executable to run.
  • MONA_NCORES specifies the number of processor cores to run Aims with.
• AIMS_SPECIES_DEFAULTS environment variable that points to the species_defaults Aims directory.

__call__(*, label=None, **kwargs)

Create an Aims task.

Parameters:

• kwargs – keyword arguments processed by plugins
• label – passed to dir_task()

Existing keywords (some are generated by plugins, see below):

• atoms: List of two-tuples of a species and a coordinate.
• geom: Instance of Molecule.
• species_specs: List of species specifications.
• tags: Dictionary of tags for control.in.
• aims: Aims executable, must be present in PATH.
• check: Whether task should error out on abnormal Aims exit.
• ncores: Number of cores to use, all available if not given.

plugin_factories = [<class 'mona.sci.aims.aims.Atoms'>, <class 'mona.sci.aims.aims.SpeciesDefaults'>, <class 'mona.sci.aims.aims.Control'>, <class 'mona.sci.aims.aims.Geom'>, <class 'mona.sci.aims.aims.Script'>]

List of plugins run in this order.

class mona.sci.aims.Atoms

Aims plugin handling geometry.

Keywords processed: atoms. Keywords added: geom.

class mona.sci.aims.SpeciesDefaults(mod=None)

Aims plugin handling species specifications.

Parameters:mod – Callable that is passed the species specifications for modification.

Keywords added: species_specs. Keywords used: geom, species_defaults.

class mona.sci.aims.Control

Aims plugin generating control.in.

Keywords processed: species_specs, tags. Keywords added: control.in.

class mona.sci.aims.Geom

Aims plugin generating geometry.in.

Keywords processed: geom. Keywords added: geometry.in.

class mona.sci.aims.Script

Aims plugin generating script for the Aims taks.

Keywords processed: aims, check. Keywords added: script.

mona.sci.aims.parse_aims(*args, **kwargs)

Create a task that parses outputs of FHI-aims calculations.

The task takes the output of mona.sci.aims.Aims as an input and returns a dictionary of parsed results as output.

LaTeX

mona.sci.tex.jinja_tex(tex_template, ctx)

Render a Jinja TeX template.

Uses <</>> for variables, <+/+> for blocks, and <#/#> for comments.

Parameters:

• tex_template (str) – a Jinja template
• ctx (dict) – a variable context

Futures and tasks

The following classes are not intended for direct use by the end user, but are part of the versioned public API neverthless.

class mona.futures.Future(parents)

class mona.hashing.HashedComposite(jsonstr, components)

class mona.tasks.Task(corofunc, *args, label=None, default=<Empty._: 0>, rule=None)

class mona.tasks.TaskComposite(jsonstr, components)

class mona.tasks.TaskComponent(task, keys, default=<Empty._: 0>)