Update docs

Author: moyner

Project.toml

@@ -1,7 +1,7 @@
 name = "Jutul"
 uuid = "2b460a1a-8a2b-45b2-b125-b5c536396eb9"
 authors = ["Olav Møyner <olav.moyner@gmail.com>"]
-version = "0.4.2"
+version = "0.4.3"
 
 [deps]
 AlgebraicMultigrid = "2169fc97-5a83-5252-b627-83903c6c433c"

docs/src/usage.md

@@ -84,6 +84,23 @@ Jutul.solve_numerical_sensitivities
 setup_parameter_optimization
 ```
 
+### Generic optimization interface
+
+```@docs
+DictParameters
+```
+
+```@docs
+free_optimization_parameter!
+freeze_optimization_parameter!
+set_optimization_parameter!
+```
+
+```@docs
+optimize
+parameters_gradient
+```
+
 ## Linear solvers
 
 ```@docs

src/DictOptimization/interface.jl

@@ -1,3 +1,55 @@
+"""
+    optimized_dict = optimize(dopt, objective)
+    optimize(dopt::DictParameters, objective, setup_fn = dopt.setup_function;
+        grad_tol = 1e-6,
+        obj_change_tol = 1e-6,
+        max_it = 25,
+        opt_fun = missing,
+        maximize = false,
+        simulator = missing,
+        config = missing,
+        solution_history = false,
+        backend_arg = (
+            use_sparsity = false,
+            di_sparse = true,
+            single_step_sparsity = false,
+            do_prep = true,
+        ),
+        kwarg...
+    )
+
+Optimize parameters defined in a [`DictParameters`](@ref) object using the
+provided objective function. At least one variable has to be declared to be free
+using `free_optimization_parameter!` prior to calling the optimizer.
+
+# Arguments
+- `dopt::DictParameters`: Container with parameters to optimize
+- `objective`: The objective function to minimize (or maximize)
+- `setup_fn`: Function to set up the optimization problem. Defaults to `dopt.setup_function`
+
+# Keyword Arguments
+- `grad_tol`: Gradient tolerance for stopping criterion
+- `obj_change_tol`: Objective function change tolerance for stopping criterion
+- `max_it`: Maximum number of iterations
+- `opt_fun`: Optional custom optimization function. If missing, L-BFGS will be used
+- `maximize`: Set to `true` to maximize the objective instead of minimizing
+- `simulator`: Optional simulator object used in forward simulations
+- `config`: Optional configuration for the setup
+- `solution_history`: If `true`, stores all intermediate solutions
+- `backend_arg`: Options for the autodiff backend:
+  - `use_sparsity`: Enable sparsity detection for the objective function
+  - `di_sparse`: Use sparse differentiation
+  - `single_step_sparsity`: Enable single step sparsity detection (if sparsity does not change during timesteps)
+  - `do_prep`: Perform preparation step
+
+# Returns
+The optimized parameters as a dictionary.
+
+# Notes
+- The function stores the optimization history and optimized parameters in the input `dopt` object.
+- If `solution_history` is `true`, intermediate solutions are stored in `dopt.history.solutions`.
+- The default optimization algorithm is L-BFGS with box constraints.
+"""
 function optimize(dopt::DictParameters, objective, setup_fn = dopt.setup_function;
         grad_tol = 1e-6,
         obj_change_tol = 1e-6,
@@ -81,6 +133,15 @@ function optimize(dopt::DictParameters, objective, setup_fn = dopt.setup_functio
     return prm_out
 end
 
+"""
+    parameters_gradient(dopt::DictParameters, objective, setup_fn = dopt.setup_function)
+
+Compute the gradient of the objective function with respect to the parameters
+defined in the `DictParameters` object. This function will return the gradient
+as a dictionary with the same structure as the input parameters, where each
+entry is a vector of gradients for each parameter. Only gradients with respect
+to free parameters will be computed.
+"""
 function parameters_gradient(dopt::DictParameters, objective, setup_fn = dopt.setup_function;
         simulator = missing,
         config = missing,
@@ -118,6 +179,16 @@ function parameters_gradient(dopt::DictParameters, objective, setup_fn = dopt.se
     return out
 end
 
+"""
+    freeze_optimization_parameter!(dopt, "parameter_name")
+    freeze_optimization_parameter!(dopt, ["dict_name", "parameter_name"])
+    freeze_optimization_parameter!(dopt::DictParameters, parameter_name, val = missing)
+
+Freeze an optimization parameter in the `DictParameters` object. This will
+remove the parameter from the optimization targets and set its value to `val` if
+provided. Any limits/lumping/scaling settings for this parameter will be
+removed.
+"""
 function freeze_optimization_parameter!(dopt::DictParameters, parameter_name, val = missing)
     parameter_name = convert_key(parameter_name)
     if !ismissing(val)
@@ -126,6 +197,54 @@ function freeze_optimization_parameter!(dopt::DictParameters, parameter_name, va
     delete!(dopt.parameter_targets, parameter_name)
 end
 
+"""
+    free_optimization_parameter!(dopt, "parameter_name", rel_min = 0.01, rel_max = 100.0)
+    free_optimization_parameter!(dopt, ["dict_name", "parameter_name"], abs_min = -8.0, abs_max = 7.0)
+
+Free an existing parameter for optimization in the `DictParameters` object. This
+will allow the parameter to be optimized through a call to [`optimize`](@ref).
+
+# Nesting structures
+If your `DictParameters` has a nesting structure, you can use a vector of
+strings or symbols to specify the parameter name, e.g. `["dict_name",
+"parameter_name"]` to access the parameter located at
+`["dict_name"]["parameter_name"]`.
+
+# Setting limits
+The limits can be set using the following keyword arguments:
+- `abs_min`: Absolute minimum value for the parameter.  If not set, no absolute
+  minimum will be applied.
+- `abs_max`: Absolute maximum value for the parameter. If not set, no absolute
+  maximum will be applied.
+- `rel_min`: Relative minimum value for the parameter. If not set, no relative
+  minimum will be applied.
+- `rel_max`: Relative maximum value for the parameter. If not set, no relative
+  maximum will be applied.
+
+For either of these entries it is possible to pass either a scalar, or an array.
+If an array is passed, it must have the same size as the parameter being set.
+
+Note that if `dopt.strict` is set to `true`, at least one of the upper or lower
+bounds must be set for free parameters. If `dopt.strict` is set to `false`, the
+bounds are optional and the `DictParameters` object can be used to compute
+sensitivities, but the built-in optimization routine assumes that finite limits
+are set for all parameters.
+
+# Other keyword arguments
+- `initial`: Initial value for the parameter. If not set, the current value in
+  `dopt.parameters` will be used.
+- `scaler=missing`: Optional scaler for the parameter. If not set, no scaling
+  will be applied. Available scalers are `:log`, `:exp`. The scaler will be
+  applied
+- `lumping=missing`: Optional lumping array for the parameter. If not set, no
+  lumping will be applied. The lumping array should have the same size as the
+  parameter and contain positive integers. The lumping array defines groups of
+  indices that should be lumped together, i.e. the same value will be used for
+  all indices in the same group. The lumping array should contain all integers
+  from 1 to the maximum value in the array, and all indices in the same group
+  should have the same value in the initial parameter, otherwise an error will
+  be thrown.
+"""
 function free_optimization_parameter!(dopt::DictParameters, parameter_name;
         initial = missing,
         abs_min = -Inf,
@@ -191,6 +310,12 @@ function free_optimization_parameters!(dopt::DictParameters, targets = all_keys(
     return dopt
 end
 
+"""
+    set_optimization_parameter!(dopt::DictParameters, parameter_name, value)
+
+Set a specific optimization parameter in the `DictParameters` object. This
+function will update the value of the parameter in the `dopt.parameters` dictionary.
+"""
 function set_optimization_parameter!(dopt::DictParameters, parameter_name, value)
     set_nested_dict_value!(dopt.parameters, parameter_name, value)
 end

src/DictOptimization/types.jl

@@ -22,7 +22,31 @@ mutable struct DictParameters
     active_type
     setup_function
     history
-    function DictParameters(parameters::AbstractDict, setup_function = missing;
+    @doc"""
+        DictParameters(parameters)
+        DictParameters(parameters::AbstractDict, setup_function = missing;
+                strict = true,
+                verbose = true,
+                active_type = Float64
+            )
+
+    Set up a `DictParameters` object for optimization. Optionally, the setup
+    function that takes an instance with the same keys as `parameters` together
+    with a `step_info` dictionary can be provided. The setup function should
+    return a `JutulCase` set up from the parameters in the Dict.
+
+    Optional keyword arguments:
+    - `strict`: If true, the optimization will throw an error if any of the
+      parameters are not set with at least one of the upper or lower bounds.
+    - `verbose`: If true, the optimization will print information about the
+      optimization process.
+    - `active_type`: The type of the parameters that are considered active in
+      the optimization. Defaults to `Float64`. This is used to determine which
+      parameters are active and should be optimized. This means that all entries
+      (and entries in nested dictionaries) of the `parameters` dictionary must
+      be of this type or an array with this type as element type.
+    """
+function DictParameters(parameters::AbstractDict, setup_function = missing;
             strict = true,
             verbose = true,
             active_type = Float64