Add DelayParentScope scoping utility (#1951)

Author: jamesjscully

docs/src/basics/Composition.md

@@ -133,7 +133,7 @@ With symbolic parameters, it is possible to set the default value of a parameter
 # ...
 sys = ODESystem(
     # ...
-    # directly in the defauls argument
+    # directly in the defaults argument
     defaults=Pair{Num, Any}[
     x => u,
     y => σ,
@@ -146,12 +146,41 @@ sys.y = u*1.1
 In a hierarchical system, variables of the subsystem get namespaced by the name of the system they are in. This prevents naming clashes, but also enforces that every state and parameter is local to the subsystem it is used in. In some cases it might be desirable to have variables and parameters that are shared between subsystems, or even global. This can be accomplished as follows.
 
 ```julia
-@variables a b c d
+@parameters t a b c d e f
+p = [
+    a #a is a local variable
+    ParentScope(b) # b is a variable that belongs to one level up in the hierarchy
+    ParentScope(ParentScope(c))# ParentScope can be nested
+    DelayParentScope(d) # skips one level before applying ParentScope
+    DelayParentScope(e,2) # second argument allows skipping N levels
+    GlobalScope(f) # global variables will never be namespaced
+]
 
-# a is a local variable
-b = ParentScope(b) # b is a variable that belongs to one level up in the hierarchy
-c = ParentScope(ParentScope(c)) # ParentScope can be nested
-d = GlobalScope(d) # global variables will never be namespaced
+level0 = ODESystem(Equation[],t,[],p; name = :level0)
+level1 = ODESystem(Equation[],t,[],[];name = :level1) ∘ level0
+parameters(level1)
+  #level0₊a
+  #b
+  #c
+  #level0₊d
+  #level0₊e
+  #f
+level2 = ODESystem(Equation[],t,[],[];name = :level2) ∘ level1
+parameters(level2)
+  #level1₊level0₊a
+  #level1₊b
+  #c
+  #level0₊d
+  #level1₊level0₊e
+  #f
+level3 = ODESystem(Equation[],t,[],[];name = :level3) ∘ level2
+parameters(level3)
+  #level2₊level1₊level0₊a
+  #level2₊level1₊b
+  #level2₊c
+  #level2₊level0₊d
+  #level1₊level0₊e
+  #f
 ```
 
 ## Structural Simplify

src/ModelingToolkit.jl

@@ -200,7 +200,7 @@ export PDESystem
 export Differential, expand_derivatives, @derivatives
 export Equation, ConstrainedEquation
 export Term, Sym
-export SymScope, LocalScope, ParentScope, GlobalScope
+export SymScope, LocalScope, ParentScope, DelayParentScope, GlobalScope
 export independent_variables, independent_variable, states, parameters, equations, controls,
        observed, structure, full_equations
 export structural_simplify, expand_connections, linearize, linearization_function

src/systems/abstractsystem.jl

@@ -364,6 +364,16 @@ function ParentScope(sym::Union{Num, Symbolic})
     setmetadata(sym, SymScope, ParentScope(getmetadata(value(sym), SymScope, LocalScope())))
 end
 
+struct DelayParentScope <: SymScope
+    parent::SymScope
+    N::Int
+end
+function DelayParentScope(sym::Union{Num, Symbolic}, N)
+    setmetadata(sym, SymScope,
+                DelayParentScope(getmetadata(value(sym), SymScope, LocalScope()), N))
+end
+DelayParentScope(sym::Union{Num, Symbolic}) = DelayParentScope(sym, 1)
+
 struct GlobalScope <: SymScope end
 GlobalScope(sym::Union{Num, Symbolic}) = setmetadata(sym, SymScope, GlobalScope())
 
@@ -382,6 +392,15 @@ function renamespace(sys, x)
                 rename(x, renamespace(getname(sys), getname(x)))
             elseif scope isa ParentScope
                 setmetadata(x, SymScope, scope.parent)
+            elseif scope isa DelayParentScope
+                if scope.N > 0
+                    x = setmetadata(x, SymScope,
+                                    DelayParentScope(scope.parent, scope.N - 1))
+                    rename(x, renamespace(getname(sys), getname(x)))
+                else
+                    #rename(x, renamespace(getname(sys), getname(x)))
+                    setmetadata(x, SymScope, scope.parent)
+                end
             else # GlobalScope
                 x
             end

test/variable_scope.jl

@@ -44,3 +44,25 @@ end
 @test renamed([:foo :bar :baz], b) == Symbol("foo₊bar₊b")
 @test renamed([:foo :bar :baz], c) == Symbol("foo₊c")
 @test renamed([:foo :bar :baz], d) == :d
+
+@parameters t a b c d e f
+p = [a
+     ParentScope(b)
+     ParentScope(ParentScope(c))
+     DelayParentScope(d)
+     DelayParentScope(e, 2)
+     GlobalScope(f)]
+
+level0 = ODESystem(Equation[], t, [], p; name = :level0)
+level1 = ODESystem(Equation[], t, [], []; name = :level1) ∘ level0
+level2 = ODESystem(Equation[], t, [], []; name = :level2) ∘ level1
+level3 = ODESystem(Equation[], t, [], []; name = :level3) ∘ level2
+
+ps = ModelingToolkit.getname.(parameters(level3))
+
+@test isequal(ps[1], :level2₊level1₊level0₊a)
+@test isequal(ps[2], :level2₊level1₊b)
+@test isequal(ps[3], :level2₊c)
+@test isequal(ps[4], :level2₊level0₊d)
+@test isequal(ps[5], :level1₊level0₊e)
+@test isequal(ps[6], :f)