An API for NOMAD Archive entries

The NOMAD project provides a rich database of both theoretical and experimental FAIR materials-science data. To access this data, the NOMAD Graphical User Interface (GUI), or the web Application Programming Interface (API) can be used. To do so, a query has to be defined, that can be sent to the NOMAD servers. If data matches this query, the corresponding data will be returned.

MADAS provides a wrapper for the NOMAD API, that allows users to query NOMAD and recieve the results as Material objects. Then, the data can be processed and filtered to be stored in a database.

A complete tutorial with examples is in the tutorials section.

class madas.apis.NOMAD_web_API.API(processing={'archive': <function get_archive>, 'atoms': <function get_atoms>}, base_url: str = 'https://nomad-lab.eu/prod/v1/api/v1', timeout: int = 600, force_auth: bool = False, logger=None)

API connection wrapper for the NOMAD project.

Allows to download and process data using the NOMAD web API.

Keyword arguments

processing: dict[str:Callable]

Dictionary that provides functions to process the data that is downloaded from NOMAD. By default, the full NOMAD Archive is stored. This is a considerable overhead if not all data is required. In that case, it is suggested to limit the amout of data that is requested from NOMAD (see, e.g., the docstring of get_calculation) and to provide a custom function to process the data, such that only the necessary meta-data is kept.

default:

DEFAULT_PROCESSING = {
    "atoms" : madas.apis.NOMAD_web_API.get_atoms,
    "archive" : madas.apis.NOMAD_web_API.get_archive
}

base_url: str

Where to pull NOMAD data from. Only change this is you are trying to connect to a NOMAD OASIS instance. An example would be: “https://nomad-lab.eu/prod/v1/oasis/api/v1”

To access data that requires a login, e.g., upublished data, you need to provide your credentials.

This can be done by setting them as environment variables in bash:

export NOMAD_USERNAME="MyLogin"
export NOMAD_PASSWORD="MyPassWord"

where “MyLogin” and “MyPassWord” are your NOMAD username and password, respectively.

timeout: int

Timeout in seconds for calls to the Oasis authentication.

force_auth: bool

Force authentification if default URL is used. This can be used to access unpublished uploads on the central NOMAD installation.

logger: logging.Logger | None

Logger to write error and info messages.

Methods:

property failed_download

List of entry_id of calculations that could not be downloaded.

Use API().retry() to try to retrieve them.

get_calculation(entry_id: str, required: dict = {'required': '*'}, return_raw: bool = False, fail_quietly: bool = False) → Material | dict

Download data for a single calculation from NOMAD.

Arguments:

entry_id: str: Unique entry_id as it is used by NOMAD

Keyword arguments:

required: dict

Dictionary containing the information which sections of the NOMAD Archive are downloaded. This argument is passed directly to the NOMAD API and _must_ follow its definition given in the NOMAD documentation. Downloads the full Archive by default.

default: {'required' : '*'}

return_raw: bool

Return the response from the NOMAD API withour processing. This is helpful for debugging and for development of own processing functions.

NOTE: The subsequent parts of the code use only the ‘data’ part of the response.

default: False

fail_quietly: bool

Instead of raising an Exception, return a dictionary with the entry_id, error message and traceback.

default: False

Returns:

material: madas.material.Material: Material object with parsed properties

or

error_dict: dict

Only if fail_quietly==True, dictionary describing the error that occured.

Format: {error_message: str, entry_id: entry_id, traceback: traceback}

get_calculations_by_search(query: dict, required: dict = {'required': '*'}, n_threads: int = 5, max_entries: int | None = None, skip_entries: list | None = None) → List[Material]

Download several calculations from NOMAD, defined by a query. Uses multithreading to maximize download speed. If entries can not be downloaded, a message will be written to the log.

Arguments:

query: dict: Query submitted to the NOMAD API. The format must comply with the NOMAD standard.

Keyword arguments:

required: dict

Dictionary containing the information which sections of the NONAD Archive are downloaded. This argument is passed directly to the NOMAD API and _must_ follow its definition given in the NOMAD documentation. Downloads the full Archive by default.

default: {'required' : '*'}

n_threads: int

Number of threads to start. A too high number may result in unexpected behaviour and unnecessary overhead.

Set to any number smaller than 1 (one) to disable threading.

default: 5

max_entries: int or None

Maximal number of entries to retrieve. Set to None to retrieve all data.

default: None

ignore_entries: List[str] or None

Do not download entries with the any id from the given list.

default: None

Returns:

materials_list: List[madas.material.Material]: List of Materials for the given query.

static get_default_processing()

Dictionary containing the defaults defining how data from NOMAD will be processed.

Keys indicate the name of the property in MADAS.

Functions are used to read values from the NOMAD archives.

get_property(processing_function: Callable, entry_id: str, required: dict = {'required': '*'}) → Any

Receive a property from NOMAD.

Arguments:

processing_function: Callable: Function to extract data from NOMAD Archive. For more details please refer to the documentation of the class.
entry_id: str: NOMAD entry id of the calculation that shall be downloaded.

Keyword arguments:

required: dict

Dictionary containing the information which sections of the NONAD Archive are downloaded. This argument is passed directly to the NOMAD API and _must_ follow its definition given in the NOMAD documentation. Downloads the full Archive by default.

default: {'required' : '*'}

Returns:

property: Any: The desired property, parsed from the NOMAD Archive.

property processing

Dictionary defining how data from NOMAD will be processed.

Keys indicate the name of the property in MADAS.

Functions are used to read values from the NOMAD archives.

retry(required: dict = {'required': '*'}, use_progress_bar: bool = False) → List[Material]

Retry previously failed downloads.

Keyword arguments:

required: dict

Dictionary containing the information which sections of the NONAD Archive are downloaded. This argument is passed directly to the NOMAD API and _must_ follow its definition given in the NOMAD documentation. Downloads the full Archive by default.

default: {'required' : '*'}

use_progress_bar: bool

Show progress bar when downloading data.

Returns:

materials: List[madas.Material]: Materials that could successfully be downloaded with this attempt.

set_processing(processing: dict) → None

Set processing property of the API.

See documentation of the class for more information.

madas.apis.NOMAD_web_API.get_archive(NOMAD_respose: dict) → dict: Return the Archive entry of a NOMAD entry from the API response.

madas.apis.NOMAD_web_API.get_atoms(NOMAD_respose: dict) → Atoms: Creates an ASE Atoms object from a NOMAD API response.