Reaction Operators

Remainder ➗

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

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

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.add_remainder_operator(ctx, warped, ref, diff, {
    nonlinearity = "identity"
})

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

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

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

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

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

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

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

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