qmcblip.flare package

FLARE

class qmcblip.flare.C_OTF(*args, **kwargs)[source]

Bases: flare.otf.OTF

Trains a Gaussian process force field on the fly during molecular dynamics.

Parameters

  • dt (float) – MD timestep.

  • number_of_steps (int) – Number of timesteps in the training simulation.

  • prev_pos_init ([type], optional) – Previous positions. Defaults to None.

  • rescale_steps (List[int], optional) – List of frames for which the velocities of the atoms are rescaled. Defaults to [].

  • rescale_temps (List[int], optional) – List of rescaled temperatures. Defaults to [].

  • gp (gp.GaussianProcess) – Initial GP model.

  • calculate_energy (bool, optional) – If True, the energy of each frame is calculated with the GP. Defaults to False.

  • calculate_efs (bool, optional) – If True, the energy and stress of each frame is calculated with the GP. Defaults to False.

  • write_model (int, optional) – If 0, write never. If 1, write at end of run. If 2, write after each training and end of run. If 3, write after each time atoms are added and end of run. If 4, write after each training and end of run, and back up after each write.

  • force_only (bool, optional) – If True, only use forces for training. Default to False, use forces, energy and stress for training.

  • std_tolerance_factor (float, optional) – Threshold that determines when DFT is called. Specifies a multiple of the current noise hyperparameter. If the epistemic uncertainty on a force component exceeds this value, DFT is called. Defaults to 1.

  • skip (int, optional) – Number of frames that are skipped when dumping to the output file. Defaults to 0.

  • init_atoms (List[int], optional) – List of atoms from the input structure whose local environments and force components are used to train the initial GP model. If None is specified, all atoms are used to train the initial GP. Defaults to None.

  • output_name (str, optional) – Name of the output file. Defaults to ‘otf_run’.

  • max_atoms_added (int, optional) – Number of atoms added each time DFT is called. Defaults to 1.

  • freeze_hyps (int, optional) – Specifies the number of times the hyperparameters of the GP are optimized. After this many updates to the GP, the hyperparameters are frozen. Defaults to 10.

  • min_steps_with_model (int, optional) – Minimum number of steps the model takes in between calls to DFT. Defaults to 0.

  • force_source (Union[str, object], optional) – DFT code used to calculate ab initio forces during training. A custom module can be used here in place of the DFT modules available in the FLARE package. The module must contain two functions: parse_dft_input, which takes a file name (in string format) as input and returns the positions, species, cell, and masses of a structure of atoms; and run_dft_par, which takes a number of DFT related inputs and returns the forces on all atoms. Defaults to “qe”.

  • npool (int, optional) – Number of k-point pools for DFT calculations. Defaults to None.

  • mpi (str, optional) – Determines how mpi is called. Defaults to “srun”.

  • dft_loc (str) – Location of DFT executable.

  • dft_input (str) – Input file.

  • dft_output (str) – Output file.

  • dft_kwargs ([type], optional) – Additional arguments which are passed when DFT is called; keyword arguments vary based on the program (e.g. ESPRESSO vs. VASP). Defaults to None.

  • store_dft_output (Tuple[Union[str,List[str]],:obj:str], optional) – After DFT calculations are called, copy the file or files specified in the first element of the tuple to a directory specified as the second element of the tuple. Useful when DFT calculations are expensive and want to be kept for later use. The first element of the tuple can either be a single file name, or a list of several. Copied files will be prepended with the date and time with the format ‘Year.Month.Day:Hour:Minute:Second:’.

  • n_cpus (int, optional) – Number of cpus used during training. Defaults to 1.

run()[source]

Performs an on-the-fly training run.

If OTF has store_dft_output set, then the specified DFT files will be copied with the current date and time prepended in the format ‘Year.Month.Day:Hour:Minute:Second:’.

initialize_train()[source]
class qmcblip.flare.C_ASE_OTF(atoms, timestep, number_of_steps, dft_calc, md_engine, md_kwargs, update_settings, calculator=None, trajectory=None, **otf_kwargs)[source]

Bases: flare.ase.otf.ASE_OTF, qmcblip.flare.otf.C_OTF

On-the-fly training module using ASE MD engine, a subclass of OTF.

Parameters

  • atoms (ASE Atoms) – the ASE Atoms object for the on-the-fly MD run.

  • timestep (float) – the timestep in MD. Please use ASE units, e.g. if the timestep is 1 fs, then set timestep = 1 * units.fs

  • number_of_steps (int) – the total number of steps for MD.

  • dft_calc (ASE Calculator) – any ASE calculator is supported, e.g. Espresso, VASP etc.

  • md_engine (str) – the name of MD thermostat, only VelocityVerlet, NVTBerendsen, NPTBerendsen, NPT and Langevin, NoseHoover are supported.

  • md_kwargs (dict) – specify the args for MD as a dictionary, the args are as required by the ASE MD modules consistent with the md_engine.

  • update_settings (List[List[dict]]) – array containg CHAMP simulation parameters to update.

  • calculator (Calculator) –

    ASE calculator.

    Must have “get_uncertainties” method

    implemented.

  • trajectory (ASE Trajectory) – default None, not recommended, currently in experiment.

The following arguments are for on-the-fly training, the user can also refer to flare.otf.OTF

Parameters

  • prev_pos_init ([type], optional) – Previous positions. Defaults to None.

  • rescale_steps (List[int], optional) – List of frames for which the velocities of the atoms are rescaled. Defaults to [].

  • rescale_temps (List[int], optional) – List of rescaled temperatures. Defaults to [].

  • calculate_energy (bool, optional) – If True, the energy of each frame is calculated with the GP. Defaults to False.

  • write_model (int, optional) – If 0, write never. If 1, write at end of run. If 2, write after each training and end of run. If 3, write after each time atoms are added and end of run. If 4, write after each training and end of run, and back up after each write.

  • std_tolerance_factor (float, optional) – Threshold that determines when DFT is called. Specifies a multiple of the current noise hyperparameter. If the epistemic uncertainty on a force component exceeds this value, DFT is called. Defaults to 1.

  • skip (int, optional) – Number of frames that are skipped when dumping to the output file. Defaults to 0.

  • init_atoms (List[int], optional) – List of atoms from the input structure whose local environments and force components are used to train the initial GP model. If None is specified, all atoms are used to train the initial GP. Defaults to None.

  • output_name (str, optional) – Name of the output file. Defaults to ‘otf_run’.

  • max_atoms_added (int, optional) – Number of atoms added each time DFT is called. Defaults to 1.

  • freeze_hyps (int, optional) – Specifies the number of times the hyperparameters of the GP are optimized. After this many updates to the GP, the hyperparameters are frozen. Defaults to 10.

  • n_cpus (int, optional) – Number of cpus used during training. Defaults to 1.

md_step(forces=None)[source]

Perform an MD step.

Get new position in molecular dynamics based on the forces predicted by FLARE_Calculator or DFT calculator

Parameters

forces (List[float]) – array containing the forces as calculated by CHAMP (or FLARE).

class qmcblip.flare.Analyze(file)[source]

Bases: object

Tool for analyzing OTF data.

Parameters

file (Path) – otf file to analyze.

results

dictionary containing simulation results.

Type

dict

to_xyz(filename='')[source]

Create an .xyz format file from the OTF trajectory.

Parameters

filename (str) – filename for the .xyz file (include extension).

get_data()[source]

Retrieve the data from the OTF file.

Note

The data will be stores in the results attributes. Allowed keys are: times, potential energy, kinetic energy, total energy, temperature.

plot_energy(filename='')[source]

Plot the energy

Parameters

filename (str) – file to save the energy plot to (leave empty if not wanted).

plot_temperature(filename='')[source]

Plot the temperature

Parameters

filename (str) – file to save the temperature plot to (leave empty if not wanted).

class qmcblip.flare.CustomVerlet(atoms, timestep=None, trajectory=None, logfile=None, loginterval=1, dt=None, append_trajectory=False)[source]

Bases: ase.md.verlet.VelocityVerlet

Custom Verlet scheme for ASE and FLARE.

step(forces=None)[source]

this needs to be implemented by subclasses

class qmcblip.flare.OTFSettings(*, theory: qmcblip.flare.quicksim.OTFSettings.Theory = FLARE(kernels=['twobody', 'threebody'], cutoffs=[5.0, 3.5], random=True, hyp_labels=['sig2', 'ls2', 'sig3', 'ls3', 'noise'], opt_algorithm='L-BFGS-B', n_cpu=1, update_style='add_n', update_threshold=None, gp_model=None, flare_calc=None), output_name: str = 'OTF', std_tolerance_factor: float = - 0.01, min_steps_with_model: int = 0, freeze_hyps: int = 10, write_model: int = 0, **extra_data: Any)[source]

Bases: pydantic.main.BaseModel

Dataclass containing FLARE(++) configuration.

class Theory(**extra_data: Any)[source]

Bases: pydantic.main.BaseModel

Abstract baseclass.

class FLARE(*, kernels: List[str] = ['twobody', 'threebody'], cutoffs: List[float] = [5.0, 3.5], random: bool = True, hyp_labels: List[str] = ['sig2', 'ls2', 'sig3', 'ls3', 'noise'], opt_algorithm: str = 'L-BFGS-B', n_cpu: int = 1, update_style: str = 'add_n', update_threshold: float = None, gp_model: Any = None, flare_calc: Any = None, **extra_data: Any)[source]

Bases: qmcblip.flare.quicksim.OTFSettings.Theory

FLARE dataclass.

kernels: List[str]

n-body functions to use.

Type

List[str], optional

cutoffs: List[float]

cutoff for the n-body functions.

Type

List[float], optional

random: bool

randomize hyperparameters.

Type

bool, optional

hyp_labels: List[str]

hyperparameter labels.

Type

List[str], optional

opt_algorithm: str

hyperparamter optimization algorithm.

Type

str, optional

n_cpu: int

amount of CPU cores to run FLARE on.

Type

int, optional

update_style: str

update algorithm for GP.

Type

str, optional

update_threshold: float

update threshold for GP, in eV/Ang.

Type

str, optional

gp_model: Any
flare_calc: Any
get_calc(atoms)[source]

Make a FLARE calculator object.

Parameters

atoms (Atoms) – atoms object.

Returns

FLARE calculator object.

Return type

FLARE_Calculator

class FLAREPP(*, update_style: str = 'threshold', update_threshold: float = 0.005, opt_algorithm: str = 'L-BFGS-B', max_iterations: int = 10, variance_type: str = 'local', sigma_e: float = 0.12, sigma_f: float = 0.115, sigma_s: float = 0.014, cutoff: float = 5.0, sigma: float = 2.0, power: int = 2, cutoff_function: str = 'quadratic', radial_basis: str = 'chebyshev', N: int = 12, lmax: int = 3, kernel: Any = None, descriptor_calculator: Any = None, gp_model: Any = None, flare_calc: Any = None, **extra_data: Any)[source]

Bases: qmcblip.flare.quicksim.OTFSettings.Theory

FLARE++ dataclass.

update_style: str

update algorithm for GP.

Type

str, optional

update_threshold: float

update threshold for GP, in eV/Ang.

Type

str, optional

opt_algorithm: str

hyperparamter optimization algorithm.

Type

str, optional

max_iterations: int

maximum number of hyperparameter optimization steps per MD step.

Type

int, optional

variance_type: str

uncertainty type on energy.

Type

str, optional

sigma_e: float

energy noise per atom, in kcal/mol.

Type

float, optional

sigma_f: float

force noise, in kcal/mol/Ang.

Type

float, optional

sigma_s: float

stress noise, in kcal/Ang^3.

Type

float, optional

cutoff: float

cutoff of kernel in Ang.

Type

float, optional

sigma: float

kernel thing in eV.

Type

float, optional

power: int

power of the kernel.

Type

int, optional

cutoff_function: str

cutoff function.

Type

str, optional

radial_basis: str

radial basis.

Type

str, optional

N: int

number of radial basis functions.

Type

int, optional

lmax: int

largest L included in spherical harmonics.

Type

int, optional

kernel: Any
descriptor_calculator: Any
gp_model: Any
flare_calc: Any
get_calc(atoms)[source]

Make a FLARE++ calculator object.

Parameters

atoms (Atoms) – atoms object.

Returns

FLARE++ calculator object.

Return type

SGP_Calculator

theory: qmcblip.flare.quicksim.OTFSettings.Theory

FLARE or FLAREPP.

Type

Theory

output_name: str

name of the files to write to.

Type

str, optional

std_tolerance_factor: float

standard tolerance with respect to noise. Negative for absolute (in eV/Ang).

Type

float, optional

min_steps_with_model: int

minimum steps with model in between ab-initio calls.

Type

int, optional

freeze_hyps: int

freeze hyperparameters after this many ab-initio calls.

Type

int, optional

write_model: int

keep at 0 for FLARE++.

Type

int, optional

qmcblip.flare.quicksim(atoms, timestep, steps, calc, otfsettings=OTFSettings(theory=FLARE(kernels=['twobody', 'threebody'], cutoffs=[5.0, 3.5], random=True, hyp_labels=['sig2', 'ls2', 'sig3', 'ls3', 'noise'], opt_algorithm='L-BFGS-B', n_cpu=1, update_style='add_n', update_threshold=None, gp_model=None, flare_calc=None), output_name='OTF', std_tolerance_factor=- 0.01, min_steps_with_model=0, freeze_hyps=10, write_model=0), changes=[])[source]

A quick-to-setup simulation using FLARE or FLARE++.

This function allows the user to do a quick simulation using ab-initio calculations and FLARE(++), but at the cost of less flexibility.

Parameters

  • atoms (Atoms) – atoms object.

  • timestep (float) – timestep of MD in fs.

  • steps (int) – amount of MD steps.

  • otfsettings (OTFSettings, optional) – OTF settings object, using defaults if not given.

  • changes (optional) – array containing settings to update for CHAMP (advanced).

Submodules