vibesketch.chem.fire

FIRE, the Fast Inertial Relaxation Engine: a minimiser on numpy alone.

FIRE moves a point downhill the way a particle of unit mass would roll in the energy landscape, damped by mixing its velocity towards the force and restarted whenever it starts to climb:

  • E. Bitzek, P. Koskinen, F. Gähler, M. Moseler and P. Gumbsch, Phys. Rev. Lett. 97, 170201 (2006), https://doi.org/10.1103/PhysRevLett.97.170201 : the velocity mixing, the delayed growth of the time step and the restart on an uphill step.

  • J. Guénolé, W. G. Nöhring, A. Vaid, F. Houllé, Z. Xie, A. Prakash and E. Bitzek, Comput. Mater. Sci. 175, 109584 (2020), https://doi.org/10.1016/j.commatsci.2020.109584 : the FIRE 2.0 rules, which take half a step back on an uphill step, keep the time step during the first n_delay steps, put a floor under it and give up when the point keeps climbing.

The integrator is velocity Verlet, as the two papers use. The parameters and their defaults, dt 0.1, dt_max 1.0, alpha_start 0.1, n_delay 5, the factors 1.1, 0.5 and 0.99 and a cap of 0.1 on a step, are those of vibe-view’s FIRE (vibeview.live_opt) and of the 2006 paper. The differences from vibe-view are deliberate:

  • vibe-view integrates with semi-implicit Euler and has no half-step back, time-step floor or stuck detector, the 2020 refinements this module adds.

  • A step that raised the energy counts as uphill here, like the power criterion. The power alone lets a time step beyond the stiffest mode’s stability limit blow the energy up for several steps before the velocity turns against the force (the Rosenbrock valley shows it); the energy catches it at once. Round-off is tolerated: ten decimal digits of the energy. After the half step back the energy and gradient are evaluated again, so the restart pushes with the force where the point is.

  • vibe-view calls the force threshold tolerance inside its loop and fmax at its request boundary; this module says fmax throughout.

  • vibe-view’s step cap bounds each atom’s displacement; the cap here bounds each coordinate, since this minimiser does not know how coordinates group into atoms.

The function to minimise returns the energy and its gradient; the force is the negative gradient. Units are the caller’s, and the time step is a numerical relaxation parameter, not a physical time: velocity Verlet is stable only while dt_max stays below twice the inverse of the stiffest mode’s angular frequency, so a stiff objective wants a smaller dt and dt_max than the defaults. Nothing is random, so a run repeats exactly.

Module Attributes

Objective

the energy at x and its gradient, in the shape of x.

Callback

Called after every step with the step count, a copy of x and the energy.

Functions

minimize(fun, x0, *, fmax, max_steps[, dt, ...])

Minimise fun from x0 with FIRE.

Classes

FireResult(x, energy, gradient, fmax, steps, ...)

Where FIRE stopped.
class vibesketch.chem.fire.FireResult(x, energy, gradient, fmax, steps, evaluations, converged, message)[source]

Bases: object

Where FIRE stopped.

Parameters:

  • x (NDArray[float64])

  • energy (float)

  • gradient (NDArray[float64])

  • fmax (float)

  • steps (int)

  • evaluations (int)

  • converged (bool)

  • message (str)

x: NDArray[float64]

The coordinates, in the shape of x0.

energy: float

The energy at x.

gradient: NDArray[float64]

The gradient at x, in the shape of x0.

fmax: float

The largest force component on a free coordinate at x.

steps: int

Integration steps taken.

evaluations: int

one at the start, one per step and one after each half step back.

Type:

Evaluations of the objective

converged: bool

Whether fmax reached the requested threshold.

message: str

converged, max_steps or stuck.

Type:

Why it stopped

vibesketch.chem.fire.minimize(fun, x0, *, fmax, max_steps, dt=0.1, dt_max=1.0, dt_min=None, alpha_start=0.1, n_delay=5, f_inc=1.1, f_dec=0.5, f_alpha=0.99, max_step=0.1, max_uphill=2000, fixed=None, constrain=None, callback=None)[source]

Minimise fun from x0 with FIRE.

fun(x) returns the energy and its gradient in the shape of x. The run stops, converged, once no free coordinate feels a force larger than fmax; otherwise after max_steps steps, or stuck once max_uphill consecutive steps went uphill.

dt is the first time step. It grows by f_inc up to dt_max after n_delay consecutive downhill steps and shrinks by f_dec down to dt_min, by default a fiftieth of dt, on an uphill step. The velocity is mixed towards the force by alpha, which starts at alpha_start, decays by f_alpha with the time step’s growth and restarts with it. max_step caps how far any coordinate moves in one step, or None leaves the step uncapped; an uphill restart first takes back half of the previous step.

fixed marks coordinates that must not move, as booleans in the shape of x0; they feel no force and count for neither the stopping rule nor fmax. constrain puts coordinates back where the caller’s constraints hold: it is called with x0 and after every move, and returns the corrected coordinates, whose displacement joins the velocity as in SHAKE (J.-P. Ryckaert, G. Ciccotti and H. J. C. Berendsen, J. Comput. Phys. 23, 327-341 (1977)); the caller’s fun then returns the gradient projected onto those constraints, so the stopping rule sees only the forces that can still move the point. callback is called after every step with the step count, a copy of x and the energy there.

Raises ValueError for an impossible setting, a gradient of the wrong shape or an energy or gradient that is not finite.

Parameters:
Return type:

FireResult