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

_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:

In the form {“prop_name”: value}.

Return type:

dict[str, Any]

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]
abstract 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[Structure | dict[str, Any] | Atoms]) – A sequence of structures to be processed. Each structure can be represented as Structure, a dictionary containing structure-related data, or Atoms.

  • n_jobs (None | int, optional) – The number of jobs to use for parallel processing. If None, the default parallelism settings of the Parallel utility will be used. Defaults to None.

  • allow_errors (bool, optional) – If True, exceptions encountered during the calculation of a structure will be caught, and None will be returned for that structure. If False, the exception is raised. Defaults to False.

  • **kwargs (Any) – Additional keyword arguments to pass to the Parallel utility.

Returns:

A generator that yields the results of the

calculations for the input structures. If an exception occurs and allow_errors is True, None will be yielded for the corresponding structure.

Return type:

Generator[dict | None, None, None]

Raises:

Exception – If any error occurs during the calculation of a structure and allow_errors is False, the exception will be raised.

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 Calculator instance.

Return type:

Calculator