Improve Parameter Support (#394)

* overall parameter handling

* updates

* Fixes

* fix tests

* minor doc update

Author: pulsipher

docs/src/develop/extensions.md

@@ -789,6 +789,7 @@ extended using the following steps:
 10. Extend [`InfiniteOpt.add_point_variable`](@ref) and 
     [`InfiniteOpt.add_semi_infinite_variable`](@ref) to use 
     [`expand_measure`](@ref) without modifying the infinite model.
+11. Extend [`InfiniteOpt.update_parameter_value`](@ref) to enable incremental parameter updates.
 
 This may seem like a lot a work, but the majority of the above steps can be
 skipped for [`JuMPBackend`](@ref)s as exemplified below. A complete extension,

docs/src/guide/expression.md

@@ -42,12 +42,12 @@ f(t)
 Here, we created a parameter function object, added it to `model`, and
 then created a Julia variable `f` that serves as a `GeneralVariableRef` that points
 to it. From here we can treat `f` as a normal infinite variable and use it with
-measures, derivatives, and constraints. For example, we can do the following:
+measures, and constraints. For example, we can do the following:
 ```jldoctest param_func
 julia> @variable(model, y, Infinite(t));
 
-julia> df = deriv(f, t)
-∂/∂t[f(t)]
+julia> f(0)
+f(0)
 
 julia> meas = integral(y - f, t)
 ∫{t ∈ [0, 10]}[y(t) - f(t)]
@@ -89,6 +89,14 @@ setpoint(t)
 Please consult the following links for more information about defining parameter
 functions: [`@parameter_function`](@ref) and [`parameter_function`](@ref).
 
+We can also update the underlying function as often required for repeated solves.
+This is accomplished via 
+[`set_parameter_value`](@ref JuMP.set_parameter_value(::ParameterFunctionRef, ::Function)):
+```jldoctest param_func
+julia> set_parameter_value(setpoint, t -> 5)
+
+```
+
 Beyond this, there are a number of query and modification methods that can be
 employed for parameter functions and these are detailed in the
 [technical manual](@ref par_func_manual).

docs/src/guide/finite_parameter.md

@@ -54,33 +54,15 @@ corresponding `GeneralVariableRef` can be used in expressions, objectives, measu
 and constraints just like infinite parameters.
 
 The value of a finite parameter can be checked using
-[`parameter_value`](@ref parameter_value(::FiniteParameterRef)) and can modified using
-[`set_value`](@ref JuMP.set_value(::FiniteParameterRef, ::Real)). For example,
+[`parameter_value`](@ref JuMP.parameter_value(::FiniteParameterRef)) and can modified using
+[`set_parameter_value`](@ref JuMP.set_parameter_value(::FiniteParameterRef, ::Real)). For example,
 let's update the value of `max_cost` to be now be `10.2`:
 ```jldoctest fpar
 julia> parameter_value(max_cost)
 42.0
 
-julia> set_value(max_cost, 10.2)
+julia> set_parameter_value(max_cost, 10.2)
 
 julia> parameter_value(max_cost)
 10.2
 ```
-
-## Advanced Details
-The ability to implement finite parameters stems from its ability to support 
-mixed variable types using by using the `GeneralVariableRef` buffer. As such, 
-finite parameters will be treated as variables until the model is transcribed. 
-For example, this means that the expression `max_cost * x` will be treated as a 
-quadratic expression when it is expressed in its `InfiniteOpt` form, however it is 
-converted into the appropriate affine expression when transcribed. 
-
-!!! note 
-    In previous versions finite parameters were just special cases of infinite 
-    parameters. However, they now have their own distinct underlying data structure. 
-
-!!! warning 
-    `InfiniteOpt`'s implementation of finite parameters should not be a reason to 
-    use `InfiniteOpt` to model non-infinite-dimensional problems, since the added 
-    overhead will make it slower than just iteratively building `JuMP` models. For 
-    this behavior, we recommend looking into using `ParametricOptInterface`.

docs/src/guide/transcribe.md

@@ -384,6 +384,16 @@ behind infinite model transformation and is what encapsulates all the methods to
 transcribe measures, variables, derivatives, and constraints. This is also the 
 method that enables the use of [`optimize!`](@ref JuMP.optimize!(::InfiniteModel)).
 
+!!! note
+    To support incremental updates of parameter functions for efficient resolves,
+    set `update_parameter_functions = true` when defining the backend:
+    ```julia
+    backend = TranscriptionBackend(Ipopt.Optimizer, update_parameter_functions = true)
+    model = InfiniteModel(backend)
+    ```
+    This setting has parameters functions mapped with JuMP parameters rather than
+    just numerical values.
+
 ### Queries
 In this section we highlight a number of query methods that pertain to 
 `TranscriptionBackend`s and their mappings. First, we can retrieve the JuMP `Model`

docs/src/guide/variable.md

@@ -636,6 +636,23 @@ julia> semi = y(0, x) # make semi-infinite variable y(0, x)
 y(0, [x[1], x[2]])
 ```
 
+## Parameters
+Like JuMP, InfiniteOpt supports the use of `MOI.Parameter`. For instance, 
+consider making a finite variable as a parameter:
+```jldoctest restrict_vars
+julia> @variable(model, param in Parameter(42))
+param
+```
+which simply produces a finite parameter (i.e., is equivalent to 
+`@finite_parameter(model, param == 42)`). For infinite variables, the use 
+of `MOI.Parameter` simply produces a parameter function:
+```jldoctest restrict_vars
+julia> @variable(model, pfunc in Parameter(sin), Infinite(t))
+pfunc(t)
+```
+which is equivalent to `@parameter_function(model, pfunc == sin(t))`. All
+parameters can be updated via [`set_parameter_value`](@ref), see [Finite Parameters](@ref finite_param_docs) and [Parameter Function](@ref par_func_docs) to learn more.
+
 ## Queries
 `InfiniteOpt` contains a large suite of methods to query information about
 variables. This suite comprises extensions to all current `JuMP` query

docs/src/manual/backend.md

@@ -72,4 +72,5 @@ expression_supports(::Any, ::AbstractTransformationBackend)
 constraint_supports(::InfOptConstraintRef, ::AbstractTransformationBackend)
 transformation_backend_ready
 set_transformation_backend_ready
+update_parameter_value(::AbstractTransformationBackend, ::Any, ::Any)
 ```

docs/src/manual/expression.md

@@ -19,21 +19,25 @@ ParameterFunctionRef
 ```@docs
 JuMP.name(::ParameterFunctionRef)
 raw_function(::ParameterFunctionRef)
+JuMP.parameter_value(::ParameterFunctionRef)
 call_function
 parameter_refs(::ParameterFunctionRef)
 parameter_list(::ParameterFunctionRef)
 raw_parameter_refs(::ParameterFunctionRef)
 is_used(::ParameterFunctionRef)
 used_by_semi_infinite_variable(::ParameterFunctionRef)
-used_by_derivative(::ParameterFunctionRef)
+used_by_point_variable(::ParameterFunctionRef)
 used_by_measure(::ParameterFunctionRef)
 used_by_constraint(::ParameterFunctionRef)
 parameter_group_int_indices(::ParameterFunctionRef)
+num_parameter_functions
+all_parameter_functions
 ```
 
 ### Modification
 ```@docs
 JuMP.set_name(::ParameterFunctionRef, ::String)
+JuMP.set_parameter_value(::ParameterFunctionRef, ::Function)
 JuMP.delete(::InfiniteModel, ::ParameterFunctionRef)
 ```
 
@@ -87,8 +91,8 @@ used_by_objective(::GeneralVariableRef)
 used_by_constraint(::GeneralVariableRef)
 is_used(::GeneralVariableRef)
 has_derivative_constraints(::GeneralVariableRef)
-parameter_value(::GeneralVariableRef)
-JuMP.set_value(::GeneralVariableRef, ::Real)
+JuMP.parameter_value(::GeneralVariableRef)
+JuMP.set_parameter_value(::GeneralVariableRef, ::Any)
 infinite_domain(::GeneralVariableRef)
 infinite_domain(::Array{<:GeneralVariableRef})
 set_infinite_domain(::GeneralVariableRef, ::InfiniteScalarDomain)

docs/src/manual/finite_parameter.md

@@ -19,8 +19,8 @@ parameter [technical manual](@ref inf_par_manual) for the remainder of the
 methods available for finite parameters (i.e., any method typed for 
 `ScalarParameterRef`s)
 ```@docs
-parameter_value(::FiniteParameterRef)
-JuMP.set_value(::FiniteParameterRef, ::Real)
+JuMP.parameter_value(::FiniteParameterRef)
+JuMP.set_parameter_value(::FiniteParameterRef, ::Real)
 used_by_objective(::FiniteParameterRef)
 core_object(::FiniteParameterRef)
 ```

docs/src/manual/transcribe.md

@@ -45,6 +45,12 @@ InfiniteOpt.constraint_supports(::InfiniteOpt.InfOptConstraintRef,::InfiniteOpt.
 InfiniteOpt.TranscriptionOpt.parameter_supports(::InfiniteOpt.TranscriptionOpt.TranscriptionBackend)
 ```
 
+## Updates
+```@docs
+InfiniteOpt.update_parameter_value(::InfiniteOpt.TranscriptionOpt.TranscriptionBackend, ::InfiniteOpt.FiniteParameterRef, ::Real)
+InfiniteOpt.update_parameter_value(::InfiniteOpt.TranscriptionOpt.TranscriptionBackend, ::InfiniteOpt.ParameterFunctionRef, ::Function)
+```
+
 ## Utilities
 ```@docs
 InfiniteOpt.TranscriptionOpt.support_index_iterator

src/InfiniteOpt.jl

@@ -33,6 +33,7 @@ include("point_variables.jl")
 include("finite_variables.jl")
 include("nlp.jl")
 include("macros.jl")
+include("parameter_function.jl")
 include("expressions.jl")
 include("measures.jl")
 
@@ -66,6 +67,7 @@ Base.@deprecate optimizer_model_variable(v; kwargs...) transformation_variable(v
 Base.@deprecate optimizer_model_expression(e; kwargs...) transformation_expression(e; kwargs...)
 Base.@deprecate optimizer_model_constraint(c; kwargs...) transformation_constraint(c; kwargs...)
 Base.@deprecate optimizer_model(m) transformation_model(m)
+Base.@deprecate set_value(v::GeneralVariableRef, val) set_parameter_value(v, val)
 
 # Define additional stuff that should not be exported
 const _EXCLUDE_SYMBOLS = [