Add Support for Functions in Variable Domains and Overhaul Domain Restrictions (#395)

* Refactor ParameterFunction

* fix typo

* more minor changes

* more progress

* more progress

* progress

* Rename restricted domain info

* more progress

* more progress

* variable_updates

* Complete main package updates

* full draft of src changes

* more updates

* More updates

* test fixes

* doc fixes

* doc fix

Author: pulsipher

Project.toml

@@ -29,7 +29,7 @@ MutableArithmetics = "1"
 Reexport = "0.2, 1"
 julia = "1.10"
 Interpolations = "0.16"
-MathOptAI = "0.1.15"
+MathOptAI = "0.1.18"
 
 [extras]
 Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"

README.md

@@ -13,8 +13,8 @@ making it a powerful and convenient tool for advanced users.
 
 | **Documentation**                                                               | **Build Status**                                                                                | **Citation** |
 |:-------------------------------------------------------------------------------:|:-----------------------------------------------------------------------------------------------:|:--------------------------------------:|
-| [![](https://img.shields.io/badge/docs-stable-blue.svg)](https://infiniteopt.github.io/InfiniteOpt.jl/stable) | [![Build Status](https://github.com/infiniteopt/InfiniteOpt.jl/workflows/CI/badge.svg?branch=release-0.5)](https://github.com/infiniteopt/InfiniteOpt.jl/actions?query=workflow%3ACI) [![codecov.io](https://codecov.io/github/infiniteopt/InfiniteOpt.jl/coverage.svg?branch=release-0.5)](https://codecov.io/github/infiniteopt/InfiniteOpt.jl?branch=release-0.5) | [![DOI](https://img.shields.io/badge/Elsevier-CompChemEng%3A107567-yellow.svg)](https://doi.org/10.1016/j.compchemeng.2021.107567) |
-| [![](https://img.shields.io/badge/docs-dev-blue.svg)](https://infiniteopt.github.io/InfiniteOpt.jl/dev) | [![Build Status](https://github.com/infiniteopt/InfiniteOpt.jl/workflows/CI/badge.svg?branch=master)](https://github.com/infiniteopt/InfiniteOpt.jl/actions?query=workflow%3ACI) [![codecov.io](https://codecov.io/github/infiniteopt/InfiniteOpt.jl/coverage.svg?branch=master)](https://codecov.io/github/infiniteopt/InfiniteOpt.jl?branch=master) | |
+| [![](https://img.shields.io/badge/docs-stable-blue.svg)](https://infiniteopt.github.io/InfiniteOpt.jl/stable) | [![Build Status](https://github.com/infiniteopt/InfiniteOpt.jl/actions/workflows/ci.yml/badge.svg?branch=release-0.5)](https://github.com/infiniteopt/InfiniteOpt.jl/actions/workflows/ci.yml) [![codecov.io](https://codecov.io/github/infiniteopt/InfiniteOpt.jl/coverage.svg?branch=release-0.5)](https://codecov.io/github/infiniteopt/InfiniteOpt.jl?branch=release-0.5) | [![DOI](https://img.shields.io/badge/Elsevier-CompChemEng%3A107567-yellow.svg)](https://doi.org/10.1016/j.compchemeng.2021.107567) |
+| [![](https://img.shields.io/badge/docs-dev-blue.svg)](https://infiniteopt.github.io/InfiniteOpt.jl/dev) | [![Build Status](https://github.com/infiniteopt/InfiniteOpt.jl/actions/workflows/ci.yml/badge.svg)](https://github.com/infiniteopt/InfiniteOpt.jl/actions/workflows/ci.yml) [![codecov.io](https://codecov.io/github/infiniteopt/InfiniteOpt.jl/coverage.svg?branch=master)](https://codecov.io/github/infiniteopt/InfiniteOpt.jl?branch=master) | |
 
 It builds upon `JuMP` to add support for many complex modeling objects which 
 include:
@@ -43,7 +43,7 @@ can be installed by entering the following in the REPL.
 ```julia
 julia> ]
 
-(v1.11) pkg> add InfiniteOpt
+(v1.12) pkg> add InfiniteOpt
 ```
 
 ## Documentation

docs/Project.toml

@@ -27,5 +27,5 @@ Literate = "2.18"
 Plots = "1"
 SpecialFunctions = "2"
 Interpolations = "0.16"
-MathOptAI = "0.1.15"
+MathOptAI = "0.1.18"
 Flux = "0.16"

docs/src/develop/extensions.md

@@ -1039,7 +1039,7 @@ Subject to
 Note that better variable naming could be used with the reformulated infinite 
 variables. Moreover, in general extensions of [`build_transformation_backend!`](@ref) 
 should account for the possibility that `InfiniteModel` contains constraints with 
-[`DomainRestrictions`](@ref) as accessed via [`domain_restrictions`](@ref).
+[`DomainRestriction`](@ref) as accessed via [`domain_restriction`](@ref).
 
 Now that we have optimized our `InfiniteModel` via the use the of a 
 `DeterministicBackend`, we probably want to access the results. All queries 

docs/src/guide/constraint.md

@@ -109,11 +109,11 @@ parameters they explicitly/implicitly depend on) that is restricted to a certain
 sub-domain. Such constraints are common for enforcing initial/boundary conditions 
 and for enforcing path constraints over a certain sub-domain.
 
-These types of constraints are defined adding [`DomainRestrictions`](@ref). For 
+These types of constraints are defined adding [`DomainRestriction`](@ref). For 
 example, let's add the initial condition ``y_b(0) = 0``:
 ```jldoctest constrs
-julia> @constraint(model, initial, yb == 0, DomainRestrictions(t => 0))
-initial : yb(t) = 0, ∀ t = 0
+julia> @constraint(model, initial, yb == 0, DomainRestriction(iszero, t))
+initial : yb(t) = 0, ∀ t ∈ [0, 10]; if iszero(t) = True
 ```
 Thus, we have added a constraint to `model` defined over the sub-domain ``t = 0`` 
 in accordance with the initial condition.
@@ -127,12 +127,15 @@ in accordance with the initial condition.
     yb(0) = 0
     ```
 
-More complex sub-domains can be specified by simply adding more restrictions. To 
+This syntax is quite general since any function can be defined for more 
+complex sub-domains can be specified by simply adding more restrictions. To 
 illustrate this, let's define the constraint 
 ``2y_b^2(t, x) + z_1 \geq 3, \ \forall t = 0, \ x \in [-1, 1]^2``:
 ```jldoctest constrs
-julia> @constraint(model, 2ya^2 + z[1] >= 3, DomainRestrictions(t => 0, x => [-1, 1]))
-2 ya(t, x)² + z[1] ≥ 3, ∀ t = 0, x[1] ∈ [-1, 1], x[2] ∈ [-1, 1]
+julia> restrict(t_s, x_s) = iszero(t_s) && -1 <= x_s <= 1;
+
+julia> @constraint(model, 2ya^2 + z[1] >= 3, DomainRestriction(restrict, t, x))
+2 ya(t, x)² + z[1] ≥ 3, ∀ t ∈ [0, 10], x[1] ∈ [-2, 2], x[2] ∈ [-2, 2]; if restrict(t, x) = True
 ```
 
 Now we have added constraints to our model, and it is ready to be solved!
@@ -155,7 +158,7 @@ and [`JuMP.VectorConstraint](https://jump.dev/JuMP.jl/v1/api/JuMP/#JuMP.VectorCo
 
 Restricted constraints are built upon this data structure where the underlying 
 constraint is created in the same manner. Then the specified 
-[`DomainRestrictions`](@ref) are added by creating a 
+[`DomainRestriction`](@ref) are added by creating a 
 [`DomainRestrictedConstraint`](@ref) which stores the `JuMP.AbstractConstraint` 
 and the restrictions.
 
@@ -180,7 +183,7 @@ The constraint objects are specified via `JuMP.build_constraint` which requires
 that the user provides a function, set, and optionally include domain 
 restrictions. For example, let's build a scalar constraint 
 ``3y_a(t, x) - y_b^2(t) \leq 0, \ \forall t \in [0, 10], x \in [-2, 2]^2`` over 
-its full infinite domain (i.e., have no `DomainRestrictions`):
+its full infinite domain (i.e., have no `DomainRestriction`):
 ```jldoctest constrs
 julia> constr = build_constraint(error, 3ya - yb^2, MOI.LessThan(0.0));
 ```
@@ -203,7 +206,7 @@ macro automate the above steps.
 As mentioned above in the Basic Usage section, the 
 [`@constraint`](https://jump.dev/JuMP.jl/v1/api/JuMP/#JuMP.@constraint) 
 macro should be used to define constraints with the syntax: 
-`@constraint(model::InfiniteModel, [container/name_expr], constr_expr, [rs::DomainRestrictions])`.
+`@constraint(model::InfiniteModel, [container/name_expr], constr_expr, [rs::DomainRestriction])`.
 
 The second argument is optional and is used to assign a name and/or define 
 indexing variables to be used in the constraint expression. When a name is provided it 
@@ -249,29 +252,25 @@ See [`JuMP`'s constraint documentation](https://jump.dev/JuMP.jl/v1/manual/const
 for a thorough tutorial on the accepted syntax and constraint types.
 
 Finally, restrictions on the inherent infinite domain of a constraint can be 
-specified via [`DomainRestrictions`](@ref) with the `rs` argument. The accepted 
-syntax is `DomainRestrictions(restricts...)` where each argument of `restricts` 
-can be any of the following forms:
-- `pref => value`
-- `pref => [lb, ub]`
-- `pref => IntervalDomain(lb, ub)`
-- `prefs => value`
-- `prefs => [lb, ub]`
-- `prefs => IntervalDomain(lb, ub)`.
-Note that `pref` and `prefs` must correspond to infinite parameters.
+specified via [`DomainRestriction`](@ref) with the `rs` argument. The accepted 
+syntax is `DomainRestriction(restrict_func, prefs...)` where `restrict_func` takes
+a support in the form of `prefs...` and returns a `Bool` that indicates if the support
+is in the domain of interest. Note that `prefs` must correspond to infinite parameters.
 
 For example, we can define the constraint ``y_a^2(t, x) + z_i \leq 1`` and 
-restrict the infinite domain of ``x_i`` to be ``[0, 1]``:
+restrict the infinite domain of ``x`` to be ``[0, 1]^2``:
  ```jldoctest constrs
-julia> @constraint(model, [i = 1:2], ya^2 + z[i] <= 1, DomainRestrictions(x[i] => [0, 1]))
+julia> restrict2(x_s) = all(0 .<= x_s .<= 1);
+
+julia> @constraint(model, [i = 1:2], ya^2 + z[i] <= 1, DomainRestriction(restrict2, x))
 2-element Vector{InfOptConstraintRef}:
- ya(t, x)² + z[1] ≤ 1, ∀ t ∈ [0, 10], x[1] ∈ [0, 1], x[2] ∈ [-2, 2]
- ya(t, x)² + z[2] ≤ 1, ∀ t ∈ [0, 10], x[1] ∈ [-2, 2], x[2] ∈ [0, 1]
+ ya(t, x)² + z[1] ≤ 1, ∀ t ∈ [0, 10], x[1] ∈ [-2, 2], x[2] ∈ [-2, 2]; if restrict2(x) = True
+ ya(t, x)² + z[2] ≤ 1, ∀ t ∈ [0, 10], x[1] ∈ [-2, 2], x[2] ∈ [-2, 2]; if restrict2(x) = True
 ```
 
 !!! tip
     Where possible, using [Restricted Variables](@ref) will tend to be more 
-    performant than using `DomainRestrictions` instead.
+    performant than using `DomainRestriction` instead.
 
 ## Queries
 In this section, we describe a variety of methods to extract constraint
@@ -313,18 +312,18 @@ c1 : z[1]² + z[2]² + 2 ya(t, x) ≤ 0, ∀ t ∈ [0, 10], x[1] ∈ [-2, 2], x[
 ### Domain Restrictions
 As explained above, restricted constraints serve as a key capability of 
 `InfiniteOpt`. Information about domain restrictions can be obtained via 
-[`has_domain_restrictions`](@ref) and [`domain_restrictions`](@ref) which indicate 
-if a constraint is restricted and what its [`DomainRestrictions`](@ref) are, 
+[`has_domain_restriction`](@ref) and [`domain_restriction`](@ref) which indicate 
+if a constraint is restricted and what its [`DomainRestriction`](@ref) are, 
 respectively. These are exemplified below:
 ```jldoctest constrs
-julia> has_domain_restrictions(c1) # check if constraint is bounded
+julia> has_domain_restriction(c1) # check if constraint is bounded
 false
 
-julia> has_domain_restrictions(initial)
+julia> has_domain_restriction(initial)
 true
 
-julia> domain_restrictions(initial)
-Subdomain restrictions (1): t = 0
+julia> domain_restriction(initial)
+iszero(t)
 ```
 
 ### General
@@ -412,7 +411,7 @@ let's update the name of `initial` to `"init_cond"`:
 julia> set_name(initial, "init_cond")
 
 julia> initial
-init_cond : yb(t) = 0, ∀ t = 0
+init_cond : yb(t) = 0, ∀ t ∈ [0, 10]; if iszero(t) = True
 ```
 
 We can also update the normalized right hand side constant value or normalized 
@@ -435,42 +434,31 @@ constr : 2.5 yb(t) - z[1] ≤ -1, ∀ t ∈ [0, 10]
     to update parameters without having to be concerned about the normalized form. 
     For more information, see the [Finite Parameters](@ref finite_param_docs) page. 
 
-### Domain Restrictions
-Domain Restrictions can be added to, modified, or removed from any constraint in 
+### Domain Restriction
+Domain Restrictions can be modified or removed from any constraint in 
 `InfiniteOpt`. Principally, this is accomplished via  
-[`add_domain_restrictions`](@ref), [`set_domain_restrictions`](@ref), 
-and [`delete_domain_restrictions`](@ref).
+[`set_domain_restriction`](@ref) and [`delete_domain_restriction`](@ref).
 
 !!! note 
-    Previous versions of `InfiniteOpt` used `@[set/add]_parameter_bounds` which 
-    have been deprecated in favor of using [`DomainRestrictions`](@ref) with the 
-    methods described used in this section.
-
-First, domain restrictions can be added to a constraint via 
-[`add_domain_restrictions`](@ref). For example, let's add the bound 
-``t \in [0, 1]`` to `constr`:
-```jldoctest constrs
-julia> add_domain_restrictions(constr, DomainRestrictions(t => [0, 1]))
-
-julia> constr
-constr : 2.5 yb(t) - z[1] ≤ -1, ∀ t ∈ [0, 1]
-```
+    Previous versions of `InfiniteOpt` used `DomainRestrictions` with a more
+    limited syntax. Now [`DomainRestriction`](@ref) has been introduced to
+    provide a more flexible syntax.
 
-In similar manner, [`set_domain_restrictions`](@ref) can be employed to specify 
+[`set_domain_restriction`](@ref) can be employed to specify 
 what restrictions a constraint has (overwriting any existing ones if forced). It  
 follows the same syntax, so let's use it to change the bounds on `t` to ``t = 0``:
 ```jldoctest constrs
-julia> set_domain_restrictions(constr, DomainRestrictions(t => 0), force = true)
+julia> set_domain_restriction(constr, DomainRestriction(iszero, t))
 
 julia> constr
-constr : 2.5 yb(t) - z[1] ≤ -1, ∀ t = 0
+constr : 2.5 yb(t) - z[1] ≤ -1, ∀ t ∈ [0, 10]; if iszero(t) = True
 ```
 
 Finally, constraint restrictions can be deleted via 
-[`delete_domain_restrictions`](@ref). Now let's delete the domain restrictions 
+[`delete_domain_restriction`](@ref). Now let's delete the domain restrictions 
 associated with our example:
 ```jldoctest constrs
-julia> delete_domain_restrictions(constr)
+julia> delete_domain_restriction(constr)
 
 julia> constr
 constr : 2.5 yb(t) - z[1] ≤ -1, ∀ t ∈ [0, 10]

docs/src/guide/derivative.md

@@ -79,7 +79,7 @@ julia> deriv(3t^2 - 2t, t)
 Conveniently, `@deriv` can be called within any measure and constraint. However, 
 in certain cases we may need to define an initial guess (initial guess trajectory). 
 This can be accomplished in 2 ways:
- - Call [`set_start_value_function`](@ref set_start_value_function(::DerivativeRef,::Union{Real, Function})) 
+ - Call [`set_start_value`](@ref) 
    using the individual derivative (e.g., `d1` above)
  - Define the derivative using `@variable` with the [`Deriv`](@ref) variable type 
    object and use the `start` keyword argument.
@@ -88,7 +88,7 @@ generate a value in accordance with the support values (i.e., following the same
 syntax as infinite variables). For example, we can specify the starting value of 
 `d1` to `0` via the following:
 ```jldoctest deriv_basic 
-julia> set_start_value_function(d1, 0)
+julia> set_start_value(d1, 0)
 ```
 
 Now let's return to our discussion on derivative evaluation methods. These are the 
@@ -584,7 +584,7 @@ dydt2(t, x, ξ) ≥ 1, ∀ t ∈ [0, 10], ξ ~ Uniform, x ∈ [-1, 1]
 julia> has_upper_bound(dydt2)
 false 
 
-julia> func = start_value_function(dydt2);
+julia> func = start_value(dydt2);
 ```
 
 ### Model Queries 
@@ -629,7 +629,7 @@ julia> fix(dydt2, 42, force = true)
 julia> fix_value(dydt2) 
 42.0
 
-julia> set_start_value_function(dydt2, (t, x, xi) -> t + x+ xi)
+julia> set_start_value(dydt2, (t, x, xi) -> t + x+ xi)
 
 julia> unfix(dydt2)
 

docs/src/guide/optimize.md

@@ -44,7 +44,6 @@ Subject to
  y(t) ≥ 0, ∀ t ∈ [0, 10]
  z ≥ 0
  c1 : z - y(t) ≥ 0, ∀ t ∈ [0, 10]
- y(0) ≥ 0
  c2 : y(0) = 42
 ```
 Now we optimize the model using `optimize!`:

docs/src/guide/result.md

@@ -38,11 +38,10 @@ julia> @constraint(model, c2, y(0) == 42);
 julia> print(model)
 Min 2 z
 Subject to
- y(t) ≥ 0.0, ∀ t ∈ [0, 10]
- z ≥ 0.0
- c1 : z - y(t) ≥ 0.0, ∀ t ∈ [0, 10]
- y(0) ≥ 0.0
- c2 : y(0) = 42.0
+ y(t) ≥ 0, ∀ t ∈ [0, 10]
+ z ≥ 0
+ c1 : z - y(t) ≥ 0, ∀ t ∈ [0, 10]
+ c2 : y(0) = 42
 
 julia> optimize!(model)
 

docs/src/guide/transcribe.md

@@ -56,7 +56,6 @@ Min 2 z + support_sum{t}[y(t)]
 Subject to
  y(t) ≥ 0, ∀ t ∈ [0, 10]
  z binary
- y(0) ≥ 0
  initial : y(0) = 1
  constr : y(t)² - z ≤ 42, ∀ t ∈ [0, 10]
 ```