local_lattice_structure

class kmcpy.structure.local_lattice_structure.LocalLatticeStructure(template_structure, center, cutoff, site_mapping=None, basis_type='chebyshev', is_write_basis=False, exclude_species=None, local_site_order=None, exclude_center_site=None)

Class to handle local environment around a site in a structure.

center defines the local-environment origin. It can be either an active site from the template structure or an abstract fractional coordinate:

• center=int is interpreted as a primitive-template site index before active-site filtering. The site must be mutable under site_mapping and is converted to the compact active-site index.

• center=(x, y, z) is treated as a fractional-coordinate point. No atom is created in the occupation vector; the coordinate is only the geometric origin for the cutoff sphere.

local_site_order only controls ordering of the sites found around this center. Its exclude_center_site flag removes the real center atom when the center is an atom. For an abstract center, it removes a site only if an existing atom lies at the center coordinate within tolerance.

as_dict()

Convert the model object to a dictionary representation.

copy()

Create a copy of the LatticeStructure

classmethod from_lattice_structure(lattice_structure, center, cutoff, site_mapping=None, basis_type='chebyshev', is_write_basis=False, exclude_species=None, local_site_order=None, exclude_center_site=None)

Create a LocalLatticeStructure from an existing LatticeStructure.

Parameters:

• lattice_structure (LatticeStructure) – The base lattice structure.

• center – Center site or coordinates for the local environment.

• cutoff (float) – Cutoff distance for the local environment.

• site_mapping (dict) – Mapping of species to sites.

• basis_type (str) – Type of basis to use.

• is_write_basis (bool) – Whether to write the basis to a file.

• exclude_species – Removed legacy argument; use site_mapping fixed sites.

Returns:

The created local lattice structure.

Return type:

LocalLatticeStructure

get_active_lattice_structure(supercell_shape=None)

Return a lattice structure containing only mutable active sites.

get_active_site_order(supercell_shape=None)

Return the compact active-site order for this lattice.

get_environment_signature()

Get a signature that uniquely identifies the environment type.

Return type:

tuple

get_occ_from_structure(structure, tol=0.1, angle_tol=5, sc_matrix=None, structure_site_mapping=None)

get_occ_from_structure() returns an Occupation object based on a comparison with the instance’s template_structure.

The supercell relationship is inferred from lattice vectors unless sc_matrix is provided. Site mapping is inferred from fractional coordinates unless structure_site_mapping is provided.

Parameters:

• structure (Structure) – The input structure, which may be a supercell of the template and may contain vacancies.

• tol (float) – Tolerance for structure matching.

• angle_tol (float) – Kept for API compatibility.

• sc_matrix (np.ndarray, optional) – Supercell matrix if known.

• structure_site_mapping (Sequence[int], optional) – Explicit mapping from each input structure site to a site in the supercell template. If provided, structure_site_mapping[j] is the supercell-template index occupied by structure[j]. Passing this skips automatic site matching.

Returns:

The occupation object for the structure with proper basis.

Return type:

Occupation

get_ordered_site_hash()

Get an order-sensitive hash for this local environment.

Return type:

str

get_ordered_site_signature()

Get an order-sensitive signature for this local environment.

Return type:

list[dict[str, Any]]

get_structure_from_occ(occ, sc_matrix=None)

get_structure_from_occ() takes an Occupation object and returns a pymatgen Structure

Parameters:

• occ (Occupation) – Occupation object containing site occupation data

• sc_matrix – Supercell matrix for creating the supercell

Returns:

pymatgen Structure with species assigned based on match/mismatch

Return type:

Structure

is_equivalent_to(other_local_env, rtol=0.001, atol=0.001)

Check if this local environment is equivalent to another.

Parameters:

• other_local_env (LocalLatticeStructure) – Other local environment to compare

• rtol (float) – Relative tolerance for comparison

• atol (float) – Absolute tolerance for comparison

Return type:

bool

Returns:

True if environments are equivalent

make_supercell(sc_matrix)

Create a supercell of the template structure

match_with_reference(reference_local_env, rtol=0.001, atol=0.001, find_nearest_if_fail=False)

Create a new LocalLatticeStructure with neighbors reordered to match reference.

Parameters:

• reference_local_env (LocalLatticeStructure) – Reference local environment to match

• rtol (float) – Relative tolerance for matching

• atol (float) – Absolute tolerance for matching

• find_nearest_if_fail (bool) – Find approximate match if exact match fails

Return type:

LocalLatticeStructure

Returns:

New LocalLatticeStructure with reordered neighbors

occupation_value_for_species(site_index, specie, allowed_species=None)

Return the occupation value for a species at a template site.

classmethod ordered_neighbor_info_from_finder(structure, center_index, local_env_finder)

Fetch near-neighbor dictionaries from a finder and return deterministic order.

This keeps keys such as image/local_index/label intact for downstream primitive-to-supercell mapping.

Return type:

List[Dict[str, Any]]

static sort_neighbor_info(neighbor_info)

Deterministically sort neighbor dictionaries while preserving all metadata.

The order matches the historical event-generator behavior: species first, then x coordinate.

Return type:

List[Dict[str, Any]]

species_for_occupation_value(site_index, value)

Return the allowed species represented by an occupation value.

to_cluster()

Return this local environment as a finite structural cluster.