Skip to content

Types Module

Type definitions and data classes used throughout MACE Inference.

Type definitions for MACE Inference.

This module provides TypedDict definitions for structured return types and Protocol classes for interface definitions.

SinglePointResult

Bases: TypedDict

Result from single-point energy calculation.

Source code in src/mace_inference/types.py 
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
class SinglePointResult(TypedDict, total=False):
    """Result from single-point energy calculation."""
    energy: float
    """Total potential energy in eV."""

    energy_per_atom: float
    """Energy per atom in eV/atom."""

    forces: ForceArray
    """Atomic forces in eV/Å, shape (n_atoms, 3)."""

    max_force: float
    """Maximum force component magnitude in eV/Å."""

    rms_force: float
    """Root mean square of forces in eV/Å."""

    stress: Optional[StressArray]
    """Stress tensor in Voigt notation (eV/ų), shape (6,)."""

    pressure_GPa: Optional[float]
    """Hydrostatic pressure in GPa."""

    # Fields used in batch operations
    success: bool
    """Whether the calculation succeeded."""

    error: str
    """Error message if calculation failed."""

    structure_index: int
    """Index of the structure in batch operations."""

energy instance-attribute 

energy: float

Total potential energy in eV.

energy_per_atom instance-attribute 

energy_per_atom: float

Energy per atom in eV/atom.

forces instance-attribute 

forces: ForceArray

Atomic forces in eV/Å, shape (n_atoms, 3).

max_force instance-attribute 

max_force: float

Maximum force component magnitude in eV/Å.

rms_force instance-attribute 

rms_force: float

Root mean square of forces in eV/Å.

stress instance-attribute 

stress: Optional[StressArray]

Stress tensor in Voigt notation (eV/ų), shape (6,).

pressure_GPa instance-attribute 

pressure_GPa: Optional[float]

Hydrostatic pressure in GPa.

success instance-attribute 

success: bool

Whether the calculation succeeded.

error instance-attribute 

error: str

Error message if calculation failed.

structure_index instance-attribute 

structure_index: int

Index of the structure in batch operations.

BulkModulusResult

Bases: TypedDict

Result from bulk modulus calculation.

Source code in src/mace_inference/types.py 
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
class BulkModulusResult(TypedDict):
    """Result from bulk modulus calculation."""
    v0: float
    """Equilibrium volume in ų."""

    e0: float
    """Equilibrium energy in eV."""

    B: float
    """Bulk modulus in eV/ų."""

    B_GPa: float
    """Bulk modulus in GPa."""

    volumes: List[float]
    """List of volumes used for fitting in ų."""

    energies: List[float]
    """List of energies used for fitting in eV."""

    eos_type: str
    """Equation of state type used for fitting."""

v0 instance-attribute 

v0: float

Equilibrium volume in ų.

e0 instance-attribute 

e0: float

Equilibrium energy in eV.

B instance-attribute 

B: float

Bulk modulus in eV/ų.

B_GPa instance-attribute 

B_GPa: float

Bulk modulus in GPa.

volumes instance-attribute 

volumes: List[float]

List of volumes used for fitting in ų.

energies instance-attribute 

energies: List[float]

List of energies used for fitting in eV.

eos_type instance-attribute 

eos_type: str

Equation of state type used for fitting.

ThermalPropertiesResult

Bases: TypedDict

Result from thermal properties calculation.

Source code in src/mace_inference/types.py 
111
112
113
114
115
116
117
118
119
120
121
122
123
class ThermalPropertiesResult(TypedDict):
    """Result from thermal properties calculation."""
    temperatures: NDArray[np.floating[Any]]
    """Temperature array in K."""

    free_energy: NDArray[np.floating[Any]]
    """Helmholtz free energy in kJ/mol."""

    entropy: NDArray[np.floating[Any]]
    """Entropy in J/(mol·K)."""

    heat_capacity: NDArray[np.floating[Any]]
    """Heat capacity at constant volume in J/(mol·K)."""

temperatures instance-attribute 

temperatures: NDArray[floating[Any]]

Temperature array in K.

free_energy instance-attribute 

free_energy: NDArray[floating[Any]]

Helmholtz free energy in kJ/mol.

entropy instance-attribute 

entropy: NDArray[floating[Any]]

Entropy in J/(mol·K).

heat_capacity instance-attribute 

heat_capacity: NDArray[floating[Any]]

Heat capacity at constant volume in J/(mol·K).

PhononResult

Bases: TypedDict

Result from phonon calculation.

Source code in src/mace_inference/types.py 
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
class PhononResult(TypedDict, total=False):
    """Result from phonon calculation."""
    phonon: Any  # Phonopy object
    """Phonopy object with calculated force constants."""

    supercell_matrix: List[List[int]]
    """Supercell transformation matrix."""

    displacement: float
    """Atomic displacement distance in Å."""

    mesh: List[int]
    """k-point mesh for phonon DOS."""

    thermal_properties: ThermalPropertiesResult
    """Thermal properties if temperature_range was specified."""

    thermal: ThermalPropertiesResult
    """Alias for thermal_properties."""

phonon instance-attribute 

phonon: Any

Phonopy object with calculated force constants.

supercell_matrix instance-attribute 

supercell_matrix: List[List[int]]

Supercell transformation matrix.

displacement instance-attribute 

displacement: float

Atomic displacement distance in Å.

mesh instance-attribute 

mesh: List[int]

k-point mesh for phonon DOS.

thermal_properties instance-attribute 

thermal_properties: ThermalPropertiesResult

Thermal properties if temperature_range was specified.

thermal instance-attribute 

thermal: ThermalPropertiesResult

Alias for thermal_properties.

AdsorptionResult

Bases: TypedDict

Result from adsorption energy calculation.

Source code in src/mace_inference/types.py 
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
class AdsorptionResult(TypedDict):
    """Result from adsorption energy calculation."""
    E_ads: float
    """Adsorption energy in eV."""

    E_mof: float
    """MOF (substrate) energy in eV."""

    E_gas: float
    """Gas molecule energy in eV."""

    E_complex: float
    """Adsorption complex energy in eV."""

    complex_structure: Any  # Atoms object
    """Final structure of the adsorption complex."""

    optimized: bool
    """Whether the complex was optimized."""

E_ads instance-attribute 

E_ads: float

Adsorption energy in eV.

E_mof instance-attribute 

E_mof: float

MOF (substrate) energy in eV.

E_gas instance-attribute 

E_gas: float

Gas molecule energy in eV.

E_complex instance-attribute 

E_complex: float

Adsorption complex energy in eV.

complex_structure instance-attribute 

complex_structure: Any

Final structure of the adsorption complex.

optimized instance-attribute 

optimized: bool

Whether the complex was optimized.

NeighborInfo

Bases: TypedDict

Information about a neighboring atom.

Source code in src/mace_inference/types.py 
168
169
170
171
172
173
174
175
176
177
class NeighborInfo(TypedDict):
    """Information about a neighboring atom."""
    index: int
    """Atom index in the structure."""

    symbol: str
    """Chemical symbol of the atom."""

    distance: float
    """Distance from the central atom in Å."""

index instance-attribute 

index: int

Atom index in the structure.

symbol instance-attribute 

symbol: str

Chemical symbol of the atom.

distance instance-attribute 

distance: float

Distance from the central atom in Å.

MetalCoordinationInfo

Bases: TypedDict

Coordination information for a single metal center.

Source code in src/mace_inference/types.py 
180
181
182
183
184
185
186
187
188
189
190
191
192
class MetalCoordinationInfo(TypedDict):
    """Coordination information for a single metal center."""
    metal_symbol: str
    """Chemical symbol of the metal atom."""

    coordination_number: int
    """Number of coordinating atoms."""

    neighbors: List[NeighborInfo]
    """List of neighboring atoms with distances."""

    average_distance: float
    """Average distance to neighbors in Å."""

metal_symbol instance-attribute 

metal_symbol: str

Chemical symbol of the metal atom.

coordination_number instance-attribute 

coordination_number: int

Number of coordinating atoms.

neighbors instance-attribute 

neighbors: List[NeighborInfo]

List of neighboring atoms with distances.

average_distance instance-attribute 

average_distance: float

Average distance to neighbors in Å.

CoordinationResult

Bases: TypedDict

Result from coordination analysis.

Source code in src/mace_inference/types.py 
195
196
197
198
199
200
201
202
203
204
class CoordinationResult(TypedDict):
    """Result from coordination analysis."""
    coordination: Dict[int, MetalCoordinationInfo]
    """Coordination info for each metal center, keyed by atom index."""

    n_metal_centers: int
    """Total number of metal centers found."""

    metal_indices: List[int]
    """List of metal atom indices."""

coordination instance-attribute 

coordination: Dict[int, MetalCoordinationInfo]

Coordination info for each metal center, keyed by atom index.

n_metal_centers instance-attribute 

n_metal_centers: int

Total number of metal centers found.

metal_indices instance-attribute 

metal_indices: List[int]

List of metal atom indices.

DeviceInfo

Bases: TypedDict

Information about compute devices.

Source code in src/mace_inference/types.py 
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
class DeviceInfo(TypedDict, total=False):
    """Information about compute devices."""
    cuda_available: bool
    """Whether CUDA is available."""

    cuda_count: int
    """Number of CUDA devices."""

    pytorch_version: str
    """PyTorch version string."""

    cuda_version: str
    """CUDA version string (if available)."""

    devices: List[Dict[str, Any]]
    """List of GPU device info dictionaries."""

cuda_available instance-attribute 

cuda_available: bool

Whether CUDA is available.

cuda_count instance-attribute 

cuda_count: int

Number of CUDA devices.

pytorch_version instance-attribute 

pytorch_version: str

PyTorch version string.

cuda_version instance-attribute 

cuda_version: str

CUDA version string (if available).

devices instance-attribute 

devices: List[Dict[str, Any]]

List of GPU device info dictionaries.

Calculator

Bases: Protocol

Protocol for ASE-compatible calculators.

Source code in src/mace_inference/types.py 
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
@runtime_checkable
class Calculator(Protocol):
    """Protocol for ASE-compatible calculators."""

    def get_potential_energy(self, atoms: Any = None, force_consistent: bool = False) -> float:
        """Calculate and return the potential energy."""
        ...

    def get_forces(self, atoms: Any = None) -> ForceArray:
        """Calculate and return the atomic forces."""
        ...

    def get_stress(self, atoms: Any = None, voigt: bool = True) -> StressArray:
        """Calculate and return the stress tensor."""
        ...

get_potential_energy 

get_potential_energy(atoms: Any = None, force_consistent: bool = False) -> float

Calculate and return the potential energy.

Source code in src/mace_inference/types.py 
233
234
235
def get_potential_energy(self, atoms: Any = None, force_consistent: bool = False) -> float:
    """Calculate and return the potential energy."""
    ...

get_forces 

get_forces(atoms: Any = None) -> ForceArray

Calculate and return the atomic forces.

Source code in src/mace_inference/types.py 
237
238
239
def get_forces(self, atoms: Any = None) -> ForceArray:
    """Calculate and return the atomic forces."""
    ...

get_stress 

get_stress(atoms: Any = None, voigt: bool = True) -> StressArray

Calculate and return the stress tensor.

Source code in src/mace_inference/types.py 
241
242
243
def get_stress(self, atoms: Any = None, voigt: bool = True) -> StressArray:
    """Calculate and return the stress tensor."""
    ...

Optimizable

Bases: Protocol

Protocol for objects that can be optimized.

Source code in src/mace_inference/types.py 
246
247
248
249
250
251
252
@runtime_checkable
class Optimizable(Protocol):
    """Protocol for objects that can be optimized."""

    def run(self, fmax: float = 0.05, steps: int = 500) -> bool:
        """Run the optimization."""
        ...

run 

run(fmax: float = 0.05, steps: int = 500) -> bool

Run the optimization.

Source code in src/mace_inference/types.py 
250
251
252
def run(self, fmax: float = 0.05, steps: int = 500) -> bool:
    """Run the optimization."""
    ...

Type Aliases

DeviceType

DeviceType = Literal["auto", "cpu", "cuda", "mps"]

Valid device specifications.

OptimizerType

OptimizerType = Literal["BFGS", "FIRE"]

Available optimizers for geometry relaxation.

EnsembleType

EnsembleType = Literal["nvt", "npt"]

Molecular dynamics ensemble types.

EOSType

EOSType = Literal["birchmurnaghan", "murnaghan", "vinet"]

Equation of state types for bulk modulus calculation.

Usage

These types are used for type hints throughout the codebase:

from mace_inference.types import DeviceType, OptimizerType

def my_function(device: DeviceType = "auto") -> None:
    ...

They help with:

  • IDE autocompletion
  • Type checking with mypy
  • Documentation