|
| 1 | +# ModelingToolkit v10 Release Notes |
| 2 | + |
| 3 | +## Callbacks |
| 4 | + |
| 5 | +Callback semantics have changed. |
| 6 | + |
| 7 | + - There is a new `Pre` operator that is used to specify which values are before the callback. |
| 8 | + For example, the affect `A ~ A + 1` should now be written as `A ~ Pre(A) + 1`. This is |
| 9 | + **required** to be specified - `A ~ A + 1` will now be interpreted as an equation to be |
| 10 | + satisfied after the callback (and will thus error since it is unsatisfiable). |
| 11 | + |
| 12 | + - All parameters that are changed by a callback must be declared as discrete parameters to |
| 13 | + the callback constructor, using the `discrete_parameters` keyword argument. |
| 14 | + |
| 15 | +```julia |
| 16 | +event = SymbolicDiscreteCallback( |
| 17 | + [t == 1] => [p ~ Pre(p) + 1], discrete_parameters = [p]) |
| 18 | +``` |
| 19 | + |
| 20 | +## New `mtkcompile` and `@mtkcompile` |
| 21 | + |
| 22 | +`structural_simplify` is now renamed to `mtkcompile`. `@mtkbuild` is renamed to |
| 23 | +`@mtkcompile`. Their functionality remains the same. However, instead of a second |
| 24 | +positional argument `structural_simplify(sys, (inputs, outputs))` the inputs and outputs |
| 25 | +should be specified via keyword arguments as `mtkcompile(sys; inputs, outputs, disturbance_inputs)`. |
| 26 | + |
| 27 | +## Reduce reliance on metadata in `mtkcompile` |
| 28 | + |
| 29 | +Previously, `mtkcompile` (formerly `structural_simplify`) used to rely on the metadata of |
| 30 | +symbolic variables to identify variables/parameters/brownians. This was regardless of |
| 31 | +what the system expected the variable to be. Now, it respects the information in the system. |
| 32 | + |
| 33 | +## Unified `System` type |
| 34 | + |
| 35 | +There is now a single common `System` type for all types of models except PDEs, for which |
| 36 | +`PDESystem` still exists. It follows the same syntax as `ODESystem` and `NonlinearSystem` |
| 37 | +did. `System(equations, t[, vars, pars])` will construct a time-dependent system. |
| 38 | +`System(equations[, vars, pars])` will construct a time-independent system. Refer to the |
| 39 | +docstring for `System` for further information. |
| 40 | + |
| 41 | +Utility constructors are defined for: |
| 42 | + |
| 43 | + - `NonlinearSystem(sys)` to convert a time-dependent system to a time-independent one for |
| 44 | + its steady state. |
| 45 | + - `SDESystem(sys, noise_eqs)` to add noise to a system |
| 46 | + - `JumpSystem(jumps, ...)` to define a system with jumps. Note that normal equations can |
| 47 | + also be passed to `jumps`. |
| 48 | + - `OptimizationSystem(cost, ...)` to define a system for optimization. |
| 49 | + |
| 50 | +All problem constructors validate that the system matches the expected structure for |
| 51 | +that problem. |
| 52 | + |
| 53 | +## No more `parameter_dependencies` |
| 54 | + |
| 55 | +The `parameter_dependencies` keyword is deprecated. All equations previously passed here |
| 56 | +should now be provided as part of the standard equations of the system. If passing parameters |
| 57 | +explicitly to the `System` constructor, the dependent parameters (on the left hand side of |
| 58 | +parameter dependencies) should also be provided. These will be separated out when calling |
| 59 | +`complete` or `mtkcompile`. Calling `parameter_dependencies` or `dependent_parameters` now |
| 60 | +requires that the system is completed. The new `SDESystem` constructor still retains the |
| 61 | +`parameter_dependencies` keyword argument since the number of equations has to match the |
| 62 | +number of columns in `noise_eqs`. |
| 63 | + |
| 64 | +ModelingToolkit now has discretion of what parameters are eliminated using the parameter |
| 65 | +equations during `complete` or `mtkcompile`. |
| 66 | + |
| 67 | +## New problem and constructors |
| 68 | + |
| 69 | +Instead of `XProblem(sys, u0map, tspan, pmap)` for time-dependent problems and |
| 70 | +`XProblem(sys, u0map, pmap)` for time-independent problems, the syntax has changed to |
| 71 | +`XProblem(sys, op, tspan)` and `XProblem(sys, op)` respectively. `op` refers to the |
| 72 | +operating point, and is a variable-value mapping containing both unknowns and parameters. |
| 73 | + |
| 74 | +`XFunction` constructors also no longer accept the list of unknowns and parameters as |
| 75 | +positional arguments. |
| 76 | + |
| 77 | +## Removed `DelayParentScope` |
| 78 | + |
| 79 | +The outdated `DelayParentScope` has been removed. |
| 80 | + |
| 81 | +## Removed `XProblemExpr` and `XFunctionExpr` |
| 82 | + |
| 83 | +The old `XProblemExpr` and `XFunctionExpr` constructors used to build an `Expr` that |
| 84 | +constructs `XProblem` and `XFunction` respectively are now removed. This functionality |
| 85 | +is now available by passing `expression = Val{true}` to any problem or function constructor. |
| 86 | + |
| 87 | +## Renaming of `generate_*` and `calculate_*` methods |
| 88 | + |
| 89 | +Several `generate_*` methods have been renamed, along with some `calculate_*` methods. |
| 90 | +The `generate_*` methods also no longer accept a list of unknowns and/or parameters. Refer |
| 91 | +to the documentation for more information. |
| 92 | + |
| 93 | +## New behavior of `getproperty` and `setproperty!` |
| 94 | + |
| 95 | +Using `getproperty` to access fields of a system has been deprecated for a long time, and |
| 96 | +this functionality is now removed. `setproperty!` previously used to update the default |
| 97 | +of the accessed symbolic variable. This is not supported anymore. Defaults can be updated by |
| 98 | +mutating `ModelingToolkit.get_defaults(sys)`. |
| 99 | + |
| 100 | +## New behavior of `@constants` |
| 101 | + |
| 102 | +`@constants` now creates parameters with the `tunable = false` metadata by default. |
| 103 | + |
| 104 | +## Removed `FunctionalAffect` |
| 105 | + |
| 106 | +`FunctionalAffect` is now removed in favor of the new `ImperativeAffect`. Refer to the |
| 107 | +documentation for more information. |
| 108 | + |
| 109 | +## Improved system metadata |
| 110 | + |
| 111 | +Instead of an empty field that can contain arbitrary data, the `System` type stores metadata |
| 112 | +identically to `SymbolicUtils.BasicSymbolic`. Metadata is stored in an immutable dictionary |
| 113 | +keyed by a user-provided `DataType` and containing arbitrary values. `System` supports the |
| 114 | +same `SymbolicUtils.getmetadata` and `SymbolicUtils.setmetadata` API as symbolic variables. |
| 115 | +Refer to the documentation of `System` and the aforementioned functions for more information. |
| 116 | + |
| 117 | +## Moved `connect` and `Connector` to ModelingToolkit |
| 118 | + |
| 119 | +Previously ModelingToolkit used the `connect` function and `Connector` type defined in |
| 120 | +Symbolics.jl. These have now been moved to ModelingToolkit along with the experimental |
| 121 | +state machine API. If you imported them from Symbolics.jl, it is recommended to import from |
| 122 | +ModelingToolkit instead. |
| 123 | + |
| 124 | +## Always wrap with `ParentScope` in `@named` |
| 125 | + |
| 126 | +When creating a system using `@named`, any symbolic quantities passed as keyword arguments |
| 127 | +to the subsystem are wrapped in `ParentScope`. Previously, this would only happen if the |
| 128 | +variable wasn't already wrapped in a `ParentScope`. However, the old behavior had issues |
| 129 | +when passing symbolic quantities down multiple levels of the hierarchy. The `@named` macro |
| 130 | +now always performs this wrapping. |
| 131 | + |
1 | 132 | # ModelingToolkit v9 Release Notes |
2 | 133 |
|
3 | 134 | ### Upgrade guide |
|
0 commit comments