Journey 03 — Configuration (contour + N)

Tune n_talbot and nu, select CONTOUR_* shapes, and pass cfg= into solve.

Prerequisites: Journey 02 works. Scenario: Tune the Talbot contour: node count, nu, and contour shape

Key APIs

solvlrde.config_defaults()
SolvlrdeConfig
CONTOUR_WEIDEMAN
solve(..., cfg=cfg)

Concepts to internalize

Auto-tuned contour — defaults work for most problems; tighten for hard spectra.
CONTOUR_ selectors* — Weideman (default), Trefethen, Tref_eq via C helper.
cfg is ctypes struct — mirrors solvlrde.h; set fields then pass to solve.

Important code

The guided tour script wraps this pattern. Copy the production shape into your pipeline:

import solvlrde as lrde
 
cfg = lrde.config_defaults()
cfg.n_talbot = 48
cfg.nu = 0.7
result = lrde.solve(A, y0, T=T, cfg=cfg)

Act-by-act walkthrough

Act 1 — What the config controls

config_defaults() returns a SolvlrdeConfig. The two knobs you tune most are n_talbot (number of contour nodes = accuracy vs cost) and nu (a contour-shape parameter). More nodes -> more accuracy and more linear solves; the auto-tuner picks a sane default per problem.

Field	Value	Notes
`n_talbot`	32
`nu`	0.6
`mu_scale`	1.0
`emit_diagnostics`	0

Act 2 — Default nodes

Solve the stiff system with the default contour and note n_talbot_used and the achieved error.

Field	Value	Notes
`survived`	True
`status`	ok
`y`	[1.88928e-15, 0.36788]
`n_talbot_used`	32
`n_solves`	32
`nu_used`	0.6
`contour_scale`	12.8
`wall_s`	0
`expected`	[0, 0.36788]
`max_abs_error`	9.153e-11

Act 3 — More nodes = tighter contour

Raise n_talbot and nu on a copy of the config, pass it via cfg=, and watch n_solves rise with accuracy. This is the accuracy/cost dial.

Field	Value	Notes
`requested_n_talbot`	64
`requested_nu`	0.7
`survived`	True
`status`	ok
`y`	[-3.92167e-10, 0.367866]
`n_talbot_used`	64
`n_solves`	64
`nu_used`	0.7
`contour_scale`	25.6
`wall_s`	0
`expected`	[0, 0.36788]
`max_abs_error`	1.369e-05

Act 4 — Contour shape

SolvLRDE ships three contour families, selectable with the module-level constants CONTOUR_WEIDEMAN (default), CONTOUR_TREFETHEN, and CONTOUR_TREF_EQ. Apply one with the C config setter.

Field	Value	Notes
`CONTOUR_WEIDEMAN`	0
`CONTOUR_TREFETHEN`	1
`CONTOUR_TREF_EQ`	2	Applied CONTOUR_TREFETHEN to a fresh config.
`survived`	True
`status`	ok
`y`	[-5.15648e-16, 0.36788]
`n_talbot_used`	32
`n_solves`	32
`nu_used`	0.5
`contour_scale`	12.8
`wall_s`	0
`expected`	[0, 0.36788]
`max_abs_error`	7.994e-09

Guided tour output

Verified console capture from 03_configuration.py:

Tune the Talbot contour: node count, nu, and contour shape

-- Act 1 - What the config controls --
  -> config_defaults() returns a SolvlrdeConfig. The two knobs you tune most are n_talbot (number of contour nodes = accuracy vs cost) and nu (a contour-shape parameter). More nodes -> more accuracy and more linear solves; the auto-tuner picks a sane default per problem.
  n_talbot: 32
  nu: 0.6
  mu_scale: 1.0
  emit_diagnostics: 0

-- Act 2 - Default nodes --
  -> Solve the stiff system with the default contour and note n_talbot_used and the achieved error.
  survived: True
  status: ok
  y: [1.88928e-15, 0.36788]
  n_talbot_used: 32
  n_solves: 32
  nu_used: 0.6
  contour_scale: 12.8
  wall_s: 0
  expected: [0, 0.36788]
  max_abs_error: 9.153e-11

-- Act 3 - More nodes = tighter contour --
  -> Raise n_talbot and nu on a copy of the config, pass it via cfg=, and watch n_solves rise with accuracy. This is the accuracy/cost dial.
  requested_n_talbot: 64
  requested_nu: 0.7
  survived: True
  status: ok
  y: [-3.92167e-10, 0.367866]
  n_talbot_used: 64
  n_solves: 64
  nu_used: 0.7
  contour_scale: 25.6
  wall_s: 0
  expected: [0, 0.36788]
  max_abs_error: 1.369e-05

-- Act 4 - Contour shape --
  -> SolvLRDE ships three contour families, selectable with the module-level constants CONTOUR_WEIDEMAN (default), CONTOUR_TREFETHEN, and CONTOUR_TREF_EQ. Apply one with the C config setter.
  CONTOUR_WEIDEMAN: 0
  CONTOUR_TREFETHEN: 1
  CONTOUR_TREF_EQ: 2
  -> Applied CONTOUR_TREFETHEN to a fresh config.
  survived: True
  status: ok
  y: [-5.15648e-16, 0.36788]
  n_talbot_used: 32
  n_solves: 32
  nu_used: 0.5
  contour_scale: 12.8
  wall_s: 0
  expected: [0, 0.36788]
  max_abs_error: 7.994e-09

-- Run complete --
  next_journey: 04_time_independence.py

Run it

cd python
# Guided tour — narrated scenario walkthrough (recommended first run):
python examples/journeys/03_configuration.py
 
# Production one-liner — same API call you ship:
python -c "import solvlrde as s; c=s.config_defaults(); c.n_talbot=48; c.nu=0.7; print(c.n_talbot)"

What comes next

Journey 04 proves T-independence on a stiff 2-mode system.

Navigation

← Journey 02 — Core path · Journey 04 — Time-independent cost →

02 Core path 04 Time-independent cost