CustomCallable

class CustomCallable(function, vocabulary, role: str, owner: str)

Bases: object

A user-supplied function bound to a fixed keyword vocabulary.

Both CustomDynamicModel and CustomMeasurement let a script hand Scarabaeus a plain Python function. To keep those functions readable, they are invoked with keyword arguments and declare only the context entries they actually need. This class performs the binding once, at construction, so a misspelt argument is reported immediately rather than on the first evaluation deep inside an integrator or a partials loop.

It also carries the central finite-difference helpers used to fill in any Jacobian the user did not supply analytically, so the two model families cannot drift apart in how they differentiate.

Parameters:

functioncallable

User-supplied function.

vocabularytuple of str

Context names the consumer is able to provide.

rolestr

Human-readable description of what the function is for, used in error messages (e.g. "acceleration").

ownerstr

Name of the model that owns the function, used in error messages.

Attributes:

function

The wrapped user function.

names

Context names this callable receives.

Methods

__call__(context)	Invoke the user function with the subset of context it declared.
default_step(values, relative)	Return a per-component central-difference step.
finite_difference(evaluate, values, steps, ...)	Central-difference Jacobian of evaluate with respect to values.
reads(name)	Report whether this callable can see name.

Raises:

CustomCallable.SignatureError

If function is not callable, uses *args, or declares an argument outside vocabulary.

See also

scarabaeus.CustomDynamicModel

User-defined force model.

scarabaeus.CustomMeasurement

User-defined measurement model.

static default_step(values: ndarray, relative: float) → ndarray

Return a per-component central-difference step.

Parameters:

valuesnumpy.ndarray

Point the derivative is taken at.

relativefloat

Relative step size.

Returns:

numpy.ndarray

relative * max(|values|, 1), elementwise.

static finite_difference(evaluate, values: ndarray, steps, n_rows: int)

Central-difference Jacobian of evaluate with respect to values.

Parameters:

evaluatecallable

Takes a perturbed copy of values and returns an (n_rows,) array.

valuesnumpy.ndarray

Point the Jacobian is evaluated at, shape (n_cols,).

stepsnumpy.ndarray

Per-component absolute step sizes, shape (n_cols,).

n_rowsint

Number of rows of the resulting Jacobian.

Returns:

numpy.ndarray

Jacobian of shape (n_rows, n_cols).

reads(name: str) → bool

Report whether this callable can see name.

A callable that takes the whole state (or **kwargs) could read the quantity from there, so it counts. Used to decide, without evaluating anything, whether a Jacobian block is structurally present.

Parameters:

namestr

Context name, e.g. "velocity".

Returns:

bool

True when the callable declares name or a container holding it.

property function

The wrapped user function.

property names: tuple

Context names this callable receives.

exception SignatureError

Bases: ValueError

Raised when a user callable declares an argument that is not supplied.