Merge pull request #2466 from AayushSabharwal/as/changelog

docs: update NEWS.md with v9 update notes

Author: ChrisRackauckas

NEWS.md

@@ -1,9 +1,40 @@
-# ModelingToolkit v8 Release Notes
+# ModelingToolkit v9 Release Notes
 
 ### Upgrade guide
 
-  - `connect` should not be overloaded by users anymore. `[connect = Flow]`
-    informs ModelingToolkit that particular variable in a connector ought to sum
-    to zero, and by default, variables are equal in a connection. Please check out
-    [acausal components tutorial](https://docs.sciml.ai/ModelingToolkit/stable/tutorials/acausal_components/)
-    for examples.
+- The function `states` is renamed to `unknowns`. In a similar vein:
+  - `unknown_states` is now `solved_unknowns`.
+  - `get_states` is `get_unknowns`.
+  - `get_unknown_states` is now `get_solved_unknowns`.
+- The default backend for using units in models is now `DynamicQuantities.jl` instead of
+  `Unitful.jl`.
+- ModelingToolkit.jl now exports common definitions of `t` (time independent variable)
+  and `D` (the first derivative with respect to `t`). Any models made using ModelingToolkit.jl
+  should leverage these common definitions. There are three variants:
+  - `t` and `D` use DynamicQuantities.jl units. This is the default for standard library
+    components.
+  - `t_unitful` and `D_unitful` use Unitful.jl units.
+  - `t_nounits` and `D_nounits` are unitless.
+- `ODAEProblem` is deprecated in favor of `ODEProblem`.
+- Specifying the independent variable for an `ODESystem` is now mandatory. The `ODESystem(eqs)`
+  constructor is removed.
+- Systems must be marked as `complete` before creating `*Function`/`*FunctionExpr`/`*Problem`/
+  `*ProblemExpr`. Typically this involved using `@mtkbuild` to create the system or calling
+  `structural_simplify` on an existing system.
+- All systems will perform parameter splitting by default. Problems created using ModelingToolkit.jl
+  systems will have a custom struct instead of a `Vector` of parameters. The internals of this
+  type are undocumented and subject to change without notice or a breaking release. Parameter values
+  can be queried, updated or manipulated using SciMLStructures.jl or SymbolicIndexingInterface.jl.
+  This also requires that the symbolic type of a parameter match its assigned value. For example,
+  `@parameters p` will always use a `Float64` value for `p`. To use `Int` instead, use
+  `@parameters p::Int`. Array-valued parameters must be array symbolics; `@parameters p = [1.0, 2.0]`
+  is now invalid and must be changed to `@parameters p[1:2] = [1.0, 2.0]`. The index of a parameter
+  in the system is also not guaranteed to be an `Int`, and will instead be a custom undocumented type.
+  To restore the old behavior:
+  - Pass the `split = false` keyword to `structural_simplify`. E.g. `ss = structural_simplify(sys; split = false)`.
+  - Pass `split = false` to `@mtkbuild`. E.g. `@mtkbuild sys = ODESystem(...) split = false`.
+- Discrete-time system using `Difference` are unsupported. Instead, use the new `Clock`-based syntax.
+- Automatic scalarization has been removed, meaning that vector variables need to be treated with proper vector
+  equations. For example, `[p[1] => 1.0, p[2] => 2.0]` is no longer allowed in default equations, use
+  `[p => [1.0, 2.0]]` instead. Also, array equations like for `@variables u[1:2]` have `D(u) ~ A*u` as an
+  array equation. If the scalarized version is desired, use `scalarize(u)`.

src/systems/abstractsystem.jl

@@ -376,8 +376,8 @@ $(TYPEDSIGNATURES)
 Mark a system as completed. If a system is complete, the system will no longer
 namespace its subsystems or variables, i.e. `isequal(complete(sys).v.i, v.i)`.
 """
-function complete(sys::AbstractSystem)
-    if has_index_cache(sys)
+function complete(sys::AbstractSystem; split = true)
+    if split && has_index_cache(sys)
         @set! sys.index_cache = IndexCache(sys)
     end
     isdefined(sys, :complete) ? (@set! sys.complete = true) : sys
@@ -1388,12 +1388,19 @@ macro component(expr)
     esc(component_post_processing(expr, false))
 end
 
-macro mtkbuild(expr)
+macro mtkbuild(exprs...)
+    expr = exprs[1]
     named_expr = ModelingToolkit.named_expr(expr)
     name = named_expr.args[1]
+    kwargs = if length(exprs) > 1
+        NamedTuple{Tuple(ex.args[1] for ex in Base.tail(exprs))}(Tuple(ex.args[2] for ex in Base.tail(exprs)))
+    else
+        (;)
+    end
+        @show kwargs
     esc(quote
         $named_expr
-        $name = $structural_simplify($name)
+        $name = $structural_simplify($name; $(kwargs)...)
     end)
 end
 

src/systems/diffeqs/abstractodesystem.jl

@@ -793,7 +793,7 @@ function process_DEProblem(constructor, sys::AbstractODESystem, u0map, parammap;
     ps = parameters(sys)
     iv = get_iv(sys)
 
-    u0, _, defs = get_u0_p(sys,
+    u0, _p, defs = get_u0_p(sys,
         u0map,
         parammap;
         tofloat,
@@ -803,7 +803,11 @@ function process_DEProblem(constructor, sys::AbstractODESystem, u0map, parammap;
         u0 = u0_constructor(u0)
     end
 
-    p = MTKParameters(sys, parammap)
+    if has_index_cache(sys) && get_index_cache(sys) !== nothing
+        p = MTKParameters(sys, parammap)
+    else
+        p = _p
+    end
 
     if implicit_dae && du0map !== nothing
         ddvs = map(Differential(iv), dvs)

src/systems/nonlinear/nonlinearsystem.jl

@@ -355,7 +355,9 @@ function process_NonlinearProblem(constructor, sys::NonlinearSystem, u0map, para
     ps = parameters(sys)
 
     u0, p, defs = get_u0_p(sys, u0map, parammap; tofloat, use_union)
-    p = MTKParameters(sys, parammap)
+    if has_index_cache(sys) && get_index_cache(sys) !== nothing
+        p = MTKParameters(sys, parammap)
+    end
     check_eqs_u0(eqs, dvs, u0; kwargs...)
 
     f = constructor(sys, dvs, ps, u0; jac = jac, checkbounds = checkbounds,

src/systems/optimization/optimizationsystem.jl

@@ -631,7 +631,7 @@ function OptimizationProblemExpr{iip}(sys::OptimizationSystem, u0map,
     end
 end
 
-function structural_simplify(sys::OptimizationSystem; kwargs...)
+function structural_simplify(sys::OptimizationSystem; split = true, kwargs...)
     sys = flatten(sys)
     cons = constraints(sys)
     econs = Equation[]
@@ -658,6 +658,6 @@ function structural_simplify(sys::OptimizationSystem; kwargs...)
     neweqs = fixpoint_sub.(equations(sys), (subs,))
     @set! sys.op = length(neweqs) == 1 ? first(neweqs) : neweqs
     @set! sys.unknowns = newsts
-    sys = complete(sys)
+    sys = complete(sys; split)
     return sys
 end

src/systems/systems.jl

@@ -16,7 +16,7 @@ The optional argument `io` may take a tuple `(inputs, outputs)`.
 This will convert all `inputs` to parameters and allow them to be unconnected, i.e.,
 simplification will allow models where `n_unknowns = n_equations - n_inputs`.
 """
-function structural_simplify(sys::AbstractSystem, io = nothing; simplify = false,
+function structural_simplify(sys::AbstractSystem, io = nothing; simplify = false, split = true,
         kwargs...)
     newsys′ = __structural_simplify(sys, io; simplify, kwargs...)
     if newsys′ isa Tuple
@@ -25,8 +25,8 @@ function structural_simplify(sys::AbstractSystem, io = nothing; simplify = false
     else
         newsys = newsys′
     end
-    @set! newsys.parent = complete(sys)
-    newsys = complete(newsys)
+    @set! newsys.parent = complete(sys; split)
+    newsys = complete(newsys; split)
     if newsys′ isa Tuple
         idxs = [parameter_index(newsys, i) for i in io[1]]
         return newsys, idxs