iprPy.calculation package

Module contents

class Calculation(model: str | Path | IOBase | DataModelDict | None = None, name: str | None = None, params: str | Path | IOBase | dict = None, database=None, subsets: tuple | None = None, **kwargs: any)

Bases: Record

Base class for managing calculations

property allkeys: list

All keys used by the calculation.

Type:

list

property atomman_version: str

The version of atomman used

Type:

str

property branch: str

The calculation branch name

Type:

str

build_model() DataModelDict

Generates and returns model content based on the values set to object.

calc(*args, **kwargs) dict

Calls the calculation’s primary function(s)

calc_inputs() dict

Builds calculation inputs from the class’s attributes

property calc_style: str

The calculation style

Type:

str

cdcsquery(key: str | list | None = None, iprPy_version: str | list | None = None, atomman_version: str | list | None = None, script: str | list | None = None, branch: str | list | None = None, status: str | list | None = None, **kwargs: any) dict

Builds a CDCS-style query based on kwargs values for the record style.

Parameters:
  • key (str or list, optional) – The unique record UUID4 keys to parse by.

  • iprPy_version (str or list) – The version(s) of iprPy to parse by.

  • atomman_version (str or list, optional) – The version(s) of atomman to parse by.

  • script (str or list, optional) – The name(s) of the calculation script to parse by.

  • branch (str or list, optional) – The calculation branch name(s) to parse by.

  • status (str or list, optional) – The status(es) of the calculations to parse by.

  • **kwargs (any) – Any extra query terms associated with one of the calculation’s subsets.

Returns:

The CDCS-style query.

Return type:

dict

clean()

Resets the calculation state for running again.

property commontemplatekeys: dict

The input keys and their descriptions shared by all calculations.

Type:

dict

property compare_fterms

The terms to compare metadata values using a tolerance.

Type:

dict

property compare_terms: list

The terms to compare metadata values absolutely.

Type:

list

property database

The Database associated with the calculation record

Type:

iprPy.Database

property error: str | None

Any error message generated by the calculation

Type:

str or None

property filenames: list

the names of each file used by the calculation.

Type:

list

property files: dict

the names and contents of all required files.

Type:

dict

property iprPy_version: str

The version of iprPy used

Type:

str

isvalid() bool

Looks at the set attributes to determine if the associated calculation would be a valid one to run.

Returns:

True if element combinations are valid, False if not.

Return type:

bool

property key: str

The UUID4 key used to identify the calculation run

Type:

str

load_model(model: str | DataModelDict, name: str | None = None)

Loads record contents from a given model.

Parameters:
  • model (str or DataModelDict) – The model contents of the record to load.

  • name (str, optional) – The name to assign to the record. Often inferred from other attributes if not given.

load_parameters(params: dict | str | IOBase, key: str | None = None)

Reads in and sets calculation parameters.

Parameters:
  • params (dict, str or file-like object) – The parameters or parameter file to read in.

  • key (str, optional) – A new key value to assign to the object. If not given, will use calc_key field in params if it exists, or leave the key value unchanged.

property maindoc: str

the overview documentation for the calculation

Type:

str

master_prepare_inputs(branch: str = 'main', **kwargs: any) dict

Utility method that build input parameters for prepare according to the workflows used by the NIST Interatomic Potentials Repository. In other words, transforms inputs from master_prepare into inputs for prepare.

Parameters:
  • branch (str, optional) – Indicates the workflow branch to prepare calculations for. Default value is ‘main’.

  • **kwargs (any) – Any parameter modifications to make to the standard workflow prepare scripts.

Returns:

params – The full set of prepare parameters based on the workflow branch

Return type:

dict

metadata() dict

Generates a dict of simple metadata values associated with the record. Useful for quickly comparing records and for building pandas.DataFrames for multiple records of the same style.

mongoquery(name: str | list | None = None, key: str | list | None = None, iprPy_version: str | list | None = None, atomman_version: str | list | None = None, script: str | list | None = None, branch: str | list | None = None, status: str | list | None = None, **kwargs: any) dict

Builds a Mongo-style query based on kwargs values for the record style.

Parameters:
  • name (str or list, optional) – The record name(s) to parse by.

  • key (str or list, optional) – The unique record UUID4 keys to parse by.

  • iprPy_version (str or list, optional) – The version(s) of iprPy to parse by.

  • atomman_version (str or list, optional) – The version(s) of atomman to parse by.

  • script (str or list, optional) – The name(s) of the calculation script to parse by.

  • branch (str or list, optional) – The calculation branch name(s) to parse by.

  • status (str or list, optional) – The status(es) of the calculations to parse by.

  • **kwargs (any) – Any extra query terms associated with one of the calculation’s subsets.

Returns:

The Mongo-style query.

Return type:

dict

property multikeys: list

Calculation key sets that can have multiple values during prepare.

Type:

list

property parent_module: str

Name of the module where the calculation’s code is located

Type:

str

process_results(results_dict: dict)

Processes calculation results and saves them to the object’s results attributes.

Parameters:

results_dict (dict) – The dictionary returned by the calc() method.

property queries: dict

Query objects and their associated parameter names.

Type:

dict

run(params: str | dict | IOBase | None = None, newkey: bool = False, results_json: bool = False, raise_error: bool = False, verbose: bool = False)

Runs the calculation using the current object attribute values or supplied parameters. Status after running will be either “finished” or “error”.

Parameters:
  • params (dict, str or file-like object, optional) – The parameters or parameter file to read in. If not given, will run based on the current object attribute values.

  • newkey (bool, optional) – If True, then the calculation’s key and name will be replaced with a new UUID4. This allows for iterations on previous runs to be uniquely labeled. Default value is False.

  • results_json (bool, optional) – If True, then a “results.json” file will be generated following the run.

  • raise_error (bool, optional) – The default behavior of run is to take any error messages from the calculation and set them to class attributes and save to results.json. This allows for calculations to successfully fail. Setting this to True will instead raise the errors, which can provide more details for debugging.

  • verbose (bool, optional) – If True, a message relating to the calculation’s status will be printed upon completion. Default value is False.

property script: str

The name of the calculation script used

Type:

str

set_values(name: str | None = None, **kwargs: any)

Set calculation values directly. Any terms not given will be set or reset to the calculation’s default values.

Parameters:
  • name (str, optional) – The name to assign to the calculation. By default, this is set as the calculation’s key.

  • iprPy_version (str, optional) – Identifies the version of iprPy used. If not given, will be set to the currently loaded iprPy version.

  • atomman_version (str, optional) – Identifies the version of atomman used. If not given, will be set to the currently loaded atomman version.

  • key (str, optional) – A UUID4 key to uniquely identify the calculation run.

  • branch (str, optional) – A branch name to differentiate sets of calculation runs based on input parameters. Default value is ‘main’.

  • status (str, optional) – The calculation’s status: ‘not calculated’, ‘finished’ or ‘error’. Default value is ‘not calculated’.

  • error (str or None, optional) – An error message for the calculation, if one was raised.

  • **kwargs (any, optional) – All extra keywords are passed on to the set_values() methods of the calculation’s subsets.

property singularkeys: list

Calculation keys that can have single values during prepare.

Type:

list

property status: str

The current status of the calculation

Type:

str

property style: str

The record style

Type:

str

property subsets: tuple

The calculation’s subsets

Type:

tuple

property template: str

The template to use for generating calc.in files.

Type:

str

property templatedoc: str

The documentation for the template lines for this calculation.

Type:

str

property templatekeys: dict

The calculation-specific input keys and their descriptions.

Type:

dict

property theorydoc: str

the methods and theory documentation for the calculation

Type:

str

property xsd_filename

The module path and file name of the record’s xsd schema

Type:

tuple

property xsl_filename

The module path and file name of the record’s xsl transform

Type:

tuple

load_calculation(style, **kwargs)

Loads a Calculation subclass associated with a given calculation style

Parameters:

style (str) – The calculation style

Returns:

A Calculation object for the style

Return type:

subclass of iprPy.calculation.Calculation