Molecular Dynamics

A DynamicalSystem object contains an Atoms object, which holds infomation about velocities and accelerations of each atom, scalar quantities such as thermostat settings, and logical masks so that thermostatting can be applied to selected atoms etc.

In Fortran code, initialise a DynamicalSystem object like this:

call initialise(MyDS, MyAtoms)

which (shallowly) copies MyAtoms into the internal atoms structure (and so MyAtoms is not required by MyDS after this call and can be finalised). In Python, a DynamicalSystem can be initialised from an Atoms instance:

MyDS = DynamicalSystem(MyAtoms)

A DynamicalSystem is constructed from an Atoms object atoms. The initial velocities and accelerations can optionally be specificed as (3,atoms.n) arrays. The constraints and rigidbodies arguments can be used to specify the number of constraints and rigid bodies respectively (the default is zero in both cases).

DynamicalSystem has an integrator,

call advance_verlet(MyDS,dt,forces)

which takes a set of forces and integrates the equations of motion forward for a time dt.

All dynamical variables are stored inside the Atoms’ properties Dictionary.

Module contents for quippy.dynamicalsystem:

Classes

DynamicalSystem(…) Initialise this DynamicalSystem from an Atoms object
Dynamics(atoms, timestep, trajectory[, …]) Wrapper around DynamicalSystem integrator compatible with ASE ase.md.MolecularDynamics interface.

Functions

gaussian_velocity_component(m,t) Draw a velocity component from the correct Gaussian distribution for a degree of freedom with (effective) mass m at temperature T
torque(pos,force,[origin])
Parameters:
distance_relative_velocity(at,i,j) Return the distance between two atoms and the relative velocity between them projected along the bond direction.
angular_momentum(*args, **kwargs) Routine is wrapper around Fortran interface angular_momentum containing multiple routines:
kinetic_virial(*args, **kwargs) Routine is wrapper around Fortran interface kinetic_virial containing multiple routines:
momentum(*args, **kwargs) Routine is wrapper around Fortran interface momentum containing multiple routines:
kinetic_energy(*args, **kwargs) Routine is wrapper around Fortran interface kinetic_energy containing multiple routines:

Attributes

Name Value
TYPE_ATOM 1
TYPE_IGNORE 0
TYPE_RIGID 3
TYPE_CONSTRAINED 2
fs 0.0982269478846
THERMOSTAT_LANGEVIN_PR 5
THERMOSTAT_NOSE_HOOVER 2
THERMOSTAT_LANGEVIN_OU 8
THERMOSTAT_LANGEVIN_NPT 4
THERMOSTAT_NONE 0
THERMOSTAT_NPH_PR 7
THERMOSTAT_ALL_PURPOSE 10
THERMOSTAT_LANGEVIN_NPT_NB 9
THERMOSTAT_LANGEVIN 1
THERMOSTAT_NPH_ANDERSEN 6
THERMOSTAT_NOSE_HOOVER_LANGEVIN 3
BAROSTAT_NONE 0
BAROSTAT_HOOVER_LANGEVIN 1
class quippy.dynamicalsystem.DynamicalSystem(atoms_in[, velocity, acceleration, constraints, restraints, rigidbodies, error])[source]

Bases: quippy._dynamicalsystem.DynamicalSystem

Initialise this DynamicalSystem from an Atoms object

Parameters:
atoms_in : Atoms object
velocity : input rank-2 array(‘d’) with bounds (qp_n0,qp_n1), optional
acceleration : input rank-2 array(‘d’) with bounds (qp_n2,qp_n3), optional
constraints : input int, optional
restraints : input int, optional
rigidbodies : input int, optional
error : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine __init__initialise defined in file src/libAtoms/DynamicalSystem.f95. Class is wrapper around Fortran type DynamicalSystem defined in file src/libAtoms/DynamicalSystem.f95.

Attributes:
avg_temp

Time-averaged temperature

avg_time

Averaging time, in fs

cur_temp

Current temperature

dt

Last time step

dw

Increment of work done this time step

ekin

Current kinetic energy

epot

Total potential energy

ext_energy

Extended energy

n

Number of atoms

nconstraints

Number of constraints

ndof

Number of degrees of freedom

nrestraints

Number of restraints

nrigid

Number of rigid bodies

nsteps

Number of integration steps

random_seed

RNG seed, used by ds_save_state and ds_restore_state only.

t

Time

thermostat_dw

Increment of work done by thermostat

thermostat_work

Total work done by thermostat

wkin

Current kinetic contribution to the virial

work

Total work done

Methods

add_atoms(*args, **kwargs) Add one or more atoms to this DynamicalSystem.
add_constraint(…) Add a constraint to the DynamicalSystem and reduce the number of degrees of freedom, unless update_Ndof is present and false.
add_thermostat(…) Add a new thermostat to this DynamicalSystem.
add_thermostats(…) ds_add_thermostats(type,n,[t,t_a,gamma,gamma_a,q,q_a,tau,tau_a,region_i])
advance_verlet(…) Calls`` advance_verlet2`` followed by advance_verlet1.
advance_verlet1(…) Advance the velocities by half the time-step dt and the positions by a full time-step.
advance_verlet2(…) Advances the velocities by the second half time-step
amend_constraint(constraint,func,data,[k]) Replace a constraint involving some atoms with a different constraint involving the same atoms
angular_momentum([origin,indices]) Return the angular momentum of all the atoms in this DynamicalSystem, defined by \(\mathbf{L} = \sum_{i} \mathbf{r_i} \times \mathbf{v_i}\).
constrain_atom_plane(…) Constrain an atom to lie in a particluar plane
constrain_bondanglecos(…) Constrain the bond angle cosine between atoms i, j, and k
constrain_bondlength(…) Constrain the bond between atoms i and j
constrain_bondlength_dev_pow(…) Constrain the bond between atoms i and j
constrain_bondlength_diff(…) Constrain the difference of bond length between atoms i–j and j–k
constrain_bondlength_sq(…) Constrain the bond between atoms i and j
constrain_gap_energy(…) Constrain the energy gap of two resonance structures
constrain_struct_factor_like_i(…) Constrain an atom to lie in a particluar plane
constrain_struct_factor_like_mag(…) Constrain an atom to lie in a particluar plane
constrain_struct_factor_like_r(…) Constrain an atom to lie in a particluar plane
disable_damping(*args, **kwargs)

References

enable_damping(damp_time) Enable damping, with damping time set to damp_time.
get_damping_time(*args, **kwargs)
Returns:
is_damping_enabled(*args, **kwargs)
Returns:
is_same_fortran_object(other) Test if self and other point to the same Fortan object.
kinetic_energy([mpi_obj,local_ke,error]) Return the total kinetic energy \(E_k = \sum_{i} \frac{1}{2} m v^2\)
kinetic_virial([mpi_obj,error]) Return the total kinetic virial \(w_ij = \sum_{k} \frac{1}{2} m v_i v_j\)
momentum([indices]) Return the total momentum \(\mathbf{p} = \sum_i \mathbf{m_i} \mathbf{v_i}\).
n_thermostat(*args, **kwargs)
Returns:
print_([file]) Print lots of information about this DynamicalSystem in text format.
print_status(…) Print a status line showing the current time, temperature, the mean temperature the total energy and the total momentum for this DynamicalSystem.
print_thermostats(*args, **kwargs) ds_print_thermostats
remove_atoms(*args, **kwargs) Remove one or more atoms from this DynamicalSystem.
remove_thermostat(index) ds_remove_thermostat(index)
rescale_velo(temp,[mass_weighted,zero_l]) Rescale the atomic velocities to temperature temp.
restore_state(to,from) Restore a DynamicalSystem to a previously saved state.
run(…) Run n_steps of dynamics using forces from Potential pot.
save_state(to,from,[error]) Save the state of a DynamicalSystem.
set_barostat(…) ds_set_barostat(type,p_ext,hydrostatic_strain,diagonal_strain,finite_strain_formulation,tau_epsilon,[w_epsilon,t,w_epsilon_factor,thermalise])
shallow_copy() Return a shallow copy of self.
shallow_copy_from(other) Transform self into a shallow copy of other.
temperature(…) Return the temperature, assuming each degree of freedom contributes \(\frac{1}{2}kT\).
thermostat_temperatures(n0)
Parameters:
update_thermostat([t,p,i]) ds_update_thermostat([t,p,i])
zero_momentum([indices]) Change velocities to those that the system would have in the zero momentum frame.
add_atoms(*args, **kwargs)

Add one or more atoms to this DynamicalSystem. Equivalent to ‘Atoms%add_atoms’, but also appends the number of degrees of freedom correctly.

Wrapper around Fortran interface add_atoms containing multiple routines:

add_atoms(z[, mass, p, v, a, t, error])
Parameters:
  • z (input rank-1 array('i') with bounds (qp_n0)) –
  • mass (input rank-1 array('d') with bounds (qp_n1), optional) –
  • p (input rank-2 array('d') with bounds (qp_n2,qp_n3), optional) –
  • v (input rank-2 array('d') with bounds (qp_n4,qp_n5), optional) –
  • a (input rank-2 array('d') with bounds (qp_n6,qp_n7), optional) –
  • t (input rank-2 array('i') with bounds (qp_n8,qp_n9), optional) –
  • error (in/output rank-0 array(int,'i'), optional) –

Routine is wrapper around Fortran routine ds_add_atom_multiple defined in file src/libAtoms/DynamicalSystem.f95.

add_atoms(z[, mass, p, v, a, t, error])
Parameters:
  • z (input int) –
  • mass (input float, optional) –
  • p (input rank-1 array('d') with bounds (3), optional) –
  • v (input rank-1 array('d') with bounds (3), optional) –
  • a (input rank-1 array('d') with bounds (3), optional) –
  • t (input rank-1 array('i') with bounds (3), optional) –
  • error (in/output rank-0 array(int,'i'), optional) –

Routine is wrapper around Fortran routine ds_add_atom_single defined in file src/libAtoms/DynamicalSystem.f95.

add_constraint(atoms, func, data[, update_ndof, restraint_k, bound, tol, print_summary])

Add a constraint to the DynamicalSystem and reduce the number of degrees of freedom, unless update_Ndof is present and false.

Parameters:
atoms : input rank-1 array(‘i’) with bounds (qp_n0)
func : input int
data : input rank-1 array(‘d’) with bounds (qp_n1)
update_ndof : input int, optional
restraint_k : input float, optional
bound : input int, optional
tol : input float, optional
print_summary : input int, optional

References

Routine is wrapper around Fortran routine ds_add_constraint defined in file src/libAtoms/DynamicalSystem.f95.

add_thermostat(type, t[, gamma, q, tau, tau_cell, p, bulk_modulus_estimate, cell_oscillation_time, nhl_tau, nhl_mu, massive, region_i])

Add a new thermostat to this DynamicalSystem. type should be one of the following thermostat types:

  • THERMOSTAT_NONE
  • THERMOSTAT_LANGEVIN
  • THERMOSTAT_NOSE_HOOVER
  • THERMOSTAT_NOSE_HOOVER_LANGEVIN
  • THERMOSTAT_LANGEVIN_NPT
  • THERMOSTAT_LANGEVIN_PR
  • THERMOSTAT_NPH_ANDERSEN
  • THERMOSTAT_NPH_PR
  • THERMOSTAT_LANGEVIN_OU
  • THERMOSTAT_LANGEVIN_NPT_NB

T is the target temperature. Q is the Nose-Hoover coupling constant. Only one of tau or gamma should be given. p is the external pressure for the case of Langevin NPT.

Parameters:
type : input int
t : input float
gamma : input float, optional
q : input float, optional
tau : input float, optional
tau_cell : input float, optional
p : input float, optional
bulk_modulus_estimate : input float, optional
cell_oscillation_time : input float, optional
nhl_tau : input float, optional
nhl_mu : input float, optional
massive : input int, optional
region_i : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine add_thermostat defined in file src/libAtoms/DynamicalSystem.f95.

add_thermostats(type, n[, t, t_a, gamma, gamma_a, q, q_a, tau, tau_a, region_i])

ds_add_thermostats(type,n,[t,t_a,gamma,gamma_a,q,q_a,tau,tau_a,region_i])

Parameters:
type : input int
n : input int
t : input float, optional
t_a : input rank-1 array(‘d’) with bounds (qp_n0), optional
gamma : input float, optional
gamma_a : input rank-1 array(‘d’) with bounds (qp_n1), optional
q : input float, optional
q_a : input rank-1 array(‘d’) with bounds (qp_n2), optional
tau : input float, optional
tau_a : input rank-1 array(‘d’) with bounds (qp_n3), optional
region_i : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine add_thermostats defined in file src/libAtoms/DynamicalSystem.f95.

advance_verlet(ds, dt, f[, virial, e, parallel, store_constraint_force, do_calc_dists, error])

Calls`` advance_verlet2`` followed by advance_verlet1. Outside this routine the velocities will be half-stepped. This allows a simpler MD loop:

for n in range(n_steps):
    pot.calc(ds.atoms, force=True, energy=True)
    ds.advance_verlet(dt, ds.atoms.force)
    ds.print_status(epot=ds.atoms.energy)
    if n % connect_interval == 0:
       ds.atoms.calc_connect()
Parameters:
ds : dynamicalsystem object
dt : input float
f : in/output rank-2 array(‘d’) with bounds (qp_n0,qp_n1)
virial : input rank-2 array(‘d’) with bounds (3,3), optional
e : in/output rank-0 array(float,’d’), optional
parallel : input int, optional
store_constraint_force : input int, optional
do_calc_dists : input int, optional
error : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine advance_verlet defined in file src/libAtoms/DynamicalSystem.f95.

advance_verlet1(dt[, virial, parallel, store_constraint_force, do_calc_dists, mpi_obj, error])

Advance the velocities by half the time-step dt and the positions by a full time-step. A typical MD loop should resemble the following code (Python example, Fortran is similar):

ds.atoms.calc_connect()
for n in range(n_steps):
   ds.advance_verlet1(dt)
   pot.calc(ds.atoms, force=True, energy=True)
   ds.advance_verlet2(dt, ds.atoms.force)
   ds.print_status(epot=ds.atoms.energy)
   if n % connect_interval == 0:
      ds.atoms.calc_connect()
Parameters:
dt : input float
virial : input rank-2 array(‘d’) with bounds (3,3), optional
parallel : input int, optional
store_constraint_force : input int, optional
do_calc_dists : input int, optional
mpi_obj : MPI_context object, optional
error : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine advance_verlet1 defined in file src/libAtoms/DynamicalSystem.f95.

advance_verlet2(dt, f[, virial, e, parallel, store_constraint_force, error])

Advances the velocities by the second half time-step

Parameters:
dt : input float
f : in/output rank-2 array(‘d’) with bounds (qp_n0,qp_n1)
virial : input rank-2 array(‘d’) with bounds (3,3), optional
e : in/output rank-0 array(float,’d’), optional
parallel : input int, optional
store_constraint_force : input int, optional
error : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine advance_verlet2 defined in file src/libAtoms/DynamicalSystem.f95.

amend_constraint(constraint, func, data[, k])

Replace a constraint involving some atoms with a different constraint involving the same atoms

Parameters:
constraint : input int
func : input int
data : input rank-1 array(‘d’) with bounds (qp_n0)
k : input float, optional

References

Routine is wrapper around Fortran routine ds_amend_constraint defined in file src/libAtoms/DynamicalSystem.f95.

angular_momentum([origin, indices])

Return the angular momentum of all the atoms in this DynamicalSystem, defined by \(\mathbf{L} = \sum_{i} \mathbf{r_i} \times \mathbf{v_i}\).

Parameters:
origin : input rank-1 array(‘d’) with bounds (3), optional
indices : input rank-1 array(‘i’) with bounds (qp_n0), optional
Returns:
ret_l : rank-1 array(‘d’) with bounds (3)

References

Routine is wrapper around Fortran routine angular_momentum defined in file src/libAtoms/DynamicalSystem.f95.

constrain_atom_plane(i, plane_n[, d, restraint_k, bound, tol, print_summary])

Constrain an atom to lie in a particluar plane

Parameters:
i : input int
plane_n : input rank-1 array(‘d’) with bounds (3)
d : input float, optional
restraint_k : input float, optional
bound : input int, optional
tol : input float, optional
print_summary : input int, optional

References

Routine is wrapper around Fortran routine constrain_atom_plane defined in file src/libAtoms/DynamicalSystem.f95.

constrain_bondanglecos(i, j, k[, c, restraint_k, bound, tol, print_summary])

Constrain the bond angle cosine between atoms i, j, and k

Parameters:
i : input int
j : input int
k : input int
c : input float, optional
restraint_k : input float, optional
bound : input int, optional
tol : input float, optional
print_summary : input int, optional

References

Routine is wrapper around Fortran routine constrain_bondanglecos defined in file src/libAtoms/DynamicalSystem.f95.

constrain_bondlength(i, j, d[, di, t0, tau, restraint_k, bound, tol, print_summary])

Constrain the bond between atoms i and j

Parameters:
i : input int
j : input int
d : input float
di : input float, optional
t0 : input float, optional
tau : input float, optional
restraint_k : input float, optional
bound : input int, optional
tol : input float, optional
print_summary : input int, optional

References

Routine is wrapper around Fortran routine constrain_bondlength defined in file src/libAtoms/DynamicalSystem.f95.

constrain_bondlength_dev_pow(i, j, p, d[, di, t0, tau, restraint_k, bound, tol, print_summary])

Constrain the bond between atoms i and j

Parameters:
i : input int
j : input int
p : input float
d : input float
di : input float, optional
t0 : input float, optional
tau : input float, optional
restraint_k : input float, optional
bound : input int, optional
tol : input float, optional
print_summary : input int, optional

References

Routine is wrapper around Fortran routine constrain_bondlength_dev_pow defined in file src/libAtoms/DynamicalSystem.f95.

constrain_bondlength_diff(i, j, k, d[, di, t0, tau, restraint_k, bound, tol, print_summary])

Constrain the difference of bond length between atoms i–j and j–k

Parameters:
i : input int
j : input int
k : input int
d : input float
di : input float, optional
t0 : input float, optional
tau : input float, optional
restraint_k : input float, optional
bound : input int, optional
tol : input float, optional
print_summary : input int, optional

References

Routine is wrapper around Fortran routine constrain_bondlength_diff defined in file src/libAtoms/DynamicalSystem.f95.

constrain_bondlength_sq(i, j[, d, restraint_k, bound, tol, print_summary])

Constrain the bond between atoms i and j

Parameters:
i : input int
j : input int
d : input float, optional
restraint_k : input float, optional
bound : input int, optional
tol : input float, optional
print_summary : input int, optional

References

Routine is wrapper around Fortran routine constrain_bondlength_sq defined in file src/libAtoms/DynamicalSystem.f95.

constrain_gap_energy(d[, restraint_k, bound, tol, print_summary])

Constrain the energy gap of two resonance structures

Parameters:
d : input float
restraint_k : input float, optional
bound : input int, optional
tol : input float, optional
print_summary : input int, optional

References

Routine is wrapper around Fortran routine constrain_gap_energy defined in file src/libAtoms/DynamicalSystem.f95.

constrain_struct_factor_like_i(z, q, sf[, restraint_k, bound, tol, print_summary])

Constrain an atom to lie in a particluar plane

Parameters:
z : input int
q : input rank-1 array(‘d’) with bounds (3)
sf : input float
restraint_k : input float, optional
bound : input int, optional
tol : input float, optional
print_summary : input int, optional

References

Routine is wrapper around Fortran routine constrain_struct_factor_like_i defined in file src/libAtoms/DynamicalSystem.f95.

constrain_struct_factor_like_mag(z, q, sf[, restraint_k, bound, tol, print_summary])

Constrain an atom to lie in a particluar plane

Parameters:
z : input int
q : input rank-1 array(‘d’) with bounds (3)
sf : input float
restraint_k : input float, optional
bound : input int, optional
tol : input float, optional
print_summary : input int, optional

References

Routine is wrapper around Fortran routine constrain_struct_factor_like_mag defined in file src/libAtoms/DynamicalSystem.f95.

constrain_struct_factor_like_r(z, q, sf[, restraint_k, bound, tol, print_summary])

Constrain an atom to lie in a particluar plane

Parameters:
z : input int
q : input rank-1 array(‘d’) with bounds (3)
sf : input float
restraint_k : input float, optional
bound : input int, optional
tol : input float, optional
print_summary : input int, optional

References

Routine is wrapper around Fortran routine constrain_struct_factor_like_r defined in file src/libAtoms/DynamicalSystem.f95.

disable_damping(*args, **kwargs)

References

Routine is wrapper around Fortran routine disable_damping defined in file src/libAtoms/DynamicalSystem.f95.

enable_damping(damp_time)

Enable damping, with damping time set to damp_time. Only atoms flagged in the damp_mask property will be affected.

Parameters:
damp_time : input float

References

Routine is wrapper around Fortran routine enable_damping defined in file src/libAtoms/DynamicalSystem.f95.

get_damping_time(*args, **kwargs)
Returns:
ret_get_damping_time : float

References

Routine is wrapper around Fortran routine get_damping_time defined in file src/libAtoms/DynamicalSystem.f95.

is_damping_enabled(*args, **kwargs)
Returns:
ret_is_damping_enabled : int

References

Routine is wrapper around Fortran routine is_damping_enabled defined in file src/libAtoms/DynamicalSystem.f95.

kinetic_energy([mpi_obj, local_ke, error])

Return the total kinetic energy \(E_k = \sum_{i} \frac{1}{2} m v^2\)

Parameters:
mpi_obj : MPI_context object, optional
local_ke : input int, optional
error : in/output rank-0 array(int,’i’), optional
Returns:
ret_ke : float

References

Routine is wrapper around Fortran routine kinetic_energy defined in file src/libAtoms/DynamicalSystem.f95.

kinetic_virial([mpi_obj, error])

Return the total kinetic virial \(w_ij = \sum_{k} \frac{1}{2} m v_i v_j\)

Parameters:
mpi_obj : MPI_context object, optional
error : in/output rank-0 array(int,’i’), optional
Returns:
ret_kv : rank-2 array(‘d’) with bounds (3,3)

References

Routine is wrapper around Fortran routine kinetic_virial defined in file src/libAtoms/DynamicalSystem.f95.

momentum([indices])

Return the total momentum \(\mathbf{p} = \sum_i \mathbf{m_i} \mathbf{v_i}\). Optionally only include the contribution of a subset of atoms.

Parameters:
indices : input rank-1 array(‘i’) with bounds (qp_n0), optional
Returns:
ret_p : rank-1 array(‘d’) with bounds (3)

References

Routine is wrapper around Fortran routine momentum defined in file src/libAtoms/DynamicalSystem.f95.

n_thermostat(*args, **kwargs)
Returns:
ret_n_thermostat : int

References

Routine is wrapper around Fortran routine n_thermostat defined in file src/libAtoms/DynamicalSystem.f95.

print_([file])

Print lots of information about this DynamicalSystem in text format.

Parameters:
file : InOutput object, optional

References

Routine is wrapper around Fortran routine print_ defined in file src/libAtoms/DynamicalSystem.f95.

print_status([label, epot, instantaneous, mpi_obj, file, error])

Print a status line showing the current time, temperature, the mean temperature the total energy and the total momentum for this DynamicalSystem. If present, the optional label parameter should be a one character label for the log lines and is printed in the first column of the output. epot should be the potential energy if this is available. instantaneous has the same meaning as in temperature routine.

Parameters:
label : input string(len=-1), optional
epot : input float, optional
instantaneous : input int, optional
mpi_obj : MPI_context object, optional
file : InOutput object, optional
error : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine ds_print_status defined in file src/libAtoms/DynamicalSystem.f95.

print_thermostats(*args, **kwargs)

ds_print_thermostats

References

Routine is wrapper around Fortran routine print_thermostats defined in file src/libAtoms/DynamicalSystem.f95.

remove_atoms(*args, **kwargs)

Remove one or more atoms from this DynamicalSystem. Equivalent of ‘Atoms%remove_atoms’, but also amends the number of degrees of freedom correctly.

Wrapper around Fortran interface remove_atoms containing multiple routines:

remove_atoms(i[, error])
Parameters:
  • i (input int) –
  • error (in/output rank-0 array(int,'i'), optional) –

Routine is wrapper around Fortran routine ds_remove_atom_single defined in file src/libAtoms/DynamicalSystem.f95.

remove_atoms(atomlist_in[, error])
Parameters:
  • atomlist_in (input rank-1 array('i') with bounds (qp_n0)) –
  • error (in/output rank-0 array(int,'i'), optional) –

Routine is wrapper around Fortran routine ds_remove_atom_multiple defined in file src/libAtoms/DynamicalSystem.f95.

remove_thermostat(index)

ds_remove_thermostat(index)

Parameters:
index : input int

References

Routine is wrapper around Fortran routine remove_thermostat defined in file src/libAtoms/DynamicalSystem.f95.

rescale_velo(temp[, mass_weighted, zero_l])

Rescale the atomic velocities to temperature temp. If the current temperature is zero, we first randomise the velocites. If mass_weighted is true, then the velocites are weighted by \(1/sqrt{m}\). Linear momentum is zeroed automatically. If zero_l is true then the angular momentum is also zeroed.

Parameters:
temp : input float
mass_weighted : input int, optional
zero_l : input int, optional

References

Routine is wrapper around Fortran routine rescale_velo defined in file src/libAtoms/DynamicalSystem.f95.

restore_state(to, from)

Restore a DynamicalSystem to a previously saved state. Only scalar members and ds.atoms (minus ds.atoms%connect) are copied back; to should be a properly initialised DynamicalSystem object. The saved state of the random number generator is also restored. calc_dists() is called on the restored atoms object.

Parameters:
to : DynamicalSystem object
from : DynamicalSystem object

References

Routine is wrapper around Fortran routine ds_restore_state defined in file src/libAtoms/DynamicalSystem.f95.

run(pot, dt, n_steps, hook[, hook_interval, summary_interval, write_interval, trajectory, args_str, error, hook_extra_args])[source]

Run n_steps of dynamics using forces from Potential pot.

For each step, forces are evaluated using the Potential pot and the DynamicalSystem is advanced by a time dt (default 1 fs). n_steps (default 10 steps) are carried out in total, with snapshots saved every save_interval steps. The connectivity is recalculated every connect_interval steps. args_str can be used to supply extra arguments to Potential.calc.

Parameters:
pot : Potential object
dt : input float
n_steps : input int
hook : call-back function
hook_interval : input int, optional
summary_interval : input int, optional
write_interval : input int, optional
trajectory : CInOutput object, optional
args_str : input string(len=-1), optional
error : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine dynamicalsystem_run defined in file src/Potentials/Potential.f95.

save_state(to, from[, error])

Save the state of a DynamicalSystem. The output object cannot be used as an initialised DynamicalSystem since connectivity and group information is not copied to save memory. Only scalar members and the ds.atoms object (minus ds.atoms%connect) are copied. The current state of the random number generator is also saved.

Parameters:
to : DynamicalSystem object
from : DynamicalSystem object
error : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine ds_save_state defined in file src/libAtoms/DynamicalSystem.f95.

set_barostat(type, p_ext, hydrostatic_strain, diagonal_strain, finite_strain_formulation, tau_epsilon[, w_epsilon, t, w_epsilon_factor, thermalise])

ds_set_barostat(type,p_ext,hydrostatic_strain,diagonal_strain,finite_strain_formulation,tau_epsilon,[w_epsilon,t,w_epsilon_factor,thermalise])

Parameters:
type : input int
p_ext : input float
hydrostatic_strain : input int
diagonal_strain : input int
finite_strain_formulation : input int
tau_epsilon : input float
w_epsilon : input float, optional
t : input float, optional
w_epsilon_factor : input float, optional
thermalise : input int, optional

References

Routine is wrapper around Fortran routine set_barostat defined in file src/libAtoms/DynamicalSystem.f95.

temperature([property, value, include_all, instantaneous, mpi_obj, error])

Return the temperature, assuming each degree of freedom contributes \(\frac{1}{2}kT\). By default only moving and thermostatted atoms are included — this can be overriden by setting include_all to true. region can be used to restrict the calculation to a particular thermostat region. instantaneous controls whether the calculation should be carried out using the current values of the velocities and masses, or whether to return the value at the last Verlet step (the latter is the default).

Parameters:
property : input string(len=-1), optional
value : input int, optional
include_all : input int, optional
instantaneous : input int, optional
mpi_obj : MPI_context object, optional
error : in/output rank-0 array(int,’i’), optional
Returns:
ret_temperature : float

References

Routine is wrapper around Fortran routine temperature defined in file src/libAtoms/DynamicalSystem.f95.

thermostat_temperatures(n0)
Parameters:
n0 : input int

shape(qp_temps,0)

Returns:
temps : rank-1 array(‘d’) with bounds (qp_n0)

References

Routine is wrapper around Fortran routine thermostat_temperatures defined in file src/libAtoms/DynamicalSystem.f95.

update_thermostat([t, p, i])

ds_update_thermostat([t,p,i])

Parameters:
t : input float, optional
p : input float, optional
i : input int, optional

References

Routine is wrapper around Fortran routine update_thermostat defined in file src/libAtoms/DynamicalSystem.f95.

zero_momentum([indices])

Change velocities to those that the system would have in the zero momentum frame. Optionalally zero the total momentum of a subset of atoms, specified by indices.

Parameters:
indices : input rank-1 array(‘i’) with bounds (qp_n0), optional

References

Routine is wrapper around Fortran routine zero_momentum defined in file src/libAtoms/DynamicalSystem.f95.

avg_temp

Time-averaged temperature

avg_time

Averaging time, in fs

cur_temp

Current temperature

dt

Last time step

dw

Increment of work done this time step

ekin

Current kinetic energy

epot

Total potential energy

ext_energy

Extended energy

n

Number of atoms

nconstraints

Number of constraints

ndof

Number of degrees of freedom

nrestraints

Number of restraints

nrigid

Number of rigid bodies

nsteps

Number of integration steps

random_seed

RNG seed, used by ds_save_state and ds_restore_state only.

t

Time

thermostat_dw

Increment of work done by thermostat

thermostat_work

Total work done by thermostat

wkin

Current kinetic contribution to the virial

work

Total work done

class quippy.dynamicalsystem.Dynamics(atoms, timestep, trajectory, trajectoryinterval=10, initialtemperature=None, logfile='-', loginterval=1, loglabel='D')[source]

Bases: object

Wrapper around DynamicalSystem integrator compatible with ASE ase.md.MolecularDynamics interface.

Note

This class uses ASE units for time (and hence velocities and momenta) which differ from the femtoseconds used in QUIP. When using this class, all times should be given in ASE time units.

Parameters:
  • atoms – quippy or ASE Atoms instance. Note that if atoms is not a quippy Atoms object, a copy will be made.
  • timestep – in ASE time units (multiply by ase.units.fs to convert from femtoseconds)
  • trajectory – output file to which to write the trajectory. Can be a string to create a new output object.
  • trajectoryinterval – interval at which to write frames
  • initialtemperature – if not None, rescale initial velocities to a specified temperature, given in K.
  • logfile – filename or open InOutput object to write log lines to. Use special filename "-" for stdout (default).
  • loginterval – interval at which to write log lines
Attributes:
average_temperature

Average temperature

averaging_time

Averaging time used for average temperature and kinetic energy

damping

Get or set the damping time constant in fs.

number_of_constraints

Get number of constraints

number_of_degrees_of_freedom

Get number of degrees of freedom in system, including QUIP constraints

number_of_restraints

Get number of restraints

number_of_rigid_bodies

Get number of rigid_bodies

state

Save or restore current state of this dynamical system

temperature

Get or set the current temperature

time

Time in ASE units (Note: NOT the same as femtoseconds)

timestep

Set timestep, in ASE time units

Methods

add_thermostat(type, T[, gamma, Q, tau, …]) Add a new thermostat to this Dynamics, and return its index.
attach(function[, interval]) Attach callback function.
get_number_of_thermostats() Return the number of active thermostats
get_thermostat_temperatures() Return the current temperatures of all thermostated regions
insert_observer(function[, position, interval]) Insert an observer.
print_thermostats() Print a table of the current thermostats in this system
remove_thermostat(index) Remove thermostat number index.
run([steps]) Run dynamics forwards for steps steps.
set_barostat(type, p_ext, …[, W_epsilon, …]) Add a barostat to this dynamical system
set_temperature(temperature) Randomise velocities to a target temperature (given in K)
step(forces) Advance dynamics by one time-step.
update_barostat(p, T) Update target pressure p or temperature T for NPT barostat
update_thermostat([T, p, index]) Change the target temperature T or presure p for thermostat index.
add_thermostat(type, T, gamma=None, Q=None, tau=None, tau_cell=None, p=None, NHL_tau=None, NHL_mu=None, massive=None)[source]

Add a new thermostat to this Dynamics, and return its index.

By default, all thermostats apply to the whole system. The ‘thermostat_region’ property can be used to control which thermostats affect which atoms. It should be set to the index of the required thermostat for each atom.

Parameters:
  • type – string or integer giving thermostat type. The following types are supported:: THERMOSTAT_NONE, THERMOSTAT_LANGEVIN, THERMOSTAT_NOSE_HOOVER, THERMOSTAT_NOSE_HOOVER_LANGEVIN, THERMOSTAT_LANGEVIN_NPT, THERMOSTAT_LANGEVIN_PR, THERMOSTAT_NPH_ANDERSEN, THERMOSTAT_NPH_PR, THERMOSTAT_LANGEVIN_OU, THERMOSTAT_LANGEVIN_NPT_NB, THERMOSTAT_ALL_PURPOSE.
  • T – target temperature for this thermostat, in K.
  • gamma – decay constant, in units of 1/fs
  • tau – time constant, in units of fs. tau == 1/gamma, and only one of the two should be specified.
  • tau_cell – time constant for the cell degrees of freedom (for variable cell thermostats only).
  • p – target pressure (for variable cell thermostats)
  • NHL_tau – time constant for Nose-Hoover-Langevein thermostats
  • NHL_mu – thermostat mass Nose-Hoover-Langevin thermostats
  • massive – set to True to enable massive Nose-Hoover-Langevin
attach(function, interval=1, *args, **kwargs)[source]

Attach callback function.

At every interval steps, call function with arguments args and keyword arguments kwargs.

get_number_of_thermostats()[source]

Return the number of active thermostats

Excludes thermostat with index zero, which is used for damping.

get_thermostat_temperatures()[source]

Return the current temperatures of all thermostated regions

insert_observer(function, position=0, interval=1, *args, **kwargs)[source]

Insert an observer.

print_thermostats()[source]

Print a table of the current thermostats in this system

remove_thermostat(index)[source]

Remove thermostat number index.

index should be in range 1 <= index <= dyn.get_number_of_thermostats()

run(steps=50)[source]

Run dynamics forwards for steps steps.

set_barostat(type, p_ext, hydrostatic_strain, diagonal_strain, finite_strain_formulation, tau_epsilon, W_epsilon=None, T=None, W_epsilon_factor=None)[source]

Add a barostat to this dynamical system

Langevin NPT barostat based on fluctuation/dissipation, as originally implemented for hydrostatic strain using EOM from Quigley, D. and Probert, M.I.J., J. Chem. Phys. 120 11432, subsequently rediscretized by Noam Bernstein based on ideas from and discussion with B. Leimkuhler.

Modified for arbitrary strain based on (but not exactly using) formulation in E. Tadmor and R. Miller Modeling Materials: Continuum, Atomistic and Multiscale Techniques (Cambridge University Press, 2011). Chap 9.5. Their definition of stress (factors of F, F^T, J, and F^-T) for finite strain is optionally used, but certain terms in EOM are excluded, and their discretization is entirely ignored.

Parameters:
  • type – The type of barostat to be used. Currently only BAROSTAT_HOOVER_LANGEVIN is supported.
  • p_ext – External pressure in QUIP units eV/A^3
  • hystrostatic_strain – Set to True to constrain a hydrostatic strain tensor
  • diagonal_strain – Set to True to constrain a diagonal strain tensor
  • finite_strain_formulation – If True, use finite instead of infinitessimal strain formulation
  • tau_epsilon – time constant for Langevin part (in fs)
  • W_epsilon – fictious cell mass used in Langevin NPT
  • T – target temperature for Langevin part
  • W_epsilon_factor – Scaling factor for fictious cell mass
set_temperature(temperature)[source]

Randomise velocities to a target temperature (given in K)

step(forces)[source]

Advance dynamics by one time-step.

Returns forces at the end of the time-step, suitable for passing to next step()

update_barostat(p, T)[source]

Update target pressure p or temperature T for NPT barostat

update_thermostat(T=None, p=None, index=1)[source]

Change the target temperature T or presure p for thermostat index.

average_temperature

Average temperature

averaging_time

Averaging time used for average temperature and kinetic energy

damping

Get or set the damping time constant in fs. Set to None to disable damping. By default damping applies to all atoms, but can be selectively enabled with the ‘damp_mask’ property.

number_of_constraints

Get number of constraints

number_of_degrees_of_freedom

Get number of degrees of freedom in system, including QUIP constraints

number_of_restraints

Get number of restraints

number_of_rigid_bodies

Get number of rigid_bodies

state

Save or restore current state of this dynamical system

temperature

Get or set the current temperature

time

Time in ASE units (Note: NOT the same as femtoseconds)

timestep

Set timestep, in ASE time units

quippy.dynamicalsystem.gaussian_velocity_component(m, t)

Draw a velocity component from the correct Gaussian distribution for a degree of freedom with (effective) mass m at temperature T

Parameters:
m : input float
t : input float
Returns:
ret_v : float

References

Routine is wrapper around Fortran routine gaussian_velocity_component defined in file src/libAtoms/DynamicalSystem.f95.

quippy.dynamicalsystem.torque(pos, force[, origin])
Parameters:
pos : input rank-2 array(‘d’) with bounds (qp_n0,qp_n1)
force : input rank-2 array(‘d’) with bounds (qp_n2,qp_n3)
origin : input rank-1 array(‘d’) with bounds (3), optional
Returns:
ret_tau : rank-1 array(‘d’) with bounds (3)

References

Routine is wrapper around Fortran routine torque defined in file src/libAtoms/DynamicalSystem.f95.

quippy.dynamicalsystem.distance_relative_velocity(at, i, j)

Return the distance between two atoms and the relative velocity between them projected along the bond direction. This is useful for time dependent constraints.

Parameters:
at : Atoms object
i : input int
j : input int
dist : float
rel_velo : float

References

Routine is wrapper around Fortran routine distance_relative_velocity defined in file src/libAtoms/DynamicalSystem.f95.

quippy.dynamicalsystem.angular_momentum(*args, **kwargs)

Routine is wrapper around Fortran interface angular_momentum containing multiple routines:

quippy.dynamicalsystem.angular_momentum(mass, pos, velo[, origin, indices])

Return the angular momentum of all the atoms in this DynamicalSystem, defined by \(\mathbf{L} = \sum_{i} \mathbf{r_i} \times \mathbf{v_i}\).

Parameters:
  • mass (input rank-1 array('d') with bounds (qp_n0)) –
  • pos (input rank-2 array('d') with bounds (qp_n1,qp_n2)) –
  • velo (input rank-2 array('d') with bounds (qp_n3,qp_n4)) –
  • origin (input rank-1 array('d') with bounds (3), optional) –
  • indices (input rank-1 array('i') with bounds (qp_n5), optional) –
Returns:

ret_l – rank-1 array(‘d’) with bounds (3)

Routine is wrapper around Fortran routine arrays_angular_momentum defined in file src/libAtoms/DynamicalSystem.f95.

quippy.dynamicalsystem.kinetic_virial(*args, **kwargs)

Routine is wrapper around Fortran interface kinetic_virial containing multiple routines:

quippy.dynamicalsystem.kinetic_virial(mass, velo)

Return the total kinetic virial given atomic masses and velocities

Parameters:
  • mass (input rank-1 array('d') with bounds (qp_n0)) –
  • velo (input rank-2 array('d') with bounds (qp_n1,qp_n2)) –
Returns:

ret_kv – rank-2 array(‘d’) with bounds (3,3)

Routine is wrapper around Fortran routine arrays_kinetic_virial defined in file src/libAtoms/DynamicalSystem.f95.

quippy.dynamicalsystem.kinetic_virial(mass, velo)

Return the kinetic virial given a mass and a velocity

Parameters:
  • mass (input float) –
  • velo (input rank-1 array('d') with bounds (3)) –
Returns:

ret_kv – rank-2 array(‘d’) with bounds (3,3)

Routine is wrapper around Fortran routine single_kinetic_virial defined in file src/libAtoms/DynamicalSystem.f95.

quippy.dynamicalsystem.momentum(*args, **kwargs)

Routine is wrapper around Fortran interface momentum containing multiple routines:

quippy.dynamicalsystem.momentum(mass, velo[, indices])

Return the total momentum \(\mathbf{p} = \sum_i \mathbf{m_i} \mathbf{v_i}\). Optionally only include the contribution of a subset of atoms.

Parameters:
  • mass (input rank-1 array('d') with bounds (qp_n0)) –
  • velo (input rank-2 array('d') with bounds (qp_n1,qp_n2)) –
  • indices (input rank-1 array('i') with bounds (qp_n3), optional) –
Returns:

ret_p – rank-1 array(‘d’) with bounds (3)

Routine is wrapper around Fortran routine arrays_momentum defined in file src/libAtoms/DynamicalSystem.f95.

quippy.dynamicalsystem.kinetic_energy(*args, **kwargs)

Routine is wrapper around Fortran interface kinetic_energy containing multiple routines:

quippy.dynamicalsystem.kinetic_energy(mass, velo[, local_ke])

Return the total kinetic energy given atomic masses and velocities

Parameters:
  • mass (input rank-1 array('d') with bounds (qp_n0)) –
  • velo (input rank-2 array('d') with bounds (qp_n1,qp_n2)) –
  • local_ke (in/output rank-1 array('d') with bounds (qp_n3), optional) –
Returns:

ret_ke – float

Routine is wrapper around Fortran routine arrays_kinetic_energy defined in file src/libAtoms/DynamicalSystem.f95.

quippy.dynamicalsystem.kinetic_energy(mass, velo)

Return the kinetic energy given a mass and a velocity

Parameters:
  • mass (input float) –
  • velo (input rank-1 array('d') with bounds (3)) –
Returns:

ret_ke – float

Routine is wrapper around Fortran routine single_kinetic_energy defined in file src/libAtoms/DynamicalSystem.f95.