data

This module provides data loading and management functionality for NEB (Nudged Elastic Band) calculations and structure databases used in Local Cluster Expansion model fitting.

class kmcpy.io.neb.data.NEBDataLoader(model=None, reference_local_lattice_structure=None, exclude_species=None)

A data loader class for managing and validating databases of structures from NEB (Nudged Elastic Band) calculations, intended for Local Cluster Expansion model fitting. This class provides methods to add NEBEntry objects with consistency checks, compute occupation and correlation matrices, retrieve property values, and serialize the dataset to JSON format. .. attribute:: neb_entries

List of NEBEntry objects loaded into the data loader.

type:

List[NEBEntry]

model_name

Name of the Local Cluster Expansion model associated with the data.

Type:

str

add(neb_entry, model=None, reference_local_lattice_structure=None, exclude_species=None, tol=0.01, angle_tol=5)

Add a NEBEntry to the loader with validation.

Parameters:

• neb_entry (NEBEntry) – NEBEntry object to add

• model (Optional[LocalClusterExpansion]) – Local Cluster Expansion model instance

• reference_local_lattice_structure (Optional[LocalLatticeStructure]) – Reference local lattice used to compute occupation and correlation vectors.

• exclude_species (Optional[Sequence[str]]) – Removed legacy argument; use site_mapping fixed sites.

• tol (float) – Structure matching tolerance.

• angle_tol (float) – Structure matching angle tolerance.

Return type:

None

add_structure(structure, property_value, model=None, metadata=None, reference_local_lattice_structure=None, exclude_species=None, tol=0.01, angle_tol=5, **from_file_kwargs)

Add a structure object or structure file and target value directly.

Parameters:

• structure (Structure | str | PathLike[str]) – Structure compatible with the reference local lattice, or a path readable by pymatgen.core.Structure.from_file.

• property_value (float) – Target value, typically an NEB barrier.

• model (Optional[LocalClusterExpansion]) – Local Cluster Expansion model instance.

• metadata (Optional[Dict[str, Any]]) – Optional metadata stored with the entry.

• reference_local_lattice_structure (Optional[LocalLatticeStructure]) – Reference local lattice used to compute occupation and correlation vectors.

• exclude_species (Optional[Sequence[str]]) – Removed legacy argument; use site_mapping fixed sites.

• tol (float) – Structure matching tolerance.

• angle_tol (float) – Structure matching angle tolerance.

• **from_file_kwargs – Additional keyword arguments passed to pymatgen when structure is a file path.

Returns:

Added entry.

Return type:

NEBEntry

add_structures(structures, property_values, model=None, metadata=None, reference_local_lattice_structure=None, exclude_species=None, tol=0.01, angle_tol=5, **from_file_kwargs)

Add multiple structure objects or structure files and target values.

Parameters:

• structures (Sequence[Structure | str | PathLike[str]]) – Structure objects or files readable by pymatgen.

• property_values (Sequence[float]) – Target values matching structures.

• model (Optional[LocalClusterExpansion]) – Local Cluster Expansion model instance.

• metadata (Optional[Sequence[Dict[str, Any]]]) – Optional metadata entries matching structures.

• reference_local_lattice_structure (Optional[LocalLatticeStructure]) – Reference local lattice used to compute occupation and correlation vectors.

• exclude_species (Optional[Sequence[str]]) – Removed legacy argument; use site_mapping fixed sites.

• tol (float) – Structure matching tolerance.

• angle_tol (float) – Structure matching angle tolerance.

• **from_file_kwargs – Additional keyword arguments passed to pymatgen for path inputs.

Return type:

None

classmethod from_structures(structures, property_values, model, reference_local_lattice_structure=None, exclude_species=None, metadata=None, tol=0.01, angle_tol=5, **from_file_kwargs)

Build a loader from structure objects or structure files.

Parameters:

• structures (Sequence[Structure | str | PathLike[str]]) – Structure objects or files readable by pymatgen.

• property_values (Sequence[float]) – Target values matching structures.

• model (LocalClusterExpansion) – Local Cluster Expansion model instance.

• reference_local_lattice_structure (Optional[LocalLatticeStructure]) – Reference local lattice used to compute occupation and correlation vectors.

• exclude_species (Optional[Sequence[str]]) – Removed legacy argument; use site_mapping fixed sites.

• metadata (Optional[Sequence[Dict[str, Any]]]) – Optional metadata entries matching structures.

• tol (float) – Structure matching tolerance.

• angle_tol (float) – Structure matching angle tolerance.

• **from_file_kwargs – Additional keyword arguments passed to pymatgen for path inputs.

Returns:

Loader containing computed fitting data.

Return type:

NEBDataLoader

get_correlation_matrix()

Get the correlation matrix for all structures.

Return type:

ndarray

get_occupation_matrix()

Get the occupation matrix for all structures.

Return type:

ndarray

get_properties()

Get the properties for all structures.

Return type:

ndarray

to(output_dir='.', prefix='ekra')

Save training data to JSON file.

Parameters:

• output_dir (str) – Output directory

• prefix (str) – Prefix for output files

Returns:

Path to saved file

Return type:

str

write_fitting_inputs(output_dir='.', weight=1.0, corr_fname='correlation_matrix.txt', ekra_fname='e_kra.txt', weight_fname='weight.txt')

Write files consumed by LocalClusterExpansion.fit.

Parameters:

• output_dir (str | PathLike[str]) – Directory for fitting input files.

• weight (Union[float, Sequence[float]]) – Scalar sample weight or one weight per entry.

• corr_fname (str) – Correlation matrix file name.

• ekra_fname (str) – Target property file name.

• weight_fname (str) – Sample weight file name.

Returns:

Keyword arguments that can be passed to

LocalClusterExpansion.fit.

Return type:

dict

class kmcpy.io.neb.data.NEBEntry(structure, property_value, occupation=None, correlation=None, metadata=None)

Represents an entry for Nudged Elastic Band (NEB) calculations, storing structural and property data. .. attribute:: structure

Structure associated with this entry.

type:

Structure

property_value

The property value (e.g., energy) associated with this entry.

Type:

float

occupation

The occupation vector for the structure. Defaults to None.

Type:

Occupation, optional

correlation

The correlation vector for the structure. Defaults to None.

Type:

List[float], optional

metadata

Additional metadata for the entry. Defaults to None.

Type:

Dict, optional

compute_occ_corr(model, reference_local_lattice_structure=None, exclude_species=None, tol=0.01, angle_tol=5)

Compute occupation and correlation vectors for the structure.

Parameters:

• model (LocalClusterExpansion) – Local Cluster Expansion model instance

• reference_local_lattice_structure (Optional[LocalLatticeStructure]) – Reference local lattice used to map structures into occupation vectors. If omitted, the model must carry local_lattice_structure from build.

• exclude_species (Optional[Sequence[str]]) – Removed legacy argument; use site_mapping fixed sites. If omitted, the reference local lattice’s exclusion list is used when available.

• tol (float) – Structure matching tolerance.

• angle_tol (float) – Structure matching angle tolerance.

Return type:

None

classmethod from_structure(structure, property_value, metadata=None, **from_file_kwargs)

Create an entry from a structure object or structure file.

Parameters:

• structure (Structure | str | PathLike[str]) – Structure compatible with the reference local lattice, or a path readable by pymatgen.core.Structure.from_file.

• property_value (float) – Target value, typically an NEB barrier.

• metadata (Optional[Dict[str, Any]]) – Optional metadata stored with the entry.

• **from_file_kwargs – Additional keyword arguments passed to pymatgen when structure is a file path.

Returns:

Entry ready to be added to a loader.

Return type:

NEBEntry