Cluster Expansion Settings

class clease.settings.Concentration(basis_elements=None, grouped_basis=None, A_lb=None, b_lb=None, A_eq=None, b_eq=None)

Bases: object

Specify concentration ranges of consituting elements for cluster expansion. Concentration range can be specified in three different ways.

1. specifying the equality and lower bound conditions by specifying A_lb, b_lb, A_eq and b_eq during initialization, 2. using set_conc_formula_unit() method, and 3. using set_conc_ranges() method.

Parameters:

basis_elements: list

List of chemical symbols of elements to occupy each basis. Even for the cases where there is only one basis (e.g., fcc, bcc, sc), a list of symbols should be grouped by basis as in [[‘Cu’, ‘Au’]] (note the nested list form).

grouped_basis: list (optional, only used when basis are grouped)

Indices of basis_elements that are considered to be equivalent when specifying concentration (e.g., useful when two basis are shared by the same set of elements and no distinctions are made between them). As an example consider a structure with three sublattices A, B and C. If sublattice A and C should be occupied by the same elements and B is occupied by a different set of elements. We can group lattice A and C by passing [(0, 2), (1,)].

A_lb: list (optional, only used for linear algebra representation)

A two-dimention matrix (or nested list) used to specify the lower bounds of the concentration ranges.

b_lb: list (optional, only used for linear algebra representation)

A list used tp specify the lower bounds of the concentration ranges.

A_eq: list (optional, only used for linear algegra representation)

A two-dimention matrix (or nested list) used to specify the equality conditions of the concentration ranges.

b_eq: list (optional, only used for linear algegra representation)

A list used tp specify the equality condisitons of the concentration ranges.

Example I: Single sublattice

>>> conc = Concentration(basis_elements=[['Au', 'Cu']])

Example II: Two sublattices >>> conc = Concentration(basis_elements=[[‘Au’, ‘Cu’], [‘Au’, ‘Cu’, ‘X’]])

Example III: Three sublattices where the first and third are grouped >>> conc = Concentration(basis_elements=[[‘Au’, ‘Cu’], [‘Au’, ‘Cu’, ‘X’], [‘Au’, ‘Cu’]], … grouped_basis=[(0, 2), (1,)])

__init__(basis_elements=None, grouped_basis=None, A_lb=None, b_lb=None, A_eq=None, b_eq=None)

add_usr_defined_eq_constraints(A_eq, b_eq)

Add user defined constraints.

The concentrations are restrictred by the equation A_eq*c = b_eq

Parameters:

A_eq: nested list of numpy array

NxM matrix where N is the number of equations and M is the overall number of concentrations

b_eq: list or numpy array

right hand side vector of the equation length N

add_usr_defined_ineq_constraints(A_lb, b_lb)

Add the user defined constraints.

The concentrations are restrictred by the equation A_lb*c > b_lb

Parameters:

A_lb: nested list of numpy array

NxM matrix where N is the number of equations and M is the overall number of concentrations

b_lb: list or numpy array

right hand side vector of the equation length N

clease_objtype = 'concentration'

conc_in_int(num_atoms_in_basis, conc) → ndarray

Convert concentration value to an integer that corresponds to the number of corresponding elements.

Parameters:

num_atoms_in_basis: list of int

Number of sites in each basis (e.g., [27, 27], [64]).

conc: array of float

Concentration per basis normalized to 1. (e.g., arrays returned by self.get_random_concentration,

self.get_conc_max_component etc.)

classmethod from_dict(data)

Initialize data from dictionary.

get_conc_max_component(comp)

Generate all end points of the composition domain.

get_conc_min_component(comp)

Generate all end points of the composition domain.

get_concentration_vector(index_by_basis, atoms)

Get the concentration vector.

get_individual_comp_range()

Return the concentration range of each component.

get_random_concentration(nib=None, sampling_attempts=200) → ndarray

Generate a valid random concentration.

Parameters:

sampling_attempts: int

Maximum number of attempts allowed to retrieve integer concentrations for each element in the structure.

is_valid(index_by_basis, atoms)

Check if the atoms object has a valid concentration.

Parameters:

index_by_basis: list

list where the indices of atoms is grouped by basis

atoms: Atoms object

wrappend_and_sorted atoms object

is_valid_conc(conc)

Check if the concentration is valid.

classmethod load(fd, **kwargs)

Method for loading class object from JSON

save(fd)

Method for writing class object to a JSON file.

set_conc_formula_unit(formulas=None, variable_range=None)

Set concentration based on formula unit strings.

Parameters:

formulas: list

List constaining formula strings (e.g., [“Li<x>Ru<1>X<2-x>”, “O<3-y>X<y>”], [‘Al<4-4x>Mg<3x>Si<x>’’]) 1. formula string should be provided per basis. 2. formula string can only have integer numbers. 3. only one dvariable is allowed per basis. 4. each variable should have at least one instance of ‘clean’ representation (e.g., <x>, <y>)

variable_range: dict

Range of each variable used in formulas. key is a string, and the value should be int or float e.g., {“x”: (0, 2), “y”: (0, 0.7)}, {‘x’: (0., 1.)}

set_conc_ranges(ranges)

Set concentration range based on lower and upper bounds of each element.

Parameters:

ranges: list

Nested list of tuples with the same shape as basis_elements. If basis_elements is [[“Li”, “Ru”, “X”], [“O”, “X”]], ranges coulde be [[(0, 1), (0.2, 0.5), (0, 1)], [(0, 0.8), (0, 0.2)]]

to_float_conc(num_atoms_in_basis, int_conc)

Convert integer number to float concentration.

Parameters:

num_atoms_in_basis: list of int

Number of sites in each basis (e.g., [27, 27], [64]).

int_conc: array of int

Concentration per basis in an integer format, which corresponds to the number of corresponding element in that basis.

todict() → dict

Return neescary information to store as JSON.

property trivial_bounds

Return trivial bounds (i.e. 0 <= x <= 1)

NOTE: One can give stricter bounds, but these

trivial bounds are always satisfied

class clease.settings.ClusterExpansionSettings(prim: Atoms, concentration: Concentration | dict, size: List[int] | None = None, supercell_factor: int | None = 27, db_name: str = 'clease.db', max_cluster_dia: Sequence[float] = (5.0, 5.0, 5.0), include_background_atoms: bool = False, basis_func_type='polynomial')

Bases: object

Base class for all Cluster Expansion settings.

Parameters:

• prim (Atoms) – The primitive atoms object.

• concentration (Union[Concentration, dict]) – Concentration object or dictionary specifying the basis elements and concentration range of constituting species.

• size (List[int] | None, optional) – Size of the supercell (e.g., [2, 2, 2] for 2x2x2 cell). supercell_factor is ignored if both size and supercell_factor are specified. Defaults to None.

• supercell_factor (int, optional) – Maximum multipilicity factor for limiting the size of supercell created from the primitive cell. supercell_factor is ignored if both size and supercell_factor are specified. Defaults to 27.

• db_name (str, optional) – Name of the database file. Defaults to 'clease.db'.

• max_cluster_dia (Sequence[float], optional) – A list of int or float containing the maximum diameter of clusters (in Å). Defaults to (5., 5., 5.), i.e. a 5 Å cutoff for 2-, 3-, and 4-body clusters.

• include_background_atoms (bool, optional) – Whether background elements are to be included. An element is considered to be a background element, if there is only 1 possible species which be ever be placed in a given basis. Defaults to False.

• basis_func_type (str, optional) – Type of basis function to use. Defaults to ‘polynomial’.

ARG_KEYS = ('prim_cell', 'concentration')

KWARG_KEYS = ('size', 'supercell_factor', 'db_name', 'max_cluster_dia', 'include_background_atoms', 'basis_func_type')

OTHER_KEYS = ('skew_threshold', 'kwargs')

__init__(prim: Atoms, concentration: Concentration | dict, size: List[int] | None = None, supercell_factor: int | None = 27, db_name: str = 'clease.db', max_cluster_dia: Sequence[float] = (5.0, 5.0, 5.0), include_background_atoms: bool = False, basis_func_type='polynomial') → None

property all_cf_names: List[str]

property all_elements: List[str]

property atomic_concentration_ratio: float

Ratio between true concentration (normalised to atoms) and the internal concentration used. For example, if one of the two basis is fully occupied, and hence ignored internally, the internal concentration is half of the actual atomic concentration.

property atoms: Atoms

The currently active template.

property background_indices: List[int]

Get indices of the background atoms.

property basis_func_type

property basis_functions

clear_cache() → None

Clear the cached objects, due to a change e.g. in the template atoms

clease_objtype = 'ce_settings'

property cluster_list: ClusterList

Get the cluster list, will be created upon request

property cluster_mng

clusters_table() → str

String with information about the clusters

connect(**kwargs) → Database

Return the ASE connection object to the internal database.

create_cluster_list_and_trans_matrix()

Prepares the internal cache objects by calculating cluster related properties

property db_name: str

Name of the underlaying data base.

ensure_clusters_exist() → None

Ensure the cluster list and trans matrix has been populated. They are not calculated upon creaton of the settings instance, for performance reasons. They will be constructed if required. Nothing is done if the cache exists.

classmethod from_dict(dct: Dict[str, Any]) → ClusterExpansionSettings

Load a new ClusterExpansionSettings class from a dictionary representation.

Example

>>> from clease.settings import CEBulk, Concentration, ClusterExpansionSettings
>>> conc = Concentration([['Au', 'Cu']])
>>> settings = CEBulk(conc, crystalstructure='fcc', a=4.1)
>>> dct = settings.todict()  # Get the dictionary representation
>>> # Remove the existing settings, perhaps due to being in a new environment
>>> del settings
>>> # Load in the settins from the dictionary representation
>>> settings = ClusterExpansionSettings.from_dict(dct)

get_active_sublattices() → List[bool]

List of booleans indicating if a (grouped) sublattice is active

get_all_figures_as_atoms() → List[Atoms]

Get the list of all possible figures, in their ASE Atoms representation.

get_all_templates()

Return a list with all template atoms

get_bg_syms() → Set[str]

Return the symbols in the basis where there is only one element

get_cluster_corresponding_to_cf_name(cf_name: str) → Cluster

Find the Cluster object which corresponds to a CF name. The cluster will not be specialized to the decoration number if such exists in the cf name.

Example

>>> from clease.settings import CEBulk, Concentration
>>> conc = Concentration([['Au', 'Cu']])
>>> settings = CEBulk(conc, crystalstructure='fcc', a=4.1)
>>> cluster = settings.get_cluster_corresponding_to_cf_name("c1_0")
>>> cluster.size
1

get_prim_cell_id(write_if_missing=False) → int

Retrieve the ID of the primitive cell in the database. Raises a PrimitiveCellNotFound error if it is not found and write_if_missing is False. If write_if_missing is True a primitive cell is written to the database if it is missing.

Returns the ID (an integer) of the row which corresponds to the primitive cell.

get_sublattice_site_ratios() → ndarray

Return the ratios of number of sites per (grouped) sublattice

property ignore_background_atoms: bool

property ignored_species_and_conc: Dict[str, float]

Return the ignored species and their concentrations normalised to the total number of atoms.

property include_background_atoms: bool

property index_by_basis: List[List[int]]

property index_by_sublattice: List[List[int]]

classmethod load(fd, **kwargs)

Method for loading class object from JSON

property max_cluster_dia: ndarray

The maximum cluster diameter, expressed in a NumPy array starting from 2-body clusters at index 0. Diameters are given in units of Ångstrom.

property max_cluster_size

property multiplicity_factor: Dict[str, float]

Return the multiplicity factor of each cluster.

property non_background_indices: List[int]

Indices of sites which are not background

property num_active_sublattices: int

Number of active sublattices

property num_basis: int

property num_cf: int

Return the number of correlation functions.

property num_elements: int

property num_unique_elements: int

prepare_new_active_template(template)

Prepare necessary data structures when setting new template.

property prim_cell: Atoms

The primitive atoms object of the model.

property ref_index_trans_symm: List[int]

requires_build() → bool

Check if the cluster list and trans matrix exist. Returns True the cluster list and trans matrix needs to be built.

save(fd)

Method for writing class object to a JSON file.

set_active_template(atoms=None)

Set a new template atoms object.

property size: ndarray | None

property skew_threshold

property spin_dict: Dict[str, float]

property supercell_factor: int | None

property template_atoms: TemplateAtoms

todict() → Dict

Return a dictionary representation of the settings class.

Example

>>> from clease.settings import CEBulk, Concentration
>>> conc = Concentration([['Au', 'Cu']])
>>> settings = CEBulk(conc, crystalstructure='fcc', a=4.1)
>>> dct = settings.todict()  # Get the dictionary representation

property trans_matrix: TransMatrix

Get the translation matrix, will be created upon request

unique_element_without_background()

Remove background elements.

property unique_elements: List[str]

view_clusters() → None

Display all clusters along with their names.

view_templates()

Display all templates in the ASE GUi

clease.settings.CEBulk(concentration: Concentration, crystalstructure='sc', a=None, c=None, covera=None, u=None, **kwargs)

Specify cluster expansion settings for bulk materials defined based on crystal structures.

Parameters:

• concentration (Union[Concentration, dict]) – Concentration object or dictionary specifying the basis elements and concentration range of constituting species

• crystalstructure (str) – Must be one of sc, fcc, bcc, hcp, diamond, zincblende, rocksalt, cesiumchloride, fluorite or wurtzite.

• a (float) – Lattice constant.

• c (float) – Lattice constant.

• covera (float) – c/a ratio used for hcp. Default is ideal ratio: sqrt(8/3).

• u (float) – Internal coordinate for Wurtzite structure.

For more kwargs, see docstring of clease.settings.ClusterExpansionSettings.

clease.settings.CECrystal(concentration: Concentration, spacegroup=1, basis=None, cell=None, cellpar=None, ab_normal=(0, 0, 1), crystal_kwargs=None, **kwargs)

Store CE settings on bulk materials defined based on space group.

Parameters:

• concentration (Union[Concentration, dict]) – Concentration object or dictionary specifying the basis elements and concentration range of constituting species

• spacegroup (int | string | Spacegroup instance) – Space group given either as its number in International Tables or as its Hermann-Mauguin symbol.

• basis (List[float]) – List of scaled coordinates. Positions of the unique sites corresponding to symbols given either as scaled positions or through an atoms instance.

• cell (3x3 matrix) – Unit cell vectors.

• cellpar ([a, b, c, alpha, beta, gamma]) – Cell parameters with angles in degree. Is not used when cell is given.

• ab_normal (vector) – Is used to define the orientation of the unit cell relative to the Cartesian system when cell is not given. It is the normal vector of the plane spanned by a and b.

• crystal_kwargs (dict | None) – Extra kwargs to be passed into the ase.spacegroup.crystal function. Nothing additional is added if None. Defaults to None.

For more kwargs, see docstring of clease.settings.ClusterExpansionSettings.

clease.settings.CESlab(conventional_cell: Atoms | str, miller: Tuple[int], concentration: Concentration, size: Sequence[int] | None = (1, 1, 1), **kwargs) → ClusterExpansionSettings

Parameters:

• conventional_cell – Bulk lattice structure. Note that the unit-cell must be the conventional cell - not the primitive cell. One can also give the chemical symbol as a string, in which case the correct bulk lattice will be generated automatically.

• miller – Surface normal in Miller indices (h,k,l).

• concentration – Class for restricting the concentrations

• size – Size of the simulations cell. The third number represents the number of layers. The two first are repetitions of the in-plane unit vectors

For more kwargs, see docstring of clease.settings.ClusterExpansionSettings.

clease.settings.settings_from_json(fname) → ClusterExpansionSettings

Initialize settings from JSON.

Exists due to compatibility. You should instead use ClusterExpansionSettings.load(fname)

Parameters:

fname: str

JSON file where settings are stored