Special Context & Poles

These helpers expose the special-function state that lives on a simulation context: the configured universe parameters, accumulated analytic-fault reports, pole inventories, synthesized pole fields, and native or Lua fallback hooks.

Universe Parameters

context_truncation_level(ctx) -> K
context_epsilon(ctx) -> epsilon

• K is the context-level truncation depth used by operators that consult the special-function universe.
• epsilon is the context-level regularization parameter used by operators that need a shared special-function shift or guard value.

If you need to set these explicitly at creation time, use context_init_with_universe(config, universe) from the Context API.

Context Fault State

special_fault_count(ctx) -> integer
special_fault_last(ctx) -> report | nil
clear_special_faults(ctx)
context_flush_special_diagnostics(ctx)

special_fault_count returns the number of accumulated context-managed special-function faults. special_fault_last returns nil until a fault has been recorded, otherwise it returns a report table with these fields:

Field	Meaning
count	Total faults accumulated on the context so far
has_fault	true when a report is present
code	Numeric fault code
fault	Fault name string
function	Originating function name, when available
input	Two-element complex input table {re, im}
q_param	q-parameter associated with the evaluation
aux_param	Auxiliary parameter, such as a shift
exponent_param	Exponent-like parameter, such as s in qzeta
iterations	Iteration count reported by the evaluator
residual	Residual reported by the evaluator
tolerance	Tolerance used by the evaluator

clear_special_faults resets the accumulated counter and last-fault snapshot.

context_flush_special_diagnostics flushes pending thread-local diagnostics into the context accumulator. Scheduler-backed stepping already does this once per step when diagnostics are enabled; call it manually when you need a mid-loop snapshot during explicit stepping.

local faults = ooc.special_fault_count(ctx)
local last = ooc.special_fault_last(ctx)

if last and last.has_fault then
    ooc.log("fault=%s function=%s residual=%.3e",
        last.fault,
        last.function,
        last.residual)
end

ooc.clear_special_faults(ctx)

Standalone Math Helpers

Direct Lua helpers such as ooc.qzeta(...) and ooc.qdigamma(...) raise Lua errors immediately when they fail. The context fault tables described here are for context-owned runtime and operator evaluation paths.

Pole Inventory

context_poles(ctx) -> poles

Returns a Lua array of pole records:

• x, y, z
• residue
• optional type

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

The pole list may be empty if the context was not initialized with an explicit universe pole set.

Synthesizing a Pole Field

pole_field_options_default() -> options
context_synthesize_pole_field(ctx, field_index, [options])

Oakfield can synthesize a simple pole-potential field from the current context poles:

$$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 zero-based. The target field must be contiguous, rank <= 2, and use real_double or complex_double. Complex targets receive {f, 0}.

Option keys:

• origin_x, origin_y
• spacing_x, spacing_y
• plane_z
• softening

pole_field_options_default() returns the default table for those keys. A zero spacing value is treated as 1, and a negative softening value keeps the implementation default.

local ctx = ooc.context_init_with_universe({}, {
    K = 12,
    epsilon = 0.125,
    poles = {
        { x = 0.0, y = 0.0, z = 0.0, residue = 1.0, type = "digamma" },
        { x = 1.5, y = 0.0, z = 0.0, residue = -0.5, type = "trigamma" },
    }
})

local field = ooc.add_field(ctx, {32, 32}, { type = "real_double", fill = 0.0 })
ooc.context_synthesize_pole_field(ctx, 0, {
    origin_x = -2.0,
    origin_y = -2.0,
    spacing_x = 0.125,
    spacing_y = 0.125,
    softening = 0.05,
})

Fallback Hooks

context_set_special_fallback(ctx, fn_or_nil)
context_special_fallback_hook(ctx) -> dispatch_ptr, userdata_ptr

context_set_special_fallback installs a Lua callback used by context-managed special-function evaluation when a fallback value is required:

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

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

The callback receives the same report shape described under special_fault_last(ctx). If the Lua callback raises or returns an unsupported value, Oakfield logs an error and the fallback fails.

context_special_fallback_hook exposes the context’s native dispatch pointer and userdata pointer as lightuserdata for embedder or FFI integrations. Clearing the Lua callback does not make this pair disappear; it simply restores the default fallback behavior behind that dispatcher.