src/baoab.jl

MEDYAN.FIREConfig

FIREConfig(; kwargs...)

Configuration for the optional FIRE 2.0 pre-relaxation used by baoab!. The non-stopping-criterion defaults are tuned for MEDYAN filament relaxation (measured by force evaluations to reach a target max_force) and work reasonably across both stiff (e.g. twistable) and soft filament systems; see “Tuning for a specific system” below. Pre-relaxation is disabled by default because max_force = Inf.

Fields

  • max_force::Float64 = Inf: run FIRE if the initial magnitude of a net force on any bead is larger than this threshold in pN. Position forces use their physical force norm. Material-direction forces use |F| / direction_radius, with direction_radius = sqrt(direction_mass / particle_mass).
  • max_force_evals::Int = typemax(Int): maximum force evaluations to spend on pre-relaxation.
  • dmax::Float64 = 1.5: maximum distance any positional bead is moved in a step.
  • dirmax::Float64 = 0.8: maximum motion any directional bead is moved in a step.
  • tstart::Float64 = 6.0: initial FIRE timestep as tstart * dt, where dt is the production BAOAB timestep.
  • tmax::Float64 = 4.0: maximum FIRE timestep as tmax * dt.
  • tmin::Float64 = 0.1: minimum FIRE timestep as tmin * dt.
  • delaystep::Int = 3: number of positive-power steps to wait before growing the timestep and shrinking alpha.
  • dtgrow::Float64 = 1.05: factor used to increase the FIRE timestep.
  • dtshrink::Float64 = 0.85: factor used to decrease the FIRE timestep.
  • alpha0::Float64 = 0.15: initial mixing coefficient for velocity and force directions.
  • alphashrink::Float64 = 0.95: factor used to decrease alpha.
  • vdfmax::Int = 2000: stop after this many consecutive backtracks.
  • initialdelay::Bool = true: if true, hold the timestep fixed for the first delaystep iterations instead of shrinking it on early uphill steps.
  • abcfire::Bool = false: if true, use the ABC-FIRE bias correction, scaling the velocity by 1 / (1 - (1 - alpha)^n) after each mixing step, where n is the number of consecutive positive-power steps. This de-biases the exponential-moving-average mixing (analogous to the Adam optimizer’s bias correction) and is largest on the first few steps after a reset.

Tuning for a specific system

The defaults aim to be robust across systems; for the last factor of performance on one system, tune these in order of impact (objective: minimize force evaluations to reach max_force):

  1. tmax — the dominant knob. It sets the timestep ceiling, i.e. how aggressive the relaxation gets. Raise it until the relaxation starts thrashing or diverging (force evals spike or it fails to converge), then back off. Stiff systems near their stability limit want a smaller tmax (closer to a constant timestep); softer systems tolerate a larger tmax.
  2. alpha0 — the velocity/force mixing strength. Stiff or strongly coupled systems (e.g. with material-direction DOFs) generally want a smaller alpha0.
  3. tstart, then alphashrink and delaystep for marginal gains.

tmin only needs to stay below tmax to allow timestep adaptation; its exact value has little effect. Note dt is redundant with the timestep multipliers during relaxation: scaling dt and tstart/tmax/tmin inversely leaves the relaxation unchanged, so there is no need to tune dt separately for it.