Skip to content

Mat_record

Overview

The mat_record class is a Pydantic-based model designed to manage and track the complete record of computation work on a material. This includes core material metadata via mat_info, history of computational process via history, and computed properties and results via results. 

from DeWorks.materials import mat_record

Attributes

Core Fields

Field Type Description
id str Unique UUID string used as a MongoDB-compatible _id.
material mat_info Base material data.
history dict Stores calculation instances by name
results dict Stores outputs for specific computed properties

Saving Settings

Field Type Description
saving_mode Literal[1, 2] Mode to control how records are saved
1: local JSON
2: internal history
saving_dir str Directory path for saving JSON.
Uses current working directory if not specified
saved_json str | None Finds the last saved path to JSON

model_config = ConfigDict(extra = 'allow')

This allows the model to accept and store fields not explicitly defined in the schema, making it extensible for unexpected or user-defined fields.

getattr(self, item: str) -> Any

Method for automatically checking the results dict for attributes if the attribute is not explicitly defined

model_dump(self, args, *kwargs)

A manual implementation of serialze_by_alias by default

Computed Fields

|name |str(computed) |Returns the standardised record name: Rc_{material.name} | |SYMMETRY |str(computed) |The symmetry analysis as implemented in matbench-discovery
The dft relaxed structre will be used if RELAX | |ML_SYMMETRY |str(computed) |matbench symmetry analysis of the ML relaxed structure| |structure_difference |dict | None (computed)|Compares DFT and ML relaxations for volume, symmetry, and atom displacement |

structure_difference_table(self) -> pd.DataFrame

Returns a pandas.DataFrame containing structure_difference data.

Validation and De-serialisation

default_id(cls, values:dict)

Sets a default UUID _id if not present. Used to handle legacy records.

default_properties(cls, value:dict)

Ensures default computed property placeholders exist.

load_history(self)

Reassigns self as host to historical calculations

load(cls, vlaue: str | dict)

Loads a mat_record either from a JSON path or directly from a dict. 

record = mat_record.load(“./data/my_record.json”)
record = mat_record.load(json_dict)

Utilities

save(mode, dump=False)

Saves the mat_record instance. - mode = 1: Writes to disk - mode = 2: Used internally to update process state. 

record.save()

confirm_overwrite(calculation, _confirmation=None)

Asks for or uses passed confirmation before overwriting history

recall(self, include, exclude)

Returns a list of calculations matching filter criteria. 

calcs = record.recall(include=[“RELAX”])

progress(self, type, state, include, exclude)

Returns a DataFrame showing job progress of calculations. - include: the calculations to include - exclude: the calculations to exclude 

record.progress(type=“simple”) # Overview table of each calculation and overall progress status
record.progress(type=“states”) # Detailed table with all individual job states under each calutiaion
record.progress(type=“full_info”) # Full raw metadat of job for each calculation, including nested JobFlow objects

status(self, include, exclude, show) -> pd.DataFrame

Returns the state of selected calculations as a DataFrame df.

list_calculations(self, show: bool = True) pd.DataFrame

List all the calculations in a Pandas DataFrame.

list_results(self, show: bool = True) -> pd.DataFrame

List all the results in a pd.DataFrame

calculate(self, calculation, generator_func, overwrite, start, submit, cluster, force_confirmation, **kwargs) -> process

Creates and optionally starts a calculation for the material. - calculation: a process subclass or the name of the subclass in str - generator_func: A user created function that takes self. Addition process() specific arguements given as **kwargs will be ignored - overwrite: option to overwrite any existing calculations of the same name in history. - start: Whether to call the start() function of the calculation automatically or requires the user to call the fucntion explicitly on the process obejct returned. - start+kwargs: kwargs parsed to the start() function of the process - force_confirmation: used by higher level objects to force a confirmation by using the confirmation it has received 

relaxJob = mat_record.calculate(calculation=“RELAX”, submit=True)

displace(self, relax_name, *kwargs)

Displaces specific relaxed structures

output_collate(self, JS, JC, include, exclude)

Collects and integrates results from JS: JobStore or JC: JobController. 

record.output_collate()

write_table(self, include, exclude, *kwargs)

Writes new computed property objects into the record based on current results.

result_collection(self, JS, JC, include, exclude, **kwargs)

Full workflow that performs both output_collate and write_property.

output_table(self, show, include, exclude) -> dict[str, pd.DataFrame]

Aggregates key result values into a single tabular dataframe for export or inspection

fail_assess(self, show, include, exclude)

Analyzes failed jobs in the record and returns a multi-indexed dataframe of errors.

plot(self, include, exclude, **kwargs) -> dict[str, pd.DataFrame]

Optional visualization method to create plots

rerun(…)

Allows for reruning failed or selected calculations with modified settings.

Notes

  • mat_record requires correct definition of its associate mat_info object.
  • This model is intended for automation an dpersistent tracking of computational experiments.
  • Inherits most functional patterns from the abstract class Record.