# Utility Functions#

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

## Transformations#

Rotation interface functions

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#

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

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

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

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

Examples

Return type

`int`