Utility Functions

Utility Functions#

Here, we provide some useful functions that we often use along with elastica.

Transformations#

Rotation interface functions

elastica.transformations.format_vector_shape(vector_collection)[source]#

Function for formatting vector shapes into correct format

Return type:

ndarray[tuple[int, ...], dtype[float64]]

Parameters:
vector_collection: numpy.ndarray

Can be 1D or 2D.

Returns:
output: numpy.ndarray

Can be 1D or 2D.

elastica.transformations.format_matrix_shape(matrix_collection)[source]#

Formats input matrix into correct format

Return type:

ndarray[tuple[int, ...], dtype[float64]]

Parameters:
matrix_collection: numpy.ndarray

Can be 1D, 2D, 3D.

Returns:
elastica.transformations.inv_skew_symmetrize(matrix_collection)[source]#

Safe wrapper around inv_skew_symmetrize that does checking and formatting on type of matrix_collection using format_matrix_shape function.

Return type:

ndarray[tuple[int, ...], dtype[float64]]

Parameters:
matrix_collection: numpy.ndarray
Returns:
elastica.transformations.rotate(matrix, scale, axis)[source]#

This function takes single or multiple frames as matrix. Then rotates these frames around a single axis for all frames, or can rotate each frame around its own rotation axis as defined by user. Scale determines how much frames rotates around this axis.

matrix: minimum shape = dim**2x1, supports shape = 3x3xn axis: minimum dim = 3x1, 1x3, supports dim = 3xn, nx3 scale: minimum float, supports 1D vectors also dim = n

Return type:

ndarray[tuple[int, ...], dtype[float64]]

Math#

Quadrature and difference kernels

elastica._calculus.position_difference_kernel(vector)#

This function computes difference between elements of a batch vector.

Return type:

ndarray[tuple[int, ...], dtype[float64]]

Parameters:
vector: numpy.ndarray

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

Returns:
result: numpy.ndarray

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

Notes

Micro benchmark results showed that for a block size of 100, using timeit Python version: 3.29 µs ± 767 ns per loop This version: 840 ns ± 14.5 ns per loop

elastica._calculus.position_average(vector)#

This function computes the average between elements of a vector.

Return type:

ndarray[tuple[int, ...], dtype[float64]]

Parameters:
vectornumpy.ndarray

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

Returns:
result: numpy.ndarray

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

Notes

Micro benchmark results showed that for a block size of 100, using timeit Python version: 2.37 µs ± 764 ns per loop This version: 713 ns ± 3.69 ns per loop

elastica._calculus.quadrature_kernel(array_collection)#

Simple trapezoidal quadrature rule with zero at end-points, in a dimension agnostic way

Return type:

ndarray[tuple[int, ...], dtype[float64]]

Parameters:
array_collectionnumpy.ndarray

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

Returns:
result: numpy.ndarray

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

Notes

Micro benchmark results, for a block size of 100, using timeit Python version: 8.14 µs ± 1.42 µs per loop This version: 781 ns ± 18.3 ns per loop

elastica._calculus.difference_kernel(array_collection)#

This function does differentiation.

Return type:

ndarray[tuple[int, ...], dtype[float64]]

Parameters:
array_collectionnumpy.ndarray

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

Returns:
result: numpy.ndarray

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

Notes

Micro benchmark results showed that for a block size of 100, using timeit Python version: 9.07 µs ± 2.15 µs per loop This version: 952 ns ± 91.1 ns per loop

elastica._calculus.quadrature_kernel_for_block_structure(array_collection, ghost_idx)#

Simple trapezoidal quadrature rule with zero at end-points, in a dimension agnostic way. This form specifically for the block structure implementation and there is a reset function call, to reset ghosts.

Return type:

ndarray[tuple[int, ...], dtype[float64]]

Parameters:
array_collectionnumpy.ndarray

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

ghost_idxnumpy.ndarray

1D (n_ghost) array containing data with ‘int’ type.

Returns:
result: numpy.ndarray

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

Notes

Micro benchmark results, for a block size of 100, using timeit Python version: 8.21 µs per loop This version: 1.03 µs per loop

User should use this function with extreme care, since this function is rewritten for block structure.

elastica._calculus.difference_kernel_for_block_structure(array_collection, ghost_idx)#

This function does the differentiation, for Cosserat rod model equations. This form specifically for the block structure implementation and there is a reset function call, to reset ghosts.

Return type:

ndarray[tuple[int, ...], dtype[float64]]

Parameters:
array_collectionnumpy.ndarray

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

ghost_idxnumpy.ndarray

1D (n_ghost) array containing data with ‘int’ type.

Returns:
result: numpy.ndarray

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

Notes

Micro benchmark results showed that for a block size of 100, using timeit Python version: 7.1 µs per loop This version: 1.01 µs per loop

User should use this function with extreme care, since this function is rewritten for block structure.

Convenient linear algebra kernels

elastica._linalg.levi_civita_tensor(dim)[source]#
Return type:

ndarray[tuple[int, ...], dtype[float64]]

Parameters:
dim
Returns:

Rotation kernels

elastica._rotations.get_relative_rotation_two_systems(system_one, index_one, system_two, index_two)[source]#

Compute the relative rotation matrix C_12 between system one and system two at the specified elements.

Parameters:
system_oneRodType | RigidBodyType

Rod or rigid-body object

index_oneConnectionIndex

Index of first system for connection.

system_twoRodType | RigidBodyType

Rod or rigid-body object

index_twoConnectionIndex

Index of second system for connection.

Returns:
relative_rotation_matrixnumpy.ndarray

2D (3, 3) array containing the relative rotation matrix C_12 between the two systems for their current state.

See also

FixedJoint

Examples

How to get the relative rotation between two systems (e.g. the rotation from end of rod one to base of rod two):

>>> rel_rot_mat = get_relative_rotation_two_systems(system1, -1, system2, 0)

How to initialize a FixedJoint with a rest rotation between the two systems, which is enforced throughout the simulation:

>>> simulator.connect(
...    first_rod=system1, second_rod=system2, first_connect_idx=-1, second_connect_idx=0
... ).using(
...    FixedJoint,
...    ku=1e6, nu=0.0, kt=1e3, nut=0.0,
...    rest_rotation_matrix=get_relative_rotation_two_systems(system1, -1, system2, 0)
... )

Miscellaneous#

Handy utilities

elastica.utils.isqrt(num)[source]#

Efficiently computes sqrt for integer values

Dropin replacement for python3.8’s isqrt function Credits : https://stackoverflow.com/a/53983683

Return type:

int

Parameters:
numint, input
Returns:
sqrt_numint, rounded down sqrt of num

Notes

Doesn’t handle edge-cases of negative numbers by design

Doesn’t type-check for integers by design, although it is hinted at

class elastica.utils.MaxDimension[source]#

Contains maximum space dimensions. Typically useful for range-checking

static value()[source]#

Returns spatial dimension

Return type:

Literal[3]

Returns:
3, static value
elastica.utils.perm_parity(lst)[source]#

Given a permutation of the digits 0..N in order as a list, returns its parity (or sign): +1 for even parity; -1 for odd. Code obtained with thanks from https://code.activestate.com/recipes/578227-generate-the-parity-or-sign-of-a-permutation/ licensed with a MIT License

Return type:

int

Parameters:
lstlist[int]
Returns:
int
elastica.utils.grouper(iterable, n)[source]#

Collect data into fixed-length chunks or blocks” https://docs.python.org/3/library/itertools.html#itertools-recipes https://stackoverflow.com/a/10791887

grouper(‘ABCDEFG’, 3) –> ABC DEF G”

Return type:

Generator[tuple[TypeVar(_T), ...], None, None]

Parameters:
iterableinput collection
nsize of chunk
elastica.utils.extend_instance(obj, cls)[source]#

Apply mixins to a class instance after creation. https://stackoverflow.com/a/31075641

Return type:

None

Parameters:
obj

object (not class!) targeted for interface extension Interface carries throughout its lifetime.

cls

class (not object!) to dynamically mixin

Contents