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>}, 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
}
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 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' : '*'}

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}

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: 100

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.

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.