pynucastro.autodiff.dual module

pynucastro.autodiff.dual module#

Forward-mode derivatives of scalar values, usable from Python and Numba.

Seed the independent variable with Dual(value, 1.0) and constants with Dual(value, 0.0). Use this module’s math helpers in place of NumPy ufuncs when an argument may be dual. CPU Numba overloads support scalar-left arithmetic, value comparisons, and two-argument min/max. Compiled min/max return a Dual if either operand is dual, with zero derivative when a scalar bound is selected. Ties select the first operand, as in Python. Use DerivativePair seeds to propagate two derivatives simultaneously. All dual operands in an expression must use the same seed kind. Other branches must likewise keep dual-valued variables consistently typed.

There are two execution paths for the same derivative rules. Ordinary Python calls use the Dual methods and math helpers such as sin. In Numba-compiled code, Dual is represented as a native namedtuple; Numba does not automatically use this subclass’s Python methods. The @overload registrations supply its arithmetic and math operations instead.

The _ol_ prefix means “overload”: _ol_sin is a compile-time factory, not another user-facing sine function. Numba passes it argument types, and it returns a function to compile for those types. That returned function receives actual values at runtime. Call sin(x) in either execution path; Numba selects the overload automatically. Keep the formulas in both paths in sync when changing a derivative rule.

class pynucastro.autodiff.dual.Dual(value, deriv=1.0)[source]#

Carry a quantity that can propagate its derivative.

A scalar seed carries one derivative; a DerivativePair seed carries two independent derivatives. Instances are immutable namedtuples, lowered by Numba to native tuple values.

Parameters:
  • value (float) – Scalar value.

  • deriv (float or DerivativePair, optional) – Derivative seed, defaulting to one. Use the same seed kind for all dual operands in an expression.

pynucastro.autodiff.dual.arctan(x)[source]#

Compute arctan(x).

pynucastro.autodiff.dual.cbrt(x)[source]#

Compute cbrt(x).

pynucastro.autodiff.dual.constant_like(x, value)[source]#

Give a constant the same scalar or dual representation as x.

Parameters:
  • x (float or Dual) – Determines the result type and derivative seed shape.

  • value (float) – Constant value, whose derivatives are zero.

Returns:

The constant with zero derivatives when x is dual.

Return type:

float or Dual

pynucastro.autodiff.dual.cos(x)[source]#

Compute cos(x), with x in radians.

pynucastro.autodiff.dual.exp(x)[source]#

Compute exp(x).

pynucastro.autodiff.dual.log(x)[source]#

Compute log(x), the natural logarithm.

pynucastro.autodiff.dual.log1p(x)[source]#

Compute log(1 + x), using the natural logarithm.

pynucastro.autodiff.dual.sin(x)[source]#

Compute sin(x), with x in radians.

pynucastro.autodiff.dual.sqrt(x)[source]#

Compute sqrt(x).