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
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
- 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: