pyxtal.lego.builder module

The builder aims to generate crystal structure from the defined building blocks (e.g., SiO2 with 4-coordined Si and 2-coordinated O) 1. Generate all possible wp combinations 2. For each wp combination,

2.1 generate structure randomly 2.2 optimize the geomtry 2.3 parse the coordination 2.4 save the qualified structure to ase.db

Todo: 1. Symmetry support for dSdX 2. add parallel for gulp optimiza

class pyxtal.lego.builder.RandomDispBounds(xmin, xmax, id1, id2, stepsize=0.1, dumpfile=None)

Bases: object

random displacement with bounds: see: https://stackoverflow.com/a/21967888/2320035

class pyxtal.lego.builder.builder(elements, composition, dim=3, prefix='mof', db_file=None, log_file=None, rank=0, verbose=False)

Bases: object

Class for generating structures with desired local environments

Parameters:

• elements (str) – e.g. [‘Si’, ‘O’]

• composition (int) – e.g. [1, 2]

• dim (int) – e.g., 0, 1, 2, 3

• db_file (str) – default is ‘mof.db’

• log_file (str) – default is ‘mof.log’

Examples

To create a new structure instance

>>> from pyxtal.lego.builder import builder
>>> bu = builder(['P', 'O', 'N'], [1, 1, 1], db_file='PON.db')

generate_xtal(spg, wps, niter, T=0.2, N_max=5, early_quit=0.03, dump=False, verbose=None, add_db=True, random_state=None)

Generate a crystal with the desired local environment

Parameters:

• spg (int) – group number

• wps (list) – list of wps for the disired crystal (e.g., [spg, wp1, wp2])

• n_iter (int) – number of iterations for basin hopping

• T (float) – for basinhopping

• N_max (int) – number of maximum

• early_quit (float) – threshhold for early termination

• dump (bool) – whether or not dump the trajectory

generate_xtals_from_wp_libs(wp_libs, N_max=5, ncpu=1, T=0.2, factor=5, early_quit=0.02)

Run multiple crystal generation from the given wp_libs This is the core part for structure generation.

Parameters:

• wp_libs (tuple) – (number, spg, wps, dof)

• N_max (int) – Number of maximum runs

• ncpu (int) – Num of parallel processes

• T (float) – basinhopping temperature

• factor (int) – the number of Basinhopping iterations = factor * dof

• early_quit (float) – early termination for basinhopping

get_input_from_letters(spg, wps)

A short cut to get (spg, wps, dof) from the get_input functions

Parameters:

• spg (int) – space group number 1-230

• wps (list) – e.g. [[‘4a’, ‘4b’]]

get_input_from_ref_xtal(xtal, substitute=None)

Generate the input from a given pyxtal

Parameters:

• xtal – pyxtal object

• substitute – a dictionary to describe chemical substitution

get_similarity(xtal)

Compute the similrity for a given xtal QZ: call calculate_S()

Parameters:

xtal – pyxtal object

Returns:

the similarity value .w.r.t the reference environment

get_wp_libs_from_spglist(spg_list, num_wp=(None, None), num_fu=(None, None), num_dof=(1, 10), per_spg=30, ncpu=1)

Generate wp choices from the list of space groups

Parameters:

• spglist (list) – list of space group numbers

• num_wp (int) – a tuple of (min_wp, max_wp)

• num_fu (int) – a tuple of (min_fu, max_fu)

• num_dof (int) – a tuple of (min_dof, max_dof)

• per_spg (int) – maximum number of wp combinations

• ncpu (int) – number of processors

get_wp_libs_from_xtals(db_file=None, num_wp=(None, None), num_dof=(1, 20), num_atoms=[1, 500])

For each struc in the database, get the (spg, wp) info

Parameters:

• df_file (str) – database file

• num_wp (int) – tuple of (min_wp, max_wp)

• num_dof (int) – tuple of (min_dof, max_dof)

• num_atoms (int) – tuple of (min_at, max_at)

import_structures(db_file, ids=(None, None), check=True, same_group=True, spglist=range(1, 231), bounds=[1, 500], relax=True)

Import the structures from the external ase database

Parameters:

• db_file (str) – ase database

• check (boolean) – whether or not

• spglist (int) – list of spg numbers

• bounds – number of atoms

• energy (boolean) – add energy or not

optimize_reps(reps, ncpu=1, opt_type='local', T=0.2, niter=20, early_quit=0.02, add_db=True, symmetrize=False, minimizers=[('Nelder-Mead', 100), ('L-BFGS-B', 100)], N_grids=None)

Perform optimization for each structure

Parameters:

• reps – list of reps

• ncpu (int)

optimize_reps_mproc(reps, ncpu, args, N_grids)

Optimization in multiprocess mode.

Parameters:

• reps – list of reps

• ncpu (int) – number of parallel python processes

• args – (opt_type, T, n_iter, early_quit, add_db, symmetrize, minimizers)

optimize_reps_serial(reps, args, N_grids)

Optimization in multiprocess mode.

Parameters:

• reps – list of reps

• ncpu (int) – number of parallel python processes

• args – (opt_type, T, n_iter, early_quit, add_db, symmetrize, minimizers)

optimize_xtal(xtal, count=0, opt_type='local', T=0.2, niter=20, early_quit=0.02, add_db=True, symmetrize=False, minimizers=[('Nelder-Mead', 100), ('L-BFGS-B', 100)], filename=None)

Further optimize the input xtal w.r.t reference environment

Parameters:

xtal (instance) – pyxtal

optimize_xtals(xtals, ncpu=1, opt_type='local', T=0.2, niter=20, early_quit=0.02, add_db=True, symmetrize=False, minimizers=[('Nelder-Mead', 100), ('L-BFGS-B', 100)])

Perform optimization for each structure

Parameters:

• xtals – list of xtals

• ncpu (int)

optimize_xtals_mproc(xtals, ncpu, args)

Optimization in multiprocess mode.

Parameters:

• xtals – list of xtals

• ncpu (int) – number of parallel python processes

• args – (opt_type, T, n_iter, early_quit, add_db, symmetrize, minimizers)

optimize_xtals_serial(xtals, args)

Optimization in serial mode.

Parameters:

• xtals – list of xtals

• args – (opt_type, T, n_iter, early_quit, add_db, symmetrize, minimizers)

print_memory_usage()

process_xtal(xtal, sim, count=0, xs=None, energy=None, topology=None, same_group=True, db=None, check=False)

Check, print and add xtal to the database

Parameters:

• xtal – pyxtal object

• sim – list of two similarity numbers

• count (int) – id of the structure in the database

• xs (tuple) – list of reps before and after optimization

• energy (float) – the energy value

• same_group (bool) – keep the same group or not

• db (str) – db path

• check (bool) – whether or not check if the structure is a duplicate

process_xtals(xtals, xs, add_db, symmetrize)

set_criteria(CN=None, dimension=None, min_density=None, exclude_ii=False)

define the criteria to check if a structure is good

Parameters:

• CN (int) – coordination number

• dimension (int) – target dimensionality (e.g. we want the 3D structure)

• min_density (float) – minimum density

• exclude_ii (bool) – allow the bond between same element

set_descriptor_calculator(dtype='SO3', mykwargs={})

Set up the calculator for descriptor computation. Here we mostly use the pyxtal_ff module

Arg:

dytpe (str): only SO3 is suppoted now

set_reference_enviroments(cif_file, substitute=None)

Get the reference enviroments

Parameters:

• cif_file (str) – cif structure

• substitute (dict) – substitution directory

pyxtal.lego.builder.generate_wp_lib_par(spgs, composition, num_wp, num_fu, num_dof)

A wrapper to generate the wp list in parallel

pyxtal.lego.builder.generate_xtal(dim, spg, wps, niter, elements, calculator, ref_environments, criteria, T, N_max, early_quit, dump=False, random_state=None, verbose=False)

Generate a crystal with the desired local environment

Parameters:

• dim (int) – 1, 2, 3

• spg – pyxtal.symmetry.Group object

• wps – list of wps for the disired crystal (e.g., [wp1, wp2])

• ref_env – reference enviroment

• f – callable function to compute env

• n_iter (int)

• T (float) – for basinhopping

Returns:

xtal and its similarity

pyxtal.lego.builder.generate_xtal_par(wp_libs, niter, dim, elements, calculator, ref_environments, criteria, T, N_max, early_quit)

A wrapper to call generate_xtal function in parallel

pyxtal.lego.builder.minimize_from_x(x, dim, spg, wps, elements, calculator, ref_environments, T=0.2, niter=20, early_quit=0.02, opt_type='local', minimizers=[('Nelder-Mead', 100), ('L-BFGS-B', 100)], filename='local_opt_data.txt', random_state=None, derivative=False)

Generate xtal from the 1d representation

Parameters:

• x – list of 1D array

• spg (int) – space group number (1-230)

• wps (string) – e.g. [[‘4a’, ‘8b’]]

• elements (string) – e.g., [‘Si’, ‘O’]

pyxtal.lego.builder.minimize_from_x_par(*args)

A wrapper to call minimize_from_x function in parallel