Merge pull request #830 from jClugstor/aliasing_system

Add aliasing API types

docs/src/interfaces/Common_Keywords.md

@@ -101,8 +101,12 @@ Note that if a method does not have adaptivity, the following rules apply:
 
 ## Memory Optimizations
 
-  - `alias_u0`: allows the solver to alias the initial condition array that is contained
-    in the problem struct. Defaults to false.
+  - `alias`: an `AbstractAliasSpecifier` object that holds fields specifying which variables to alias
+    when solving. For example, to tell an ODE solver to alias the `u0` array, you can use an `ODEAliases` object, 
+    and the `alias_u0` keyword argument, e.g. `solve(prob,alias = ODEAliases(alias_u0 = true))`. 
+    For more information on what can be aliased for each problem type, see the documentation for the `AbstractAliasSpecifier`
+    associated with that problem type. Set to `true` to alias every variable possible, or to `false` to disable aliasing.
+    Defaults to an `AbstractAliasSpecifier` instance with `nothing` for all fields, which tells the solver to use the default behavior.
   - `cache`: pass a solver cache to decrease the construction time. This is not implemented
     for any of the problem interfaces at this moment.
 

src/SciMLBase.jl

@@ -642,6 +642,14 @@ abstract type ADOriginator end
 """
 $(TYPEDEF)
 
+Used to specify which variables can be aliased in a solve. 
+Every concrete AbstractAliasSpecifier should have at least the fields `alias_p` and `alias_f`. 
+"""
+abstract type AbstractAliasSpecifier end
+
+"""
+$(TYPEDEF)
+
 Internal. Used for signifying the AD context comes from a ChainRules.jl definition.
 """
 struct ChainRulesOriginator <: ADOriginator end
@@ -863,4 +871,6 @@ export ContinuousCallback, DiscreteCallback, CallbackSet, VectorContinuousCallba
 
 export Clocks, TimeDomain, is_discrete_time_domain, isclock, issolverstepclock, iscontinuous
 
+export ODEAliasSpecifier, LinearAliasSpecifier
+
 end

src/problems/analytical_problems.jl

@@ -28,3 +28,43 @@ function AnalyticalProblem(f, u0, tspan, p = NullParameters(); kwargs...)
 end
 
 export AnalyticalProblem, AbstractAnalyticalProblem
+
+
+@doc doc"""
+
+Holds information on what variables to alias
+when solving an AnalyticalProblem. Conforms to the AbstractAliasSpecifier interface. 
+    `AnalyticalAliasSpecifier(;alias_p = nothing, alias_f = nothing, alias_u0 = nothing, alias_du0 = nothing, alias_tstops = nothing, alias = nothing)`
+
+When a keyword argument is `nothing`, the default behaviour of the solver is used.
+    
+### Keywords 
+* `alias_p::Union{Bool, Nothing}`
+* `alias_f::Union{Bool, Nothing}`
+* `alias_u0::Union{Bool, Nothing}`: alias the u0 array.
+* `alias_du0::Union{Bool, Nothing}`: alias the du0 array for DAEs. Defaults to false.
+* `alias_tstops::Union{Bool, Nothing}`: alias the tstops array
+* `alias::Union{Bool, Nothing}`: sets all fields of the `AnalyticalAliasSpecifier` to `alias`
+
+"""
+struct AnalyticalAliasSpecifier <: AbstractAliasSpecifier
+    alias_p::Union{Bool, Nothing}
+    alias_f::Union{Bool, Nothing}
+    alias_u0::Union{Bool, Nothing}
+    alias_du0::Union{Bool, Nothing}
+    alias_tstops::Union{Bool, Nothing}
+
+    function AnalyticalAliasSpecifier(;
+            alias_p = nothing, alias_f = nothing, alias_u0 = nothing,
+            alias_du0 = nothing, alias_tstops = nothing, alias = nothing)
+        if alias == true
+            new(true, true, true, true, true)
+        elseif alias == false
+            new(false, false, false, false, false)
+        elseif isnothing(alias)
+            new(alias_p, alias_f, alias_u0, alias_du0, alias_tstops)
+        end
+    end
+end
+
+

src/problems/bvp_problems.jl

@@ -438,3 +438,42 @@ function TwoPointSecondOrderBVProblem(
     u0 = [initialGuess(i) for i in tspan]
     return TwoPointSecondOrderBVProblem(f, bc, u0, (tspan[1], tspan[end]), p; kwargs...)
 end
+
+@doc doc"""
+
+Holds information on what variables to alias
+when solving an BVP. Conforms to the AbstractAliasSpecifier interface. 
+    `BVPAliasSpecifier(;alias_p = nothing, alias_f = nothing, alias_u0 = nothing, alias_du0 = nothing, alias_tstops = nothing, alias = nothing)`
+
+When a keyword argument is `nothing`, the default behaviour of the solver is used.
+
+### Keywords 
+* `alias_p::Union{Bool, Nothing}`
+* `alias_f::Union{Bool, Nothing}`
+* `alias_u0::Union{Bool, Nothing}`: alias the u0 array. Defaults to false .
+* `alias_du0::Union{Bool, Nothing}`: alias the du0 array for DAEs. Defaults to false.
+* `alias_tstops::Union{Bool, Nothing}`: alias the tstops array
+* `alias::Union{Bool, Nothing}`: sets all fields of the `BVPAliasSpecifier` to `alias`
+
+"""
+struct BVPAliasSpecifier <: AbstractAliasSpecifier
+    alias_p::Union{Bool, Nothing}
+    alias_f::Union{Bool, Nothing}
+    alias_u0::Union{Bool, Nothing}
+    alias_du0::Union{Bool, Nothing}
+    alias_tstops::Union{Bool, Nothing}
+
+    function BVPAliasSpecifier(; alias_p = nothing, alias_f = nothing, alias_u0 = nothing,
+            alias_du0 = nothing, alias_tstops = nothing, alias = nothing)
+        if alias == true
+            new(true, true, true, true, true)
+        elseif alias == false
+            new(false, false, false, false, false)
+        elseif isnothing(alias)
+            new(alias_p, alias_f, alias_u0, alias_du0, alias_tstops)
+        end
+    end
+end
+
+
+

src/problems/dae_problems.jl

@@ -119,3 +119,42 @@ function ConstructionBase.constructorof(::Type{P}) where {P <: DAEProblem}
         return DAEProblem{iip}(f, du0, u0, tspan, p; differential_vars = dv, kw...)
     end
 end
+
+@doc doc"""
+
+Holds information on what variables to alias
+when solving a DAE. Conforms to the AbstractAliasSpecifier interface. 
+    `DAEAliasSpecifier(;alias_p = nothing, alias_f = nothing, alias_u0 = nothing, alias_du0 = nothing, alias_tstops = nothing, alias = nothing)`
+
+When a keyword argument is `nothing`, the default behaviour of the solver is used.
+
+### Keywords 
+* `alias_p::Union{Bool, Nothing}`
+* `alias_f::Union{Bool, Nothing}`
+* `alias_u0::Union{Bool, Nothing}`: alias the u0 array. Defaults to false.
+* `alias_du0::Union{Bool, Nothing}`: alias the du0 array for DAEs. Defaults to false.
+* `alias_tstops::Union{Bool, Nothing}`: alias the tstops array
+* `alias::Union{Bool, Nothing}`: sets all fields of the `DAEAliasSpecifier` to `alias`
+
+"""
+struct DAEAliasSpecifier
+    alias_p::Union{Bool, Nothing}
+    alias_f::Union{Bool, Nothing}
+    alias_u0::Union{Bool, Nothing}
+    alias_du0::Union{Bool, Nothing}
+    alias_tstops::Union{Bool, Nothing}
+
+    function DAEAliasSpecifier(; alias_p = nothing, alias_f = nothing, alias_u0 = nothing,
+            alias_du0 = nothing, alias_tstops = nothing, alias = nothing)
+        if alias == true
+            new(true, true, true, true, true)
+        elseif alias == false
+            new(false, false, false, false, false)
+        elseif isnothing(alias)
+            new(alias_p, alias_f, alias_u0, alias_du0, alias_tstops)
+        end
+    end
+end
+
+
+

src/problems/dde_problems.jl

@@ -396,3 +396,41 @@ function SecondOrderDDEProblem(f::DynamicalDDEFunction, args...; kwargs...)
             kwargs...)
     end
 end
+
+
+@doc doc"""
+
+Holds information on what variables to alias
+when solving a DDE. Conforms to the AbstractAliasSpecifier interface. 
+    `DDEAliasSpecifier(;alias_p = nothing, alias_f = nothing, alias_u0 = nothing, alias_du0 = nothing, alias_tstops = nothing, alias = nothing)`
+
+When a keyword argument is `nothing`, the default behaviour of the solver is used.
+
+### Keywords 
+* `alias_p::Union{Bool, Nothing}`
+* `alias_f::Union{Bool, Nothing}`
+* `alias_u0::Union{Bool, Nothing}`: alias the u0 array. Defaults to false .
+* `alias_du0::Union{Bool, Nothing}`: alias the du0 array for DAEs. Defaults to false.
+* `alias_tstops::Union{Bool, Nothing}`: alias the tstops array
+* `alias::Union{Bool, Nothing}`: sets all fields of the `DDEAliasSpecifier` to `alias`
+
+"""
+struct DDEAliasSpecifier
+    alias_p::Union{Bool, Nothing}
+    alias_f::Union{Bool, Nothing}
+    alias_u0::Union{Bool, Nothing}
+    alias_tstops::Union{Bool, Nothing}
+
+    function DDEAliasSpecifier(; alias_p = nothing, alias_f = nothing, alias_u0 = nothing,
+            alias_du0 = nothing, alias_tstops = nothing, alias = nothing)
+        if alias == true
+            new(true, true, true, true, true)
+        elseif alias == false
+            new(false, false, false, false, false)
+        elseif isnothing(alias)
+            new(alias_p, alias_f, alias_u0, alias_du0, alias_tstops)
+        end
+    end
+end
+
+

src/problems/discrete_problems.jl

@@ -153,3 +153,39 @@ function DiscreteProblem(u0::Union{AbstractArray, Number}, tspan::Tuple,
     end
     DiscreteProblem(f, u0, tspan, p; kwargs...)
 end
+
+@doc doc"""
+
+Holds information on what variables to alias
+when solving a DiscreteProblem. Conforms to the AbstractAliasSpecifier interface. 
+    `DiscreteAliasSpecifier(;alias_p = nothing, alias_f = nothing, alias_u0 = nothing, alias = nothing)`
+
+When a keyword argument is `nothing`, the default behaviour of the solver is used.
+
+### Keywords 
+* `alias_p::Union{Bool, Nothing}`
+* `alias_f::Union{Bool, Nothing}`
+* `alias_u0::Union{Bool, Nothing}`: alias the u0 array. Defaults to false .
+* `alias::Union{Bool, Nothing}`: sets all fields of the `DiscreteAliasSpecifier` to `alias`
+
+"""
+struct DiscreteAliasSpecifier
+    alias_p::Union{Bool, Nothing}
+    alias_f::Union{Bool, Nothing}
+    alias_u0::Union{Bool, Nothing}
+
+    function DiscreteAliasSpecifier(;
+            alias_p = nothing, alias_f = nothing, alias_u0 = nothing,
+            alias_du0 = nothing, alias = nothing)
+        if alias == true
+            new(true, true, true, true, true)
+        elseif alias == false
+            new(false, false, false, false, false)
+        elseif isnothing(alias)
+            new(alias_p, alias_f, alias_u0)
+        end
+    end
+end
+
+
+

src/problems/implicit_discrete_problems.jl

@@ -119,3 +119,38 @@ function ImplicitDiscreteProblem(f, u0, tspan, p = NullParameters();
     iip = isinplace(f, 6)
     ImplicitDiscreteProblem(ImplicitDiscreteFunction{iip}(f), u0, tspan, p; kwargs...)
 end
+
+@doc doc"""
+
+Holds information on what variables to alias
+when solving an ODE. Conforms to the AbstractAliasSpecifier interface. 
+    `DiscreteAliasSpecifier(;alias_p = nothing, alias_f = nothing, alias_u0 = nothing, alias = nothing)`
+
+When a keyword argument is `nothing`, the default behaviour of the solver is used.
+
+### Keywords 
+* `alias_p::Union{Bool, Nothing}`
+* `alias_f::Union{Bool, Nothing}`
+* `alias_u0::Union{Bool, Nothing}`: alias the u0 array. Defaults to false .
+* `alias::Union{Bool, Nothing}`: sets all fields of the `ImplicitDiscreteAliasSpecifier` to `alias`
+
+"""
+struct ImplicitDiscreteAliasSpecifier
+    alias_p::Union{Bool,Nothing}
+    alias_f::Union{Bool, Nothing}
+    alias_u0::Union{Bool, Nothing}
+
+    function ImplicitDiscreteAliasSpecifier(;
+            alias_p = nothing, alias_f = nothing, alias_u0 = nothing,
+            alias_du0 = nothing, alias = nothing)
+        if alias == true
+            new(true, true, true, true, true)
+        elseif alias == false
+            new(false, false, false, false, false)
+        elseif isnothing(alias)
+            new(alias_p, alias_f, alias_u0)
+        end
+    end
+end
+
+

src/problems/integral_problems.jl

@@ -167,3 +167,34 @@ struct SampledIntegralProblem{Y, X, K} <: AbstractIntegralProblem{false}
         new{typeof(y), typeof(x), typeof(kwargs)}(y, x, dim, kwargs)
     end
 end
+
+@doc doc"""
+
+Holds information on what variables to alias
+when solving an IntegralProblem. Conforms to the AbstractAliasSpecifier interface. 
+    `IntegralAliasSpecifier(;alias_p = nothing, alias_f = nothing, alias_u0 = nothing, alias = nothing)``
+
+When a keyword argument is `nothing`, the default behaviour of the solver is used.
+
+### Keywords 
+* `alias_p::Union{Bool, Nothing}`
+* `alias_f::Union{Bool, Nothing}`
+* `alias::Union{Bool, Nothing}`: sets all fields of the `IntegralAliasSpecifier` to `alias`
+
+"""
+struct IntegralAliasSpecifier <: AbstractAliasSpecifier
+    alias_p::Union{Bool, Nothing}
+    alias_f::Union{Bool, Nothing}
+
+    function IntegralAliasSpecifier(alias_p = nothing, alias_f = nothing, alias = nothing)
+        if alias == true
+            new(true, true)
+        elseif alias == false
+            new(false, false)
+        elseif isnothing(alias)
+            new(alias_p, alias_f)
+        end
+    end
+end
+
+

src/problems/linear_problems.jl

@@ -76,3 +76,39 @@ function LinearProblem(A, b, args...; kwargs...)
         LinearProblem{isinplace(A, 4)}(A, b, args...; kwargs...)
     end
 end
+
+@doc doc"""
+Holds information on what variables to alias
+when solving a LinearProblem. Conforms to the AbstractAliasSpecifier interface. 
+    `LinearAliasSpecifier(;alias_p = nothing, alias_f = nothing, alias_A = nothing, alias_b = nothing, alias = nothing)`
+
+When a keyword argument is `nothing`, the default behaviour of the solver is used.
+
+### Keywords
+
+* `alias_p::Union{Bool, Nothing}`
+* `alias_f::Union{Bool, Nothing}`
+* `alias_A::Union{Bool, Nothing}`: alias the `A` array.
+* `alias_b::Union{Bool, Nothing}`: alias the `b` array. 
+* `alias::Union{Bool, Nothing}`: sets all fields of the `LinearAliasSpecifier` to `alias`. 
+
+Creates a `LinearAliasSpecifier` where `alias_A` and `alias_b` default to `nothing`.
+When `alias_A` or `alias_b` is nothing, the default value of the solver is used.
+"""
+struct LinearAliasSpecifier <: AbstractAliasSpecifier
+    alias_A::Union{Bool,Nothing}
+    alias_b::Union{Bool,Nothing}
+
+    function LinearAliasSpecifier(; alias_A = nothing, alias_b = nothing,
+            alias_p = nothing, alias_f = nothing, alias = nothing)
+        if alias == true
+            new(true, true, true, true)
+        elseif alias == false
+            new(false, false, false, false)
+        elseif isnothing(alias)
+            new(alias_p, alias_f, alias_A, alias_b)
+        end
+    end
+end
+
+

src/problems/nonlinear_problems.jl

@@ -549,3 +549,36 @@ function SymbolicIndexingInterface.set_parameter!(prob::SCCNonlinearProblem, val
         set_parameter!(scc, val, idx)
     end
 end
+
+@doc doc"""
+Holds information on what variables to alias when solving a `NonlinearProblem`. 
+Conforms to the AbstractAliasSpecifier interface. 
+    `NonlinearAliasSpecifier(;alias_p = nothing, alias_f = nothing, alias_u0 = nothing, alias = nothing)`
+
+When a keyword argument is `nothing`, the default behaviour of the solver is used.
+
+### Keywords
+
+* `alias_p::Union{Bool, Nothing}`
+* `alias_f::Union{Bool, Nothing}`
+* `alias_u0::Union{Bool, Nothing}`: alias the `u0` array.
+* `alias::Union{Bool, Nothing}`: sets all fields of the `NonlinearAliasSpecifier` to `alias`. 
+"""
+
+struct NonlinearAliasSpecifier <: AbstractAliasSpecifier
+    alias_p::Union{Bool,Nothing}
+    alias_f::Union{Bool,Nothing}
+    alias_u0::Union{Bool,Nothing}
+
+    function NonlinearAliasSpecifier(;
+            alias_p = nothing, alias_f = nothing, alias_u0 = nothing, alias = nothing)
+        if isnothing(alias)
+            new(alias_p, alias_f, alias_u0)
+        elseif alias
+            new(true, true, true)
+        elseif !alias
+            new(false, false, false)
+        end
+    end
+end
+