basis

Basis functions and occupation management for lattice models in kMCpy.

This module provides different basis functions for converting between species and numerical values used in cluster expansion and other lattice-based calculations, as well as an Occupation class for managing site occupation states with support for custom basis functions via registry.

class kmcpy.structure.basis.BasisFunction

Abstract base class for all basis functions.

This defines the interface that all basis functions must implement, allowing users to create custom basis functions that work with the Occupation class.

as_dict()

Serialize the basis definition.

Return type:

dict

abstract property basis_function: List[int | float]

List defining the basis function values.

convert_to(value, target_basis)

Convert a value to another basis function.

Return type:

Union[int, float]

flip(value)

Flip between match and mismatch values.

Return type:

Union[int, float]

classmethod from_dict(data)

Create a basis function from a Monty-style payload.

Return type:

BasisFunction

classmethod load(file_path)

Loads a class from a provided json file.

Parameters:

file_path (os.PathLike) – The json file to load from.

Returns:

An instance of the class being reloaded.

Return type:

MSONable

abstract property match_value: int | float

Value representing specie matches template structure.

abstract property mismatch_value: int | float

Value representing specie doesn’t match template structure.

num_site_basis_functions(n_states)

Return number of non-constant site basis functions.

Return type:

int

save(json_path, mkdir=True, json_kwargs=None, pickle_kwargs=None, strict=True)

Utility that uses the standard tools of MSONable to convert the class to json format, but also save it to disk. In addition, this method intelligently uses pickle to individually pickle class objects that are not serializable, saving them separately. This maximizes the readability of the saved class information while allowing _any_ class to be at least partially serializable to disk.

For a fully MSONable class, only a class.json file will be saved to the location {save_dir}/class.json. For a partially MSONable class, additional information will be saved to the save directory at {save_dir}. This includes a pickled object for each attribute that e serialized.

Parameters:

• file_path (os.PathLike) – The file to which to save the json object. A pickled object of the same name but different extension might also be saved if the class is not entirely MSONable.

• mkdir (bool) – If True, makes the provided directory, including all parent directories.

• json_kwargs (dict) – Keyword arguments to pass to the serializer.

• pickle_kwargs (dict) – Keyword arguments to pass to pickle.dump.

• strict (bool) – If True, will not allow you to overwrite existing files.

site_basis_values(n_states)

Return basis values with shape (n_states, n_basis_functions).

Return type:

ndarray

state_value(state_index, n_states=None)

Return the occupation value used for a species-state index.

Return type:

Union[int, float]

to_json()

Returns a json string representation of the MSONable object.

Return type:

str

unsafe_hash()

Returns an hash of the current object. This uses a generic but low performance method of converting the object to a dictionary, flattening any nested keys, and then performing a hash on the resulting object

property uses_state_indices: bool

Whether occupations store discrete species-state indices.

abstract property valid_values: set

Set of all valid values in this basis.

classmethod validate_monty_v1(_MSONable__input_value)

Pydantic validator with correct signature for pydantic v1.x

classmethod validate_monty_v2(_MSONable__input_value, _)

Pydantic validator with correct signature for pydantic v2.x

class kmcpy.structure.basis.ChebyshevBasis(max_states=2)

Discrete site-state Chebyshev basis used for cluster expansion.

kMCpy stores occupations as species-state indices. A site with q allowed species has states 0 through q - 1 and q - 1 non-constant Chebyshev basis functions.

as_dict()

Serialize the basis definition.

Return type:

dict

property basis_function: List[int | float | list]

List defining the basis function values.

convert_to(value, target_basis)

Convert a value to another basis function.

Return type:

Union[int, float]

flip(value)

Flip between match and mismatch.

Return type:

int

classmethod from_dict(data)

Create a basis function from a Monty-style payload.

Return type:

BasisFunction

from_occupation(value)

Convert occupation value to Chebyshev basis.

Occupation: 0 (vacant), 1 (occupied) Chebyshev: 0 (first species), 1 (missing/second species)

Return type:

int

is_occupied(value)

Check if value represents the first mapped species state.

Return type:

bool

is_vacant(value)

Check if value represents the missing/second-species state.

Return type:

bool

classmethod load(file_path)

Loads a class from a provided json file.

Parameters:

file_path (os.PathLike) – The json file to load from.

Returns:

An instance of the class being reloaded.

Return type:

MSONable

property match_value: int

Value when site matches the first mapped species.

property mismatch_value: int

Value when site is missing or matches another allowed species.

num_site_basis_functions(n_states)

Return q - 1 non-constant basis functions for q states.

Return type:

int

property occupied_value: int

Alias for the first mapped species state.

save(json_path, mkdir=True, json_kwargs=None, pickle_kwargs=None, strict=True)

Utility that uses the standard tools of MSONable to convert the class to json format, but also save it to disk. In addition, this method intelligently uses pickle to individually pickle class objects that are not serializable, saving them separately. This maximizes the readability of the saved class information while allowing _any_ class to be at least partially serializable to disk.

For a fully MSONable class, only a class.json file will be saved to the location {save_dir}/class.json. For a partially MSONable class, additional information will be saved to the save directory at {save_dir}. This includes a pickled object for each attribute that e serialized.

Parameters:

• file_path (os.PathLike) – The file to which to save the json object. A pickled object of the same name but different extension might also be saved if the class is not entirely MSONable.

• mkdir (bool) – If True, makes the provided directory, including all parent directories.

• json_kwargs (dict) – Keyword arguments to pass to the serializer.

• pickle_kwargs (dict) – Keyword arguments to pass to pickle.dump.

• strict (bool) – If True, will not allow you to overwrite existing files.

site_basis_values(n_states)

Return discrete Chebyshev values for a site’s allowed species.

The species states are encoded as equally spaced points in [-1, 1]. For q species, the returned columns are T_1 through T_{q-1} evaluated at those points.

Return type:

ndarray

state_value(state_index, n_states=None)

Return the occupation value for a species-state index.

Return type:

int

to_json()

Returns a json string representation of the MSONable object.

Return type:

str

to_occupation(value)

Convert Chebyshev value to occupation basis.

Chebyshev: 0 (first species), 1 (missing/second species) Occupation: 0 (vacant), 1 (occupied)

Return type:

int

unsafe_hash()

Returns an hash of the current object. This uses a generic but low performance method of converting the object to a dictionary, flattening any nested keys, and then performing a hash on the resulting object

property uses_state_indices: bool

Chebyshev occupations are stored as species-state indices.

property vacant_value: int

Alias for the missing/second-species state.

property valid_values: set

Set of all valid values in this basis.

classmethod validate_monty_v1(_MSONable__input_value)

Pydantic validator with correct signature for pydantic v1.x

classmethod validate_monty_v2(_MSONable__input_value, _)

Pydantic validator with correct signature for pydantic v2.x

class kmcpy.structure.basis.Occupation(data, basis='chebyshev', validate=True)

Encapsulates site occupation data with basis conversion and validation.

Provides a clean interface for managing occupation arrays with different basis representations. Supports any registered basis function, allowing users to define custom basis functions.

Features: - Automatic validation of occupation values using basis classes - Basis conversion between any registered basis types - Common operations like counting match/mismatch sites - Immutable and mutable variants - Efficient numpy operations under the hood - Extensible via basis function registry

array_equal(array)

Check if the underlying data array equals the given array.

This is useful for unit tests where you want to compare the raw data without creating another Occupation object.

Parameters:

array (Union[List, Tuple, ndarray]) – Array-like object to compare with

Return type:

bool

Returns:

True if the arrays are equal

property basis: str

Get the basis type name.

property basis_obj: BasisFunction

Get the basis function object.

copy()

Create a deep copy of this Occupation.

Return type:

Occupation

count_match()

Count sites with match (specie matches template).

Return type:

int

count_mismatch()

Count sites with mismatch (specie doesn’t match template).

Return type:

int

count_occupied()

Count sites with occupied state.

Return type:

int

count_vacant()

Count sites with vacant state.

Return type:

int

property data: ndarray

Get the underlying numpy array (read-only view).

equivalent_to(other)

Check if two Occupation objects represent the same occupation pattern, regardless of basis type.

This is useful for comparing occupations that might be in different bases but represent the same physical state.

Parameters:

other (Occupation) – Another Occupation object to compare with

Return type:

bool

Returns:

True if both objects represent the same occupation pattern

flip(indices)

Return new Occupation with flipped values at specified indices.

Parameters:

indices (Union[int, List[int]]) – Site index or list of indices to flip

Return type:

Occupation

Returns:

New Occupation object with flipped values

flip_inplace(indices)

Flip values at specified indices in-place.

Parameters:

indices (Union[int, List[int]]) – Site index or list of indices to flip

Return type:

None

get_match_indices()

Get indices of sites with match (specie matches template).

Return type:

List[int]

get_mismatch_indices()

Get indices of sites with mismatch (specie doesn’t match template).

Return type:

List[int]

get_occupied_indices()

Get indices of occupied sites.

Return type:

List[int]

get_vacant_indices()

Get indices of vacant sites.

Return type:

List[int]

classmethod ones(n_sites, basis='chebyshev')

Create Occupation with all sites occupied (atoms present).

Parameters:

• n_sites (int) – Number of sites

• basis (Union[str, BasisFunction]) – Basis function or name

Return type:

Occupation

Returns:

Occupation object with all sites occupied

classmethod random(n_sites, basis='chebyshev', fill_fraction=0.5, seed=None)

Create random Occupation using appropriate basis values.

Parameters:

• n_sites (int) – Number of sites

• basis (Union[str, BasisFunction]) – Basis function or name

• fill_fraction (float) – Fraction of sites to be occupied (atoms present) (0.0 to 1.0)

• seed (int) – Random seed for reproducibility

Return type:

Occupation

Returns:

Random Occupation object

to_basis(target_basis)

Convert to different basis representation using basis objects.

Parameters:

target_basis (Union[str, BasisFunction]) – Target basis - either string name or BasisFunction instance

Return type:

Occupation

Returns:

New Occupation object in target basis

property values: List[int]

Get occupation values as a list.

classmethod zeros(n_sites, basis='chebyshev')

Create Occupation with all sites vacant (no atoms).

Parameters:

• n_sites (int) – Number of sites

• basis (Union[str, BasisFunction]) – Basis function or name

Return type:

Occupation

Returns:

Occupation object with all sites vacant

class kmcpy.structure.basis.OccupationBasis

Occupation basis function that maps between binary occupation states. Uses [0, 1] representation for site occupancy.

In occupation basis: - 0 = vacant (no atom present) - 1 = occupied (atom present)

This is the most intuitive binary representation.

as_dict()

Serialize the basis definition.

Return type:

dict

property basis_function: List[int]

List defining the basis function values.

convert_to(value, target_basis)

Convert a value to another basis function.

Return type:

Union[int, float]

flip(value)

Flip between match and mismatch.

Return type:

int

from_chebyshev(value)

Convert the Chebyshev species-state value to occupation basis.

Return type:

int

classmethod from_dict(data)

Create a basis function from a Monty-style payload.

Return type:

BasisFunction

is_occupied(value)

Check if value represents occupied state.

Return type:

bool

is_vacant(value)

Check if value represents vacant state.

Return type:

bool

classmethod load(file_path)

Loads a class from a provided json file.

Parameters:

file_path (os.PathLike) – The json file to load from.

Returns:

An instance of the class being reloaded.

Return type:

MSONable

property match_value: int

Value when site matches template (has atom = occupied).

property mismatch_value: int

Value when site doesn’t match template (no atom = vacant).

num_site_basis_functions(n_states)

Return number of non-constant site basis functions.

Return type:

int

property occupied_value: int

Value representing occupied site (atom present).

save(json_path, mkdir=True, json_kwargs=None, pickle_kwargs=None, strict=True)

Utility that uses the standard tools of MSONable to convert the class to json format, but also save it to disk. In addition, this method intelligently uses pickle to individually pickle class objects that are not serializable, saving them separately. This maximizes the readability of the saved class information while allowing _any_ class to be at least partially serializable to disk.

For a fully MSONable class, only a class.json file will be saved to the location {save_dir}/class.json. For a partially MSONable class, additional information will be saved to the save directory at {save_dir}. This includes a pickled object for each attribute that e serialized.

Parameters:

• file_path (os.PathLike) – The file to which to save the json object. A pickled object of the same name but different extension might also be saved if the class is not entirely MSONable.

• mkdir (bool) – If True, makes the provided directory, including all parent directories.

• json_kwargs (dict) – Keyword arguments to pass to the serializer.

• pickle_kwargs (dict) – Keyword arguments to pass to pickle.dump.

• strict (bool) – If True, will not allow you to overwrite existing files.

site_basis_values(n_states)

Return basis values with shape (n_states, n_basis_functions).

Return type:

ndarray

state_value(state_index, n_states=None)

Return the occupation value used for a species-state index.

Return type:

Union[int, float]

to_chebyshev(value)

Convert occupation value to the Chebyshev species-state basis.

Return type:

int

to_json()

Returns a json string representation of the MSONable object.

Return type:

str

unsafe_hash()

Returns an hash of the current object. This uses a generic but low performance method of converting the object to a dictionary, flattening any nested keys, and then performing a hash on the resulting object

property uses_state_indices: bool

Whether occupations store discrete species-state indices.

property vacant_value: int

Value representing vacant site (no atom).

property valid_values: set

Set of all valid values in this basis.

classmethod validate_monty_v1(_MSONable__input_value)

Pydantic validator with correct signature for pydantic v1.x

classmethod validate_monty_v2(_MSONable__input_value, _)

Pydantic validator with correct signature for pydantic v2.x

kmcpy.structure.basis.get_basis(name, **kwargs)

Get a basis function instance by name.

Parameters:

name (str) – Name of the basis function

Return type:

BasisFunction

Returns:

Instance of the requested basis function

Raises:

ValueError – If basis name is not registered

kmcpy.structure.basis.register_basis(name)

Decorator to register a basis function class.

Parameters:

name (str) – Name to register the basis function under