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