transition_sampling.algo package

Submodules

transition_sampling.algo.acceptors module

class transition_sampling.algo.acceptors.AbstractAcceptor

Bases: abc.ABC

Abstract class that defines what shooting points should be accepted

abstract is_accepted(result)

Determines if a ShootingResult should be accepted or rejected

Parameters

result (ShootingResult) – The ShootingResult to be tested

Return type

bool

Returns

True if it should be accepted, False otherwise.

class transition_sampling.algo.acceptors.DefaultAcceptor

Bases: transition_sampling.algo.acceptors.AbstractAcceptor

Accepts as long as both trajectories committed to different basins

is_accepted(result)

Determines if a ShootingResult should be accepted or rejected

Parameters

result (ShootingResult) – The ShootingResult to be tested

Return type

bool

Returns

True if it should be accepted, False otherwise.

class transition_sampling.algo.acceptors.MultiBasinAcceptor(reactants, products)

Bases: transition_sampling.algo.acceptors.AbstractAcceptor

Acceptor with basins split into reactants and products.

To be accepted, both trajectories must have committed and must commit to a different basin type, e.g. one to reactants and one to products, but not both to products.

Parameters

• reactants (set[int]) – Set of basins to be considered as reactants, as defined in the plumed input

• products (set[int]) – Set of basins to be considered as products, as defined in the plumed input

reactants

Set of basins to be considered as reactants, as defined in the plumed input

products

Set of basins to be considered as products, as defined in the plumed input

Raises

ValueError – If the intersection of reactants and products is not empty, i.e. there is a basin shared by both.

is_accepted(result)

Determines if a ShootingResult should be accepted or rejected

Parameters

result (ShootingResult) – The ShootingResult to be tested

Return type

bool

Returns

True if it should be accepted, False otherwise.

transition_sampling.algo.aimless_shooting module

Implementation of the aimless shooting algorithm

class transition_sampling.algo.aimless_shooting.AimlessShootingDriver(engine, position_dir, temp, log_name, acceptor=None)

Bases: object

Driver to run one or multiple aimless shootings.

Given parameters are copied and used for each shooting, making the only difference the randomness that the aimless shooting algorithm introduces.

Parameters

• engine (AbstractEngine) – Engine to be used. This specific engine will not be modified, but deep copies of it made for each parallel shooting.

• position_dir (str) – Directory containing starting xyz positions

• temp (float) – The temperature in Kelvin to generate initial velocities for

• log_name (str) – Base name for the log (csv and xyz) files. A call to run will generate log_name.csv and log_name.xyz files that hold results from all shootings. For each parallel shooting, there will be an additional log_name{i}.csv and log_name{i}.xyz files that track results from that specific shooting.

• acceptor (Optional[AbstractAcceptor]) – An acceptor that implements an is_accepted method to determine if a shooting point should be considered accepted or not. Deep copied and used as a template for all parallel shootings.

base_engine

Engine template to be used for all shootings

Type

AbstractEngine

position_dir

Directory containing starting xyz positions to be used for all shootings

Type

str

temp

The temperature in Kelvin to generate initial velocities for

Type

float

log_name

Root name for all logging

Type

str

base_acceptor

Acceptor template to be used for all shootings

Type

AbstractAcceptor

run(n_parallel, **run_args)

Run multiple AimlessShootings in parallel.

Note that calling this method after completion will start new aimless shootings, not continue them from the previous call.

Parameters

• n_parallel (int) – Number of parallel AimlessShootings to execute. Note this will lead to 2 * n_parallel simulations running simultaneously.

• run_args – Keyword arguments to pass to each aimless shootings run method.

Return type

None

class transition_sampling.algo.aimless_shooting.AsyncAimlessShooting(engine, position_dir, temp, results_logger, acceptor=None, logger=None)

Bases: object

Aimless Shooting runner.

Implements the aimless shooting algorithm by interacting with a given engine.

Parameters

• engine (AbstractEngine) – The specific engine (e.g. CP2KEngine) that will run the simulations

• position_dir (str) – A directory containing only xyz positions of guesses at transition states. These positions will be used to try to kickstart the algorithm.

• temp (float) – The temperature in Kelvin to generate initial velocities for

• results_logger (ResultsLogger) – Logger to write xyz and csv results to. Use a logger with a defined base_logger to record these in more than one location.

• acceptor (Optional[AbstractAcceptor]) – An acceptor that implements an is_accepted method to determine if a shooting point should be considered accepted or not. If None, the DefaultAcceptor is used, which accepts if both trajectories commit to different basins.

engine

Engine used to run the simulations

Type

AbstractEngine

position_dir

Directory containing initial xyz guesses of transition states.

Type

str

temp

The temperature in Kelvin to generate initial velocities for

Type

float

current_offset

-1, 0 or +1. The delta-t offset the point being run with engine currently represents for purposes of choosing the next point.

Type

int

results_logger

Logger to write xyz and csv results to. Log function is invoked on every successful shooting point, no matter if it is accepted or unaccepted.

Type

ResultsLogger

current_start

xyz array of the current starting position. Has shape (num_atoms, 3)

Type

np.ndarray

accepted_states

A list of the accepted positions. Contains duplicates.

Type

list[np.ndarray]

acceptor

An acceptor that implements an is_accepted method to determine if a shooting point should be considered accepted or not.

Type

AbstractAcceptor

static is_accepted(result)

Determines if a ShootingResult should be accepted or rejected

Parameters

result (ShootingResult) – The ShootingResult to be tested

Return type

bool

Returns

True if it should be accepted, False otherwise.

pick_starting(result)

Pick the next point to be used as a starting position

Parameters

result (ShootingResult) – A valid ShootingResult that we will pick a new starting position from

Return type

array

Returns

• A randomly selected new starting position based on the current time

• offset.

async run(n_points, n_state_tries, n_vel_tries, **kwargs)

Run the aimless shooting algorithm to generate n_points.

Each state that is generated is written as a .xyz to the given results directory.

There are two loops of tries before failing to generate a new transition state. The outer loop is over starting positions and the inner loop is over resampled velocities.

This implementation works as described below:

1. Pick a starting state

2. For that starting state, try n_vel_tries number of times to get it accepted by regenerating the velocities each time it is rejected.

3. Either:

   1. An accepted state was found. Pick the next starting point from this accepted state and repeat from 1.

   2. An accepted state was not found. Randomly select a state we know has worked before and repeat from 1.

4. If 3b occurs n_state_tries in a row without generating a new accepted state, we’ve failed. Raise an exception.

Parameters

• n_points (int) – Number of total points to generate

• n_state_tries (int) – Number of consecutive states to try resampling before failing completely

• n_vel_tries (int) – Number of times to try resampling velocities on a single state before moving on to try a new state

• kwargs – All other kwargs are ignored

Return type

None

class transition_sampling.algo.aimless_shooting.ResultsLogger(name, base_logger=None)

Bases: object

Class for logging everything from aimless shooting with multiple levels.

An instance of this class is passed to an AimlessShooting instance in order to log the results to an xyz file and csv file. If constructed with another ResultLogger, that logger is invoked at the same time and duplicates to its respective files.

This allows one “parent” logger to keep all results in a single pair of files, while many “child loggers” are attached to parallel shootings, each recording only their respective results in a separate pair of files.

The tracked files are name.csv and name.xyz. If these files already exist, they are appended to.

Parameters

• name (str) – The root name of the xyz and csv file

• base_logger (Optional[ResultsLogger]) – An optional “parent” logger to pass logs up to. If not None, everything logged to this logger is also logged by the base_logger

name

The root name of the xyz and csv file to use, e.g. “results”

Type

str

base_logger

An optional “parent” logger to pass logs up to. If not None, everything logged to this logger is also logged by the base_logger

Type

ResultsLogger

cur_index

The next index that will be written in the CSV.

Type

int

property csv_name: str

Name of the CSV file

Return type

str

log_result(result, atoms, frame, accepted, box_size)

Log results to xyz and csv. Invoke the base logger if we have one.

This writes all the passed results synchronously to the corresponding XYZ and CSV. The base logger is also invoked, allowing synchronous logging to it as well.

Parameters

• result (ShootingResult) – The shooting result we’re logging

• atoms (Sequence[str]) – Periodic table format sequence of atom names

• frame (ndarray) – xyz frame we’re logging, each row corresponding to the atoms

• accepted (bool) – True if this result was accepted, false otherwise

• box_size (Sequence[float]) – x, y, z of the box size used.

Return type

None

property xyz_name: str

Name of the XYZ file

Return type

str

transition_sampling.algo.aimless_shooting.generate_velocities(atoms, temp)

Generates velocities for atoms at a temperature from MB distribution.

Parameters

• atoms (Sequence[str]) – A list of the atoms to generate velocities for. Strings in periodic table format (e.g. Ar = Argon).

• temp (float) – Temperature in Kelvin

Return type

array

Returns

• An array of velocities generated randomly from the Maxwell-Boltzmann

• distribution. Has the shape (n_atoms, 3), where 3 is the x,y,z directions.

Module contents