transition_sampling.engines package

Subpackages

Submodules

transition_sampling.engines.abstract_engine module

Abstract class interface defining what methods a valid engine must define in order to be used by the aimless shooting algorithm

class transition_sampling.engines.abstract_engine.AbstractEngine(inputs, working_dir=None, logger=None)

Bases: abc.ABC

Base class for all concrete engine implementations.

This class defines the methods that an engine is required to implement in order to be used in the aimless shooting algorithm. Each engine can define what fields are required for its inputs, and should override validate_inputs to ensure that these are true.

Things in common that all engines will have:

  • A plumed input handler for adjusting the plumed COMMITTOR

  • A working directory where all temporary files should be stored

  • A command to execute the engine with

Parameters

  • inputs (dict) – Dictionary of inputs required for the engine. See engine specific documentation for more detail.

  • working_dir (Optional[str]) – The directory that all temporary input/output files will be placed in. If not specified or is None, defaults to the current directory.

md_cmd

A list of tokens that when joined by spaces, represent the command to invoke the actual engine. Additional leading arguments such as mpirun can be included.

Type

list[str]

plumed_handler

Handler for the passed input file. The engine can set the FILE arg of the COMMITTOR section with this and write the full input to a location

Type

PlumedInputHandler

Raises

ValueError – if inputs are not valid for the concrete engine class or if a given working directory is not a real directory.

abstract property atoms: Sequence[str]

Get the atoms held by the engine.

Get a sequence of the string representations of the atoms in use by this engine. String representations are the same as the periodic table.

Return type

Sequence[str]

Returns

An ordered sequence of atoms in the engine.

abstract property box_size: tuple

Get the box size of the engine in A.

Return type

tuple[float]

Returns

Box size (x, y, z) the engine is set to in A

abstract flip_velocity()

Flip the velocities currently held by multiplying by -1

Return type

None

abstract get_engine_str()

Get the string representation of this engine.

This string is what defines the engine name in the inputs dictionary.

Return type

str

Returns

String of the engine’s representation

async run_shooting_point()

Run the forward and reverse trajectories to get a shooting point.

Launch the MD simulation in both the forward and reverse direction from the assigned starting points and velocities, in parallel. These are spawned in new processes. Awaiting this waits for both simulations to commit to a basin or time out

Return type

ShootingResult

Returns

  • The positions of the +/- dt frames, as well as the committing

  • results of both simulations.

abstract set_delta_t(value)

Set the time offset of this engine. Set the value of the time offset of frame to save in femtoseconds. If this isn’t a multiple of the engine’s time step, the closest frame will be taken.

Parameters

value (float) – Time offset in femtoseconds

Return type

None

abstract set_positions(positions)

Set the positions of atoms in the engine.

Positions are ordered for n atoms, in shape (n, 3). Rows represent atoms and columns represent (x, y, z) dimensions.

Parameters

positions (np.ndarray with shape (n, 3)) – The positions for atoms to be set to.

Raises

ValueError – If the array does not match the required specifications

Return type

None

abstract set_velocities(velocities)

Set the velocities of atoms in the engine.

Velocities are ordered for n atoms, in shape (n, 3). Rows represent atoms and columns represent (x, y, z) dimensions.

Parameters

velocities (np.ndarray with shape (n, 3)) – The velocities for atoms to be set to.

Raises

ValueError – If the array does not match the required specifications

Return type

None

abstract validate_inputs(inputs)

Validate the given inputs for the specific engine.

Given a dictionary input, validate that it represents a well-formed input with all requirements for this engine

Parameters

inputs (dict) – dict of engine-specific inputs

Return type

Tuple[bool, str]

Returns

  • (True, “”) if the inputs passed validation. Otherwise,

  • (False, “<Relevant Error Message>”)

class transition_sampling.engines.abstract_engine.ShootingResult(fwd, rev)

Bases: object

Wrapper class for the results of a single shooting point.

A shooting point consists of a forwards and reverse trajectory through time from a single point. Information about each are stored in the respective dictionary attribute.

fwd

Forward trajectory. Two fields are defined, “commit” and “frames”.

commitUnion[int, None]

integer value of the plumed basin that the trajectory committed to, or None if it did not commit.

framesnp.ndarray

An array of the +delta_t and +2*delta_t frames. Has the shape (2, n, 3) corresponding to (frames, # of atoms, xyz dimensions). The first frame is the closest to t=0, so +delta_t

Type

dict

rev

Reverse trajectory. Two fields are defined, “commit” and “frames”.

commitUnion[int, None]

See fwd[“commit”] documentation

framesnp.ndarray

See fwd[“frames”] documentation. The first frame is the closest to t=0, so -delta_t

Type

dict

transition_sampling.engines.plumed module

Collection of classes and methods for handling the committor sections of plumed used during the shooting point generation.

class transition_sampling.engines.plumed.PlumedInputHandler(plumed_file)

Bases: object

Handles copying and modifying a template plumed file.

This class is used to read a template plumed file that has exactly one COMMITTOR section, add a given FILE argument to it, and write it to a new location. This can be invoked repeatedly.

Will not modify the original file. The original file is read once at init and no modifications to it after this object is constructed will carry over.

Parameters

plumed_file (str) – path to the plumed file. This file will not be modified.

before

The string to be written before FILE=arg

Type

str

after

The string to be written after FILE=arg

Type

str

Raises

ValueError – If plumed_file is not a file.

write_plumed(new_location, out_name)

Copy the plumed file and set the committor output file.

The plumed file is object is tied to is copied to new_location. Within the COMMITTOR section, the FILE arguments is set to out_name

Parameters

  • new_location (str) – Location to copy the plumed file to

  • out_name (str) – Name to be set for the COMMITTOR out file

Return type

None

class transition_sampling.engines.plumed.PlumedOutputHandler(plumed_out_file)

Bases: object

Reads the output of a plumed committor file.

Used for parsing which basin the trajectory committed to.

Parameters

plumed_out_file (str) – Path of the plumed file that will be output by the committor

Raises

ValueError – If the passed string is not a file

check_basin()

Read the basin of the attached plumed committor output.

Looks at the plumed output file that this object was created with and returns the basin it committed to.

Return type

int

Returns

The basin the attached plumed file committed to. None if did not commit.

Module contents