Reaction Operators

➗ Remainder

sim_add_remainder_operator(ctx, warped, reference, out, opts)

Measure analytic residues between a warped field and a reference field with optional nonlinear transformations. Useful for computing error metrics, loss functions, and field comparisons with configurable nonlinearities.

Method Signature

sim_add_remainder_operator(ctx, warped, reference, output, [options]) -> operator

Returns: Operator handle (userdata)

Mathematical Formulation

The operator computes:

$$\text{out}_i = w \cdot f(\text{warped}_i - \text{reference}_i) + b$$

where:

• $w$ is the weight parameter
• $b$ is the bias parameter
• $f$ is the nonlinearity function

Nonlinearity options:

• identity: $f(x) = x$ (linear difference)
• abs: $f(x) = |x|$ (absolute error)
• log_abs: $f(x) = \log(|x| + \varepsilon)$ (log-scale error)
• power: $f(x) = |x|^p \cdot \text{sign}(x)$ (power-law error)
• tanh: $f(x) = \tanh(x)$ (saturating error)

Complex mode handling:

• component: Compare real and imaginary parts independently
• polar: Compare magnitude and phase

Parameters

Parameter	Type	Default	Range	Description
weight	double	1.0	unbounded	Gain applied to residue
bias	double	0.0	unbounded	Additive bias after nonlinearity
exponent	double	1.0	unbounded	Power for nonlinearity = "power"
epsilon	double	1e-4	>0	Guard for log/power modes
nonlinearity	enum	"identity"	see below	Analytic transform to apply
complex_mode	enum	"component"	see below	Complex comparison mode
accumulate	boolean	false	—	Add to output instead of overwriting
scale_by_dt	boolean	true	—	Scale accumulated writes by dt

Nonlinearity options: identity, abs, log_abs, power, tanh

Complex mode options: component, polar

Boundary & Initial Conditions

• Operates elementwise; no boundary handling required
• All three fields (warped, reference, output) must have compatible dimensions
• For complex fields, complex_mode determines comparison semantics

Stability & Convergence

• identity/abs: Unconditionally stable
• log_abs: Protected by epsilon; avoid very small epsilon values
• power: Sign-preserving for odd-integer exponents; epsilon guards against |x|^p overflow
• tanh: Saturates smoothly at ±1; useful for bounded error signals

Performance Notes

• Lightweight pointwise operation
• log_abs and power require transcendental function evaluation
• tanh uses fast approximation when available
• complex_mode = "polar" requires magnitude/phase extraction

Examples

-- Simple difference (identity)
ooc.sim_add_remainder_operator(ctx, warped, ref, diff, {
    nonlinearity = "identity"
})

-- Squared error (power = 2)
ooc.sim_add_remainder_operator(ctx, warped, ref, sq_error, {
    nonlinearity = "power",
    exponent = 2
})

-- Absolute error
ooc.sim_add_remainder_operator(ctx, warped, ref, abs_error, {
    nonlinearity = "abs"
})

-- Log-scale error (for wide dynamic range)
ooc.sim_add_remainder_operator(ctx, warped, ref, log_error, {
    nonlinearity = "log_abs",
    epsilon = 1e-5
})

-- Saturating error (bounded output)
ooc.sim_add_remainder_operator(ctx, warped, ref, bounded_error, {
    nonlinearity = "tanh",
    weight = 2.0  -- scale before tanh
})

-- Weighted and biased residue
ooc.sim_add_remainder_operator(ctx, warped, ref, weighted, {
    nonlinearity = "abs",
    weight = 0.5,
    bias = 0.1
})

-- Accumulate error over time
ooc.sim_add_remainder_operator(ctx, warped, ref, integrated_error, {
    nonlinearity = "power",
    exponent = 2,
    accumulate = true,
    scale_by_dt = true
})

-- Complex polar comparison
ooc.sim_add_remainder_operator(ctx, complex_warped, complex_ref, diff, {
    nonlinearity = "abs",
    complex_mode = "polar"
})

-- L1 loss with custom epsilon
ooc.sim_add_remainder_operator(ctx, prediction, target, l1_loss, {
    nonlinearity = "abs",
    epsilon = 1e-8
})