Structure Generation

Module for generating new structures for training.

class clease.structgen.new_struct.NewStructures(settings: ClusterExpansionSettings, generation_number: int | None = None, struct_per_gen: int = 5, check_db: bool = True)

Generate new structure in ASE Atoms object format.

Parameters:

• settings – Cluster expansion settings.

• generation_number – Generation number to be assigned to the newly generated structure

• struct_per_gen – Number of structures to generate per generation

• check_db – Should a new structure which is being inserted into the database be checked against pre-existing structures? Should only be disabled if you know what you are doing. Default is True.

connect(**kwargs)

Short-cut to access the settings connection.

generate_conc_extrema() → None

Generate initial pool of structures with max/min concentration.

generate_gs_structure(atoms: Atoms | List[Atoms], eci: Dict[str, float], init_temp: float = 2000.0, final_temp: float = 1.0, num_temp: int = 10, num_steps_per_temp: int = 1000, random_composition: bool = False) → None

Generate ground-state structures based on cell sizes and shapes of the passed ASE Atoms.

Parameters:

• atoms – Atoms object with the desired size and composition of the new structure. A list of Atoms with different size and/or compositions can be passed. Compositions of the supplied Atoms object(s) are ignored when random_composition=True.

• eci – cluster names and their ECI values

• init_temp – Initial temperature (does not represent physical temperature)

• final_temp – Final temperature (does not represent physical temperature)

• num_temp – Number of temperatures to use in simulated annealing

• num_steps_per_temp – Number of steps in simulated annealing

• random_composition –

  Whether or not to fix the composition of the generated structure.

  1. False and atoms = Atoms object: One ground-state structure with

     matching size and composition of the supplied Atoms object is generated

  2. False and atoms = list: The same number of ground-state

     structures that matches the length of the list is generated

     • Note 1: num_struct_per_gen is ignored and all of the generated

       structures have the same generation number

     • Note 2: each GS structure will have matching size and

       composition of the suplied Atoms objects

  3. True and atoms = Atoms object: GS structure(s) with a

     matching size of the Atoms object is generated at a random composition (within the composition range specified in Concentration class)

     • Note 1: This will generate GS structures until the number of

       structures with the current generation number equals num_struct_per_gen

     • Note 2: A check is performed to ensure that none of the newly

       generated GS structures have the same composition

  4. True and atoms = list: The same number of GS structures that

     matches the length of the list is generated

     • Note 1: num_struct_per_gen is ignored and all of the generated

       structures have the same generation number

     • Note 2: each GS structure will have matching sizes of the

       supplied Atoms objects but with a random composition

     • Note 3: No check is performed to ensure that all new GS

       structures have unique composition

generate_gs_structure_multiple_templates(eci: Dict[str, float], num_templates: int = 20, num_prim_cells: int = 2, init_temp: float = 2000.0, final_temp: float = 1.0, num_temp: int = 10, num_steps_per_temp: int = 1000) → None

Generate ground-state structures using multiple templates (rather than using fixed cell size and shape). Structures are generated until the number of structures with the current generation_number in database reaches struct_per_gen.

Parameters:

• num_templates – Number of templates to search in. Simmulated annealing is done in each cell and the one with the lowest energy is taken as the ground state.

• num_prim_cells – Number of primitive cells to use when constructing templates. The volume of all the templates used will be num_prim_cells*vol_primitive, where vol_primitive is the volume of the primitive cell.

See docstring of generate_gs_structure for the rest of the arguments.

generate_initial_pool(atoms: Atoms | None = None) → None

Generate initial pool of structures.

Initial pool of structures are generated, in sequence, using

1. generate_conc_extrema(): structures at concentration where the number of consituting elements is at its max/min.

2. generate_random_structures(): random structures are random concentration.

Structures are genereated until the number of structures reaches struct_per_gen.

Parameters:

atoms – If Atoms object is passed, the size and shape of its cell will be used for all the random structures. If None, a randome size and shape will be chosen for each structure.

generate_metropolis_trajectory(atoms: Atoms | None = None, random_comp: bool = True) → None

Generate a set of structures consists of single atom swaps

Parameters:

• atoms – ASE Atoms object that will be used as a template for the trajectory

• random_comp – If ‘True’ the passed atoms object will be initialised with a random composition. Otherwise, the trajectory will start from the passed Atoms object.

generate_one_random_structure(atoms: Atoms | None = None) → bool

Generate and insert a random structure to database if a unique structure is found.

Returns True if unique structure is found and inserted in DB, False otherwise.

Parameters:

atoms – If Atoms object is passed, the passed object will be used as a template for all the random structures being generated. If None, a random template will be chosen. (different for each structure)

generate_probe_structure(atoms: Atoms | None = None, init_temp: float | None = None, final_temp: float | None = None, num_temp: int = 5, num_steps_per_temp: int = 1000, approx_mean_var: bool = True, num_samples_var: int = 10000) → None

Generate a probe structure according to PRB 80, 165122 (2009).

Parameters:

• atoms – ASE Atoms object with the desired cell size and shape of the new structure.

• init_temp – initial temperature (does not represent physical temperature)

• final_temp – final temperature (does not represent physical temperature)

• num_temp – number of temperatures to be used in simulated annealing

• num_steps_per_temp – number of steps in simulated annealing

• approx_mean_var –

  whether or not to use a spherical and isotropical distribution approximation scheme for determining the mean variance.

  -True: Assume a spherical and isotropical distribution of

  structures in the configurational space. Corresponds to eq.4 in PRB 80, 165122 (2009)

  -False: Use sigma and mu of eq.3 in PRB 80, 165122 (2009)

  to characterize the distribution of structures in population. Requires pre-sampling of random structures before generating probe structures. sigma and mu are generated and stored in ‘probe_structure-sigma_mu.npz’ file.

• num_samples_var – number of samples to be used in determining signam and mu. Only used when approx_mean_var is True.

Note: init_temp and final_temp are automatically generated if either

one of the two is not specified.

generate_random_structures(atoms: Atoms | None = None) → None

Generate random structures until the number of structures with generation_number equals struct_per_gen.

Parameters:

atoms – If Atoms object is passed, the passed object will be used as a template for all the random structures being generated. If None, a random template will be chosen. (different for each structure)

insert_structure(init_struct: Atoms | str, final_struct: Atoms | str | None = None, name: str | None = None, cf: Dict[str, float] | None = None, meta: Dict[str, Any] | None = None, warn_on_skip: bool = True) → int | Tuple[int, int] | None

Insert a structure to the database.

Returns the ID of the initial structure which was inserted into the database. If a row for the final structure is also inserted, a tuple of (initial_id, final_id) is returned. If no structure was inserted, Ǹone is returned, instead.

Parameters:

• init_struct – Unrelaxed initial structure. If a string is passed, it should be the file name with .xyz, .cif or .traj extension.

• final_struct – (Optional) final structure that contains energy. It can be either ASE Atoms object or file name readable by ASE.

• name – (Optional) name of the DB entry if a custom name is to be used. If None, default naming convention will be used.

• cf – (Optional) full correlation function of the initial structure (correlation functions with zero values should also be included). If cf is given, the preprocessing of the init_structure is bypassed and the given cf is inserted in DB.

• meta – (Optional) Extra information which will be added to the key-value pair entries in the database.

• warn_on_skip – (Bool, optional) Toggle emitting a warning if a structure was not inserted due to having a symmetrically equivalent structure in the database. Defaults to true.

insert_structures(traj_init: str, traj_final: str | None = None, cb=<function NewStructures.<lambda>>) → None

Insert a sequence of initial and final structures from their trajectory files.

Parameters:

• traj_init – Name of a trajectory file with initial structures

• traj_final – Name of a trajectory file with the final structures

• cb – Callback function that is called every time a structure is inserted (or rejected because it exists before). The signature of the function is cb(num, tot) where num is the number of inserted structure and tot is the total number of structures that should be inserted