Defining OptimizationProblems
SciMLBase.OptimizationProblem
— TypeSciMLBase.SciMLBase.OptimizationProblem(sys::System, op; kwargs...)
SciMLBase.SciMLBase.OptimizationProblem{iip}(sys::System, op; kwargs...)
SciMLBase.SciMLBase.OptimizationProblem{iip, specialize}(sys::System, op; kwargs...)
Build a SciMLBase.OptimizationProblem
given a system sys
and operating point op
. iip
is a boolean indicating whether the problem should be in-place. specialization
is a SciMLBase.AbstractSpecalize
subtype indicating the level of specialization of the SciMLBase.OptimizationFunction. The operating point should be an iterable collection of key-value pairs mapping variables/parameters in the system to the (initial) values they should take in SciMLBase.OptimizationProblem
. Any values not provided will fallback to the corresponding default (if present).
ModelingToolkit will build an initialization problem that will run parameter initialization. Since it does not solve for initial values of unknowns, observed equations will not be initialization constraints. If an initialization equation of the system must involve the initial value of an unknown x
, it must be used as Initial(x)
in the equation. For example, an equation to be used to solve for parameter p
in terms of unknowns x
and y
must be provided as Initial(x) + Initial(y) ~ p
instead of x + y ~ p
. See the Initialization documentation for more information.
Keyword arguments
eval_expression
: Whether to compile any functions viaeval
orRuntimeGeneratedFunctions
.eval_module
: Ifeval_expression == true
, the module toeval
into. Otherwise, the module in which to generate theRuntimeGeneratedFunction
.guesses
: The guesses for variables in the system, used as initial values for the initialization problem.warn_initialize_determined
: Warn if the initialization system is under/over-determined.initialization_eqs
: Extra equations to use in the initialization problem.fully_determined
: Override whether the initialization system is fully determined.use_scc
: Whether to useSCCNonlinearProblem
for initialization if the system is fully determined.check_initialization_units
: Enable or disable unit checks when constructing the initialization problem.tofloat
: Passed tovarmap_to_vars
when building the parameter vector of a non-split system.u0_eltype
: Theeltype
of theu0
vector. Ifnothing
, finds the promoted floating point type fromop
.u0_constructor
: A function to apply to theu0
value returned fromvarmap_to_vars
. to construct the finalu0
value.p_constructor
: A function to apply to each array buffer created when constructing the parameter object.warn_cyclic_dependency
: Whether to emit a warning listing out cycles in initial conditions provided for unknowns and parameters.circular_dependency_max_cycle_length
: Maximum length of cycle to check for. Only applicable ifwarn_cyclic_dependency == true
.circular_dependency_max_cycles
: Maximum number of cycles to check for. Only applicable ifwarn_cyclic_dependency == true
.substitution_limit
: The number times to substitute initial conditions into each other to attempt to arrive at a numeric value.
check_compatibility
: Whether to check if the given systemsys
contains all the information necessary to create aSciMLBase.OptimizationProblem
and no more. If disabled, assumes thatsys
at least contains the necessary information.expression
:Val{true}
to return anExpr
that constructs the corresponding problem instead of the problem itself.Val{false}
otherwise.
All other keyword arguments are forwarded to the SciMLBase.OptimizationFunction constructor.
Extended docs
The following API is internal and may change or be removed without notice. Its usage is highly discouraged.
build_initializeprob
: Iffalse
, avoids building the initialization problem.check_length
: Whether to check the number of equations along with number of unknowns and length ofu0
vector for consistency. Iffalse
, do not check with equations. This is forwarded tocheck_eqs_u0
.time_dependent_init
: Whether to build a time-dependent initialization for the problem. A time-dependent initialization solves for a consistentu0
, whereas a time-independent one only runs parameter initialization.algebraic_only
: Whether to build the initialization problem using only algebraic equations.allow_incomplete
: Whether to allow incomplete initialization problems.
Defines an optimization problem. Documentation Page: https://docs.sciml.ai/Optimization/stable/API/optimization_problem/
Mathematical Specification of an Optimization Problem
To define an optimization problem, you need the objective function $f$ which is minimized over the domain of $u$, the collection of optimization variables:
\[min_u f(u,p)\]
$u₀$ is an initial guess for the minimizer. f
should be specified as f(u,p)
and u₀
should be an AbstractArray
whose geometry matches the desired geometry of u
. Note that we are not limited to vectors for u₀
; one is allowed to provide u₀
as arbitrary matrices / higher-dimension tensors as well.
Problem Type
Constructors
OptimizationProblem{iip}(f, u0, p = SciMLBase.NullParameters(),;
lb = nothing,
ub = nothing,
lcons = nothing,
ucons = nothing,
sense = nothing,
kwargs...)
isinplace
optionally sets whether the function is in-place or not. This is determined automatically, but not inferred. Note that for OptimizationProblem, in-place refers to the objective's derivative functions, the constraint function and its derivatives. OptimizationProblem
currently only supports in-place.
Parameters p
are optional, and if not given, then a NullParameters()
singleton will be used, which will throw nice errors if you try to index non-existent parameters.
lb
and ub
are the upper and lower bounds for box constraints on the optimization variables. They should be an AbstractArray
matching the geometry of u
, where (lb[i],ub[i])
is the box constraint (lower and upper bounds) for u[i]
.
lcons
and ucons
are the upper and lower bounds in case of inequality constraints on the optimization and if they are set to be equal then it represents an equality constraint. They should be an AbstractArray
, where (lcons[i],ucons[i])
are the lower and upper bounds for cons[i]
.
The f
in the OptimizationProblem
should typically be an instance of OptimizationFunction
to specify the objective function and its derivatives either by passing predefined functions for them or automatically generated using the ADType.
If f
is a standard Julia function, it is automatically transformed into an OptimizationFunction
with NoAD()
, meaning the derivative functions are not automatically generated.
Any extra keyword arguments are captured to be sent to the optimizers.
Fields
f
: the function in the problem.u0
: the initial guess for the optimization variables.p
: Either the constant parameters or fixed data (full batch) used in the objective or a MLUtilsDataLoader
for minibatching with stochastic optimization solvers. Defaults toNullParameters
.lb
: the lower bounds for the optimization variablesu
.ub
: the upper bounds for the optimization variablesu
.int
: integrality indicator foru
. Ifint[i] == true
, thenu[i]
is an integer variable. Defaults tonothing
, implying no integrality constraints.lcons
: the vector of lower bounds for the constraints passed to OptimizationFunction. Defaults tonothing
, implying no lower bounds for the constraints (i.e. the constraint bound is-Inf
)ucons
: the vector of upper bounds for the constraints passed toOptimizationFunction
. Defaults tonothing
, implying no upper bounds for the constraints (i.e. the constraint bound isInf
)sense
: the objective sense, can takeMaxSense
orMinSense
from Optimization.jl.kwargs
: the keyword arguments passed on to the solvers.
Inequality and Equality Constraints
Both inequality and equality constraints are defined by the f.cons
function in the OptimizationFunction
description of the problem structure. This f.cons
is given as a function f.cons(u,p)
which computes the value of the constraints at u
. For example, take f.cons(u,p) = u[1] - u[2]
. With these definitions, lcons
and ucons
define the bounds on the constraint that the solvers try to satisfy. If lcons
and ucons
are nothing
, then there are no constraints bounds, meaning that the constraint is satisfied when -Inf < f.cons < Inf
(which of course is always!). If lcons[i] = ucons[i] = 0
, then the constraint is satisfied when f.cons(u,p)[i] = 0
, and so this implies the equality constraint u[1] = u[2]
. If lcons[i] = ucons[i] = a
, then $u[1] - u[2] = a$ is the equality constraint.
Inequality constraints are then given by making lcons[i] != ucons[i]
. For example, lcons[i] = -Inf
and ucons[i] = 0
would imply the inequality constraint $u[1] <= u[2]$ since any f.cons[i] <= 0
satisfies the constraint. Similarly, lcons[i] = -1
and ucons[i] = 1
would imply that -1 <= f.cons[i] <= 1
is required or $-1 <= u[1] - u[2] <= 1$.
Note that these vectors must be sized to match the number of constraints, with one set of conditions for each constraint.
Data handling
As described above the second argument of the objective definition can take a full batch or a DataLoader
object for mini-batching which is useful for stochastic optimization solvers. Thus the data either as an Array or a DataLoader
object should be passed as the third argument of the OptimizationProblem
constructor. For an example of how to use this data handling, see the Sophia
example in the Optimization.jl documentation or the mini-batching tutorial.