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

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

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.

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

Math#

Quadrature and difference kernels

elastica._calculus.position_difference_kernel(vector)#

This function computes difference between elements of a batch vector.

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.

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

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.

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.

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.

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]#
Parameters:
dim
Returns:

Rotation kernels

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

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.

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

Collect data into fixed-length chunks or blocks”

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

Apply mixins to a class instance after creation

Parameters:
objobject (not class!) targeted for interface extension

Interface carries throughout its lifetime.

clsclass (not object!) to dynamically mixin
Returns:
None