Update scimlfunctions.jl

Added docstring for the MOO struct.

src/scimlfunctions.jl

@@ -1930,6 +1930,97 @@ end
 
 """
 $(TYPEDEF)
+
+A representation of a multi-objective optimization problem, where multiple objective functions `f1, f2, ..., fn` are to be minimized:
+
+\[
+\min_{u} F(u, p) = [f1(u, p), f2(u, p), ..., fn(u, p)]
+\]
+
+`F` represents a vector of objective functions, where `u` are the optimization variables and `p` are fixed parameters or data. This struct defines all related functions such as Jacobians, Hessians, constraint functions, and their derivatives needed to solve multi-objective optimization problems.
+
+## Constructor
+
+```julia
+MultiObjectiveOptimizationFunction{iip}(F, adtype::AbstractADType = NoAD();
+ jac = nothing, hess = nothing, hv = nothing,
+ cons = nothing, cons_j = nothing, cons_jvp = nothing,
+ cons_vjp = nothing, cons_h = nothing,
+ hess_prototype = nothing,
+ cons_jac_prototype = nothing,
+ cons_hess_prototype = nothing,
+ observed = __has_observed(F) ? F.observed : DEFAULT_OBSERVED_NO_TIME,
+ lag_h = nothing,
+ hess_colorvec = __has_colorvec(F) ? F.colorvec : nothing,
+ cons_jac_colorvec = __has_colorvec(F) ? F.colorvec : nothing,
+ cons_hess_colorvec = __has_colorvec(F) ? F.colorvec : nothing,
+ lag_hess_colorvec = nothing,
+ sys = __has_sys(F) ? F.sys : nothing)
+```
+
+## Positional Arguments
+
+- `F(u, p, args...)`: The vector-valued multi-objective function `F` to be minimized. `u` is the vector of decision variables, 
+ `p` contains the parameters, and extra arguments can be passed as needed. Each element of `F` corresponds to an individual objective function `f1, f2, ..., fn`.
+
+## Keyword Arguments
+- `jac(J, u, p)` or `J = jac(u, p)`: Jacobian of the multi-objective function `F` with respect to `u`. Can accept additional arguments: `jac(J, u, p, args...)`.
+- `hess(H, u, p)` or `H = hess(u, p)`: Hessian matrix of the multi-objective function `F`. Accepts additional arguments: `hess(H, u, p, args...)`.
+- `hv(Hv, u, v, p)` or `Hv = hv(u, v, p)`: Hessian-vector product for the multi-objective function `F`. Extra arguments: `hv(Hv, u, v, p, args...)`.
+- `cons(res,u,p)` or `res=cons(u,p)` : the constraints function, should mutate the passed `res` array
+ with value of the `i`th constraint, evaluated at the current values of variables
+ inside the optimization routine. This takes just the function evaluations
+ and the equality or inequality assertion is applied by the solver based on the constraint
+ bounds passed as `lcons` and `ucons` to [`OptimizationProblem`](@ref), in case of equality
+ constraints `lcons` and `ucons` should be passed equal values.
+- `cons_j(J,u,p)` or `J=cons_j(u,p)`: the Jacobian of the constraints.
+- `cons_jvp(Jv,u,v,p)` or `Jv=cons_jvp(u,v,p)`: the Jacobian-vector product of the constraints.
+- `cons_vjp(Jv,u,v,p)` or `Jv=cons_vjp(u,v,p)`: the Jacobian-vector product of the constraints.
+- `cons_h(H,u,p)` or `H=cons_h(u,p)`: the Hessian of the constraints, provided as
+ an array of Hessians with `res[i]` being the Hessian with respect to the `i`th output on `cons`.
+- `hess_prototype`: a prototype matrix matching the type that matches the Hessian. For example,
+ if the Hessian is tridiagonal, then an appropriately sized `Hessian` matrix can be used
+ as the prototype and optimization solvers will specialize on this structure where possible. Non-structured
+ sparsity patterns should use a `SparseMatrixCSC` with a correct sparsity pattern for the Hessian.
+ The default is `nothing`, which means a dense Hessian.
+- `cons_jac_prototype`: a prototype matrix matching the type that matches the constraint Jacobian.
+ The default is `nothing`, which means a dense constraint Jacobian.
+- `cons_hess_prototype`: a prototype matrix matching the type that matches the constraint Hessian.
+ This is defined as an array of matrices, where `hess[i]` is the Hessian w.r.t. the `i`th output.
+ For example, if the Hessian is sparse, then `hess` is a `Vector{SparseMatrixCSC}`.
+ The default is `nothing`, which means a dense constraint Hessian.
+- `lag_h(res,u,sigma,mu,p)` or `res=lag_h(u,sigma,mu,p)`: the Hessian of the Lagrangian,
+ where `sigma` is a multiplier of the cost function and `mu` are the Lagrange multipliers
+ multiplying the constraints. This can be provided instead of `hess` and `cons_h`
+ to solvers that directly use the Hessian of the Lagrangian.
+- `hess_colorvec`: a color vector according to the SparseDiffTools.jl definition for the sparsity
+ pattern of the `hess_prototype`. This specializes the Hessian construction when using
+ finite differences and automatic differentiation to be computed in an accelerated manner
+ based on the sparsity pattern. Defaults to `nothing`, which means a color vector will be
+ internally computed on demand when required. The cost of this operation is highly dependent
+ on the sparsity pattern.
+- `cons_jac_colorvec`: a color vector according to the SparseDiffTools.jl definition for the sparsity
+ pattern of the `cons_jac_prototype`.
+- `cons_hess_colorvec`: an array of color vector according to the SparseDiffTools.jl definition for
+ the sparsity pattern of the `cons_hess_prototype`.
+
+When [Symbolic Problem Building with ModelingToolkit](https://docs.sciml.ai/Optimization/stable/tutorials/symbolic/) interface is used the following arguments are also relevant:
+
+- `observed`: an algebraic combination of optimization variables that is of interest to the user
+ which will be available in the solution. This can be single or multiple expressions.
+- `sys`: field that stores the `OptimizationSystem`.
+
+## iip: In-Place vs Out-Of-Place
+
+For more details on this argument, see the ODEFunction documentation.
+
+## specialize: Controlling Compilation and Specialization
+
+For more details on this argument, see the ODEFunction documentation.
+
+## Fields
+
+The fields of the MultiObjectiveOptimizationFunction type directly match the names of the inputs.
 """
 
 struct MultiObjectiveOptimizationFunction{