derivative (pmrf.derivative)

pmrf.derivative(eval_fn: Callable[[...], Any], *args: Unpack[Ts], space: str = 'declared') → Tuple[Unpack[Ts]]

Computes the exact derivative of a function.

Dynamically routes to the most relevant autodiff method: - grad (reverse-mode) for scalar outputs. - jacfwd (forward-mode) for wide Jacobians (output size > input size). - jacrev (reverse-mode) for tall Jacobians (input size >= output size).

Complex outputs always use jacfwd, since reverse mode requires real outputs; their derivatives are complex. Complex inputs are not supported.

Parameters are differentiated with respect to their value in space, so by default a derivative is per unit the parameter declares: per pF for a capacitance declared with scale=1e-12. A tie is recomputed from its source inside the differentiated function, so the source’s derivative includes the path through the tie. Raw JAX arrays are differentiated as they are.

In declared and physical space a parameter on a closed bound, such as a NonNegative loss at 0, has a finite derivative. In raw space it has none: its raw value there is infinite, so a derivative with respect to it has no finite meaning.

Safely handles models as inputs by filtering out non-differentiable static fields (like strings, booleans, integers, AND NumPy arrays).

Parameters:

  • eval_fn (Callable) – The function to differentiate. It is called with the arguments unwrapped.

  • *args (*Ts) – The arguments to evaluate the derivative at. Can be raw arrays or full Models.

  • space ({'declared', 'physical', 'raw'}, default='declared') – The space parameter values are differentiated in. See pmrf.Param.

Returns:

A tuple containing the derivatives, one per argument. Each keeps its argument’s structure with every parameter replaced by its derivative, so pmrf.values() reads the derivatives by name. Non-differentiable leaves are None.

Return type:

Tuple[*Ts]

Raises:

  • ValueError – If space is not one of the supported spaces.

  • TypeError – If any differentiable input is complex-valued.

Examples

Compute the sensitivity of a component’s response with respect to its parameters:

>>> import pmrf as prf
>>> from pmrf.models import ShuntCapacitor
>>>
>>> freq = prf.Frequency(2.4, 2.4, 1, 'GHz')
>>> cap = ShuntCapacitor(C=prf.Unconstrained(1.0, scale=1e-12), name='c1')
>>>
>>> def eval_s21(model):
...     return model.s_mag(freq)[0, 1, 0]
...
>>> (d_cap,) = derivative(eval_s21, cap)
>>>
>>> # Per pF, the unit the capacitance was declared in
>>> print(f"{prf.values(d_cap)['C']:.3e}")
-1.164e-01