docs: define the AbstractSystem implementation contract

docs/src/API/abstract_system_interface.md

@@ -40,9 +40,8 @@ The following rules apply to every subtype:
     is itself an `AbstractSystem`. It never returns transitive descendants.
   - The hierarchy reachable through [`ModelingToolkit.get_systems`](@ref) must be finite and
     acyclic. Every generic accessor below recurses through it without cycle detection.
-  - Systems are treated as immutable values. A generic function may retain, compare, or hash
-    a system, and may assume that a system it received earlier still describes the same
-    model.
+  - Generic accessors do not mutate a system. Treat the system and the collections returned
+    by its accessors as read-only unless a function explicitly documents a mutating operation.
 
 ## Optional Storage and the `has_x`/`get_x` Protocol
 

lib/ModelingToolkitBase/src/ModelingToolkitBase.jl

@@ -189,7 +189,38 @@ in a non-breaking release. Usage of these arguments is not advised.
 """
 $(TYPEDEF)
 
-Abstract supertype of all system types. Any custom system types must subtype this.
+Abstract supertype of all system types.
+
+Custom system types must subtype `AbstractSystem` and implement the required structural
+interface:
+
+- `nameof(sys)::Symbol` must identify the system within its parent's subsystem list.
+- `get_systems(sys)::Vector{<:AbstractSystem}` must return the direct, finite, acyclic
+  subsystem hierarchy.
+
+Both requirements default to fields named `name` and `systems`, respectively. Additional
+system data is optional. Generic code must use the public `has_x`/`get_x` accessors described
+in the [AbstractSystem interface](@ref abstract_system_interface), rather than depending on
+the fields of `System` or another concrete subtype. A custom type may extend the documented
+generic accessors, including `independent_variable`, when its storage does not match those
+defaults; it should not extend internal compilation or problem-construction functions.
+
+# Examples
+
+A minimal custom system can participate in generic hierarchy traversal without implementing
+any methods:
+
+```julia
+struct CustomSystem <: AbstractSystem
+    name::Symbol
+    systems::Vector{AbstractSystem}
+end
+
+leaf = CustomSystem(:leaf, AbstractSystem[])
+root = CustomSystem(:root, AbstractSystem[leaf])
+nameof(root)
+get_systems(root)
+```
 """
 abstract type AbstractSystem end
 # Solely so that `ODESystem` can be deprecated and still act as a valid type.

lib/ModelingToolkitBase/test/abstractsystem_interface.jl

@@ -15,7 +15,7 @@ D = Differential(t)
 "A subtype carrying only the two required fields."
 struct MinimalSystem <: MT.AbstractSystem
     name::Symbol
-    systems::Vector
+    systems::Vector{MT.AbstractSystem}
 end
 
 "A subtype carrying the optional fields backing the equation/unknown/parameter accessors."
@@ -25,32 +25,32 @@ struct ComponentSystem <: MT.AbstractSystem
     ps::Vector
     iv::Any
     name::Symbol
-    systems::Vector
+    systems::Vector{MT.AbstractSystem}
 end
 
 "A subtype which supplies its independent variable through the scalar extension point."
 struct RenamedIVSystem <: MT.AbstractSystem
     time::Any
     name::Symbol
-    systems::Vector
+    systems::Vector{MT.AbstractSystem}
 end
 MT.independent_variable(sys::RenamedIVSystem) = getfield(sys, :time)
 
-leaf = ComponentSystem([D(x) ~ p * x], [x], [p], t, :leaf, [])
-branch = ComponentSystem([D(y) ~ q * y], [y], [q], t, :branch, [leaf])
-root = ComponentSystem(Equation[], [], [], t, :root, [branch])
+leaf = ComponentSystem([D(x) ~ p * x], [x], [p], t, :leaf, MT.AbstractSystem[])
+branch = ComponentSystem([D(y) ~ q * y], [y], [q], t, :branch, MT.AbstractSystem[leaf])
+root = ComponentSystem(Equation[], [], [], t, :root, MT.AbstractSystem[branch])
 
 @testset "Required surface" begin
-    sys = MinimalSystem(:sys, [])
+    sys = MinimalSystem(:sys, MT.AbstractSystem[])
     @test nameof(sys) === :sys
     @test isempty(MT.get_systems(sys))
 
-    parent = MinimalSystem(:parent, [sys])
+    parent = MinimalSystem(:parent, MT.AbstractSystem[sys])
     @test map(nameof, MT.get_systems(parent)) == [:sys]
 end
 
 @testset "Accessors defaulted for absent optional fields" begin
-    sys = MinimalSystem(:sys, [])
+    sys = MinimalSystem(:sys, MT.AbstractSystem[])
     @test MT.independent_variable(sys) === nothing
     @test isempty(independent_variables(sys))
     @test MT.description(sys) == ""
@@ -64,7 +64,7 @@ end
 end
 
 @testset "`has_x` reports optional field availability" begin
-    minimal = MinimalSystem(:sys, [])
+    minimal = MinimalSystem(:sys, MT.AbstractSystem[])
 
     @test MT.has_name(minimal)
     @test MT.has_name(leaf)
@@ -84,9 +84,9 @@ end
     @test isequal(MT.get_iv(leaf), t)
 
     # `get_x` on absent storage throws, so generic code has to guard it with `has_x`.
-    @test_throws ErrorException MT.get_eqs(minimal)
-    @test_throws ErrorException MT.get_unknowns(minimal)
-    @test_throws ErrorException MT.get_ps(minimal)
+    @test_throws FieldError MT.get_eqs(minimal)
+    @test_throws FieldError MT.get_unknowns(minimal)
+    @test_throws FieldError MT.get_ps(minimal)
 
     # The event accessors are the documented exceptions: they default to empty.
     @test MT.has_continuous_events(minimal) == false
@@ -96,7 +96,7 @@ end
 end
 
 @testset "Scalar independent variable extension point" begin
-    sys = RenamedIVSystem(t, :sys, [])
+    sys = RenamedIVSystem(t, :sys, MT.AbstractSystem[])
     @test isequal(MT.independent_variable(sys), t)
     @test isequal(independent_variables(sys), [t])
     @test isequal(SII.independent_variable_symbols(sys), [t])
@@ -140,7 +140,9 @@ end
 end
 
 @testset "Equation classification" begin
-    algebraic = ComponentSystem([0 ~ p - x], [x], [p], t, :algebraic, [])
+    algebraic = ComponentSystem(
+        [0 ~ p - x], [x], [p], t, :algebraic, MT.AbstractSystem[]
+    )
 
     @test has_diff_equations(leaf)
     @test !has_alg_equations(leaf)