Constant Strain¶

The constant-strain package evaluates the Lie operators used to propagate kinematics along rod segments with constant body strain. Planar and spatial operators have separate namespaces, so their function names remain concise:

from soromox.utils.lie_algebra.constant_strain import se2, se3

planar_tangent = se2.tangent(xi_planar, arc_length, eps)
spatial_operators = se3.operators(xi_spatial, arc_length, eps, xid_spatial)

Use a single-operator function when only one result is required. Use operators when several related expressions are needed at the same strain and arclength; it shares intermediate work and returns a fixed named bundle.

For an accumulated Lie-algebra coordinate rather than a constant strain plus arclength, use lie_algebra.se2.left_jacobian or lie_algebra.se3.left_jacobian. Their directional-derivative APIs likewise do not require a rod interpretation.

Package Structure¶

constant_strain.se2 provides planar operators using direct rotation and translation blocks.
constant_strain.se3 provides spatial operators using exact reduced matrix polynomials.
ConstantStrainOperators is the common named result returned by both modules' operators functions.

Operator Bundle¶

soromox.utils.lie_algebra.constant_strain.ConstantStrainOperators ¶

Bases: NamedTuple


              flowchart TD
              soromox.utils.lie_algebra.constant_strain.ConstantStrainOperators[ConstantStrainOperators]

              

              click soromox.utils.lie_algebra.constant_strain.ConstantStrainOperators href "" "soromox.utils.lie_algebra.constant_strain.ConstantStrainOperators"

Related constant-strain Lie operators evaluated as one shared bundle.

Attributes:

Name	Type	Description
`adjoint`	`Array`	Forward adjoint `exp(s * ad_xi)`.
`adjoint_inverse`	`Array`	Inverse of `adjoint` assembled from Lie-group blocks rather than a dense matrix inverse.
`tangent`	`Array`	Integrated adjoint `integral_0^s exp(sigma * ad_xi) d sigma`.
`tangent_derivative`	`Array \| None`	Analytic directional derivative `D_xi tangent[xid]`. This is `None` when the bundle was requested without `xid`.

SE(2)¶

soromox.utils.lie_algebra.constant_strain.se2 ¶

Closed-form constant-strain operators for :math:SE(2).

The planar implementation uses exact rotation/translation blocks and stable forward-Jacobian coefficients. Public names are unsuffixed because the module itself supplies the algebra context.

adjoint ¶

adjoint(xi: Array, s: Array, eps: float | Array) -> Array

Return the adjoint accumulated along a constant planar strain segment.

This is a rod-kinematics helper, not a generic transform adjoint. For a segment with constant planar strain xi evaluated at arclength s, the returned matrix represents the closed-form adjoint associated with the segment transform exp(s * xi) under the angular-first se(2) convention. Equivalently, the returned matrix is exp(s * se2.small_adjoint(xi)). It transports planar twists between the material frames at the segment base and at arclength s.

Parameters:

Name	Type	Description	Default
`xi`	`Array`	Constant planar strain with shape `(3,)` or `(3, 1)` in `[theta, v_x, v_y]` order.	required
`s`	`Array`	Scalar arclength position measured from the base of the segment.	required
`eps`	`float \| Array`	Minimum rotational-strain threshold. The actual dimensionless cutoff also accounts for `s` and the input dtype.	required

Returns:

Type	Description
`Array`	Array with shape `(3, 3)` mapping planar twists through the segment
`Array`	adjoint at arclength `s`.

Notes

The implementation uses the exact SE(2) rotation/translation block form, not a truncated matrix-exponential series. At zero curvature it retains the complete translation/shear dependence of exp(s * ad_xi). The Taylor branch affects only removable scalar coefficient quotients.

adjoint_inverse ¶

adjoint_inverse(xi: Array, s: Array, eps: float | Array) -> Array

Return the inverse adjoint for a constant planar strain segment.

This computes the inverse of :func:adjoint without explicitly inverting the full homogeneous segment transform. It is used when propagating planar body-frame Jacobians backward through a constant-strain segment. For Ad = adjoint(xi, s, eps), this function returns Ad**-1 = adjoint(-xi, s, eps) while exploiting the block structure of an SE(2) adjoint instead of applying a generic matrix inverse.

Parameters:

Name	Type	Description	Default
`xi`	`Array`	Constant planar strain with shape `(3,)` or `(3, 1)` in `[theta, v_x, v_y]` order.	required
`s`	`Array`	Scalar arclength position measured from the base of the segment.	required
`eps`	`float \| Array`	Minimum rotational-strain threshold forwarded to :func:`adjoint`.	required

Returns:

Type	Description
`Array`	Array with shape `(3, 3)` representing the inverse segment adjoint.

Notes

This path shares the stabilized forward-adjoint block assembler, so forward and inverse transport have one near-zero policy. The inverse translation is formed explicitly as -R.T @ q without a generic matrix inverse. It is intended for body-frame PCS/GVS recurrences.

tangent ¶

tangent(xi: Array, s: Array, eps: float | Array) -> Array

Return the tangent operator for a constant planar strain segment.

The tangent operator integrates the local strain perturbation over arclength for a segment whose strain is constant. In PCS/GVS recurrences it maps strain-basis contributions into body-frame Jacobian contributions at arclength s. Mathematically,

.. math::

T(s,\xi) = \int_0^s
\exp(\sigma\,\operatorname{ad}_\xi)\,d\sigma.

Parameters:

Name	Type	Description	Default
`xi`	`Array`	Constant planar strain with shape `(3,)` or `(3, 1)` in `[theta, v_x, v_y]` order.	required
`s`	`Array`	Scalar arclength position measured from the base of the segment.	required
`eps`	`float \| Array`	Minimum rotational-strain threshold. The actual dimensionless cutoff also accounts for `s` and the input dtype.	required

Returns:

Type	Description
`Array`	Array with shape `(3, 3)` containing the planar constant-strain
`Array`	tangent operator at arclength `s`.

Notes

The exact limits are T(0, xi) = 0 and T(s, 0) = s I. Pure translation is handled by the same reduced polynomial and does not require a separate curvature-zero formula.

tangent_derivative ¶

tangent_derivative(xi: Array, xid: Array, s: Array, eps: float | Array) -> Array

Return the directional derivative of the planar tangent operator.

This differentiates :func:tangent with respect to time through the strain xi and strain rate xid while holding arclength s fixed. The function uses the same angular-first planar convention as se2 and computes D_xi T(s, xi)[xid] analytically.

Parameters:

Name	Type	Description	Default
`xi`	`Array`	Constant planar strain with shape `(3,)` or `(3, 1)` in `[theta, v_x, v_y]` order.	required
`xid`	`Array`	Time derivative of `xi` with the same shape and coordinate order.	required
`s`	`Array`	Scalar arclength position measured from the base of the segment.	required
`eps`	`float \| Array`	Minimum rotational-strain threshold. The actual dimensionless cutoff also accounts for `s` and the input dtype.	required

Returns:

Type	Description
`Array`	Array with shape `(3, 3)` containing `d/dt tangent(xi, s)`.

Notes

The SE(2) rotation/translation blocks and scalar coefficients are differentiated explicitly. No jvp, grad, or Jacobian transform is invoked in this production path. The result is linear in xid and is exactly zero when either s == 0 or xid == 0.

operators ¶

operators(xi: Array, s: Array, eps: float | Array, xid: Array | None = None) -> ConstantStrainOperators

Return the related SE(2) constant-strain operators as one bundle.

Use this function when a caller needs more than one of :func:adjoint, :func:adjoint_inverse, :func:tangent, and :func:tangent_derivative at the same (xi, s). The bundled evaluation shares stabilized scalar coefficients and adjoint components instead of repeating them in separate public calls.

Parameters:

Name	Type	Description	Default
`xi`	`Array`	Constant planar strain with shape `(3,)` or `(3, 1)` in `[theta, v_x, v_y]` order.	required
`s`	`Array`	Scalar arclength position measured from the segment base.	required
`eps`	`float \| Array`	Minimum rotational-strain threshold used consistently by all returned operators.	required
`xid`	`Array \| None`	Optional strain direction/rate with the same shape as `xi`. When supplied, `tangent_derivative` contains `D_xi T(s, xi)[xid]`; otherwise that field is `None`.	`None`

Returns:

Type	Description
`ConstantStrainOperators`	class:`ConstantStrainOperators` containing the forward and inverse
`ConstantStrainOperators`	adjoints, tangent, and optional analytic tangent derivative.

Notes

The result has a fixed named-field interface and is compatible with JAX transformations. No autodiff operation is executed internally. Call a single-operator function when only one expression is needed; this avoids assembling unused matrices.

SE(3)¶

soromox.utils.lie_algebra.constant_strain.se3 ¶

Closed-form constant-strain operators for :math:SE(3).

The spatial implementation evaluates exact reduced fourth-order polynomials and supports prepared powers shared across arclength evaluations. Public names are unsuffixed because the module itself supplies the algebra context.

adjoint ¶

adjoint(xi: Array, s: Array, eps: float | Array) -> Array

Return the adjoint accumulated along a constant spatial strain segment.

This is a rod-kinematics helper for spatial PCS/GVS segments. For constant strain xi evaluated at arclength s, the returned matrix represents the closed-form adjoint associated with the segment transform exp(s * xi) under the angular-first se(3) convention. Equivalently, it is exp(s * lie_se3.small_adjoint(xi)).

Parameters:

Name	Type	Description	Default
`xi`	`Array`	Constant spatial strain with shape `(6,)` or `(6, 1)` in `[omega_x, omega_y, omega_z, v_x, v_y, v_z]` order.	required
`s`	`Array`	Scalar arclength position measured from the base of the segment.	required
`eps`	`float \| Array`	Minimum rotational-strain threshold. The actual dimensionless cutoff also accounts for `s` and the input dtype.	required

Returns:

Type	Description
`Array`	Array with shape `(6, 6)` mapping spatial twists through the segment
`Array`	adjoint at arclength `s`.

Notes

Rotation enters the scalar coefficients only through dot(omega, omega). This avoids differentiating a Euclidean norm at zero while retaining arbitrary-axis behavior. The fourth-order matrix polynomial is exact for an se(3) adjoint.

adjoint_inverse ¶

adjoint_inverse(xi: Array, s: Array, eps: float | Array) -> Array

Return the inverse adjoint for a constant spatial strain segment.

This computes the inverse of :func:adjoint without explicitly constructing and inverting the homogeneous segment transform. It is used when propagating body-frame Jacobians backward through spatial constant-strain segments. It uses the rotation and translation-skew blocks of the stabilized forward adjoint rather than a generic 6 x 6 inverse.

Parameters:

Name	Type	Description	Default
`xi`	`Array`	Constant spatial strain with shape `(6,)` or `(6, 1)` in `[omega_x, omega_y, omega_z, v_x, v_y, v_z]` order.	required
`s`	`Array`	Scalar arclength position measured from the base of the segment.	required
`eps`	`float \| Array`	Minimum rotational-strain threshold forwarded to :func:`adjoint`.	required

Returns:

Type	Description
`Array`	Array with shape `(6, 6)` representing the inverse segment adjoint.

Notes

Building the inverse from the forward blocks keeps strict-singularity and stable-default behavior aligned with :func:adjoint and avoids the cost and conditioning of a dense solve.

tangent ¶

tangent(xi: Array, s: Array, eps: float | Array) -> Array

Return the tangent operator for a constant spatial strain segment.

The tangent operator integrates local spatial strain perturbations over arclength for a segment whose strain is constant. In PCS/GVS recurrences it maps strain-basis contributions into body-frame Jacobian contributions at arclength s. It evaluates

.. math::

T(s,\xi) = \int_0^s
\exp(\sigma\,\operatorname{ad}_\xi)\,d\sigma

with the exact reduced se(3) polynomial.

Parameters:

Name	Type	Description	Default
`xi`	`Array`	Constant spatial strain with shape `(6,)` or `(6, 1)` in `[omega_x, omega_y, omega_z, v_x, v_y, v_z]` order.	required
`s`	`Array`	Scalar arclength position measured from the base of the segment.	required
`eps`	`float \| Array`	Minimum rotational-strain threshold. The actual dimensionless cutoff also accounts for `s` and the input dtype.	required

Returns:

Type	Description
`Array`	Array with shape `(6, 6)` containing the spatial constant-strain
`Array`	tangent operator at arclength `s`.

Notes

The implementation covers pure translation and arbitrary-axis rotation with one formula. At zero arclength the result is exactly zero; at zero strain it is s * I.

tangent_derivative ¶

tangent_derivative(xi: Array, xid: Array, s: Array, eps: float | Array) -> Array

Return the directional derivative of the spatial tangent operator.

This differentiates :func:tangent with respect to time through the strain xi and strain rate xid while holding arclength s fixed. The coefficient derivative is expressed through the squared rotational magnitude, avoiding a division by norm(omega) at zero rotation. The returned matrix is D_xi T(s, xi)[xid].

Parameters:

Name	Type	Description	Default
`xi`	`Array`	Constant spatial strain with shape `(6,)` or `(6, 1)` in `[omega_x, omega_y, omega_z, v_x, v_y, v_z]` order.	required
`xid`	`Array`	Time derivative of `xi` with the same shape and coordinate order.	required
`s`	`Array`	Scalar arclength position measured from the base of the segment.	required
`eps`	`float \| Array`	Minimum rotational-strain threshold. The actual dimensionless cutoff also accounts for `s` and the input dtype.	required

Returns:

Type	Description
`Array`	Array with shape `(6, 6)` containing `d/dt tangent(xi, s)`.

Notes

The derivative uses d dot(omega, omega) / dt = 2 * dot(omega, omega_dot) and the generic product-rule recurrence for powers of s * ad_xi. It is fully analytic and linear in xid; autodiff appears only in tests that validate this implementation.

operators ¶

operators(xi: Array, s: Array, eps: float | Array, xid: Array | None = None) -> ConstantStrainOperators

Return the related SE(3) constant-strain operators as one bundle.

This is the spatial counterpart of :func:.se2.operators. It is intended for users who require multiple expressions at the same constant strain and arclength. Matrix powers through B**4 are constructed once; the tangent and its optional derivative also share their stable coefficients.

Parameters:

Name	Type	Description	Default
`xi`	`Array`	Constant spatial strain with shape `(6,)` or `(6, 1)` in `[omega_x, omega_y, omega_z, v_x, v_y, v_z]` order.	required
`s`	`Array`	Scalar arclength position measured from the segment base.	required
`eps`	`float \| Array`	Minimum rotational-strain threshold used consistently by all returned operators.	required
`xid`	`Array \| None`	Optional strain direction/rate with the same shape as `xi`. When supplied, `tangent_derivative` contains `D_xi T(s, xi)[xid]`; otherwise that field is `None`.	`None`

Returns:

Type	Description
`ConstantStrainOperators`	class:`ConstantStrainOperators` containing the forward and inverse
`ConstantStrainOperators`	adjoints, tangent, and optional analytic tangent derivative.

Notes

The fixed named result is JAX-transformable. The implementation uses explicit matrix-power and coefficient derivatives and performs no runtime autodiff. For one expression, prefer the corresponding single-operator function to avoid unused assembly.