matcalc._base module
Define basic API.
- class ChainedCalc(prop_calcs: Sequence[PropCalc])[source]
Bases:
PropCalcA chained calculator that runs a series of PropCalcs on a structure or set of structures.
Often, you may want to obtain multiple properties at once, e.g., perform a relaxation with a formation energy computation and a elasticity calculation. This can be done using this class by supplying a list of calculators. Note that it is likely
Initialize a chained calculator.
- Parameters:
prop_calcs – Sequence of prop calcs.
- calc(structure: Structure | dict[str, Any]) dict[str, Any][source]
Runs the series of PropCalcs on a structure.
- Parameters:
structure – Pymatgen structure or a dict containing a pymatgen Structure under a “final_structure” or “structure” key. Allowing dicts provide the means to chain calculators, e.g., do a relaxation followed by an elasticity calculation.
- Returns:
In the form {“prop_name”: value}.
- Return type:
dict[str, Any]
- calc_many(structures: Sequence[Structure | dict[str, Any]], n_jobs: None | int = None, allow_errors: bool = False, **kwargs: Any) Generator[dict | None][source]
Runs the sequence of PropCalc on many structures.
- Parameters:
structures – List or generator of Structures.
n_jobs – The maximum number of concurrently running jobs. If -1 all CPUs are used. For n_jobs below -1, (n_cpus + 1 + n_jobs) are used. None is a marker for unset that will be interpreted as n_jobs=1 unless the call is performed under a parallel_config() context manager that sets another value for n_jobs.
allow_errors – Whether to skip failed calculations. For these calculations, None will be returned. For large scale calculations, you may want this to be True to avoid the entire calculation failing. Defaults to False.
**kwargs – Passthrough to calc_many method of all PropCalcs.
- Returns:
Generator of dicts.
- class PropCalc[source]
Bases:
ABCAbstract base class for property calculations.
This class defines the interface for performing property calculations on structures (using pymatgen’s Structure objects or a dictionary containing a pymatgen structure). Subclasses are expected to implement the calc method to define specific property calculation logic. Additionally, this class provides an implementation of the calc_many method, which enables concurrent calculations on multiple structures using joblib.
- abstract calc(structure: Structure | dict[str, Any]) dict[str, Any][source]
Abstract method to calculate and return a standardized format of structural data.
This method processes input structural data, which could either be a dictionary or a pymatgen Structure object, and returns a dictionary representation. If a dictionary is provided, it must include either the key
final_structureorstructure. For a pymatgen Structure input, it will be converted to a dictionary with the keyfinal_structure. To support chaining, a super() call should be made by subclasses to ensure that the input dictionary is standardized.- Parameters:
structure (Structure | dict[str, Any]) – A pymatgen Structure object or a dictionary containing structural data with keys such as
final_structureorstructure.- Returns:
A dictionary with the key
final_structuremapping to the corresponding structural data.- Return type:
dict[str, Any]
- Raises:
ValueError – If the input dictionary does not include the required keys
final_structureorstructure.
- calc_many(structures: Sequence[Structure | dict[str, Any]], n_jobs: None | int = None, allow_errors: bool = False, **kwargs: Any) Generator[dict | None][source]
Calculate properties for multiple structures concurrently.
This method leverages parallel processing to compute properties for a given sequence of structures. It uses the joblib.Parallel library to support multi-job execution and manage error handling behavior based on user configuration.
- Parameters:
structures – A sequence of Structure objects or dictionaries representing the input structures to be processed. Each entry in the sequence is processed independently.
n_jobs – The number of jobs to run in parallel. If set to None, joblib will determine the optimal number of jobs based on the system’s CPU configuration.
allow_errors – A boolean flag indicating whether to tolerate exceptions during processing. When set to True, any failed calculation will result in a None value for that structure instead of raising an exception.
kwargs – Additional keyword arguments passed directly to joblib.Parallel, which allows customization of parallel processing behavior.
- Returns:
A generator yielding dictionaries with computed properties for each structure or None if an error occurred (depending on the allow_errors flag).