pycif.plugins.minimizers.m1qn3 — API reference

pycif.plugins.minimizers.m1qn3 — API reference#

Configuration reference: m1qn3 plugin

pycif.plugins.minimizers.m1qn3.aux.mlis0(self, xn, fn, fpn, t, tmin, tmax, d, g, amd, amf, imp, io, nap, napmax, niter, **kwargs)[source]#

Wolfe line search for M1QN3 (cubic interpolation with safeguards).

Finds a step t satisfying the Wolfe conditions starting from xn along descent direction d. Uses systematic cubic interpolation and a progressively shrinking barrier (barr) to prevent overshoots.

Parameters:

  • self (Plugin) – M1QN3 plugin instance (provides the simulator).

  • xn (np.ndarray) – current iterate, shape (n,).

  • fn (float) – function value at xn.

  • fpn (float) – directional derivative at xn (must be < 0).

  • t (float) – initial step-length trial.

  • tmin (float) – minimum acceptable step length.

  • tmax (float) – maximum acceptable step length.

  • d (np.ndarray) – descent direction, shape (n,).

  • g (np.ndarray) – gradient at xn, shape (n,); updated on exit.

  • amd (float) – sufficient-curvature (Wolfe) parameter (0 < amf < amd < 1).

  • amf (float) – sufficient-decrease (Armijo) parameter.

  • imp (int) – verbosity level.

  • io (int) – log-file unit (unused in Python version).

  • nap (int) – simulator call counter on entry; incremented on exit.

  • napmax (int) – maximum number of simulator calls allowed.

  • niter (int) – current iteration count (for logging only).

  • **kwargs – forwarded to the simulator.

Returns:

(xn, fn, g, nap, logic)

  • xn (np.ndarray): accepted point.

  • fn (float): function value at the accepted point.

  • g (np.ndarray): gradient at the accepted point.

  • nap (int): updated simulator call counter.

  • logic (int): exit code — 0 = serious step accepted, 1 = step blocked, 4 = simulator call limit reached, 5 = user-requested return, 6 = function/gradient inconsistency on entry. < 0 = implicit constraint activated

Return type:

tuple

pycif.plugins.minimizers.m1qn3.aux.descentdir(n, sscale, nm, depl, jmin, jmax, precos, diag, alpha, ybar, sbar)[source]#

Apply the inverse L-BFGS two-loop recursion (H·g product).

Computes the product of the approximate inverse Hessian H with a vector depl (typically the gradient) using the L-BFGS two-loop recursion (Nocedal, 1980). H is constructed from nm stored curvature pairs (ybar, sbar) and a diagonal preconditioner diag.

Reference: Nocedal (1980), Updating Quasi-Newton Matrices with Limited Storage, Mathematics of Computation 35/151, 773–782.

Parameters:

  • n (int) – dimension of the problem.

  • sscale (bool) – True for scalar initial scaling (SIS), False for diagonal initial scaling (DIS).

  • nm (int) – number of stored L-BFGS memory pairs.

  • depl (np.ndarray) – input vector g; overwritten with H·g on exit, shape (n,).

  • jmin (int) – index of oldest stored pair.

  • jmax (int) – index of most recent stored pair.

  • precos (float) – scalar preconditioner (used in SIS mode).

  • diag (np.ndarray) – diagonal preconditioner, shape (n,).

  • alpha (np.ndarray) – work array, shape (nm,).

  • ybar (np.ndarray) – stored gradient differences, shape (n, 10).

  • sbar (np.ndarray) – stored iterate differences, shape (n, 10).

Returns:

depl updated in-place to H·g.

Return type:

np.ndarray

pycif.plugins.minimizers.m1qn3.aux.ecube(t, f, fp, ta, fa, fpa, tlower, tupper)[source]#

Compute a safeguarded cubic interpolation step.

Given function values and derivatives at two points t and ta, fits a cubic polynomial and returns its minimiser clamped to [tlower, tupper].

Parameters:

  • t (float) – current trial step.

  • f (float) – function value at t.

  • fp (float) – derivative at t.

  • ta (float) – previous trial step.

  • fa (float) – function value at ta.

  • fpa (float) – derivative at ta.

  • tlower (float) – lower bound for the new step.

  • tupper (float) – upper bound for the new step.

Returns:

new safeguarded cubic-interpolation step in [tlower, tupper].

Return type:

float

pycif.plugins.minimizers.m1qn3.check.check_options(self, chi, finit, **kwargs)[source]#

Validate M1QN3 parameters and initialise the working zone.

Reads convergence parameters from the plugin instance (falling back to maxiter when niter/nsim are absent), validates their ranges, detects warm vs cold start from the mode flag, and writes the resolved values back to self so that m1qn3 can read them.

Parameters:

  • self (Plugin) –

    M1QN3 minimizer plugin instance. The following attributes are read (with defaults where noted):

    • niter / nsim — explicit iteration/simulation limits; if absent, both are derived from maxiter.

    • nupdates (int, default 5) — number of L-BFGS memory pairs.

    • dxmin (float, default 1e-20) — absolute precision on x.

    • epsg (float, default 1e-20) — relative precision on the gradient.

    • mode (int, default 0) — scaling and restart mode.

    • df1 (float, default 0.01) — expected fractional decrease of f.

    • iz (np.ndarray[int], default zeros(6)) — warm-start working zone.

  • chi (np.ndarray) – initial iterate \(\chi_0\), used only to read its dimension.

  • finit (float) – initial cost value; used to scale df1.

  • **kwargs – unused; accepted for interface consistency.

Returns:

self with all resolved parameters written back as attributes.

Return type:

Plugin

Raises:

ValueError – if any parameter is outside its valid range, or if a warm restart is requested with an inconsistent iz vector.

pycif.plugins.minimizers.m1qn3.minimize.minimize(self, finit, gradinit, chi0, **kwargs)[source]#

Run the M1QN3 L-BFGS minimisation and return the optimal iterate.

Parameters:

  • self (Plugin) – M1QN3 minimizer plugin instance.

  • finit (float) – initial cost function value \(J(\chi_0)\).

  • gradinit (np.ndarray) – initial gradient \(\nabla J(\chi_0)\), shape (n,).

  • chi0 (np.ndarray) – initial iterate \(\chi_0\), shape (n,).

  • **kwargs – forwarded to the simulator.

Returns:

optimal iterate \(\chi_\mathrm{opt}\), shape (n,).

Return type:

np.ndarray

pycif.plugins.minimizers.m1qn3.opt.m1qn3(self, f, g, chi, **kwargs)[source]#

Execute the M1QN3 L-BFGS main loop.

Runs the limited-memory quasi-Newton iterations until the gradient convergence criterion or the iteration/simulation limit is reached. At each step, the descent direction is computed from the L-BFGS two-loop recursion and a step length is found by the mlis0 Wolfe line search.

Parameters:

  • self (Plugin) – M1QN3 minimizer plugin instance with all parameters already resolved by check_options (niter, nsim, epsg, dxmin, df1, nupdates, mode, iz).

  • f (float) – initial cost function value.

  • g (np.ndarray) – initial gradient, shape (n,).

  • chi (np.ndarray) – initial iterate, shape (n,).

  • **kwargs – forwarded to the simulator.

Returns:

(xopt, fopt, gradopt, niter, nsim, epsg, mode)

  • xopt (np.ndarray): optimal iterate.

  • fopt (float): cost at xopt.

  • gradopt (np.ndarray): gradient at xopt.

  • niter (int): number of iterations performed.

  • nsim (int): number of simulator calls performed.

  • epsg (float): achieved relative gradient precision.

  • mode (int): exit mode (0 = converged on gradient, 1 = converged on x, 4 = iteration limit, 5 = simulation limit).

Return type:

tuple

Note

Wolfe parameter rm2 is set to 0.99 (since version 2.0d, July 1996) to accelerate step acceptance in the line search.