PyElastica

This the the documentation page for PyElastica. For more information about PyElastica, see the project website.

Rods

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.

__init__()[source]

RodBase does not take any arguments.

Cosserat Rod

Module containing implementations of Cosserat Rod classes

class elastica.rod.cosserat_rod.CosseratRod(n_elements, shear_matrix, bend_matrix, rod, *args, **kwargs)[source]

Bases: elastica.rod.constitutive_model._LinearConstitutiveModelMixin, elastica.rod.cosserat_rod._CosseratRodBase, elastica.rod.data_structures._RodSymplecticStepperMixin

Cosserat Rod public class. This is the preferred class for rods because it is derived from some of the essential base classes. Although the attributes of this CosseratRod class are inherited from its parent classes, for convenience and easy access, the variable names are given below.

n_elems

The number of elements of the rod.

Type:int
position_collection

2D (dim, n_nodes) array containing data with ‘float’ type. Array containing node position vectors.

Type:numpy.ndarray
velocity_collection

2D (dim, n_nodes) array containing data with ‘float’ type. Array containing node velocity vectors.

Type:numpy.ndarray
acceleration_collection

2D (dim, n_nodes) array containing data with ‘float’ type. Array containing node acceleration vectors.

Type:numpy.ndarray
omega_collection

2D (dim, n_elems) array containing data with ‘float’ type. Array containing element angular velocity vectors.

Type:numpy.ndarray
alpha_collection

2D (dim, n_elems) array containing data with ‘float’ type. Array contining element angular acceleration vectors.

Type:numpy.ndarray
director_collection

3D (dim, dim, n_elems) array containing data with ‘float’ type. Array containing element director matrices.

Type:numpy.ndarray
rest_lengths

1D (blocksize) array containing data with ‘float’ type. Rod element lengths at rest configuration.

Type:numpy.ndarray
density

1D (blocksize) array containing data with ‘float’ type. Rod elements densities.

Type:numpy.ndarray
volume

1D (blocksize) array containing data with ‘float’ type. Rod element volumes.

Type:numpy.ndarray
mass

1D (blocksize) array containing data with ‘float’ type. Rod node masses. Note that masses are stored on the nodes, not on elements.

Type:numpy.ndarray
mass_second_moment_of_inertia

3D (dim, dim, blocksize) array containing data with ‘float’ type. Rod element mass second moment of interia.

Type:numpy.ndarray
inv_mass_second_moment_of_inertia

3D (dim, dim, blocksize) array containing data with ‘float’ type. Rod element inverse mass moment of inertia.

Type:numpy.ndarray
nu

1D (blocksize) array containing data with ‘float’ type. Rod element dissipation coefficient.

Type:numpy.ndarray
rest_voronoi_lengths

1D (blocksize) array containing data with ‘float’ type. Rod lengths on the voronoi domain at the rest configuration.

Type:numpy.ndarray
internal_forces

2D (dim, blocksize) array containing data with ‘float’ type. Rod node internal forces. Note that internal forces are stored on the node, not on elements.

Type:numpy.ndarray
internal_torques

2D (dim, blocksize) array containing data with ‘float’ type. Rod element internal torques.

Type:numpy.ndarray
external_forces

2D (dim, blocksize) array containing data with ‘float’ type. External forces acting on rod nodes.

Type:numpy.ndarray
external_torques

2D (dim, blocksize) array containing data with ‘float’ type. External torques acting on rod elements.

Type:numpy.ndarray
lengths

1D (blocksize) array containing data with ‘float’ type. Rod element lengths.

Type:numpy.ndarray
tangents

2D (dim, blocksize) array containing data with ‘float’ type. Rod element tangent vectors.

Type:numpy.ndarray
radius

1D (blocksize) array containing data with ‘float’ type. Rod element radius.

Type:numpy.ndarray
dilatation

1D (blocksize) array containing data with ‘float’ type. Rod element dilatation.

Type:numpy.ndarray
voronoi_dilatation

1D (blocksize) array containing data with ‘float’ type. Rod dilatation on voronoi domain.

Type:numpy.ndarray
dilatation_rate

1D (blocksize) array containing data with ‘float’ type. Rod element dilatation rates.

Type:numpy.ndarray
classmethod straight_rod(n_elements, start, direction, normal, base_length, base_radius, density, nu, youngs_modulus, poisson_ratio, alpha_c=1.3333333333333333, *args, **kwargs)[source]

Call this method to initialize and generate a Cosserat rod object that is a straight rod. Future versions will contain methods for curvilinear rods.

Parameters:
  • n_elements (float) – Rod number of elements.
  • start (numpy.ndarray) – 1D (dim) array containing data with ‘float’ type. Start position of the rod.
  • direction (numpy.ndarray) – 1D (dim) array containing data with ‘float’ type. Direction or tangent of the rod.
  • normal (numpy.ndarray) – 1D (dim) array containing data with ‘float’ type. Normal direction of the rod.
  • base_length (float) – Initial length of the rod.
  • base_radius (float) – Initial radius of the rod.
  • density (float) – Density of the rod.
  • nu (float) – Dissipation constant of the rod.
  • youngs_modulus (float) – Youngs modulus of the rod.
  • poisson_ratio (float) – Poisson ratio of the rod is used to compute shear modulus.
  • alpha_c (float) –
  • *args – Variable length argument list.
  • **kwargs – Arbitrary keyword arguments.

Boundary Conditions

Endpoint Constraints

Module for boundary condition implementations that constrain or define displacement conditions on the 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.

__init__()[source]

Free rod has no input parameters.

constrain_rates(rod, time)[source]

Constrain rates (velocity and/or omega) of a rod object.

In FreeRod class, this routine simply passes.

Parameters:
  • rod (object) – Rod-like object.
  • time (float) – The time of simulation.
constrain_values(rod, time)[source]

Constrain values (position and/or directors) of a rod object.

In FreeRod class, this routine simply passes.

Parameters:
  • rod (object) – Rod-like object.
  • time (float) – The time of simulation.
class elastica.boundary_conditions.HelicalBucklingBC(position_start, position_end, director_start, director_end, twisting_time, slack, number_of_rotations)[source]

Bases: elastica.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

Time to complete twist.

Type:float
final_start_position

2D (dim, 1) array containing data with ‘float’ type. Position of first node of rod after twist completed.

Type:numpy.ndarray
final_end_position

2D (dim, 1) array containing data with ‘float’ type. Position of last node of rod after twist completed.

Type:numpy.ndarray
ang_vel

2D (dim, 1) array containing data with ‘float’ type. Angular velocity of rod during twisting time.

Type:numpy.ndarray
shrink_vel

2D (dim, 1) array containing data with ‘float’ type. Shrink velocity of rod during twisting time.

Type:numpy.ndarray
final_start_directors

3D (dim, dim, blocksize) array containing data with ‘float’ type. Directors of first element of rod after twist completed.

Type:numpy.ndarray
final_end_directors

3D (dim, dim, blocksize) array containing data with ‘float’ type. Directors of last element of rod after twist completed.

Type:numpy.ndarray
__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.
constrain_rates(rod, time)[source]

Constrain rates (velocity and/or omega) of a rod object.

In FreeRod class, this routine simply passes.

Parameters:
  • rod (object) – Rod-like object.
  • time (float) – The time of simulation.
constrain_values(rod, time)[source]

Constrain values (position and/or directors) of a rod object.

In FreeRod class, this routine simply passes.

Parameters:
  • rod (object) – Rod-like object.
  • time (float) – The time of simulation.
class elastica.boundary_conditions.OneEndFixedRod(fixed_position, fixed_directors)[source]

Bases: elastica.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

2D (dim, 1) array containing data with ‘float’ type.

Type:numpy.ndarray
fixed_directors

3D (dim, dim, 1) array containing data with ‘float’ type.

Type:numpy.ndarray
__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.
constrain_rates(rod, time)[source]

Constrain rates (velocity and/or omega) of a rod object.

In FreeRod class, this routine simply passes.

Parameters:
  • rod (object) – Rod-like object.
  • time (float) – The time of simulation.
constrain_values(rod, time)[source]

Constrain values (position and/or directors) of a rod object.

In FreeRod class, this routine simply passes.

Parameters:
  • rod (object) – Rod-like object.
  • time (float) – The time of simulation.

External Forces

Module for boundary condition implementations that apply external forces to the rod.

class elastica.external_forces.EndpointForces(start_force, end_force, ramp_up_time=0.0)[source]

Bases: elastica.external_forces.NoForces

This class applies constant forces on the endpoint nodes.

start_force

2D (dim, 1) array containing data with ‘float’ type. Force applied to first node of the rod-like object.

Type:numpy.ndarray
end_force

2D (dim, 1) array containing data with ‘float’ type. Force applied to last node of the rod-like object.

Type:numpy.ndarray
ramp_up_time

Applied forces are ramped up until ramp up time.

Type:float
__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 rod-like object.
  • end_force (numpy.ndarray) – 2D (dim, 1) array containing data with ‘float’ type. Force applied to last node of the rod-like object.
  • ramp_up_time (float) – Applied forces are ramped up until ramp up time.
apply_forces(system, time=0.0)[source]

Apply forces to a rod-like object.

In NoForces class, this routine simply passes.

Parameters:
  • system (object) – System that is Rod-like.
  • time (float) – The time of simulation.
class elastica.external_forces.GravityForces(acc_gravity=array([ 0., -9.80665, 0. ]))[source]

Bases: elastica.external_forces.NoForces

This class applies a constant gravitational force to the entire rod.

acc_gravity

1D (dim) array containing data with ‘float’ type. Gravitational acceleration vector.

Type:numpy.ndarray
__init__(acc_gravity=array([ 0., -9.80665, 0. ]))[source]
Parameters:acc_gravity (numpy.ndarray) – 1D (dim) array containing data with ‘float’ type. Gravitational acceleration vector.
apply_forces(system, time=0.0)[source]

Apply forces to a rod-like object.

In NoForces class, this routine simply passes.

Parameters:
  • system (object) – System that is Rod-like.
  • time (float) – The time of simulation.
class elastica.external_forces.MuscleTorques(base_length, b_coeff, period, wave_number, phase_shift, direction, ramp_up_time=0.0, with_spline=False)[source]

Bases: elastica.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

2D (dim, 1) array containing data with ‘float’ type. Muscle torque direction.

Type:numpy.ndarray
angular_frequency

Angular frequency of traveling wave.

Type:float
wave_number

Wave number of traveling wave.

Type:float
phase_shift

Phase shift of traveling wave.

Type:float
ramp_up_time

Applied muscle torques are ramped up until ramp up time.

Type:float
my_spline

1D (blocksize) array containing data with ‘float’ type. Generated spline.

Type:numpy.ndarray
__init__(base_length, b_coeff, period, wave_number, phase_shift, direction, ramp_up_time=0.0, with_spline=False)[source]
Parameters:
  • base_length (float) – Rest length of the rod-like object.
  • b_coeff (nump.ndarray) – 1D array containing data with ‘float’ type. Beta coefficients for beta-spline.
  • 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 beta-spline.
apply_torques(system, time: float = 0.0)[source]

Apply torques to a rod-like object.

In NoForces class, this routine simply passes.

Parameters:
  • system (object) – System that is Rod-like.
  • time (float) – The time of simulation.
class elastica.external_forces.NoForces[source]

Bases: object

This is the base class for external forcing boundary conditions applied to rod-like objects.

Note

Every new external forcing class must be derived from NoForces class.

__init__()[source]

NoForces class does not need any input parameters.

apply_forces(system, time: float = 0.0)[source]

Apply forces to a rod-like object.

In NoForces class, this routine simply passes.

Parameters:
  • system (object) – System that is Rod-like.
  • time (float) – The time of simulation.
apply_torques(system, time: float = 0.0)[source]

Apply torques to a rod-like object.

In NoForces class, this routine simply passes.

Parameters:
  • system (object) – System that is Rod-like.
  • time (float) – The time of simulation.
class elastica.external_forces.UniformForces(force, direction=array([0., 0., 0.]))[source]

Bases: elastica.external_forces.NoForces

This class applies a uniform force to the entire rod.

force

2D (dim, 1) array containing data with ‘float’ type. Total force applied to a rod-like object.

Type:numpy.ndarray
__init__(force, direction=array([0., 0., 0.]))[source]
Parameters:
  • force (float) – Force magnitude applied to a rod-like object.
  • direction (numpy.ndarray) – 1D (dim) array containing data with ‘float’ type. Direction in which force applied.
apply_forces(system, time: float = 0.0)[source]

Apply forces to a rod-like object.

In NoForces class, this routine simply passes.

Parameters:
  • system (object) – System that is Rod-like.
  • time (float) – The time of simulation.
class elastica.external_forces.UniformTorques(torque, direction=array([0., 0., 0.]))[source]

Bases: elastica.external_forces.NoForces

This class applies a uniform torque to the entire rod.

torque

2D (dim, 1) array containing data with ‘float’ type. Total torque applied to a rod-like object.

Type:numpy.ndarray
__init__(torque, direction=array([0., 0., 0.]))[source]
Parameters:
  • torque (float) – Torque magnitude applied to a rod-like object.
  • direction (numpy.ndarray) – 1D (dim) array containing data with ‘float’ type. Direction in which torque applied.
apply_torques(system, time: float = 0.0)[source]

Apply torques to a rod-like object.

In NoForces class, this routine simply passes.

Parameters:
  • system (object) – System that is Rod-like.
  • time (float) – The time of simulation.

Environment Interactions

Module containing interactions between a rod and its environment.

class elastica.interaction.AnisotropicFrictionalPlane(k, nu, plane_origin, plane_normal, slip_velocity_tol, static_mu_array, kinetic_mu_array)[source]

Bases: elastica.external_forces.NoForces, elastica.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

Stiffness coefficient between the plane and the rod-like object.

Type:float
nu

Dissipation coefficient between the plane and the rod-like object.

Type:float
plane_origin

2D (dim, 1) array containing data with ‘float’ type. Origin of the plane.

Type:numpy.ndarray
plane_normal

2D (dim, 1) array containing data with ‘float’ type. The normal vector of the plane.

Type:numpy.ndarray
slip_velocity_tol

Velocity tolerance to determine if the element is slipping or not.

Type:float
static_mu_array

1D (3,) array containing data with ‘float’ type. [forward, backward, sideways] static friction coefficients.

Type:numpy.ndarray
kinetic_mu_array

1D (3,) array containing data with ‘float’ type. [forward, backward, sideways] kinetic friction coefficients.

Type:numpy.ndarray
__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 rod-like object.
  • nu (float) – Dissipation coefficient between the plane and the rod-like 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.
apply_forces(system, time=0.0)[source]

Apply forces to a rod-like object.

In NoForces class, this routine simply passes.

Parameters:
  • system (object) – System that is Rod-like.
  • time (float) – The time of simulation.
class elastica.interaction.InteractionPlane(k, nu, plane_origin, plane_normal)[source]

Bases: object

The interaction plane class computes the plane reaction force on a rod-like object. For more details regarding the contact module refer to Eqn 4.8 of Gazzola et al. RSoS (2018).

k

Stiffness coefficient between the plane and the rod-like object.

Type:float
nu

Dissipation coefficient between the plane and the rod-like object.

Type:float
plane_origin

2D (dim, 1) array containing data with ‘float’ type. Origin of the plane.

Type:numpy.ndarray
plane_normal

2D (dim, 1) array containing data with ‘float’ type. The normal vector of the plane.

Type:numpy.ndarray
surface_tol

Penetration tolerance between the plane and the rod-like object.

Type:float
__init__(k, nu, plane_origin, plane_normal)[source]
Parameters:
  • k (float) – Stiffness coefficient between the plane and the rod-like object.
  • nu (float) – Dissipation coefficient between the plane and the rod-like 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.
apply_normal_force(system)[source]

In the case of contact with the plane, this function computes the plane reaction force on the element.

Parameters:system (object) – Rod-like object.
Returns:
  • plane_response_force_mag (numpy.ndarray) – 1D (blocksize) array containing data with ‘float’ type. Magnitude of plane response force acting on rod-like object.
  • no_contact_point_idx (numpy.ndarray) – 1D (blocksize) array containing data with ‘int’ type. Index of rod-like object elements that are not in contact with the plane.
class elastica.interaction.SlenderBodyTheory(dynamic_viscosity)[source]

Bases: elastica.external_forces.NoForces

This slender body theory class is for flow-structure 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

Dynamic viscosity of the fluid.

Type:float
__init__(dynamic_viscosity)[source]
Parameters:dynamic_viscosity (float) – Dynamic viscosity of the fluid.
apply_forces(system, time=0.0)[source]

Apply forces to a rod-like object.

In NoForces class, this routine simply passes.

Parameters:
  • system (object) – System that is Rod-like.
  • time (float) – The time of simulation.
elastica.interaction.find_slipping_elements(velocity_slip, velocity_threshold)[source]

This function takes the velocity of elements and checks if they are larger than the threshold velocity. If the velocity of elements is larger than threshold velocity, that means those elements are slipping. In other words, kinetic friction will be acting on those elements, not static friction. This function outputs an array called slip function, this array has a size of the number of elements. If the velocity of the element is smaller than the threshold velocity slip function value for that element is 1, which means static friction is acting on that element. If the velocity of the element is larger than the threshold velocity slip function value for that element is between 0 and 1, which means kinetic friction is acting on that element.

Parameters:
  • velocity_slip (numpy.ndarray) – 2D (dim, blocksize) array containing data with ‘float’ type. Rod-like object element velocity.
  • velocity_threshold (float) – Threshold velocity to determine slip.
Returns:

slip_function – 2D (dim, blocksize) array containing data with ‘float’ type.

Return type:

numpy.ndarray

elastica.interaction.node_to_element_velocity[source]

This function computes the velocity of the elements. Here we define a separate function because benchmark results showed that using Numba, we get almost 3 times faster calculation.

Parameters:node_velocity (numpy.ndarray) – 2D (dim, blocksize) array containing data with ‘float’ type.
Returns:element_velocity – 2D (dim, blocksize) array containing data with ‘float’ type.
Return type:numpy.ndarray
elastica.interaction.nodes_to_elements(input)[source]

This function converts the rod-like object dofs on nodes to dofs on elements. For example, node velocity is converted to element velocity.

Parameters:input (numpy.ndarray) – 2D (dim, blocksize) array containing data with ‘float’ type.
Returns:output – 2D (dim, blocksize) array containing data with ‘float’ type.
Return type:numpy.ndarray
elastica.interaction.slender_body_forces[source]

This function computes hydrodynamic forces on a body using slender body theory. The below implementation is from Eq. 4.13 in Gazzola et al. RSoS. (2018).

\[F_{h}=\frac{-4\pi\mu}{\ln{(L/r)}}\left(\mathbf{I}-\frac{1}{2}\mathbf{t}^{\textrm{T}}\mathbf{t}\right)\mathbf{v}\]
Parameters:
  • tangents (numpy.ndarray) – 2D (dim, blocksize) array containing data with ‘float’ type. Rod-like element tangent directions.
  • velocity_collection (numpy.ndarray) – 2D (dim, blocksize) array containing data with ‘float’ type. Rod-like object velocity collection.
  • dynamic_viscosity (float) – Dynamic viscosity of the fluid.
  • length (numpy.ndarray) – 1D (blocksize) array containing data with ‘float’ type. Rod-like object element lengths.
  • radius (numpy.ndarray) – 1D (blocksize) array containing data with ‘float’ type. Rod-like object element radius.
Returns:

stokes_force – 2D (dim, blocksize) array containing data with ‘float’ type.

Return type:

numpy.ndarray

elastica.interaction.sum_over_elements[source]

This function sums all elements of the input array. Using a Numba njit decorator shows better performance compared to python sum(), .sum() and np.sum()

Parameters:input (numpy.ndarray) – 1D (blocksize) array containing data with ‘float’ type.
Returns:
Return type:float

Multiple Rod Connections

Module containing joint classes to connect multiple rods together.

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

Stiffness coefficient of the joint.

Type:float
nu

Damping coefficient of the joint.

Type:float
kt

Rotational stiffness coefficient of the joint.

Type:float
__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) – Rod-like object
  • index_one (int) – Index of first rod for joint.
  • rod_two (object) – Rod-like 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) – Rod-like object
  • index_one (int) – Index of first rod for joint.
  • rod_two (object) – Rod-like object
  • index_two (int) – Index of second rod for joint.
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

Stiffness coefficient of the joint.

Type:float
nu

Damping coefficient of the joint.

Type:float

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) – Rod-like object
  • index_one (int) – Index of first rod for joint.
  • rod_two (object) – Rod-like 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) – Rod-like object
  • index_one (int) – Index of first rod for joint.
  • rod_two (object) – Rod-like 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

Stiffness coefficient of the joint.

Type:float
nu

Damping coefficient of the joint.

Type:float
kt

Rotational stiffness coefficient of the joint.

Type:float
normal_direction

2D (dim, 1) array containing data with ‘float’ type. Constraint rotation direction.

Type:numpy.ndarray
__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) – Rod-like object
  • index_one (int) – Index of first rod for joint.
  • rod_two (object) – Rod-like 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) – Rod-like object
  • index_one (int) – Index of first rod for joint.
  • rod_two (object) – Rod-like object
  • index_two (int) – Index of second rod for joint.

Callback Functions

Module contains callback classes to save simulation data for rod-like objects

class elastica.callback_functions.CallBackBaseClass[source]

Bases: object

This is the base class for callbacks for rod-like objects.

Note

Every new callback class must be derived from CallBackBaseClass.

__init__()[source]

CallBackBaseClass does not need any input parameters.

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 rod-like 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

Collect data using make_callback method every sampling step.

Type:int
callback_params

Collected callback data is saved in this dictionary.

Type:dict
__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 rod-like 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 rod-like objects.

class elastica.timestepper.symplectic_steppers.PEFRL[source]

Bases: elastica.timestepper.symplectic_steppers.SymplecticStepper

Position Extended Forest-Ruth Like Algorithm of I.M. Omelyan, I.M. Mryglod, and R. Folk, Computer Physics Communications 146, 188 (2002), http://arxiv.org/abs/cond-mat/0110585

class elastica.timestepper.symplectic_steppers.PositionVerlet[source]

Bases: elastica.timestepper.symplectic_steppers.SymplecticStepper

Position Verlet symplectic time stepper class, which includes methods for second-order position Verlet.

Wrappers

Wrappers are simple objects that you can subclass to provide extended functionality to the simulation, such as adding an environment, joints, controllers, etc.

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 of allowed type rod-like objects. Here use a base class for objects, i.e. RodBase.

Type:tuple
_systems

List of rod-like objects.

Type:list
_features

List of classes acting on the rod-like object, such as external forces classes.

Type:list
finalize()[source]

This method finalizes the simulator class. When it is called, it is assumed that the user has appended all rod-like objects to the simulator as well as all boundary conditions, callbacks, etc., acting on these rod-like 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 of call back classes defined for rod-like objects.

Type:list
collect_diagnostics(system)[source]

This method calls user-defined call-back classes for a user-defined system or rod-like object. You need to input the system or rod-like object that you want to collect data from.

Parameters:system (object) – System is a rod-like object.

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 rod-like objects using joints selected by the user. To connect two rod-like objects, the simulator class must be derived from the Connections class.

_connections

List of joint classes defined for rod-like objects.

Type:list
connect(first_rod, second_rod, first_connect_idx=0, second_connect_idx=-1)[source]

This method connects two rod-like objects using the selected joint class. You need to input the two rod-like objects that are to be connected as well as set the element indexes of these rods where the connection occurs.

Parameters:
  • first_rod (object) – Rod-like object
  • second_rod (object) – Rod-like 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 rod-like objects, the simulator class must be derived from Constraints class.

_constraints

List of boundary condition classes defined for rod-like objects.

Type:list
constrain(system)[source]

This method enforces a displacement boundary conditions to the relevant user-defined system or rod-like object. You must input the system or rod-like object that you want to enforce boundary condition on.

Parameters:system (object) – System is a rod-like object.

Forcing

Provides the forcing interface to apply forces and torques to rod-like 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 rod-like objects, the simulator class must be derived from the Forcing class.

_ext_forces_torques

List of forcing class defined for rod-like objects.

Type:list
add_forcing_to(system)[source]

This method applies external forces and torques on the relevant user-defined system or rod-like object. You must input the system or rod-like object that you want to apply external forces and torques on.

Parameters:system (object) – System is a rod-like object.