matcalc._base module

Define basic API.

class ChainedCalc(prop_calcs: Sequence[PropCalc])[source]

Bases: PropCalc

A 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 followed by a formation energy computation and an elasticity calculation. This can be done by supplying a list of calculators. Each calculator receives the full result dict from the previous step, so downstream calculators can skip redundant relaxations by setting relax_structure=False.

Initialize a chained calculator.

Parameters:

prop_calcs – Sequence of prop calcs.

_abc_impl = <_abc._abc_data object>[source]
calc(structure: Structure | Atoms | 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:

Merged dict from all steps (final keys depend on the chain).

calc_many(structures: Sequence[Structure | Atoms | dict[str, Any]], n_jobs: None | int = None, allow_errors: bool = False, **kwargs: Any) → Generator[dict | None, None, 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: ABC

Abstract 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.

_abc_impl = <_abc._abc_data object>[source]
static _merge_units(prev: dict[str, Any] | None, new: dict[str, str]) → dict[str, str][source]

Merge unit annotations, preserving upstream entries.

Use this when building the _units field on a result dict that may already contain _units from an earlier step in a chain. Keys present in new overwrite the upstream value (the calc emitting them owns the unit string for those fields).

Parameters:

  • prev – The upstream result dict (or its _units value), or None.

  • new – The units this calc is contributing.

Returns:

A merged dict suitable for use as the _units field.

_prerelax(structure: Structure | Atoms, result: dict[str, Any], **relax_kwargs: Any) → tuple[dict[str, Any], Structure | Atoms][source]

Optionally relax structure and merge the relaxation result.

Centralises the if self.relax_structure: ... else ... pattern shared by most property calculators. Honors self.relax_structure; when False (or absent), the input is returned unchanged.

Constructs a fresh RelaxCalc using self.calculator and the merged kwargs each call. Callers that need to reuse a relaxer for downstream relaxations (deformed cells, elemental references, …) should hold their own RelaxCalc instance and use it directly.

Parameters:

  • structure – Input structure (already extracted from the result dict).

  • result – The current result dict; relaxation outputs are merged in.

  • **relax_kwargs – Forwarded to RelaxCalc. relax_calc_kwargs on the subclass (if any) takes precedence over these, mirroring the existing per-calc convention.

Returns:

(result, structure) — both updated when a relaxation ran, both unchanged otherwise.

Raises:

RuntimeError – If the pre-relaxation did not converge within max_steps. Downstream property calculations (elastic constants, EOS, phonons, …) sample the PES around what is meant to be an equilibrium structure; running them on an unrelaxed structure yields physically meaningless numbers, so the chain is aborted rather than propagating bad inputs.

abstractmethod calc(structure: Structure | Atoms | dict[str, Any]) → dict[str, Any][source]

Abstract method to calculate and process a given structure.

Processes a provided structure in the form of a pymatgen Structure, ASE Atoms, or a dictionary with specific keys, and returns a processed dictionary. If the input structure is a dictionary, it must contain the key final_structure or structure; otherwise, a ValueError is raised. The returned dictionary includes the key final_structure pointing to the provided or derived structure.

Parameters:

structure – A Structure, Atoms, or dict containing structural data to be processed. If a dictionary is provided, it must include either final_structure or structure keys.

Returns:

A dictionary with the key final_structure, representing the provided structure or the structure derived from the dictionary input.

Raises:

ValueError – If the provided dictionary does not contain the required keys final_structure or structure.

calc_many(structures: Sequence[Structure | dict[str, Any] | Atoms], n_jobs: None | int = None, allow_errors: bool = False, **kwargs: Any) → Generator[dict | None, None, None][source]

Calculates multiple structures in parallel with optional error tolerance.

This method processes a sequence of structures, allowing them to be calculated in parallel. It offers the ability to handle errors on a per-structure basis. If error tolerance is enabled, calculation failures for individual structures result in returning None for those structures, without raising exceptions.

Parameters:

  • structures – Sequence of structures or structure dicts.

  • n_jobs – joblib worker count; None uses joblib defaults.

  • allow_errors – If True, failed structures yield None instead of raising.

  • **kwargs – Forwarded to joblib.Parallel.

Yields:

Result dict from calc, or None when allow_errors and a structure fails.

Raises:

Exception – Any error from calc when allow_errors is False.

property calculator: Calculator[source]

Provides access to the Calculator instance used internally.

This property retrieves an instance of the Calculator class, which is associated with the current object and utilized internally for performing operations or calculations. The property ensures encapsulation and controlled access to the underlying calculator.

Returns:

The internal ASE calculator instance.