Special Context & Poles

Some special-function implementations maintain per-context universe parameters (like truncation level and pole sets) and can emit structured fault reports. These helpers expose that state to Lua for diagnostics and visualization tooling.

🔢 Universe Parameters

sim_context_truncation_level(ctx) -> K
sim_context_epsilon(ctx) -> epsilon

• K is the truncation level used by certain series/recurrence evaluations.
• epsilon is a small regularization parameter used by some convergence logic.

📍 Poles

sim_context_poles(ctx) -> poles

Returns an array of pole tables:

• x, y, z (numbers)
• residue (number)
• optional type (string)

for _, p in ipairs(ooc.sim_context_poles(ctx)) do
    ooc.log("pole @ (%.3f, %.3f, %.3f) residue=%.3g", p.x, p.y, p.z, p.residue)
end

🗺️ Synthesizing a Pole Field

sim_pole_field_options_default() -> options
sim_context_synthesize_pole_field(ctx, field_index, [options])

Fills a 1D/2D field with samples of a simple pole potential built from the current pole set:

$$f(x,y) = \sum_i \frac{\mathrm{residue}_i}{\sqrt{(x-x_i)^2+(y-y_i)^2+(z-z_i)^2 + \mathrm{softening}^2}}.$$

field_index is the zero-based field index. The target field must be contiguous, rank ≤ 2, and real_double or complex_double (complex receives {re=f, im=0}).

Option keys:

• origin_x, origin_y (numbers)
• spacing_x, spacing_y (numbers; 0 treated as 1)
• plane_z (number)
• softening (number; negative uses default)

🪝 Special Fallback Hook

sim_context_set_special_fallback(ctx, fn_or_nil)

Registers a Lua callback used as a fallback value provider when special-function evaluation emits a fault report. The callback is invoked as:

fn(report) -> number | {re, im}

Pass nil to clear the callback and restore the default fallback behavior.

For embedder/FFI use, you can also fetch the native hook pair:

sim_context_special_fallback_hook(ctx) -> dispatch_ptr, userdata_ptr

Both values are returned as Lua lightuserdata and are intended for native integrations.