PyElastica¶
This the the documentation page for PyElastica. For more information about PyElastica, see the project website.
Rods¶
Rod classes and its data structures

class
elastica.rod.__init__.
RodBase
[source]¶ Bases:
object
Base class for all rods.
Note
All new rod classes must be derived from this RodBase class.
Cosserat Rod¶
Rod base classes and implementation details that need to be hidden from the user

class
elastica.rod.cosserat_rod.
CosseratRod
(n_elements, _vector_states, _matrix_states, radius, mass_second_moment_of_inertia, inv_mass_second_moment_of_inertia, shear_matrix, bend_matrix, density, volume, mass, dissipation_constant_for_forces, dissipation_constant_for_torques, internal_forces, internal_torques, external_forces, external_torques, lengths, rest_lengths, tangents, dilatation, dilatation_rate, voronoi_dilatation, rest_voronoi_lengths, sigma, kappa, rest_sigma, rest_kappa, internal_stress, internal_couple, damping_forces, damping_torques)[source]¶ Bases:
elastica.rod.RodBase
,elastica._elastica_numpy._rod._data_structures._RodSymplecticStepperMixin

_compute_internal_bending_twist_stresses_from_model
()[source]¶ Linear force functional Operates on B : (3,3,n) tensor and curvature kappa (3,n)

_compute_internal_forces_and_torques
(time)[source]¶ Compute internal forces and torques. We need to compute internal forces and torques before the acceleration because they are used in interaction. Thus in order to speed up simulation, we will compute internal forces and torques one time and use them. Previously, we were computing internal forces and torques multiple times in interaction. Saving internal forces and torques in a variable take some memory, but we will gain speed up. :param time:

Boundary Conditions¶
Endpoint Constraints¶
Boundary conditions for rod

class
elastica.boundary_conditions.
FreeRod
[source]¶ Bases:
object
This is the base class for displacement boundary conditions. It applies no constraints or displacements to the rod.
Note
Every new displacement boundary condition class must be derived from FreeRod class.

class
elastica.boundary_conditions.
OneEndFixedRod
(fixed_position, fixed_directors)[source]¶ Bases:
elastica._elastica_numpy._boundary_conditions.FreeRod
This boundary condition class fixes one end of the rod. Currently, this boundary condition fixes position and directors at the first node and first element of the rod.
 fixed_positions : numpy.ndarray
 2D (dim, 1) array containing data with ‘float’ type.
 fixed_directors : numpy.ndarray
 3D (dim, dim, 1) array containing data with ‘float’ type.

__init__
(fixed_position, fixed_directors)[source]¶ Parameters:  fixed_position (numpy.ndarray) – 2D (dim, 1) array containing data with ‘float’ type.
 fixed_directors (numpy.ndarray) – 3D (dim, dim, 1) array containing data with ‘float’ type.

class
elastica.boundary_conditions.
HelicalBucklingBC
(position_start, position_end, director_start, director_end, twisting_time, slack, number_of_rotations)[source]¶ Bases:
elastica._elastica_numpy._boundary_conditions.FreeRod
This is the boundary condition class for Helical Buckling case in Gazzola et. al. RSoS (2018). The applied boundary condition is twist and slack on to the first and last nodes and elements of the rod.
 twisting_time: float
 Time to complete twist.
 final_start_position: numpy.ndarray
 2D (dim, 1) array containing data with ‘float’ type. Position of first node of rod after twist completed.
 final_end_position: numpy.ndarray
 2D (dim, 1) array containing data with ‘float’ type. Position of last node of rod after twist completed.
 ang_vel: numpy.ndarray
 2D (dim, 1) array containing data with ‘float’ type. Angular velocity of rod during twisting time.
 shrink_vel: numpy.ndarray
 2D (dim, 1) array containing data with ‘float’ type. Shrink velocity of rod during twisting time.
 final_start_directors: numpy.ndarray
 3D (dim, dim, blocksize) array containing data with ‘float’ type. Directors of first element of rod after twist completed.
 final_end_directors: numpy.ndarray
 3D (dim, dim, blocksize) array containing data with ‘float’ type. Directors of last element of rod after twist completed.

__init__
(position_start, position_end, director_start, director_end, twisting_time, slack, number_of_rotations)[source]¶ Parameters:  position_start (numpy.ndarray) – 2D (dim, 1) array containing data with ‘float’ type. Initial position of first node.
 position_end (numpy.ndarray) – 2D (dim, 1) array containing data with ‘float’ type. Initial position of last node.
 director_start (numpy.ndarray) – 3D (dim, dim, blocksize) array containing data with ‘float’ type. Initial director of first element.
 director_end (numpy.ndarray) – 3D (dim, dim, blocksize) array containing data with ‘float’ type. Initial director of last element.
 twisting_time (float) – Time to complete twist.
 slack (float) – Slack applied to rod.
 number_of_rotations (float) – Number of rotations applied to rod.
External Forces¶
External forcing for rod

class
elastica.external_forces.
NoForces
[source]¶ Bases:
object
This is the base class for external forcing boundary conditions applied to rodlike objects.
Note
Every new external forcing class must be derived from NoForces class.

class
elastica.external_forces.
GravityForces
(acc_gravity=array([ 0., 9.80665, 0. ]))[source]¶ Bases:
elastica._elastica_numpy._external_forces.NoForces
This class applies a constant gravitational force to the entire rod.
 acc_gravity: numpy.ndarray
 1D (dim) array containing data with ‘float’ type. Gravitational acceleration vector.

class
elastica.external_forces.
EndpointForces
(start_force, end_force, ramp_up_time=0.0)[source]¶ Bases:
elastica._elastica_numpy._external_forces.NoForces
This class applies constant forces on the endpoint nodes.
 start_force: numpy.ndarray
 2D (dim, 1) array containing data with ‘float’ type. Force applied to first node of the rodlike object.
 end_force: numpy.ndarray
 2D (dim, 1) array containing data with ‘float’ type. Force applied to last node of the rodlike object.
 ramp_up_time: float
 Applied forces are ramped up until ramp up time.

__init__
(start_force, end_force, ramp_up_time=0.0)[source]¶ Parameters:  start_force (numpy.ndarray) – 2D (dim, 1) array containing data with ‘float’ type. Force applied to first node of the rodlike object.
 end_force (numpy.ndarray) – 2D (dim, 1) array containing data with ‘float’ type. Force applied to last node of the rodlike object.
 ramp_up_time (float) – Applied forces are ramped up until ramp up time.

class
elastica.external_forces.
UniformTorques
(torque, direction=array([0., 0., 0.]))[source]¶ Bases:
elastica._elastica_numpy._external_forces.NoForces
This class applies a uniform torque to the entire rod.
 torque: numpy.ndarray
 2D (dim, 1) array containing data with ‘float’ type. Total torque applied to a rodlike object.

class
elastica.external_forces.
UniformForces
(force, direction=array([0., 0., 0.]))[source]¶ Bases:
elastica._elastica_numpy._external_forces.NoForces
This class applies a uniform force to the entire rod.
 force: numpy.ndarray
 2D (dim, 1) array containing data with ‘float’ type. Total force applied to a rodlike object.

class
elastica.external_forces.
MuscleTorques
(base_length, b_coeff, period, wave_number, phase_shift, direction, rest_lengths, ramp_up_time=0.0, with_spline=False)[source]¶ Bases:
elastica._elastica_numpy._external_forces.NoForces
This class applies muscle torques along the body. The applied muscle torques are treated as applied external forces. This class can apply muscle torques as a traveling wave with a beta spline or only as a traveling wave. For implementation details refer to Gazzola et. al. RSoS. (2018).
 direction: numpy.ndarray
 2D (dim, 1) array containing data with ‘float’ type. Muscle torque direction.
 angular_frequency: float
 Angular frequency of traveling wave.
 wave_number: float
 Wave number of traveling wave.
 phase_shift: float
 Phase shift of traveling wave.
 ramp_up_time: float
 Applied muscle torques are ramped up until ramp up time.
 my_spline: numpy.ndarray
 1D (blocksize) array containing data with ‘float’ type. Generated spline.

__init__
(base_length, b_coeff, period, wave_number, phase_shift, direction, rest_lengths, ramp_up_time=0.0, with_spline=False)[source]¶ Parameters:  base_length (float) – Rest length of the rodlike object.
 b_coeff (nump.ndarray) – 1D array containing data with ‘float’ type. Beta coefficients for betaspline.
 period (float) – Period of traveling wave.
 wave_number (float) – Wave number of traveling wave.
 phase_shift (float) – Phase shift of traveling wave.
 direction (numpy.ndarray) – 1D (dim) array containing data with ‘float’ type. Muscle torque direction.
 ramp_up_time (float) – Applied muscle torques are ramped up until ramp up time.
 with_spline (boolean) – Option to use betaspline.
Environment Interactions¶
Interaction module

class
elastica.interaction.
AnisotropicFrictionalPlane
(k, nu, plane_origin, plane_normal, slip_velocity_tol, static_mu_array, kinetic_mu_array)[source]¶ Bases:
elastica._elastica_numpy._external_forces.NoForces
,elastica._elastica_numpy._interaction.InteractionPlane
This anisotropic friction plane class is for computing anisotropic friction forces on rods. A detailed explanation of the implemented equations can be found in Gazzola et al. RSoS. (2018).
 k: float
 Stiffness coefficient between the plane and the rodlike object.
 nu: float
 Dissipation coefficient between the plane and the rodlike object.
 plane_origin: numpy.ndarray
 2D (dim, 1) array containing data with ‘float’ type. Origin of the plane.
 plane_normal: numpy.ndarray
 2D (dim, 1) array containing data with ‘float’ type. The normal vector of the plane.
 slip_velocity_tol: float
 Velocity tolerance to determine if the element is slipping or not.
 static_mu_array: numpy.ndarray
 1D (3,) array containing data with ‘float’ type. [forward, backward, sideways] static friction coefficients.
 kinetic_mu_array: numpy.ndarray
 1D (3,) array containing data with ‘float’ type. [forward, backward, sideways] kinetic friction coefficients.

__init__
(k, nu, plane_origin, plane_normal, slip_velocity_tol, static_mu_array, kinetic_mu_array)[source]¶ Parameters:  k (float) – Stiffness coefficient between the plane and the rodlike object.
 nu (float) – Dissipation coefficient between the plane and the rodlike object.
 plane_origin (numpy.ndarray) – 2D (dim, 1) array containing data with ‘float’ type. Origin of the plane.
 plane_normal (numpy.ndarray) – 2D (dim, 1) array containing data with ‘float’ type. The normal vector of the plane.
 slip_velocity_tol (float) – Velocity tolerance to determine if the element is slipping or not.
 static_mu_array (numpy.ndarray) – 1D (3,) array containing data with ‘float’ type. [forward, backward, sideways] static friction coefficients.
 kinetic_mu_array (numpy.ndarray) – 1D (3,) array containing data with ‘float’ type. [forward, backward, sideways] kinetic friction coefficients.

class
elastica.interaction.
SlenderBodyTheory
(dynamic_viscosity)[source]¶ Bases:
elastica._elastica_numpy._external_forces.NoForces
This slender body theory class is for flowstructure interaction problems. This class applies hydrodynamic forces on the body using the slender body theory given in Eq. 4.13 of Gazzola et al. RSoS (2018).
 dynamic_viscosity: float
 Dynamic viscosity of the fluid.
Multiple Rod Connections¶
Module containing joint classes to connect multiple rods together.

class
elastica.joint.
FreeJoint
(k, nu)[source]¶ Bases:
object
This free joint class is the base class for all joints. Free or spherical joints constrains the relative movement between two nodes (chosen by the user) by applying restoring forces. For implementation details, refer to Zhang et al. Nature Communications (2019).
 k: float
 Stiffness coefficient of the joint.
 nu: float
 Damping coefficient of the joint.
Note
Every new joint class must be derived from the FreeJoint class.

__init__
(k, nu)[source]¶ Parameters:  k (float) – Stiffness coefficient of the joint.
 nu (float) – Damping coefficient of the joint.

apply_forces
(rod_one, index_one, rod_two, index_two)[source]¶ Apply joint force to the connected rod objects.
Parameters:  rod_one (object) – Rodlike object
 index_one (int) – Index of first rod for joint.
 rod_two (object) – Rodlike object
 index_two (int) – Index of second rod for joint.

apply_torques
(rod_one, index_one, rod_two, index_two)[source]¶ Apply restoring joint torques to the connected rod objects.
In FreeJoint class, this routine simply passes.
Parameters:  rod_one (object) – Rodlike object
 index_one (int) – Index of first rod for joint.
 rod_two (object) – Rodlike object
 index_two (int) – Index of second rod for joint.

class
elastica.joint.
HingeJoint
(k, nu, kt, normal_direction)[source]¶ Bases:
elastica.joint.FreeJoint
This hinge joint class constrains the relative movement and rotation (only one axis defined by the user) between two nodes and elements (chosen by the user) by applying restoring forces and torques. For implementation details, refer to Zhang et. al. Nature Communications (2019).
 k: float
 Stiffness coefficient of the joint.
 nu: float
 Damping coefficient of the joint.
 kt: float
 Rotational stiffness coefficient of the joint.
 normal_direction: numpy.ndarray
 2D (dim, 1) array containing data with ‘float’ type. Constraint rotation direction.

__init__
(k, nu, kt, normal_direction)[source]¶ Parameters:  k (float) – Stiffness coefficient of the joint.
 nu (float) – Damping coefficient of the joint.
 kt (float) – Rotational stiffness coefficient of the joint.
 normal_direction (numpy.ndarray) – 2D (dim, 1) array containing data with ‘float’ type. Constraint rotation direction.

apply_forces
(rod_one, index_one, rod_two, index_two)[source]¶ Apply joint force to the connected rod objects.
Parameters:  rod_one (object) – Rodlike object
 index_one (int) – Index of first rod for joint.
 rod_two (object) – Rodlike object
 index_two (int) – Index of second rod for joint.

apply_torques
(rod_one, index_one, rod_two, index_two)[source]¶ Apply restoring joint torques to the connected rod objects.
In FreeJoint class, this routine simply passes.
Parameters:  rod_one (object) – Rodlike object
 index_one (int) – Index of first rod for joint.
 rod_two (object) – Rodlike object
 index_two (int) – Index of second rod for joint.

class
elastica.joint.
FixedJoint
(k, nu, kt)[source]¶ Bases:
elastica.joint.FreeJoint
The fixed joint class restricts the relative movement and rotation between two nodes and elements by applying restoring forces and torques. For implementation details, refer to Zhang et al. Nature Communications (2019).
 k: float
 Stiffness coefficient of the joint.
 nu: float
 Damping coefficient of the joint.
 kt: float
 Rotational stiffness coefficient of the joint.

__init__
(k, nu, kt)[source]¶ Parameters:  k (float) – Stiffness coefficient of the joint.
 nu (float) – Damping coefficient of the joint.
 kt (float) – Rotational stiffness coefficient of the joint.

apply_forces
(rod_one, index_one, rod_two, index_two)[source]¶ Apply joint force to the connected rod objects.
Parameters:  rod_one (object) – Rodlike object
 index_one (int) – Index of first rod for joint.
 rod_two (object) – Rodlike object
 index_two (int) – Index of second rod for joint.

apply_torques
(rod_one, index_one, rod_two, index_two)[source]¶ Apply restoring joint torques to the connected rod objects.
In FreeJoint class, this routine simply passes.
Parameters:  rod_one (object) – Rodlike object
 index_one (int) – Index of first rod for joint.
 rod_two (object) – Rodlike object
 index_two (int) – Index of second rod for joint.

class
elastica.joint.
ExternalContact
(k, nu)[source]¶ Bases:
elastica.joint.FreeJoint
Assumes that the second entity is a rigid body for now, can be changed at a later time
Most of the cylindercylinder contact SHOULD be implemented as given in this paper: http://larochelle.sdsmt.edu/publications/20052009/Collision%20Detection%20of%20Cylindrical%20Rigid%20Bodies%20Using%20Line%20Geometry.pdf
but, it isn’t (the elasticacpp kernels are implented)! This is maybe to speedup the kernel, but it’s potentially dangerous as it does not deal with “end” conditions correctly.

_ExternalContact__find_min_dist
(x1, e1, x2, e2)¶ Assumes x2, e2 is one elment for now
Will definitely get speedup from numba

Callback Functions¶
Module contains callback classes to save simulation data for rodlike objects

class
elastica.callback_functions.
CallBackBaseClass
[source]¶ Bases:
object
This is the base class for callbacks for rodlike objects.
Note
Every new callback class must be derived from CallBackBaseClass.

make_callback
(system, time, current_step: int)[source]¶ This method is called every time step. Users can define which parameters are called back and recorded. Also users can define the sampling rate of these parameters inside the method function.
Parameters:  system (object) – System is a rodlike object.
 time (float) – The time of the simulation.
 current_step (int) – Simulation step.


class
elastica.callback_functions.
MyCallBack
(step_skip: int, callback_params)[source]¶ Bases:
elastica.callback_functions.CallBackBaseClass
MyCallBack class is derived from the base callback class. This is just an example of a callback class, this class as an example/template to write new call back classes in your client file.
 sample_every: int
 Collect data using make_callback method every sampling step.
 callback_params: dict
 Collected callback data is saved in this dictionary.

__init__
(step_skip: int, callback_params)[source]¶ Parameters:  step_skip (int) – Collect data using make_callback method every step_skip step.
 callback_params (dict) – Collected data is saved in this dictionary.

make_callback
(system, time, current_step: int)[source]¶ This method is called every time step. Users can define which parameters are called back and recorded. Also users can define the sampling rate of these parameters inside the method function.
Parameters:  system (object) – System is a rodlike object.
 time (float) – The time of the simulation.
 current_step (int) – Simulation step.
Time steppers¶
Symplectic time steppers and concepts for integrating the kinematic and dynamic equations of rodlike objects.
Wrappers¶
Wrappers are simple objects that you can subclass to provide extended functionality to the simulation, such as adding an environment, joints, controllers, etc.

class
elastica.wrappers.__init__.
BaseSystemCollection
[source]¶ Bases:
collections.abc.MutableSequence
Base System for simulator classes. Every simulation class written by the user must be derived from the BaseSystemCollection class; otherwise the simulation will proceed.
 allowed_sys_types: tuple
 Tuple of allowed type rodlike objects. Here use a base class for objects, i.e. RodBase.
 _systems: list
 List of rodlike objects.
 _features: list
 List of classes acting on the rodlike object, such as external forces classes.

finalize
()[source]¶ This method finalizes the simulator class. When it is called, it is assumed that the user has appended all rodlike objects to the simulator as well as all boundary conditions, callbacks, etc., acting on these rodlike objects. After the finalize method called, the user cannot add new features to the simulator class.

class
elastica.wrappers.__init__.
Connections
[source]¶ Bases:
object
The Connections class is a wrapper for connecting rodlike objects using joints selected by the user. To connect two rodlike objects, the simulator class must be derived from the Connections class.
 _connections: list
 List of joint classes defined for rodlike objects.

connect
(first_rod, second_rod, first_connect_idx=0, second_connect_idx=1)[source]¶ This method connects two rodlike objects using the selected joint class. You need to input the two rodlike objects that are to be connected as well as set the element indexes of these rods where the connection occurs.
Parameters:  first_rod (object) – Rodlike object
 second_rod (object) – Rodlike object
 first_connect_idx (int) – Index of first rod for joint.
 second_connect_idx (int) – Index of second rod for joint.

class
elastica.wrappers.__init__.
Constraints
[source]¶ Bases:
object
The Constraints class is a wrapper for enforcing displacement boundary conditions. To enforce boundary conditions on rodlike objects, the simulator class must be derived from Constraints class.
 _constraints: list
 List of boundary condition classes defined for rodlike objects.

class
elastica.wrappers.__init__.
Forcing
[source]¶ Bases:
object
The Forcing class is a wrapper for applying boundary conditions that consist of applied external forces. To apply forcing on rodlike objects, the simulator class must be derived from the Forcing class.
 _ext_forces_torques: list
 List of forcing class defined for rodlike objects.

class
elastica.wrappers.__init__.
CallBacks
[source]¶ Bases:
object
CallBacks class is a wrapper for calling callback functions, set by the user. If the user wants to collect data from the simulation, the simulator class has to be derived from the CallBacks class.
 _callbacks: list
 List of call back classes defined for rodlike objects.
Base System¶
Basic coordinating for multiple, smaller systems that have an independently integrable interface (i.e. works with symplectic or explicit routines timestepper.py.)

class
elastica.wrappers.base_system.
BaseSystemCollection
[source]¶ Bases:
collections.abc.MutableSequence
Base System for simulator classes. Every simulation class written by the user must be derived from the BaseSystemCollection class; otherwise the simulation will proceed.
 allowed_sys_types: tuple
 Tuple of allowed type rodlike objects. Here use a base class for objects, i.e. RodBase.
 _systems: list
 List of rodlike objects.
 _features: list
 List of classes acting on the rodlike object, such as external forces classes.

finalize
()[source]¶ This method finalizes the simulator class. When it is called, it is assumed that the user has appended all rodlike objects to the simulator as well as all boundary conditions, callbacks, etc., acting on these rodlike objects. After the finalize method called, the user cannot add new features to the simulator class.
CallBacks¶
Provides the callBack interface to collect data over time (see callback_functions.py).

class
elastica.wrappers.callbacks.
CallBacks
[source]¶ Bases:
object
CallBacks class is a wrapper for calling callback functions, set by the user. If the user wants to collect data from the simulation, the simulator class has to be derived from the CallBacks class.
 _callbacks: list
 List of call back classes defined for rodlike objects.
Connect¶
Provides the connections interface to connect entities (rods, rigid bodies) using joints (see joints.py).

class
elastica.wrappers.connections.
Connections
[source]¶ Bases:
object
The Connections class is a wrapper for connecting rodlike objects using joints selected by the user. To connect two rodlike objects, the simulator class must be derived from the Connections class.
 _connections: list
 List of joint classes defined for rodlike objects.

connect
(first_rod, second_rod, first_connect_idx=0, second_connect_idx=1)[source]¶ This method connects two rodlike objects using the selected joint class. You need to input the two rodlike objects that are to be connected as well as set the element indexes of these rods where the connection occurs.
Parameters:  first_rod (object) – Rodlike object
 second_rod (object) – Rodlike object
 first_connect_idx (int) – Index of first rod for joint.
 second_connect_idx (int) – Index of second rod for joint.
Constraints¶
Provides the constraints interface to enforce displacement boundary conditions (see boundary_conditions.py).

class
elastica.wrappers.constraints.
Constraints
[source]¶ Bases:
object
The Constraints class is a wrapper for enforcing displacement boundary conditions. To enforce boundary conditions on rodlike objects, the simulator class must be derived from Constraints class.
 _constraints: list
 List of boundary condition classes defined for rodlike objects.
Forcing¶
Provides the forcing interface to apply forces and torques to rodlike objects (external point force, muscle torques, etc).

class
elastica.wrappers.forcing.
Forcing
[source]¶ Bases:
object
The Forcing class is a wrapper for applying boundary conditions that consist of applied external forces. To apply forcing on rodlike objects, the simulator class must be derived from the Forcing class.
 _ext_forces_torques: list
 List of forcing class defined for rodlike objects.