API reference¶

Decorators
Dataclasses
Database sub-package

Decorators ¶

Instruction ¶

asr.instruction(module=None, version=0, argument_hooks=[<function set_calculator_hook>], package_dependencies=('asr', 'ase', 'gpaw'))[source]¶

Make instruction object.

Parameters

module (str) – Name of recipe that instruction belongs to.
version (int) – Instruction version number.
argument_hooks (list[callable]) – Functions for preprocessing arguments. Gets a parameter object and should return parameter object.
package_dependencies (Tuple[str]) – Python packages for which versions should be logged.

CLI constructors ¶

asr.option(*aliases, matcher=<function EQUAL>, **kwargs)[source]¶

Make argument descriptor for a CLI option.

Parameters

aliases (list[str]) –
matcher (callable) – Matching function that wraps value when matching parameter with cache. Default is to use “equal”, eg. EQUAL(“value”).
kwargs (dict) – Arguments forwarded to click.option.

asr.argument(name, matcher=<function EQUAL>, **kwargs)[source]¶

Make argument descriptor for a CLI argument.

Parameters

name (str) – Name of argument.
matcher (callable) – Matching function that wraps value when matching parameter with cache. Default is to use “equal”, eg. EQ(“value”).
kwargs (dict) – Arguments forwarded to click.argument.

Mutation ¶

asr.mutation(function=None, *, selector=None, uid=None, eagerness=0, description=None)[source]¶

Mutation decorator.

Parameters

selector – Callable that returns a boolean used to select records to be migrated. Will be applied to all records in the cache.
uid – (optional) uuid.uuid4() uid which can be used to identify migration.
eagerness – Integer representing how eager the migration is to be applied. Migrations with higher eagerness will take priority over other migrations with lower values. Default is 0.
description – (optional) Description of the mutation. Default is to use the docstring of the decorated function.

Dataclasses ¶

Record ¶

class asr.Record(result=None, run_specification=None, resources=None, dependencies=None, history=None, tags=None, metadata=None)[source]¶

Class that represent a record object.

The Record object is used to store contextual data about the execution of an instruction.

Parameters

result (Optional[Any]) –
run_specification (Optional[asr.core.specification.RunSpecification]) –
resources (Optional[asr.core.resources.Resources]) –
dependencies (Optional[asr.core.dependencies.Dependencies]) –
history (Optional[asr.core.history.History]) –
tags (Optional[List[str]]) –
metadata (Optional[asr.core.metadata.Metadata]) –

Return type

None

result¶

The result of the instruction.

Type: Optional[Any]

run_specification¶

The description of the run particular run.

Type: asr.RunSpecification

resources¶

The resources consumed during the run.

Type: asr.Resources

dependencies¶

The record dependencies.

Type: asr.Dependencies

history¶

The revision history.

Type: asr.RevisionHistory

tags¶

Custom tags of the record.

Type: Optional[List[str]]

metadata¶

The record metadata.

Type: asr.Metadata

Run Specification ¶

class asr.RunSpecification(name, parameters, version, codes, uid)[source]¶

Class that represents a run specification.

A run specification is constructed when an instruction is run and represents all information available prior to the instruction has been executed.

Parameters

name (str) –
parameters (asr.core.parameters.Parameters) –
version (int) –
codes (asr.core.codes.Codes) –
uid (str) –

Return type

None

name¶

Name of the instruction.

Type: str

parameters¶

Parameters passed to the instruction during execution.

Type: asr.Parameters

codes¶

Code versions.

Type: asr.Codes

version¶

Instruction version.

Type: int

uid¶

Record UID.

Type: str

class asr.Resources(execution_start: Union[float, NoneType] = None, execution_end: Union[float, NoneType] = None, execution_duration: Union[float, NoneType] = None, ncores: Union[int, NoneType] = None)[source]¶

Parameters

execution_start (Optional[float]) –
execution_end (Optional[float]) –
execution_duration (Optional[float]) –
ncores (Optional[int]) –

Return type

None

Dependencies ¶

class asr.Dependencies(deps: List[asr.core.dependencies.Dependency] = <factory>)[source]¶

Parameters: deps (List[asr.core.dependencies.Dependency]) –
Return type: None

History ¶

class asr.RevisionHistory(history=<factory>)[source]¶

A class that represents the revision history.

Parameters: history (List[asr.core.migrate.Revision]) –
Return type: None

history¶

A chronological list of the revisions that led to the latest (current) revision. The latest revision is the last element of this list.

Type: List[asr.core.migrate.Revision]

add(revision)[source]¶

Add revision to history.

Parameters: revision (asr.core.migrate.Revision) –

property latest_revision: Optional[asr.core.migrate.Revision]¶: Get the latest revision, ‘None’ if no revisions.

Metadata ¶

class asr.Metadata(created=None, modified=None, directory=None)[source]¶

Class representing record metadata.

Parameters

created (Optional[datetime.datetime]) –
modified (Optional[datetime.datetime]) –
directory (Optional[str]) –

Return type

None

created¶

Type: Record creation date.

modified¶

Type: Record modification date.

directory¶

Type: Record directory.

Database sub-package ¶

For a tutorial on how to use the database subpackage see Creating ASR databases. The database sub-package contains utilities for creating a web application that browses multiple database projects. The basic workflow is to first create an asr.database.DatabaseProject. Then an application can be created and started conveniently with asr.database.run_app(). If more flexibility is needed an application object asr.database.App() can be created manually.

Database project ¶

class asr.database.DatabaseProject(name, title, database, uid_key='uid', key_descriptions=<factory>, tmpdir=None, row_to_dict_function=<function row_to_dict>, handle_query_function=<function args2query>, default_columns=<factory>, table_template='asr/database/templates/table.html', row_template='asr/database/templates/row.html', search_template='asr/database/templates/search.html', layout_function=<factory>, pool=None, template_search_path=None)[source]¶

Class that represents a database project.

Parameters

name (str) – The name of the database project.
title (str) – The title of the database object.
database (ase.db.core.Database) – A database connection
uid_key (str) – Key to be used as unique identifier.
key_descriptions (Dict[str, Tuple[str, str, str]]) – Key descriptions used by the web application
tmpdir (Optional[pathlib.Path]) – Path to temporary directory used by project to store files.
row_to_dict_function (Callable) – A function that takes (row, project) as input and produces an object (normally a dict) that is handed to the row template also specified in this project.
handle_query_function (Callable) – A function that takes a query tuple and returns a query tuple. Useful for doing translations when the query uses aliases for values, for example to convert stability=low to stability=1.
default_columns (List[str]) – Default columns that the application should show on the search page.
table_template (str) – Path to the table jinja-template. The table template shows the rows of the database.
row_template (str) – Path to the row jinja-template. The row template is responsible for showing a detailed description of a particular row.
search_template (str) – Path to the search jinja-template. The search template embeds the table template and is responsible for formatting the search field.
function (layout) – Function used by the defuault row_to_dict_function to create columns, figures, tables etc.
pool (Union[bool, None, multiprocessing.pool.Pool]) – Processes used for generating figures. If False, then figures are produced by the main process. If None, then a pool is created by automatically.
template_search_path (Optional[str]) – Path that will be added to flask’s template search paths where the row, search and/or table template should be located. If None, ASR/ASE assumes the templates to be located at default locations within ASE or ASR in that order.
layout_function (Callable) –

Return type

None

classmethod from_database(path)[source]¶

Make a database project from an ASE database.

The project construction acquires project attributes from the database metadata. These includes the name, title, uid, default_columns, table_template, search_template, row_template. Additionally, the project construction requires that the database metadata contains a key named keys whose value is a list of strings for which key-descriptions should be generated from a default set of key descriptions.

If name is not specified then the filename is used. If title is not specified then it is set to the same value as name.

Parameters: path (str) – Path to an ASE database with the metadata outlined above.
Returns: A database project constructed from the input database.
Return type: DatabaseProject

Examples

A minimal valid metadata examples looks like

{
    "name": "Name of my database",
    "keys": ["formula", "natoms"],
}

classmethod from_pyfile(path)[source]¶

Make a database project from a Python file.

The project is constructed from the variables defined in the input python script. The extracted variable names are the same as as the parameters to the asr.database.DatabaseProject constructor.

Parameters: path (str) – Path to a Python file that defines some or all of the attributes that defines a database project, e.g. name=, title=. At a minimum name, title and database needs to be defined.
Returns: A database project constructed from the attributes defined in the python file.
Return type: DatabaseProject

Examples

A minimal valid python script to define a database project looks like

from ase.db import connect
name = "Name of my database"
title = "Title of my database"
database = connect("path/to/my/database.db")

Run Application ¶

asr.database.run_app(projects, extra_key_descriptions=None, host='0.0.0.0', test=False)[source]¶

Start and run a database application.

Convencience function for creating an Application object, initializing projects and running the application. The application can be viewed in a browser at “host” address.

Parameters

projects (List[DatabaseProject]) – Add these projects to the application
extra_key_descriptions (Optional[dict]) – Add these key value pair descriptions to the projects before starting the application, by default None
host (str, optional) – The host address, by default “0.0.0.0”
test (bool, optional) – Whether to query all rows of all input projects/databases, by default False

Application object ¶

class asr.database.App[source]¶

App that can browse multiple database projects.

add_project(project)[source]¶

Add a project to application.

Parameters: project (DatabaseProject) – The project to be added.

add_projects(projects)[source]¶

Add multiple projects to application.

Parameters: projects (List[DatabaseProject]) – Databases to be added.

run(host='localhost', debug=False)[source]¶

Run app.

Parameters

host (str, optional) – The host address, for example “0.0.0.0”, by default “localhost”
debug (bool, optional) – Run server in debug mode, by default False

API reference¶

Decorators ¶

Instruction ¶

CLI constructors ¶

Mutation ¶

Dataclasses ¶

Record ¶

Run Specification ¶

Resources ¶

Dependencies ¶

History ¶

Metadata ¶

Database sub-package ¶

Database project ¶

Run Application ¶

Application object ¶

Atomic Simulation Recipes

Navigation