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 #
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 #
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 #
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 #
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 #
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 #
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.
- README
- fn newton
- fn newton_bisection
- fn BFGS.new
- fn BFGS.new_with_params
- fn BFGSStatus.from
- fn Bisection.new
- fn Brent.new
- fn Brent.new_with_params
- fn BrentMinimizer.new
- fn BrentMinimizer.new_with_params
- fn BrentStatus.from
- fn GoldenSection.new
- fn GoldenSection.new_with_params
- fn MinimizeStatus.from
- fn NelderMead.new
- fn NelderMead.new_with_params
- fn NelderMeadStatus.from
- type MultivariateGradientFn
- enum BFGSStatus
- enum BrentStatus
- enum MinimizeStatus
- enum NelderMeadStatus
- struct BFGS
- struct BFGSParams
- struct BFGSResult
- struct Bisection
- struct BisectionIteration
- struct BisectionParams
- struct Brent
- struct BrentIteration
- struct BrentMinimizer
- struct BrentMinimizerIteration
- struct BrentMinimizerParams
- struct BrentParams
- struct GoldenSection
- struct GoldenSectionIteration
- struct GoldenSectionParams
- struct NelderMead
- struct NelderMeadParams
- struct NelderMeadResult