Skip to content

roots #

vsl.roots

Root-finding and minimization routines in vsl.roots accept callbacks from vsl.func. Current public APIs include:

API Method Notes
newton(f, x0, x_eps, fx_eps, n_max) Newton iteration Uses a function and derivative callback (FnFdf).
newton_bisection(f, x_min, x_max, tol, max_iter) Newton with bisection safeguard Requires a bracket and derivative callback.
Bisection.new(f, params).solve() Bisection Requires a sign-changing interval; returns the last iteration or the limit result.
Brent.new_with_params(f, params).solve() Brent's method Returns root, final bracket, residual, counts, and a termination status.
NelderMead.new_with_params(f, params).solve() Nelder-Mead minimization Derivative-free local minimization for multivariate scalar objectives.
BFGS.new_with_params(f, gradient, params).solve() BFGS minimization Analytic-gradient local minimization with an Armijo line search.
GoldenSection.new_with_params(f, params).solve() Golden-section minimization Bounded unimodal scalar minimizer.
BrentMinimizer.new_with_params(f, params).solve() Brent minimization Safeguarded scalar minimizer.

BisectionParams configures bounds, relative and absolute tolerances, and the iteration limit. Bisection.next() exposes individual steps. BrentParams configures the bracket, tolerance, iteration limit, and function-evaluation limit. A valid bracket is required. The solver reports .converged, .invalid_bracket, .max_iterations, .max_evaluations, or .non_finite_function_value, or .precision_limit in its result; invalid parameter values return an error. error_bound is the maximum distance from the reported estimate to either end of the final bracket, so it bounds the estimate's distance to any root still enclosed by that bracket. A precision limit means floating-point spacing prevents the requested tolerance from being reached.

NelderMeadParams configures the initial point, a positive step applied to each simplex axis in turn, absolute coordinate and objective tolerances, and iteration/evaluation limits. The evaluation limit must allow the initial n+1 simplex vertices. The result reports the best point, objective value, maximum coordinate spread, objective spread, counts, and termination status. Nelder-Mead is derivative-free and has no bounds or global-optimum guarantee; it is most appropriate for low-dimensional local optimization.

BFGSParams configures the initial point, gradient-norm tolerance, initial line-search step, iteration/evaluation limits, and maximum backtracking trials. The gradient callback must return a finite vector with the same length as the input and receives the objective's FnND parameters. The result reports the accepted point, objective, gradient norm, objective and gradient callback counts, and termination status. The dense inverse Hessian uses O(n²) storage. BFGS has no bounds or global-optimum guarantee.

GoldenSectionParams configures the minimizer's bounds, absolute tolerance, iteration limit, and callback evaluation limit. It assumes the objective is unimodal over the full interval; it does not search for multiple local minima. The result reports the best finite point observed, the final interval, its maximum distance from that point, iteration and evaluation counts, and a termination status. The function is evaluated only at interior points. A precision-limit status also reports when adjacent objective values are indistinguishable at floating-point precision, so the solver cannot safely narrow the interval. It can have a NaN fx and zero evaluations when no representable interior point exists.

BrentMinimizerParams exposes the same bounds, absolute tolerance, iteration, and evaluation limits. Brent minimization uses parabolic interpolation when the proposed step is safe and falls back to golden-section steps otherwise. Like Golden-section minimization, it assumes a unimodal objective and reports the best observed point, final interval, maximum distance to either endpoint, counts, and termination status.

import math
import vsl.func
import vsl.roots

fn objective(x f64, _ []f64) f64 {
    return math.cos(x)
}

f := func.Fn.new(f: objective)
mut solver := roots.Bisection.new(f, roots.BisectionParams{
    xmin: 0.0
    xmax: 3.0
})
result := solver.solve() or { panic('root was not found') }
println(result.x)

Brent returns convergence diagnostics without requiring a derivative:

import math
import vsl.func
import vsl.roots

fn objective(x f64, _ []f64) f64 {
    return math.cos(x)
}

f := func.Fn.new(f: objective)
mut solver := roots.Brent.new_with_params(f, roots.BrentParams{
    x1:  0.0
    x2:  3.0
    tol: 1e-10
})
result := solver.solve()!
println('status=${result.status} root=${result.x} residual=${result.fx}')
println('bracket=[${result.lower}, ${result.upper}] evaluations=${result.n_calls}')

Nelder-Mead minimizes multivariate objectives without derivative callbacks:

import vsl.func
import vsl.roots

fn objective(x []f64, _ []f64) f64 {
    a := 1.0 - x[0]
    b := x[1] - x[0] * x[0]
    return a * a + 100.0 * b * b
}

f := func.FnND.new(objective)
mut optimizer := roots.NelderMead.new_with_params(f, roots.NelderMeadParams{
    x0:           [-1.2, 1.0]
    initial_step: 0.5
    x_tol:        1e-6
    f_tol:        1e-12
    n_max:        2000
    max_evals:    5000
})
result := optimizer.solve()!
println('status=${result.status}, x=${result.x}, f(x)=${result.fx}')
println('spreads=(${result.x_spread}, ${result.f_spread}), evaluations=${result.n_calls}')

See the Nelder-Mead example and the multivariate minimization guide.

BFGS uses an explicit gradient callback:

import vsl.func
import vsl.roots

fn rosenbrock(x []f64, _ []f64) f64 {
    a := 1.0 - x[0]
    b := x[1] - x[0] * x[0]
    return a * a + 100.0 * b * b
}

fn rosenbrock_gradient(x []f64, _ []f64) []f64 {
    b := x[1] - x[0] * x[0]
    return [2.0 * (x[0] - 1.0) - 400.0 * x[0] * b, 200.0 * b]
}

objective := func.FnND.new(rosenbrock)
mut optimizer := roots.BFGS.new_with_params(objective, rosenbrock_gradient,
    roots.BFGSParams{
        x0:           [-1.2, 1.0]
        gradient_tol: 1e-6
        n_max:        1000
        max_evals:    5000
    })
result := optimizer.solve()!
println('status=${result.status}, x=${result.x}, f(x)=${result.fx}')

See the BFGS example.

Golden-section minimization reports bounded execution diagnostics:

import vsl.func
import vsl.roots

fn objective(x f64, _ []f64) f64 {
    return (x - 1.25) * (x - 1.25)
}

f := func.Fn.new(f: objective)
mut minimizer := roots.GoldenSection.new_with_params(f, roots.GoldenSectionParams{
    xmin:      -5.0
    xmax:      5.0
    tol:       1e-8
    n_max:     100
    max_evals: 104
})
result := minimizer.solve()!
println('status=${result.status} x=${result.x} f(x)=${result.fx}')
println('interval=[${result.lower}, ${result.upper}] evaluations=${result.n_calls}')

Brent minimization uses the same objective and reports its termination diagnostics:

import vsl.func
import vsl.roots

fn objective(x f64, _ []f64) f64 {
    return (x - 1.25) * (x - 1.25)
}

f := func.Fn.new(f: objective)
mut minimizer := roots.BrentMinimizer.new_with_params(f, roots.BrentMinimizerParams{
    xmin:      -5.0
    xmax:      5.0
    tol:       1e-8
    n_max:     100
    max_evals: 102
})
result := minimizer.solve()!
println('status=${result.status} x=${result.x} f(x)=${result.fx}')
println('interval=[${result.lower}, ${result.upper}] evaluations=${result.n_calls}')

See the bisection example, the Brent example, the Nelder-Mead example, the Golden-section example, the Brent minimization example, bisection.v, and newton.v.

fn newton #

fn newton(f func.FnFdf, x0 f64, x_eps f64, fx_eps f64, n_max int) !f64

Find the root of a function using Newton's algorithm with the Armijo line search to ensure the absolute value of the function decreases along the iterations.

fn newton_bisection #

fn newton_bisection(f func.FnFdf, x_min f64, x_max f64, tol f64, max_iter int) !f64

Find the root of a function by combining Newton's method with the bisection method

fn BFGS.new #

fn BFGS.new(f func.FnND, gradient MultivariateGradientFn) &BFGS

BFGS.new creates an optimizer with default tolerances and limits. Set x0 before calling solve, or use new_with_params.

fn BFGS.new_with_params #

fn BFGS.new_with_params(f func.FnND, gradient MultivariateGradientFn, params BFGSParams) &BFGS

BFGS.new_with_params creates a configured optimizer.

fn BFGSStatus.from #

fn BFGSStatus.from[W](input W) !BFGSStatus

from returns the BFGSStatus value of an integer or of a field name, or an error if there is none.

fn Bisection.new #

fn Bisection.new(f func.Fn, params BisectionParams) &Bisection

Bisection.new creates a new Bisection object with the given parameters

fn Brent.new #

fn Brent.new(f func.Fn) &Brent

Brent.new creates a Brent solver with default tolerances and limits. Set x1 and x2 before calling solve, or use Brent.new_with_params.

fn Brent.new_with_params #

fn Brent.new_with_params(f func.Fn, params BrentParams) &Brent

Brent.new_with_params creates a configured Brent solver.

fn BrentMinimizer.new #

fn BrentMinimizer.new(f func.Fn) &BrentMinimizer

BrentMinimizer.new creates a minimizer with default tolerances and limits. Set xmin and xmax before calling solve, or use new_with_params.

fn BrentMinimizer.new_with_params #

fn BrentMinimizer.new_with_params(f func.Fn, params BrentMinimizerParams) &BrentMinimizer

BrentMinimizer.new_with_params creates a configured minimizer.

fn BrentStatus.from #

fn BrentStatus.from[W](input W) !BrentStatus

from returns the BrentStatus value of an integer or of a field name, or an error if there is none.

fn GoldenSection.new #

fn GoldenSection.new(f func.Fn) &GoldenSection

GoldenSection.new creates a minimizer with default tolerances and limits. Set xmin and xmax before calling solve, or use new_with_params.

fn GoldenSection.new_with_params #

fn GoldenSection.new_with_params(f func.Fn, params GoldenSectionParams) &GoldenSection

GoldenSection.new_with_params creates a configured minimizer.

fn MinimizeStatus.from #

fn MinimizeStatus.from[W](input W) !MinimizeStatus

from returns the MinimizeStatus value of an integer or of a field name, or an error if there is none.

fn NelderMead.new #

fn NelderMead.new(f func.FnND) &NelderMead

NelderMead.new creates an optimizer with default tolerances and limits. Set x0 before calling solve, or use new_with_params.

fn NelderMead.new_with_params #

fn NelderMead.new_with_params(f func.FnND, params NelderMeadParams) &NelderMead

NelderMead.new_with_params creates a configured optimizer.

fn NelderMeadStatus.from #

fn NelderMeadStatus.from[W](input W) !NelderMeadStatus

from returns the NelderMeadStatus value of an integer or of a field name, or an error if there is none.

type MultivariateGradientFn #

type MultivariateGradientFn = fn (x []f64, params []f64) []f64

MultivariateGradientFn evaluates the gradient of an FnND objective.

enum BFGSStatus #

enum BFGSStatus {
	converged
	max_iterations
	max_evaluations
	line_search_failed
	non_finite_function_value
	invalid_gradient
	precision_limit
}

BFGSStatus reports why the optimizer stopped.

enum BrentStatus #

enum BrentStatus {
	converged
	invalid_bracket
	max_iterations
	max_evaluations
	non_finite_function_value
	precision_limit
}

BrentStatus reports why a Brent solver stopped.

enum MinimizeStatus #

enum MinimizeStatus {
	converged
	max_iterations
	max_evaluations
	non_finite_function_value
	precision_limit
}

MinimizeStatus reports why a bounded minimizer stopped.

enum NelderMeadStatus #

enum NelderMeadStatus {
	converged
	max_iterations
	max_evaluations
	non_finite_function_value
	precision_limit
}

NelderMeadStatus reports why the optimizer stopped.

struct BFGS #

struct BFGS {
pub:
	f        func.FnND              @[required]
	gradient MultivariateGradientFn @[required]
pub mut:
	x0             []f64
	gradient_tol   f64
	initial_step   f64
	n_max          int
	max_evals      int
	max_linesearch int
	n_calls        int
	n_grad_calls   int
	n_iter         int
mut:
	gradient_params []f64
}

BFGS minimizes a differentiable scalar objective over an n-dimensional input.

fn (BFGS) solve #

fn (mut solver BFGS) solve() !BFGSResult

solve minimizes the objective with inverse-Hessian BFGS and an Armijo backtracking line search. Invalid parameters return errors; callback failures and execution limits are reported in the result.

struct BFGSParams #

@[params]
struct BFGSParams {
pub:
	x0             []f64
	gradient_tol   f64 = 1e-6
	initial_step   f64 = 1.0
	n_max          int = 200
	max_evals      int = 1000
	max_linesearch int = 25
}

BFGSParams configures inverse-Hessian BFGS minimization.

struct BFGSResult #

struct BFGSResult {
pub:
	x             []f64
	fx            f64
	gradient_norm f64
	n_calls       int
	n_grad_calls  int
	n_iter        int
	status        BFGSStatus
}

BFGSResult contains the best accepted point and convergence diagnostics.

struct Bisection #

struct Bisection {
	f func.Fn @[required]
mut:
	last_iter ?&BisectionIteration // last iteration
pub mut:
	xmin      f64 // lower bound
	xmax      f64 // upper bound
	epsrel    f64 // relative error tolerance
	epsabs    f64 // absolute error tolerance
	n_max     int // maximum number of iterations
	n_f_calls int // number of function calls
	n_iter    int // number of iterations
}

Bisection implements a bisection method for finding the root of a function

fn (Bisection) next #

fn (mut solver Bisection) next() ?&BisectionIteration

next returns the next iteration of the bisection method.

fn (Bisection) solve #

fn (mut solver Bisection) solve() ?&BisectionIteration

solve solves for the root of the function using the bisection method.

struct BisectionIteration #

struct BisectionIteration {
pub mut:
	x         f64
	fx        f64
	n_f_calls int
	n_iter    int
}

BisectionIteration defines a public data structure for this module.

struct BisectionParams #

@[params]
struct BisectionParams {
pub:
	xmin   f64
	xmax   f64
	epsrel f64 = 1e-6
	epsabs f64 = 1e-6
	n_max  int = 100
}

BisectionParams defines a public data structure for this module.

struct Brent #

struct Brent {
pub:
	f func.Fn @[required]
pub mut:
	x1        f64
	x2        f64
	tol       f64
	n_max     int
	max_evals int
	n_calls   int
	n_iter    int
}

Brent implements Brent's method for finding a root in [x1, x2]. The function must be continuous and the interval must bracket a root.

fn (Brent) solve #

fn (mut solver Brent) solve() !BrentIteration

solve finds a root in the configured bracket and returns its diagnostics. A non-converged termination is returned in result.status; invalid solver parameters are returned as errors.

struct BrentIteration #

struct BrentIteration {
pub:
	x           f64
	fx          f64
	lower       f64
	upper       f64
	error_bound f64
	n_calls     int
	n_iter      int
	status      BrentStatus
}

BrentIteration is the final root estimate and convergence diagnostics.

struct BrentMinimizer #

struct BrentMinimizer {
pub:
	f func.Fn @[required]
pub mut:
	xmin      f64
	xmax      f64
	tol       f64
	n_max     int
	max_evals int
	n_calls   int
	n_iter    int
}

BrentMinimizer minimizes a unimodal scalar function over [xmin, xmax].

fn (BrentMinimizer) solve #

fn (mut solver BrentMinimizer) solve() !BrentMinimizerIteration

solve minimizes a unimodal function over the configured interval. A non-converged termination is returned in result.status; invalid parameters are returned as errors. The function is evaluated only at interior points.

struct BrentMinimizerIteration #

struct BrentMinimizerIteration {
pub:
	x           f64
	fx          f64
	lower       f64
	upper       f64
	error_bound f64
	n_calls     int
	n_iter      int
	status      MinimizeStatus
}

BrentMinimizerIteration is the best point and termination diagnostics.

struct BrentMinimizerParams #

@[params]
struct BrentMinimizerParams {
pub:
	xmin      f64
	xmax      f64
	tol       f64 = 1e-6
	n_max     int = 100
	max_evals int = 102
}

BrentMinimizerParams configures a bounded scalar minimizer.

struct BrentParams #

@[params]
struct BrentParams {
pub:
	x1        f64
	x2        f64
	tol       f64 = 1e-6
	n_max     int = 100
	max_evals int = 102
}

BrentParams configures a bracketed Brent root solver.

struct GoldenSection #

struct GoldenSection {
pub:
	f func.Fn @[required]
pub mut:
	xmin      f64
	xmax      f64
	tol       f64
	n_max     int
	max_evals int
	n_calls   int
	n_iter    int
}

GoldenSection minimizes a unimodal scalar function over [xmin, xmax].

fn (GoldenSection) solve #

fn (mut solver GoldenSection) solve() !GoldenSectionIteration

solve minimizes a unimodal function over the configured interval. A non-converged termination is returned in result.status; invalid parameters are returned as errors. The function is evaluated only at interior points.

struct GoldenSectionIteration #

struct GoldenSectionIteration {
pub:
	x           f64
	fx          f64
	lower       f64
	upper       f64
	error_bound f64
	n_calls     int
	n_iter      int
	status      MinimizeStatus
}

GoldenSectionIteration is the best observed point and termination diagnostics.

struct GoldenSectionParams #

@[params]
struct GoldenSectionParams {
pub:
	xmin      f64
	xmax      f64
	tol       f64 = 1e-6
	n_max     int = 100
	max_evals int = 104
}

GoldenSectionParams configures a bounded scalar minimizer.

struct NelderMead #

struct NelderMead {
pub:
	f func.FnND @[required]
pub mut:
	x0           []f64
	initial_step f64
	x_tol        f64
	f_tol        f64
	n_max        int
	max_evals    int
	n_calls      int
	n_iter       int
}

NelderMead minimizes a scalar objective over an n-dimensional input.

fn (NelderMead) solve #

fn (mut solver NelderMead) solve() !NelderMeadResult

solve minimizes a multivariate objective using the Nelder-Mead simplex method. Invalid parameters return errors; other termination reasons appear in the result. The initial simplex applies the same positive step along each coordinate axis, and convergence requires both coordinate and objective spreads to meet their absolute tolerances.

struct NelderMeadParams #

@[params]
struct NelderMeadParams {
pub:
	x0           []f64
	initial_step f64 = 1.0
	x_tol        f64 = 1e-8
	f_tol        f64 = 1e-8
	n_max        int = 200
	max_evals    int = 1000
}

NelderMeadParams configures derivative-free multivariate minimization.

struct NelderMeadResult #

struct NelderMeadResult {
pub:
	x        []f64
	fx       f64
	x_spread f64
	f_spread f64
	n_calls  int
	n_iter   int
	status   NelderMeadStatus
}

NelderMeadResult contains the best point and simplex convergence diagnostics.