Cluster Expansion Settings

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

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

Parameters:

  • concentration (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)[source]

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

Parameters:

  • concentration (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.

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', _allow_direct_instantiation: bool = False)[source]

Base class for all Cluster Expansion settings.

Note

This class should not be instantiated directly. Use one of the factory functions instead: - clease.settings.CEBulk() for bulk materials with crystal structures - clease.settings.CECrystal() for bulk materials with space groups - clease.settings.CESlab() for slab/surface calculations

Parameters:

  • prim (Atoms) – The primitive atoms object.

  • concentration (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’.

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.

clear_cache() → None[source]

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

property cluster_list: ClusterList

Get the cluster list, will be created upon request

clusters_table() → str[source]

String with information about the clusters

connect(**kwargs) → Database[source]

Return the ASE connection object to the internal database.

create_cluster_list_and_trans_matrix()[source]

Prepares the internal cache objects by calculating cluster related properties

property db_name: str

Name of the underlaying data base.

ensure_clusters_exist() → None[source]

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[source]

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][source]

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

get_all_figures_as_atoms() → list[Atoms][source]

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

get_all_templates()[source]

Return a list with all template atoms

get_bg_syms() → set[str][source]

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

get_cluster_corresponding_to_cf_name(cf_name: str) → Cluster[source]

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[source]

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[source]

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

property ignored_species_and_conc: dict[str, float]

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

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 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_cf: int

Return the number of correlation functions.

prepare_new_active_template(template)[source]

Prepare necessary data structures when setting new template.

property prim_cell: Atoms

The primitive atoms object of the model.

requires_build() → bool[source]

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)[source]

Set a new template atoms object.

todict() → dict[source]

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()[source]

Remove background elements.

view_clusters() → None[source]

Display all clusters along with their names.

view_templates()[source]

Display all templates in the ASE GUi

clease.settings.settings_from_json(fname) → ClusterExpansionSettings[source]

Initialize settings from JSON.

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

Parameters:

fname: str

JSON file where settings are stored

I/O helpers for CLEASE.

clease.io.cecrystal_from_cif(cif_path: str | Path, concentration: Concentration, *, index: int | str = 0, infer_spacegroup: bool = True, symprec: float = 0.001, spacegroup_override: int | str | None = None, **ce_kwargs: Any)[source]

Build CECrystal from a CIF file.

This is the convenience wrapper for CIF-driven settings creation. The CIF file contributes geometry (cell + basis positions) and spacegroup information. Concentration must be passed explicitly.

This function does not infer concentration constraints from CIF occupancy. For disordered systems, first call read_cif(...) to inspect symbols and metadata, then build Concentration(basis_elements=..., grouped_basis=...) from your model assumptions, and finally call cecrystal_from_cif(..., concentration=con, spacegroup_override=...).

Parameters:

  • cif_path – Path to input CIF file.

  • concentration – User-defined concentration model for all basis sites.

  • index – CIF structure index passed to ASE read.

  • infer_spacegroup – Try spglib inference when CIF info is incomplete.

  • symprec – Tolerance used by spglib inference.

  • spacegroup_override – Explicit SG value to use instead of inferred/parsed.

  • **ce_kwargs – Extra keyword args forwarded to CECrystal.

Returns:

Cluster expansion settings object created by CECrystal(…).

Raises:

ValueError – If no valid spacegroup is available and no override is given.

clease.io.read_cif(path: str | Path, index: int | str = 0, infer_spacegroup: bool = True, symprec: float = 0.001) → tuple[Atoms, dict[str, Any]][source]

Read one CIF structure and return (atoms, metadata).

The returned Atoms is normalized with CLEASE’s wrapped/sorted convention. Metadata is intended to support manual concentration setup before calling cecrystal_from_cif(…).

Metadata includes cellpar, spacegroup_number, spacegroup_symbol, occupancy diagnostics, and collected warnings. This reader does not translate partial occupancy into concentration constraints. Use the metadata as guidance and build Concentration explicitly in your setup code.

Parameters:

  • path – Path to input CIF file.

  • index – CIF structure index passed to ASE read.

  • infer_spacegroup – Will try spglib inference when CIF info is incomplete.

  • symprec – Tolerance used by spglib inference.

Returns:

Tuple of (atoms, metadata).

Raises:

ValueError – If CIF reading fails.

An Example

In many workflows, the CIF file is used only to define the parent crystal structure (lattice, positions, and spacegroup), while concentration constraints are defined explicitly by the user in CLEASE. This is especially useful for partially occupied or mixed-site systems where occupancy values in the CIF should not directly become model constraints.

The example below shows a typical flow: 1) read the CIF with read_cif(...) and inspect metadata, 2) build a manual Concentration from your chemistry assumptions, 3) construct settings with cecrystal_from_cif(...) using that concentration.

from clease.io import read_cif, cecrystal_from_cif
from clease.settings import Concentration

cif_path = "my_structure.cif"
atoms, meta = read_cif(cif_path, infer_spacegroup=True)
# Build manual concentration model
symbols = [a.symbol for a in atoms]
# Define allowed species per current symbol.
allowed = {
   "Li": ["X", "Li"],
   "Ti": ["Ti", "Sn"],
   "Sn": ["Ti", "Sn"],
   "P": ["P"],
   "O": ["O"],
}
basis_elements = [allowed.get(a.symbol, [a.symbol]) for a in atoms]
# Group indices by identical allowed-species list.
groups = {}
for i, be in enumerate(basis_elements):
   groups.setdefault(tuple(be), []).append(i)

con = Concentration(
   basis_elements=basis_elements,
   grouped_basis=list(groups.values()),
)
# Step 3: Build CECrystal from the cif file and stated concentration
settings = cecrystal_from_cif(
   cif_path=cif_path,
   concentration=con,  # explicit concentration overrides default
   spacegroup_override=meta["spacegroup_number"],  # fallback-safe
   size=[(3, 0, 0), (0, 2, 0), (0, 0, 2)],
   max_cluster_dia=[10, 8, 5],
)
...