Thermostat Operators

Thermostat ♨️

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

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:

Mode options: soft_lambda, add, mult, none

Lambda Parameters (soft_lambda mode):

Advanced Parameters:

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.add_thermostat_operator(ctx, field, {
    E_target = 1.5,
    mode = "soft_lambda",
    lambda_soft_gain = 0.2
})

-- Conservative soft lambda with tight bounds
ooc.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.add_thermostat_operator(ctx, field, {
    mode = "add",
    E_target = 2.0,
    mu = 0.1
})

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

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

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

-- High-gain responsive thermostat
ooc.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.add_thermostat_operator(ctx, field, {
    mode = "none"
})

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

-- Fine-tuned softplus clamping
ooc.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
})