From 0f8ccc83b13fefd33de942420620b9dd7fe8e1ce Mon Sep 17 00:00:00 2001 From: sebapersson Date: Fri, 11 Apr 2025 10:02:37 +0100 Subject: [PATCH 1/2] Minor doc updates --- README.md | 2 +- docs/src/index.md | 4 ++-- docs/src/tutorial.md | 12 ++++++------ src/problem.jl | 30 +++++++++++++++--------------- src/solve.jl | 4 ++-- 5 files changed, 26 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index e0544c9..1b2ca3b 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ [![codecov](https://codecov.io/gh/fides-dev/Fides.jl/graph/badge.svg?token=J7PXRF30JG)](https://codecov.io/gh/fides-dev/Fides.jl) [![SciML Code Style](https://img.shields.io/static/v1?label=code%20style&message=SciML&color=9558b2&labelColor=389826)](https://github.com/SciML/SciMLStyle) -Fides.jl is a Julia wrapper of the Python package [Fides.py](https://github.com/fides-dev/fides), which implements an Interior Trust Region Reflective for bounds constrained optimization problems based on [1, 2]. Fides targets problems on the form: +Fides.jl is a Julia wrapper of the Python package [Fides.py](https://github.com/fides-dev/fides), which implements an Interior Trust Region Reflective algorithm for bounds constrained optimization problems based on [1, 2]. Fides targets problems on the form: ```math \min_{x \in \mathbb{R}^n} f(x) \quad \mathrm{subject \ to} \quad \text{lb} \leq x \leq \text{ub} diff --git a/docs/src/index.md b/docs/src/index.md index 4c0024e..c46ddf8 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -1,6 +1,6 @@ # Fides.jl -Fides.jl is a Julia wrapper of the Python package [Fides.py](https://github.com/fides-dev/fides), which implements an Interior Trust Region Reflective for boundary costrained optimization problems based on [1, 2]. Fides targets problems on the form: +Fides.jl is a Julia wrapper of the Python package [Fides.py](https://github.com/fides-dev/fides), which implements an Interior Trust Region Reflective algorithm for boundary constrained optimization problems based on [1, 2]. Fides targets problems on the form: ```math \min_{x \in \mathbb{R}^n} f(x) \quad \mathrm{subject \ to} \quad lb \leq x \leq ub @@ -13,7 +13,7 @@ Where `f` is a continues at least twice-differentaible function, and `lb` and `u - Boundary-constrained interior trust-region optimization. - Recursive reflective and truncated constraint management. - Full and 2D subproblem solution solvers. -- Supports used provided HEssian, and BFGS, DFP, and SR1 Hessian approximations. +- Supports used provided Hessian, and BFGS, DFP, and SR1 Hessian approximations. - Good performance for parameter estimating Ordinary Differential Equation models [3]. !!! note "Star us on GitHub!" diff --git a/docs/src/tutorial.md b/docs/src/tutorial.md index 8b18784..f537570 100644 --- a/docs/src/tutorial.md +++ b/docs/src/tutorial.md @@ -1,6 +1,6 @@ # Tutorial -This overarching tutorial describes how to minimize an objective function with Fides. It further provides performance tips for computationally intensive objective functions. +This overarching tutorial describes how to solve an optimization problem with Fides. It further provides performance tips for computationally intensive objective functions. ## Input - a Function to Minimize @@ -32,7 +32,7 @@ Both the gradient and Hessian functions are expected to be in-place on the form; ## Optimization with a Hessian Approximation -Given an objective function and its gradient, the optimization is performed in a two-step procedure. First, a `FidesProblem` is created. When the Hessian is unavailable or too expensive to compute, a Hessian approximation is chosen during this step: +Given an objective function and its gradient, the optimization is performed in a two-step procedure. First, a `FidesProblem` is created. ```@example 1 using Fides @@ -42,14 +42,14 @@ x0 = [ 2.0, 2.0] prob = FidesProblem(f, grad!, x0; lb = lb, ub = ub) ``` -Where `x0` is the initial guess for parameter estimation, and `lb` and `ub` are the lower and upper parameter bounds (defaulting to `-Inf` and `Inf` if unspecified). The problem is then minimized by calling `solve`: +Where `x0` is the initial guess for parameter estimation, and `lb` and `ub` are the lower and upper parameter bounds (defaulting to `-Inf` and `Inf` if unspecified). The problem is then minimized by calling `solve`, and when the Hessian is unavailable or too expensive to compute, a Hessian approximation is chosen during this step: ```@example 1 sol = solve(prob, Fides.BFGS()) # hide sol = solve(prob, Fides.BFGS()) ``` -Here, the second argument is the Hessian approximation. Several approximations are supported (see the [API](@ref API)), and `BFGS` generally performs well. Additional tuning options can be set by providing a [`FidesOptions`](@ref) struct via the `options` keyword in `solve`, and a full list of available options is documented in the [API](@ref API). +Several Hessian approximations are supported (see the [API](@ref API)), and of these `BFGS` generally performs well. Additional tuning options can be set by providing a [`FidesOptions`](@ref) struct via the `options` keyword in `solve`, and a full list of available options is documented in the [API](@ref API). ## Optimization with a User-Provided Hessian @@ -65,7 +65,7 @@ Since a Hessian function is provided, no Hessian approximation needs to be speci ## Performance tip: Computing Derivatives and Objective Simultaneously -Internally, the objective function and its derivatives are computed simultaneously by Fides. Hence, runtime can be reduced if intermediate quantities are reused between the objective and derivative computations. To take advantage of this, a `FidesProblem` can be created with a function that computes the objective and gradient (and optionally the Hessian) for a given `Vector`. For example, when only the gradient is available: +Internally, the objective function and its derivatives are computed simultaneously by Fides. Hence, runtime can be reduced if intermediate quantities are reused between the objective and derivative computations. To take advantage of this, a `FidesProblem` can be created with a function that computes the objective and gradient (and optionally the Hessian) for a given input. For example, when only the gradient is available: ```@example 1 function fides_obj(x) @@ -96,4 +96,4 @@ sol = solve(prob) # hide sol = solve(prob) ``` -In this simple example, no runtime benefit is obtained as not quantities are reused. However, if quantities can be reused (for example, when gradients are computed for ODE models), runtime can be noticeably reduced. +In this simple example, no runtime benefit is obtained as not quantities are reused between objective and derivative computations. However, if quantities can be reused (for example, when gradients are computed for ODE models), runtime can be noticeably reduced. diff --git a/src/problem.jl b/src/problem.jl index 1f5beb2..3bd8828 100644 --- a/src/problem.jl +++ b/src/problem.jl @@ -4,7 +4,8 @@ Optimization problem to be minimized with the Fides Newton Trust Region optimizer. ## Arguments -- `f`: The objective function to minimize. Accepts a vector as input and return a scalar. +- `f`: The objective function to minimize. Accepts a `Vector` or `ComponentVector` as input + and return a scalar. - `grad!`: In-place function to compute the gradient of `f` on the form `grad!(g, x)`. - `x0`: Initial starting point for the optimization. Can be a `Vector` or `ComponentVector` from [ComponentArrays.jl](https://github.com/SciML/ComponentArrays.jl). @@ -16,6 +17,16 @@ Optimization problem to be minimized with the Fides Newton Trust Region optimize See also [solve](@ref) and [FidesOptions](@ref). + FidesProblem(fides_obj, x0, hess::Bool; lb = nothing, ub = nothing) + +Optimization problem created from a function that computes: +- `hess = false`: Objective and gradient; `fides_obj(x) -> (obj, g)`. +- `hess = true`: Objective, gradient and Hessian; `fides_obj(x) -> (obj, g, H)`. + +Internally, Fides computes the objective function and derivatives simultaneously. Therefore, +this constructor is the most runtime-efficient option when intermediate quantities can be +reused between the objective and derivative computations. + ## Description of Fides method Fides implements an Interior Trust Region Reflective method for boundary-constrained @@ -34,9 +45,9 @@ At each iteration, the Fides approximates the objective function by a second-ord ``` Where, `Δₖ` is the trust region radius reflecting the confidence in the second-order -approximation, `∇f(xₖ)` of `f` at the current iteration `xₖ`, and `Bₖ` is a symmetric -positive-semidefinite matrix, that is either the exact Hessian (if `hess!` is provided) or -an approximation. +approximation, `∇f(xₖ)` is the gradient of `f` at the current iteration `xₖ`, and `Bₖ` is a +symmetric positive-semidefinite matrix, that is either the exact Hessian (if `hess!` is +provided) or an approximation. ## References 1. Coleman, T. F., & Li, Y. (1994). On the convergence of interior-reflective Newton @@ -65,17 +76,6 @@ function FidesProblem(f::Function, grad!::Function, x0::InputVector; hess! = not user_hessian = !isnothing(hess!) return FidesProblem(fides_objective, fides_objective_py, x0, _lb, _ub, user_hessian) end -""" - FidesProblem(fides_obj, x0, hess::Bool; lb = nothing, ub = nothing) - -Optimization problem created from a function that computes: -- `hess = false`: Objective and gradient; `fides_obj(x) -> (obj, g)`. -- `hess = true`: Objective, gradient and Hessian; `fides_obj(x) -> (obj, g, H)`. - -Internally, Fides computes the objective function and derivatives simultaneously. Therefore, -this constructor is the most runtime-efficient option when intermediate quantities can be -reused between the objective and derivative computations. -""" function FidesProblem(fides_objective::Function, x0::InputVector, hess::Bool; lb = nothing, ub = nothing) _lb = _get_bounds(x0, lb, :lower) diff --git a/src/solve.jl b/src/solve.jl index 3164e9b..d4c0432 100644 --- a/src/solve.jl +++ b/src/solve.jl @@ -31,9 +31,9 @@ end solve(prob::FidesProblem, hess_approximation; options = FidesOptions()) Solve the given `FidesProblem` using the Fides Trust Region method, with the specified -`hess_approximation` to approximate the Hessian matrix. +`hess_approximation` method for approximating the Hessian matrix. -A complete list of available Hessian approximations is provided in the documentation. +A complete list of available Hessian approximations can be found in the API documentation. See also [FidesOptions](@ref). """ From b8175ea933f794212da69a05826078a0709b2225 Mon Sep 17 00:00:00 2001 From: sebapersson Date: Fri, 11 Apr 2025 10:07:54 +0100 Subject: [PATCH 2/2] Update JuliaFormatter --- test/problem.jl | 2 +- test/show.jl | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/test/problem.jl b/test/problem.jl index 5b56859..350a32b 100644 --- a/test/problem.jl +++ b/test/problem.jl @@ -15,7 +15,7 @@ function fides_obj2(x) return (f, g, H) end -x0, lb, ub, = [2.0, 2.0], [-10.0, -10.0], [10.0, 10.0] +x0, lb, ub = [2.0, 2.0], [-10.0, -10.0], [10.0, 10.0] @testset "FidesProblem" begin prob1 = FidesProblem(rosenbrock, rosenbrock_grad!, x0; lb = lb, ub = ub) sol1 = solve(prob1, Fides.BFGS()) diff --git a/test/show.jl b/test/show.jl index 1558aa0..98154bd 100644 --- a/test/show.jl +++ b/test/show.jl @@ -2,7 +2,7 @@ using Fides, Printf, Test include(joinpath(@__DIR__, "common.jl")) -x0, lb, ub, = [2.0, 2.0], [-10.0, -10.0], [10.0, 10.0] +x0, lb, ub = [2.0, 2.0], [-10.0, -10.0], [10.0, 10.0] prob = FidesProblem(rosenbrock, rosenbrock_grad!, x0; lb = lb, ub = ub) sol = solve(prob, Fides.BFGS())