Visual & Display

Quick Reference ✨

set_visual_mode(ctx, mode) / get_visual_mode(ctx) — switch the primary visualization preset.
set_visual_auto_scale(ctx, bool) / set_visual_scale(ctx, scale) — control display amplitude scaling.
set_visual_enable_field(ctx, field, bool) — show or hide individual fields in the renderer.
set_phase_mode(ctx, mode) / get_phase_mode(ctx) — select the phase-portrait rendering style (requires phase_portrait visual mode).
set_phase_coherence_* — global phase coherence configuration used by the statistics system.

Visual Modes 🎨

Mode Palette

Mode string	Description
`phase_portrait`	Scatter plot of real vs. imaginary components — exposes attractors and limit cycles.
`waveform`	Time-domain waveform — useful for scalar fields and debugging.
`phase`	Phase-only rendering — highlights angular structure.
`energy`	Energy-density view — quick stability checks.
`frequency`	Spectral magnitude — inspect dispersion, filtering, and energy distribution.
`polar`	Polar plot of magnitude/phase pairs.
`fft`	Raw FFT magnitude display.
`singularities`	Highlight detected singular structures and related diagnostics.
`phase_magnitude`	Combined phase + magnitude view.
`spectrum`	Fourier-spectrum view.

phase_magnitude also accepts the aliases phase_mag and phase+magnitude.

spectrum also accepts the aliases spectral and fourier_spectrum.

`set_visual_mode(ctx, mode)`

Set the active visualization preset. Accepts any mode string from the table above, or an integer mode code.

ooc.set_visual_mode(ctx, "phase_portrait")
ooc.set_visual_mode(ctx, "phase_magnitude")
ooc.set_visual_mode(ctx, "spectrum")

`get_visual_mode(ctx)`

Returns mode_code, mode_name — both the integer code and the canonical string name.

local code, name = ooc.get_visual_mode(ctx)
ooc.log("visual mode: %d → %s", code, name)

Display Scale 🔭

`set_visual_auto_scale(ctx, enabled)`

Enable or disable automatic amplitude scaling. When true, the renderer adjusts the display range to fit the field’s current value range. Returns true on success.

ooc.set_visual_auto_scale(ctx, true)    -- auto-scale to field range
ooc.set_visual_auto_scale(ctx, false)   -- use fixed scale

`set_visual_scale(ctx, scale)`

Set a fixed display scale factor (used when auto-scale is disabled). Returns true on success.

ooc.set_visual_scale(ctx, 2.5)   -- amplify display by 2.5×

Field Visibility 🔍

`set_visual_enable_field(ctx, field, enabled)`

Show or hide an individual field in the renderer. field may be a field handle or a 0-based integer index. Returns true on success.

local f0 = ooc.get_field(ctx, 0)
ooc.set_visual_enable_field(ctx, f0, false)   -- hide field 0
ooc.set_visual_enable_field(ctx, 1, true)     -- show field 1

Phase Portrait Sub-modes 🌀

When visual_mode is phase_portrait, you can select a rendering style with set_phase_mode. Calling set_phase_mode while a different visual mode is active raises a Lua error.

Phase Mode Palette

Mode string	Description
`trace`	Continuous trace of the complex trajectory over time.
`scatter`	Scatter of (Re, Im) sample points without connecting lines.
`rosette`	Rosette / Lissajous-style closed-orbit rendering.
`rose_hist`	Histogram-weighted rose pattern — highlights density of visited states.

`set_phase_mode(ctx, mode)`

Set the phase-portrait rendering style. Must be called after set_visual_mode(ctx, "phase_portrait").

ooc.set_visual_mode(ctx, "phase_portrait")
ooc.set_phase_mode(ctx, "rosette")

`get_phase_mode(ctx)`

Returns mode_code, mode_name. Returns nil if no phase mode is set.

local code, name = ooc.get_phase_mode(ctx)
ooc.log("phase mode: %d → %s", code, name)

Phase Coherence Configuration 📡

These five functions configure the global phase coherence system used by field_stats and the statistics pipeline. They accept a ctx argument but operate on process-wide state — settings apply to all contexts in the process.

`set_phase_coherence_thresholds(ctx, abs_threshold, rel_threshold)`

Set the amplitude thresholds for phase sample inclusion:

abs_threshold — minimum absolute amplitude for a sample to count.
rel_threshold — minimum amplitude relative to the current field max_abs.

ooc.set_phase_coherence_thresholds(ctx, 0.01, 0.05)

`set_phase_coherence_weighted(ctx, weighted)`

When true, weight each phase sample by its amplitude when computing coherence. Amplitude-weighted coherence is more robust for fields with large dynamic range.

ooc.set_phase_coherence_weighted(ctx, true)

`set_phase_coherence_lock_thresholds(ctx, on_threshold, off_threshold)`

Set the hysteresis thresholds for the phase-lock state machine:

on_threshold — coherence level required to enter the locked state.
off_threshold — coherence level at which the lock is released (must be ≤ on_threshold).

ooc.set_phase_coherence_lock_thresholds(ctx, 0.85, 0.70)

`set_phase_coherence_smoothing(ctx, smoothing_seconds)`

Set the EMA smoothing time constant for phase_coherence_ema. Larger values produce slower, more stable estimates.

ooc.set_phase_coherence_smoothing(ctx, 0.5)   -- 0.5-second EMA window

`set_phase_coherence_deramp(ctx, enabled)`

Enable or disable phase-ramp detrending before computing coherence. Useful when the field has a dominant linear phase drift that would otherwise suppress the coherence estimate.

ooc.set_phase_coherence_deramp(ctx, true)

Examples 📖

Switching modes during a run

ooc.set_visual_mode(ctx, "waveform")
for i = 1, 100 do ooc.step(ctx) end

ooc.set_visual_mode(ctx, "frequency")
for i = 1, 100 do ooc.step(ctx) end

ooc.set_visual_mode(ctx, "spectrum")

Phase portrait with rosette rendering

ooc.set_visual_mode(ctx, "phase_portrait")
ooc.set_phase_mode(ctx, "rosette")

local code, name = ooc.get_phase_mode(ctx)
ooc.log("rendering as: %s", name)   -- "rosette"

Fixed scale with selective field display

ooc.set_visual_auto_scale(ctx, false)
ooc.set_visual_scale(ctx, 4.0)

-- Two fields; only show field 0
ooc.set_visual_enable_field(ctx, 0, true)
ooc.set_visual_enable_field(ctx, 1, false)

Full phase coherence setup before a run

-- Amplitude thresholds: ignore samples below 1% of max
ooc.set_phase_coherence_thresholds(ctx, 0.0, 0.01)
-- Weight by amplitude for dynamic-range robustness
ooc.set_phase_coherence_weighted(ctx, true)
-- Hysteresis: lock at 85%, release at 70%
ooc.set_phase_coherence_lock_thresholds(ctx, 0.85, 0.70)
-- Smooth over ~1 second of simulation time
ooc.set_phase_coherence_smoothing(ctx, 1.0)
-- Detrend linear phase ramps
ooc.set_phase_coherence_deramp(ctx, true)

for i = 1, 1000 do ooc.step(ctx) end