derivkit.adaptive.transforms module

Helpers for parameter transformations and converting derivatives between coordinate systems.

This module provides small, self-contained transforms that make adaptive polynomial fitting robust near parameter boundaries.

derivkit.adaptive.transforms.signed_log_derivatives_to_x(order: int, x0: float, dfdq: ndarray, d2fdq2: ndarray | None = None) → ndarray

Converts derivatives from the signed-log coordinate q to the original parameter x at x0 ≠ 0.

This method uses the chain rule to convert derivatives computed in the internal signed-log coordinate q back to physical coordinates x at a non-zero expansion point x0.

Parameters:

  • order – Derivative order to return (1 or 2).

  • x0 – Expansion point in the original parameter x (the model’s native coordinate); must be finite and non-zero.

  • dfdq – First derivative in q (shape: (n_components,) or broadcastable).

  • d2fdq2 – Second derivative with respect to q; required when order == 2. A 1-D array with one value per component (shape (n_components,)) or broadcastable to that.

Returns:

The derivative(s) in physical coordinates at x0.

Raises:

  • ValueError – If x0 == 0, if required inputs (d2fdq2) are missing for order=2, or if x0 is not finite.

  • NotImplementedError – If order not in {1, 2}.

derivkit.adaptive.transforms.signed_log_forward(x0: float) → Tuple[float, float]

Computes the signed-log coordinates for an expansion point.

The signed-log map represents a physical coordinate x as x = sgn * exp(q), where q = log(|x|) and sgn = sign(x). Here, physical means the model’s native parameter (x), while internal means the reparameterized coordinate used for numerics (q). This reparameterization keeps multiplicative variation (orders of magnitude) well-behaved and avoids crossing through zero during local polynomial fits.

Parameters:

x0 – Expansion point in physical coordinates. Must be finite and non-zero.

Returns:

(q0, sgn), where q0 = log(|x0|) and sgn = +1.0 if x0 > 0 else -1.0.

Return type:

Tuple[float, float]

Raises:

ValueError – If x0 is not finite or equals zero.

derivkit.adaptive.transforms.signed_log_to_physical(q: ndarray, sgn: float) → ndarray

Maps internal signed-log coordinate(s) to physical coordinate(s).

Parameters:

  • q – Internal coordinate(s) q = log(abs(x)).

  • sgn – Fixed sign (+1 or -1) taken from sign(x0).

Returns:

Physical coordinate(s) x = sgn * exp(q).

Raises:

ValueError – If sgn is not +1 or -1, or if q contains non-finite values.

derivkit.adaptive.transforms.sqrt_derivatives_to_x_at_zero(order: int, x0: float, g2: ndarray | None = None, g4: ndarray | None = None) → ndarray

Pull back derivatives at value x0=0 from u-space (sqrt-domain) to physical x.

This method maps derivatives computed in the internal sqrt-domain coordinate u back to physical coordinates x at the expansion point x0=0 using the chain rule.

Parameters:

  • order – Derivative order to return (1 or 2).

  • x0 – Expansion point in physical coordinates (finite). May be +0.0 or -0.0 to select the domain side at the boundary. The domain sign is inferred solely from x0 (including the sign of zero).

  • g2 – Second derivative of g with respect to u at u=0; required for order=1.

  • g4 – Fourth derivative of g with respect to u at u=0; required for order=2.

Returns:

The derivative(s) in physical coordinates at x0=0.

Raises:

  • ValueError – If required inputs (g2/g4) are missing for the requested order.

  • NotImplementedError – If order not in {1, 2}.

derivkit.adaptive.transforms.sqrt_domain_forward(x0: float) → tuple[float, float]

Computes the internal domain coordinate u0 for the square-root domain transformation.

The square-root domain transform re-expresses a parameter x as x = s * u**2, where s is the domain sign (+1 or –1). This mapping flattens steep behavior near a boundary such as x = 0 and allows smooth polynomial fitting on either the positive or negative side.

Parameters:

x0 – Expansion point in physical coordinates (finite). May be ±0.0

Returns:

(u0, s), with u0 >= 0 and sgn in {+1.0, -1.0}.

Return type:

Tuple[float, float]

derivkit.adaptive.transforms.sqrt_to_physical(u: ndarray, sign: float) → ndarray

Maps internal domain coordinate(s) to physical coordinate(s).

This method maps internal coordinate(s) u to physical coordinate(s) x using the relation x = sign * u^2.

Parameters:

  • u – Internal coordinate(s).

  • sign – Domain sign (+1 for x ≥ 0, -1 for x ≤ 0).

Returns:

Physical coordinate(s) x = sign * u^2.

Raises:

ValueError – If sign is not +1 or -1, or if u contains non-finite values.