ASEDynamics

class narupatools.ase.dynamics.ASEDynamics(dynamics: TIntegrator, *, universe: Optional[MDAnalysis.core.universe.Universe] = None, playback_interval: float = 0.0)

Run dynamics using an ASE MolecularDynamics object.

This allows the simulation to be run at a set playback rate, as well as exposing standard properties such as time step and elapsed steps.

Inheritance

Methods

__init__	Create a SimulationDynamics wrapper around an ASE MolecularDynamics object.
check_task	Check if a task has thrown an exception, and reraise it if so.
create_langevin	Create ASE Langevin dynamics with the provided ASE atoms object.
create_velocity_verlet	Create ASE velocity verlet dynamics for the provided ASE atoms object.
end_broadcast	Called when this object is stopped being broadcasted.
from_ase_dynamics	Create ASE dynamics from an existing dynamics object.
get_frame	Get the current state of the system as a Narupa FrameData.
health_check	Check background tasks to ensure they have not encountered an exception.
pause	Pause this object if it is running.
play	Play the given object.
reset	Reset the simulation.
restart	Restart this back to its initial state.
run	Run the dynamics.
start	An alias for run().
start_broadcast	Called when this object is about to be broadcast.
step	Step forward by one step, and then pause the simulation.
stop	Stop the object if it is running.

__init__(dynamics: TIntegrator, *, universe: Optional[MDAnalysis.core.universe.Universe] = None, playback_interval: float = 0.0)

Create a SimulationDynamics wrapper around an ASE MolecularDynamics object.

Parameters

• dynamics – ASE MolecularDynamics object to be simulated.

• universe – Optional MDAnalysis universe to provide additional topology.

• playback_interval – Time to wait between steps in seconds. Defaults to 0.0 (run as fast as possible).

classmethod check_task(task: Optional[concurrent.futures._base.Future]) → None

Check if a task has thrown an exception, and reraise it if so.

Parameters

task – Background task to check for an exception.

static create_langevin(atoms: ase.atoms.Atoms, *, universe: Optional[MDAnalysis.core.universe.Universe] = None, friction: float = 0.01, temperature: float = 300, timestep: float = 1) → narupatools.ase.dynamics.ASEDynamics[ase.md.langevin.Langevin]

Create ASE Langevin dynamics with the provided ASE atoms object.

Parameters

• atoms – An ASE atoms object to simulate.

• universe – Optional MDAnalysis universe with additional system information.

• friction – Friction of the Langevin integrator in inverse picoseconds.

• temperature – Temperature of the Langevin integrator in kelvin.

• timestep – Timestep of the Langevin integrator in picoseconds.

Returns

An ASEDynamics object which wraps a Langevin integrator running on the specified system.

static create_velocity_verlet(atoms: ase.atoms.Atoms, *, universe: Optional[MDAnalysis.core.universe.Universe] = None, timestep: float = 1) → narupatools.ase.dynamics.ASEDynamics[ase.md.verlet.VelocityVerlet]

Create ASE velocity verlet dynamics for the provided ASE atoms object.

Parameters

• atoms – An ASE atoms object to simulate.

• universe – Optional MDAnalysis universe with additional system information.

• timestep – Timestep of the Velocity Verlet integrator in picoseconds.

Returns

An ASEDynamics object which wraps a Velocity Verlet integrator running on the specified system.

end_broadcast(broadcaster: narupatools.core.broadcastable.Broadcaster) → None

Called when this object is stopped being broadcasted.

Parameters

broadcaster – Broadcaster that is about to stop broadcasting this object.

static from_ase_dynamics(dynamics: TIntegrator, *, universe: Optional[MDAnalysis.core.universe.Universe] = None) → narupatools.ase.dynamics.ASEDynamics[TIntegrator]

Create ASE dynamics from an existing dynamics object.

This object implements the SimulationDynamics API, and hence can be played at a specific playback rate. It also provides callbacks for when the simulation advances a step or is reset.

Parameters

• dynamics – Any ASE dynamics derived from MolecularDynamics.

• universe – Optional MDAnalysis universe with additional system information.

Returns

An ASEDynamics object which wraps the provided dynamics.

get_frame(fields: infinite_sets.infinite_sets.InfiniteSet[str]) → narupa.trajectory.frame_data.FrameData

Get the current state of the system as a Narupa FrameData.

Parameters

fields – Collection of keys to include in the FrameData

Returns

Narupa FrameData populated with requested fields.

health_check() → None

Check background tasks to ensure they have not encountered an exception.

Calling this allows exceptions raised on background threads to be thrown on the main thread. It is a useful tool for checking if an object has crashed silently in the background.

It is recommended to call this periodically from the main thread to ensure an object is healthy. If no exceptions have occurred, this method will do nothing.

pause(wait: bool = True) → None

Pause this object if it is running.

This will not cancel the current run if present, merely suspend it until a subsequent call to play() is made.

Parameters

wait – Wait until the pause has actually occurred.

play() → None

Play the given object.

If this is not running, run this on a background thread. Else, unpause if this is paused.

reset() → None

Reset the simulation.

The behaviour of this depends on the implementation of the dynamics, but commonly an implementation of SimulationDynamics should record the initial state of the simulation on initialization, and use this to reset the simulation.

This method is called whenever a client runs the reset command, described in frame_server.

restart() → None

Restart this back to its initial state.

run(steps: Optional[int] = None, block: Optional[bool] = None) → Union[bool, concurrent.futures._base.Future[bool]]

Run the dynamics.

Raises

ValueError – The number of steps was negative or 0.

Parameters

• steps – The number of steps to run for, or None to run indefinitely. If provided, must be larger than 0.

• block – Should this be run in this thread (block=True) or in a background thread (block=False)

Returns

If run in blocking mode, returns True if the dynamics completed and False if it was interrupted. If not run in blocking mode, returns a Future with the same result.

start(block: bool = True) → None

An alias for run().

Parameters

block – Should this block?

start_broadcast(broadcaster: narupatools.core.broadcastable.Broadcaster) → None

Called when this object is about to be broadcast.

Parameters

broadcaster – Broadcaster that is about to broadcast this object.

step() → None

Step forward by one step, and then pause the simulation.

stop(wait: bool = True) → None

Stop the object if it is running.

If this is running, this object will stop executing at the next available point.

Parameters

wait – Should this call wait until this object has stopped running before returning?

Attributes

atoms	Get the wrapped ASE Atoms object.
dynamic_fields	Set of fields which are marked as having changed after a dynamics step.
elapsed_steps	Elapsed number of steps of the simulation since initialization/last reset.
elapsed_time	Elapsed time of the simulation since initialization/last reset in picoseconds.
forces	Forces on particles in kilojoules per mole per nanometer.
imd	Access to the interactions currently being applied to the simulation.
is_paused	Is this currently running but paused?
is_playing	Is this currently playing and not paused?
is_running	Is this currently running?
kinetic_energy	Kinetic energy in kilojoules per mole.
masses	Masses of particles in daltons.
molecular_dynamics	Get the wrapped ASE MolecularDynamics` object.
on_field_changed
on_post_step	Event triggered after each step of the dynamics is run.
on_pre_step	Event triggered before each step of the dynamics is run.
on_reset	Event triggered when dynamics is reset.
playback_interval	Time in seconds between individual steps of this playable.
playback_rate	Number of steps this playable goes through in 1 second.
positions	Positions of particles in nanometers.
potential_energy	Potential energy in kilojoules per mole.
temperature	Current temperature of the dynamics in Kelvin.
timestep	Current time step of the simulation in picoseconds.
total_steps	Total number of steps of the simulation.
total_time	Total time of the simulation in picoseconds.
velocities	Velocities of particles in nanometers per picosecond.

atoms

Get the wrapped ASE Atoms object.

Direct modification of this may have side effects.

dynamic_fields = {'energy.kinetic', 'energy.potential', 'particle.positions', 'particle.velocities'}

Set of fields which are marked as having changed after a dynamics step.

elapsed_steps

Elapsed number of steps of the simulation since initialization/last reset.

When the system is reset, this value is reset to 0.

elapsed_time

Elapsed time of the simulation since initialization/last reset in picoseconds.

When the system is reset, this value is reset to 0.

forces

imd

is_paused

Is this currently running but paused?

is_playing

Is this currently playing and not paused?

is_running

Is this currently running?

This is True even if the playback is paused.

kinetic_energy

masses

molecular_dynamics

Get the wrapped ASE MolecularDynamics` object.

Direct modification of this may have side effects.

on_field_changed

on_post_step

Event triggered after each step of the dynamics is run.

on_pre_step

Event triggered before each step of the dynamics is run.

on_reset

Event triggered when dynamics is reset.

This can be used when the behaviour of reset that the current dynamics performs is insufficient, or the user would like to perform a more detailed reset such as reinitializing velocities.

playback_interval

Time in seconds between individual steps of this playable.

playback_rate

Number of steps this playable goes through in 1 second.

positions

potential_energy

temperature

Current temperature of the dynamics in Kelvin.

Raises

AttributeError – Temperature is not defined for this dynamics.

timestep

total_steps

Total number of steps of the simulation.

This includes all times the simulation has been reset.

total_time

Total time of the simulation in picoseconds.

This includes all times the simulation has been reset.

velocities