Thermostat Operators

♨️ Thermostat

sim_add_thermostat_operator(ctx, field, opts)

Regulate field kinetic energy toward a target value using feedback control. Implements multiple regulation strategies for energy stabilization in dynamical systems, maintaining constant temperature in molecular dynamics analogs, and preventing runaway growth or decay.

Method Signature

sim_add_thermostat_operator(ctx, field, [options]) -> operator

Returns: Operator handle (userdata)

Mathematical Formulation

Energy Computation:

The instantaneous kinetic energy is computed as:

$$E = \frac{1}{N} \sum_{i=1}^{N} |u_i|^2$$

Soft Lambda Mode (default):

Applies spectral damping with feedback-controlled coefficient:

$$\lambda = \lambda_{\text{base}} + g \cdot (E - E_{\text{target}})$$ $$\hat{u}(k) \leftarrow \hat{u}(k) \cdot e^{-\lambda |k|^2 \Delta t}$$

The lambda value is smoothed and clamped:

$$\lambda_{\text{smooth}} = \alpha \cdot \lambda_{\text{prev}} + (1 - \alpha) \cdot \lambda$$ $$\lambda_{\text{final}} = \text{softplus\_clamp}(\lambda_{\text{smooth}}, \lambda_{\min}, \lambda_{\max})$$

Additive Mode:

Adds a correction proportional to energy error:

$$u \leftarrow u + \mu \cdot (E_{\text{target}} - E) \cdot \Delta t$$

Multiplicative Mode:

Scales the field to match target energy:

$$u \leftarrow u \cdot \sqrt{\frac{E_{\text{target}}}{E + \varepsilon}}$$

Parameters

Core Parameters:

Parameter	Type	Default	Range	Description
mode	enum	"soft_lambda"	see below	Regulation strategy
E_target	double	1.0	≥0	Target energy
mu	double	1.0	unbounded	Relaxation factor for add/mult modes

Mode options: soft_lambda, add, mult, none

Lambda Parameters (soft_lambda mode):

Parameter	Type	Default	Range	Description
lambda_base	double	0.0	unbounded	Baseline lambda before feedback
lambda_soft_gain	double	0.1	≥0	Feedback gain for energy error
lambda_min	double	-1.0	unbounded	Minimum lambda clamp
lambda_max	double	1.0	unbounded	Maximum lambda clamp
lambda_smooth	double	0.9	[0, 1]	Smoothing factor for lambda updates
lambda_rebuild_thresh	double	0.1	≥0	Threshold for kernel rebuilds
softplus_k	double	10.0	>0	Softplus sharpness for clamping

Advanced Parameters:

Parameter	Type	Default	Description
auto_nu_guard	boolean	false	Enable damping guard for mult mode
memory_field	field	nil	Optional per-sample target field

Boundary & Initial Conditions

• Soft lambda mode uses spectral methods (periodic boundaries)
• Add/mult modes operate pointwise (no boundary requirements)
• Initial energy should be finite and positive
• Transient period as lambda stabilizes ≈ 10/(1 - lambda_smooth) timesteps

Stability & Convergence

• soft_lambda: Stable for reasonable gain values; high gain can cause oscillation
• add: Linear feedback; stable for small mu
• mult: Instantaneous rescaling; can be aggressive; use auto_nu_guard for safety
• none: Pass-through; no regulation

Tuning guidelines:

• Start with small lambda_soft_gain (0.01-0.1) and increase as needed
• High lambda_smooth (>0.9) reduces oscillation but slows response
• For mult mode, mu < 1 provides gentler correction

Performance Notes

• Soft lambda mode requires FFT/IFFT pair per timestep
• Add/mult modes are O(N) pointwise operations
• Lambda smoothing adds minimal overhead
• memory_field enables spatially-varying targets at cost of extra field read

Examples

-- Basic soft lambda thermostat
ooc.sim_add_thermostat_operator(ctx, field, {
    E_target = 1.5,
    mode = "soft_lambda",
    lambda_soft_gain = 0.2
})

-- Conservative soft lambda with tight bounds
ooc.sim_add_thermostat_operator(ctx, field, {
    E_target = 1.0,
    mode = "soft_lambda",
    lambda_soft_gain = 0.05,
    lambda_min = -0.5,
    lambda_max = 0.5,
    lambda_smooth = 0.95
})

-- Additive feedback mode
ooc.sim_add_thermostat_operator(ctx, field, {
    mode = "add",
    E_target = 2.0,
    mu = 0.1
})

-- Additive with lambda bounds
ooc.sim_add_thermostat_operator(ctx, field, {
    mode = "add",
    lambda_base = 0.1,
    lambda_min = -2.0,
    lambda_max = 2.0
})

-- Multiplicative rescaling
ooc.sim_add_thermostat_operator(ctx, field, {
    mode = "mult",
    E_target = 1.0,
    mu = 0.5  -- gentle correction
})

-- Multiplicative with damping guard
ooc.sim_add_thermostat_operator(ctx, field, {
    mode = "mult",
    E_target = 0.5,
    auto_nu_guard = true
})

-- High-gain responsive thermostat
ooc.sim_add_thermostat_operator(ctx, field, {
    E_target = 1.0,
    mode = "soft_lambda",
    lambda_soft_gain = 1.0,
    lambda_smooth = 0.8,
    lambda_min = -5.0,
    lambda_max = 5.0
})

-- No regulation (pass-through)
ooc.sim_add_thermostat_operator(ctx, field, {
    mode = "none"
})

-- Spatially-varying target with memory field
ooc.sim_add_thermostat_operator(ctx, field, {
    mode = "add",
    memory_field = target_energy_field,
    mu = 0.2
})

-- Fine-tuned softplus clamping
ooc.sim_add_thermostat_operator(ctx, field, {
    E_target = 1.0,
    mode = "soft_lambda",
    lambda_soft_gain = 0.1,
    softplus_k = 20.0,  -- sharper clamp
    lambda_min = 0.0,
    lambda_max = 1.0
})