Integrators documentation¶

Integrator Base Class¶

class peripy.integrators.Integrator(dt, context=None)¶

Base class for integrators.

All integrators must define an init method, which may or may not inherit Integrator as a parent class using super(). All integrators that inherit Integrator are OpenCL implementations that can use GPU or CPU. All integrators must also define a call method which performs one integration step, a _build_special method which builds the OpenCL programs which are special to the integrator, and a _create_special_buffers method which creates the OpenCL buffers which are special to the integrator.

Create an Integrator object.

This method should be implemented in every concrete integrator.

Parameters:	dt (float) – The length of time (in seconds [s]) of one time-step. context (`pyopencl._cl.Context` or NoneType) – Optional argument for the user to provide a context with a single suitable device, default is None.
Returns:	A `Integrator` object

build(nnodes, degrees_freedom, max_neighbours, coords, volume, family, bc_types, bc_values, force_bc_types, force_bc_values, stiffness_corrections, bond_types, densities)¶

Build OpenCL programs.

Builds the programs that are common to all integrators and the buffers which are independent of peripy.model.Model.simulate() parameters.

create_buffers(nlist, n_neigh, bond_stiffness, critical_stretch, plus_cs, u, ud, udd, force, body_force, damage, regimes, nregimes, nbond_types)¶

Initialise the OpenCL buffers.

Initialises only the buffers which are dependent on peripy.model.Model.simulate() parameters.

write(u, ud, udd, force, body_force, damage, nlist, n_neigh)¶: Copy the state variables from device memory to host memory.

Euler¶

class peripy.integrators.Euler(dt)¶

Euler integrator for cython.

C implementation of the Euler integrator generated using Cython. Uses CPU only. The Euler method is a first-order numerical integration method. The integration is given by,

\[u(t + \delta t) = u(t) + \delta t f(t),\]

where \(u(t)\) is the displacement at time \(t\), \(f(t)\) is the force density at time \(t\), \(\delta t\) is the time step.

Create an Euler integrator object.

Parameters:	dt (float) – The length of time (in seconds [s]) of one time-step.
Returns:	An `Euler` object

__call__(displacement_bc_magnitude, force_bc_magnitude)¶

Conduct one iteration of the integrator.

Parameters:	displacement_bc_magnitude (float) – the magnitude applied to the displacement boundary conditions for the current time-step. force_bc_magnitude (float) – the magnitude applied to the force boundary conditions for the current time-step.

build(nnodes, degrees_freedom, max_neighbours, coords, volume, family, bc_types, bc_values, force_bc_types, force_bc_values, stiffness_corrections, bond_types, densities)¶

Initiate integrator arrays.

Since Euler uses cython in place of OpenCL, there are no OpenCL programs or buffers to be built/created. Instead, this method instantiates the arrays and variables that are independent of peripy.model.Model.simulate() parameters as python objects that are used as arguments of the cython functions.

create_buffers(nlist, n_neigh, bond_stiffness, critical_stretch, plus_cs, u, ud, udd, force, body_force, damage, regimes, nregimes, nbond_types)¶

Initiate arrays that are dependent on simulation parameters.

Initiates arrays that are dependent on peripy.model.Model.simulate() parameters. Since Euler uses cython in place of OpenCL, there are no buffers to be created, just python objects that are used as arguments of the cython functions.

write(damage, u, ud, udd, force, body_force, nlist, n_neigh)¶: Return the state variable arrays.

EulerCL¶

class peripy.integrators.EulerCL(*args, **kwargs)¶

Euler integrator for OpenCL.

The Euler method is a first-order numerical integration method. The integration is given by,

\[u(t + \delta t) = u(t) + \delta t f(t),\]

where \(u(t)\) is the displacement at time \(t\), \(f(t)\) is the force density at time \(t\), \(\delta t\) is the time step.

Create an EulerCL integrator object.

Returns:	An `EulerCL` object

__call__(displacement_bc_magnitude, force_bc_magnitude)¶

Conduct one iteration of the integrator.

Parameters:	displacement_bc_magnitude (float) – the magnitude applied to the displacement boundary conditions for the current time-step. force_bc_magnitude (float) – the magnitude applied to the force boundary conditions for the current time-step.

EulerCromerCL¶

class peripy.integrators.EulerCromerCL(damping, *args, **kwargs)¶

Euler Cromer integrator for OpenCL which can use GPU or CPU.

The Euler-Cromer method is a first-order numerical integration method. The integration is given by,

\[\dot{u}(t + \delta t) = \dot{u}(t) + \delta t \ddot{u}(t),\]

\[u(t + \delta t) = u(t) + \delta t \dot{u}(t + \delta t),\]

where \(u(t)\) is the displacement at time \(t\), \(\dot{u}(t)\) is the velocity at time \(t\), \(\ddot{u}(t)\) is the acceleration at time \(t\), and \(\delta t\) is the time step.

A dynamic relaxation damping term \(\eta \dot{u}(t)\) is added to the equation of motion so that the solution to quickly converges to a steady state solution in quasi-static problems. Given the velocity and displacement vectors of each node at time step \(t\), the acceleration at time step \(t\) is given by the equation of motion,

\[\ddot{u}(t) = \frac{f(t) - \eta \dot{u}(t)}{\rho},\]

where \(f(t)\) is the force density at time \(t\), \(\eta\) is the dynamic relaxation damping constant and \(\rho\) is the density.

Create an EulerCromerCL integrator object.

Parameters:	damping (float) – The dynamic relaxation damping constant with units [kg/(m^3 s)]
Returns:	An `EulerCromerCL` object

__call__(displacement_bc_magnitude, force_bc_magnitude)¶

Conduct one iteration of the integrator.

Parameters:	displacement_bc_magnitude (float) – the magnitude applied to the displacement boundary conditions for the current time-step. force_bc_magnitude (float) – the magnitude applied to the force boundary conditions for the current time-step.

VelocityVerletCL¶

class peripy.integrators.VelocityVerletCL(damping, *args, **kwargs)¶

Velocity-Verlet integrator for OpenCL.

The Velocity-Verlet method is a second-order numerical integration method. The integration is given by,

\[\dot{u}(t + \frac{\delta t}{2}) = \dot{u}(t) + \frac{\delta t}{2}\ddot{u}(t),\]

\[u(t + \delta t) = u(t) + \delta t \dot{u}(t) + \frac{\delta t}{2} \ddot{u}(t),\]

\[\dot{u}(t + \delta t) = \dot{u}(t + \frac{\delta t}{2}) + \frac{\delta t}{2} \ddot{u}(t + \delta t),\]

where \(u(t)\) is the displacement at time \(t\), \(\dot{u}(t)\) is the velocity at time \(t\), \(\ddot{u}(t)\) is the acceleration at time \(t\) and \(\delta t\) is the time step.

A dynamic relaxation damping term \(\eta \dot{u}(t)\) is added to the equation of motion so that the solution to quickly converges to a steady state solution in quasi-static problems. Given the displacement vectors of each node at time step t, and half-step velocity vectors of each node at time step \(t + \frac{\delta t}{2}\), the acceleration at time step \(t + \delta t\) is given by the equation of motion,

\[\ddot{u}(t + \delta t) = \frac{f(t + \delta t) - \eta \dot{u}(t + \frac{\delta t}{2})}{\rho},\]

where \(f(t)\) is the force density at time \(t\), \(\eta\) is the dynamic relaxation damping constant and \(\rho\) is the density.

Create an VelocityVerletCL integrator object.

Parameters:	damping (float) – The dynamic relaxation damping constant with units [kg/(m^3 s)]
Returns:	A `VelocityVerletCL` object

__call__(displacement_bc_magnitude, force_bc_magnitude)¶

Conduct one iteration of the integrator.

Parameters:	displacement_bc_magnitude (float) – the magnitude applied to the displacement boundary conditions for the current time-step. force_bc_magnitude (float) – the magnitude applied to the force boundary conditions for the current time-step.

Exceptions¶

exception peripy.integrators.ContextError¶

No suitable context was found by get_context().

Exception constructor.