seibuilder.core package

Core subpackage with SEI builder functions.

It contains functions for getting SEI’s salts crystal unit cells, building grains, and identifying the atoms at the boundary.

from_d_to_grain(d: ndarray, generator: Structure, planes: list, surface_energies: list, maxiter: int = 20, tol: float = 0.05, timeout: int = 60, verbose: int = 0) → Tuple[int, float, float, float, Atoms]

Get iterative the closest grain given a characteristic size.

Parameters:

• d (np.ndarray) – target characteristic size

• generator (pymatgen.Structure) – pymatgen.Structure represents the crystal unit cells.

• planes (list) – List of Miller indices corresponding to the cutting planes to use.

• surface_energies (list) – surface energy corresponds to each planes

• maxiter (int, optional) – maximum iteration number for the secant algorithm. Defaults to 20.

• tol (float, optional) – convergence tolerance. Defaults to 0.05.

• timeout (int, optional) – max waiting time in seconds. Defaults to 60.

• verbose (int, optional) – loudness controller: - 0: print errors - 1: print errors and warnings - 2: print errors, warnings and info - 3: print errors, warnings, info and debugger messages. Defaults to 2.

Returns:

tuple containing:

Tuple[int, float, float, float, Atoms]: tuple containg:

• int: number of atoms for the optimal grain

• float: grain volume

• float: grain caracteristic lenght

• float: maximum radium

• ASE.Atoms: computed grain

Return type:

Tuple[int, float, float, float, Atoms]

get_gcd_pedices(formula: str) → int

Get the greatest common divisor (GCD) from number of each atom type in a empirical chemical formula.

Parameters:

formula (str) – empirical chemical formula (e.g. Glucose: C6H12O6 ).

Returns:

the greatest common divisor from number of each atom type.

Return type:

int

get_stable_crystal(chem_formula: str) → Tuple[Atoms, Structure]

Get the stable crystal unit-cell from its chemical formula.

Download from Materials Project the cristal file for a given chemical formula. If in the database are present metastables configuration, the one with the “minimum formation energy per atom” is chosen.

Parameters:

chem_formula (str) – Cristal chemical formula (e.g. LiF)

Returns:

tuple containing:

• Strcuture: crystal unit as pymatgen object

• Atoms: crystal unit as ASE object

Return type:

(tuple)

random_sei_grains(Natoms: int, species_unitcell: List[Structure], species_fractions: list, random_sampler: List[Callable], species_fraction_tol: float = 0.005, Ngrains_max: int | None = None, report: str | None = None, cutting_planes: list | None = None, n_planes: int = 2, seed: int | None = None) → Tuple[ndarray, ndarray, ndarray, ndarray, List[Atoms]]

Get the different grains knowing the size distribution, cutting planes, and molar fraction.

The function random generates a grain knowing the crystal unit cell and the grain size distribution. The sampling is constrained to get the final number of atoms close to Natoms and to respect the molar fraction of each component (species_fractions). :param Natomas: Max number of atoms to sample. :type Natomas: int :param species_unitcell: list containing pymatgen.Structure objects that represent :type species_unitcell: List[Structure] :param the unit cells of each SEI crystal component.: :param species_fractions: The molar fraction for each crystal. :type species_fractions: list :param random_sampler: list containing the size distribution functions, i.e., a callable

object that returns the characteristic grain size (diameter).

Parameters:

• species_fraction_tol (float, optional) – tolerance for final molar fraction. Defaults to 0.005.

• Ngrains_max (int, optional) – Max number of atoms for each grain, if None will be set as 1/10 of Natoms. Defaults to None.

• report (str | None, optional) – report .csv file name. If None, the report will be saved in the file report_grains_sei.csv. Defaults to None.

• cutting_planes (list | None, optional) – list of Miller indices corresponding to the cutting planes to use.

• None. (Defaults to) –

• n_planes (int, optional) – number of planes to randomly choose from cutting_planes. Defaults to 2.

• seed (int, optional) – random state seed for the random number generator. Defaults to None.

Returns:

tuple containing:

• NumPy.ndarray: an array containing the index of the cristal sampled.

• NumPy.ndarray: an array containing grain size sampled.

• NumPy.ndarray: an array containing grain volume computed as the “convex hull” volume from the atoms’ positions.

• NumPy.ndarray: array with the final molar fraction for each cristal.

• NumPy.ndarray[Atoms]: a list containing ASE.Atoms are the random grains generated.

Return type:

Tuple[numpy.ndarray, NumPy.ndarray, NumPy.ndarray, NumPy.ndarray, List[Atoms]]

Submodules

This is the SEI builder functions module.

It contains functions for getting SEI’s salts crystal unit cells, building grains, and identifying the atoms at the boundary.

from_d_to_grain(d: ndarray, generator: Structure, planes: list, surface_energies: list, maxiter: int = 20, tol: float = 0.05, timeout: int = 60, verbose: int = 0) → Tuple[int, float, float, float, Atoms]

Get iterative the closest grain given a characteristic size.

Parameters:

• d (np.ndarray) – target characteristic size

• generator (pymatgen.Structure) – pymatgen.Structure represents the crystal unit cells.

• planes (list) – List of Miller indices corresponding to the cutting planes to use.

• surface_energies (list) – surface energy corresponds to each planes

• maxiter (int, optional) – maximum iteration number for the secant algorithm. Defaults to 20.

• tol (float, optional) – convergence tolerance. Defaults to 0.05.

• timeout (int, optional) – max waiting time in seconds. Defaults to 60.

• verbose (int, optional) – loudness controller: - 0: print errors - 1: print errors and warnings - 2: print errors, warnings and info - 3: print errors, warnings, info and debugger messages. Defaults to 2.

Returns:

tuple containing:

Tuple[int, float, float, float, Atoms]: tuple containg:

• int: number of atoms for the optimal grain

• float: grain volume

• float: grain caracteristic lenght

• float: maximum radium

• ASE.Atoms: computed grain

Return type:

Tuple[int, float, float, float, Atoms]

get_bulk_atoms(atoms: Atoms, threshold: float = 0.6, cutoff: float = 7.5) → Tuple[ndarray, ndarray]

Identify the atoms in bulk or at the surface.

Parameters:

• atoms (Atoms) – system to analyze as ASE.Atoms object.

• threshold (float, optional) – relative coordination threshold. If the scaled coordination number of atoms is above the threshold is identified as a bulk atom. Defaults to 0.6.

• cutoff (float, optional) – cutoff radius for each atom. Defaults to 7.5.

Returns:

tuple containing:

• Numpy.ndarray: boolean array with True the bulk atoms and False the surface atoms.

• Numpy.ndarray : an array containing the scaled coordination number.

Return type:

Tuple[Numpy.ndarray, Numpy.ndarray]

get_gcd_pedices(formula: str) → int

Get the greatest common divisor (GCD) from number of each atom type in a empirical chemical formula.

Parameters:

formula (str) – empirical chemical formula (e.g. Glucose: C6H12O6 ).

Returns:

the greatest common divisor from number of each atom type.

Return type:

int

get_materials_ids(formula: str) → List[str]

Given a chemical formula retrive the MP ids.

Parameters:

formula (str) – Chemical formulas

Returns:

list of MP ids with that specific chemical formula

Return type:

List[str]

get_stable_crystal(chem_formula: str) → Tuple[Atoms, Structure]

Get the stable crystal unit-cell from its chemical formula.

Download from Materials Project the cristal file for a given chemical formula. If in the database are present metastables configuration, the one with the “minimum formation energy per atom” is chosen.

Parameters:

chem_formula (str) – Cristal chemical formula (e.g. LiF)

Returns:

tuple containing:

• Strcuture: crystal unit as pymatgen object

• Atoms: crystal unit as ASE object

Return type:

(tuple)

get_structure_by_material_id(material_ids: List[str]) → List[Structure]

Given a list of the MP ids it retrive the associated Stucture.

Parameters:

material_ids (List[str]) – List of MP ids

Returns:

List containg the structures

Return type:

List[Structure]

random_sei_grains(Natoms: int, species_unitcell: List[Structure], species_fractions: list, random_sampler: List[Callable], species_fraction_tol: float = 0.005, Ngrains_max: int | None = None, report: str | None = None, cutting_planes: list | None = None, n_planes: int = 2, seed: int | None = None) → Tuple[ndarray, ndarray, ndarray, ndarray, List[Atoms]]

Get the different grains knowing the size distribution, cutting planes, and molar fraction.

The function random generates a grain knowing the crystal unit cell and the grain size distribution. The sampling is constrained to get the final number of atoms close to Natoms and to respect the molar fraction of each component (species_fractions). :param Natomas: Max number of atoms to sample. :type Natomas: int :param species_unitcell: list containing pymatgen.Structure objects that represent :type species_unitcell: List[Structure] :param the unit cells of each SEI crystal component.: :param species_fractions: The molar fraction for each crystal. :type species_fractions: list :param random_sampler: list containing the size distribution functions, i.e., a callable

object that returns the characteristic grain size (diameter).

Parameters:

• species_fraction_tol (float, optional) – tolerance for final molar fraction. Defaults to 0.005.

• Ngrains_max (int, optional) – Max number of atoms for each grain, if None will be set as 1/10 of Natoms. Defaults to None.

• report (str | None, optional) – report .csv file name. If None, the report will be saved in the file report_grains_sei.csv. Defaults to None.

• cutting_planes (list | None, optional) – list of Miller indices corresponding to the cutting planes to use.

• None. (Defaults to) –

• n_planes (int, optional) – number of planes to randomly choose from cutting_planes. Defaults to 2.

• seed (int, optional) – random state seed for the random number generator. Defaults to None.

Returns:

tuple containing:

• NumPy.ndarray: an array containing the index of the cristal sampled.

• NumPy.ndarray: an array containing grain size sampled.

• NumPy.ndarray: an array containing grain volume computed as the “convex hull” volume from the atoms’ positions.

• NumPy.ndarray: array with the final molar fraction for each cristal.

• NumPy.ndarray[Atoms]: a list containing ASE.Atoms are the random grains generated.

Return type:

Tuple[numpy.ndarray, NumPy.ndarray, NumPy.ndarray, NumPy.ndarray, List[Atoms]]