From 97e23d6589c791873ce89654107dede1e2154826 Mon Sep 17 00:00:00 2001 From: Aayush Sabharwal Date: Mon, 11 Aug 2025 05:50:52 +0530 Subject: [PATCH 01/12] refactor: make `AbstractSystem` public, add docs --- docs/src/API/System.md | 1 + src/ModelingToolkit.jl | 3 ++- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/src/API/System.md b/docs/src/API/System.md index 379e7fa19b..7620014b19 100644 --- a/docs/src/API/System.md +++ b/docs/src/API/System.md @@ -7,6 +7,7 @@ optimizations). ```@docs System +ModelingToolkit.AbstractSystem ``` ## Utility constructors diff --git a/src/ModelingToolkit.jl b/src/ModelingToolkit.jl index 1dbf9d37dd..0a7b999cc3 100644 --- a/src/ModelingToolkit.jl +++ b/src/ModelingToolkit.jl @@ -134,7 +134,7 @@ in a non-breaking release. Usage of these arguments is not advised. """ $(TYPEDEF) -TODO +Abstract supertype of all system types. Any custom system types must subtype this. """ abstract type AbstractSystem end # Solely so that `ODESystem` can be deprecated and still act as a valid type. @@ -336,6 +336,7 @@ export DynamicOptSolution @public is_diff_equation, Equality, linearize_symbolic, reorder_unknowns @public similarity_transform, inputs, outputs, bound_inputs, unbound_inputs, bound_outputs @public unbound_outputs, is_bound +@public AbstractSystem for prop in [SYS_PROPS; [:continuous_events, :discrete_events]] getter = Symbol(:get_, prop) From d4f4af628af4c82c75d4ab6fdaf2370f396e6be0 Mon Sep 17 00:00:00 2001 From: Aayush Sabharwal Date: Mon, 11 Aug 2025 06:05:13 +0530 Subject: [PATCH 02/12] refactor: document `check` keyword flags, mark as public --- docs/src/API/System.md | 14 ++++++++++++++ src/ModelingToolkit.jl | 2 +- src/utils.jl | 22 ++++++++++++++++++++++ 3 files changed, 37 insertions(+), 1 deletion(-) diff --git a/docs/src/API/System.md b/docs/src/API/System.md index 7620014b19..b5dd08bdc7 100644 --- a/docs/src/API/System.md +++ b/docs/src/API/System.md @@ -186,3 +186,17 @@ ModelingToolkit.is_bound ```@docs debug_system ``` + +## Input validation + +The following values can be passed to the `check` keyword of `System` to toggle validation +of input. Flags can be combined with bitwise `|` and `&`. + +```@docs +ModelingToolkit.CheckAll +ModelingToolkit.CheckNone +ModelingToolkit.CheckComponents +ModelingToolkit.CheckUnits +``` + +These can also be used by custom `AbstractSystem` subtypes. diff --git a/src/ModelingToolkit.jl b/src/ModelingToolkit.jl index 0a7b999cc3..800ae899da 100644 --- a/src/ModelingToolkit.jl +++ b/src/ModelingToolkit.jl @@ -336,7 +336,7 @@ export DynamicOptSolution @public is_diff_equation, Equality, linearize_symbolic, reorder_unknowns @public similarity_transform, inputs, outputs, bound_inputs, unbound_inputs, bound_outputs @public unbound_outputs, is_bound -@public AbstractSystem +@public AbstractSystem, CheckAll, CheckNone, CheckComponents, CheckUnits for prop in [SYS_PROPS; [:continuous_events, :discrete_events]] getter = Symbol(:get_, prop) diff --git a/src/utils.jl b/src/utils.jl index d028d4ed18..8ec9def5e9 100644 --- a/src/utils.jl +++ b/src/utils.jl @@ -88,9 +88,31 @@ function readable_code(expr) end # System validation enums +""" + const CheckNone + +Value that can be provided to the `check` keyword of `System` to disable checking of input. +""" const CheckNone = 0 +""" + const CheckAll + +Value that can be provided to the `check` keyword of `System` to enable all input +validation. +""" const CheckAll = 1 << 0 +""" + const CheckComponents + +Value that can be provided to the `check` keyword of `System` to only enable checking of +basic components of the system, such as equations, variables, etc. +""" const CheckComponents = 1 << 1 +""" + const CheckUnits + +Value that can be provided to the `check` keyword of `System` to enable checking of units. +""" const CheckUnits = 1 << 2 function check_independent_variables(ivs) From 42034e9642c86966410579def4eb271fc37e503a Mon Sep 17 00:00:00 2001 From: Aayush Sabharwal Date: Mon, 11 Aug 2025 06:08:01 +0530 Subject: [PATCH 03/12] refactor: mark common `t*` and `D*` as public --- docs/src/API/model_building.md | 23 +++++++++++++++++++++++ src/ModelingToolkit.jl | 1 + 2 files changed, 24 insertions(+) diff --git a/docs/src/API/model_building.md b/docs/src/API/model_building.md index cbdf72edae..28069b535e 100644 --- a/docs/src/API/model_building.md +++ b/docs/src/API/model_building.md @@ -3,6 +3,29 @@ This page lists functionality and utilities related to building hierarchical models. It is recommended to read the page on the [`System`](@ref System_type) before this. +## Common definitions of `t` and `D` + +ModelingToolkit provides common definitions for the independent variable `t` (time) and the +derivative with respect to it `D`. + +```@docs +ModelingToolkit.t_nounits +ModelingToolkit.D_nounits +ModelingToolkit.t +ModelingToolkit.D +ModelingToolkit.t_unitful +ModelingToolkit.D_unitful +``` + +Users are recommended to use the appropriate common definition in their models. The required +definitions can be imported with convenient aliased names. For example: + +```julia +using ModelingToolkit: t_nounits as t, D_nounits as D +``` + +Allows using `t` and `D` to refer to `t_nounits` and `D_nounits` respectively. + ## Hierarchical model composition The `System` data structure can represent a tree-like hierarchy of systems for building models diff --git a/src/ModelingToolkit.jl b/src/ModelingToolkit.jl index 800ae899da..0a225e4e12 100644 --- a/src/ModelingToolkit.jl +++ b/src/ModelingToolkit.jl @@ -337,6 +337,7 @@ export DynamicOptSolution @public similarity_transform, inputs, outputs, bound_inputs, unbound_inputs, bound_outputs @public unbound_outputs, is_bound @public AbstractSystem, CheckAll, CheckNone, CheckComponents, CheckUnits +@public t, D, t_nounits, D_nounits, t_unitful, D_unitful for prop in [SYS_PROPS; [:continuous_events, :discrete_events]] getter = Symbol(:get_, prop) From 9cfba5b517831c06e5a520f4b1023344b34b4921 Mon Sep 17 00:00:00 2001 From: Aayush Sabharwal Date: Mon, 11 Aug 2025 06:20:25 +0530 Subject: [PATCH 04/12] refactor: mark `SymbolicContinuousCallback`, `SymbolicDiscreteCallback` as public --- src/ModelingToolkit.jl | 1 + 1 file changed, 1 insertion(+) diff --git a/src/ModelingToolkit.jl b/src/ModelingToolkit.jl index 0a225e4e12..98a9267e57 100644 --- a/src/ModelingToolkit.jl +++ b/src/ModelingToolkit.jl @@ -338,6 +338,7 @@ export DynamicOptSolution @public unbound_outputs, is_bound @public AbstractSystem, CheckAll, CheckNone, CheckComponents, CheckUnits @public t, D, t_nounits, D_nounits, t_unitful, D_unitful +@public SymbolicContinuousCallback, SymbolicDiscreteCallback for prop in [SYS_PROPS; [:continuous_events, :discrete_events]] getter = Symbol(:get_, prop) From eb5f1fd9af427d961c26d27810d7162315ecc4f9 Mon Sep 17 00:00:00 2001 From: Aayush Sabharwal Date: Mon, 11 Aug 2025 06:45:13 +0530 Subject: [PATCH 05/12] refactor: mark `VariableType`, `MTKVariableTypeCtx` as public --- docs/src/API/variables.md | 9 +++++++++ src/ModelingToolkit.jl | 1 + src/parameters.jl | 13 +++++++++++++ 3 files changed, 23 insertions(+) diff --git a/docs/src/API/variables.md b/docs/src/API/variables.md index 4c11d900c9..9724f3372b 100644 --- a/docs/src/API/variables.md +++ b/docs/src/API/variables.md @@ -263,6 +263,15 @@ hasunit getunit ``` +## Variable type + +This metadata is used by the [`System`](@ref) constructor for automatically identifying the different types of variables in a system. + +```@docs +ModelingToolkit.VariableType +ModelingToolkit.MTKVariableTypeCtx +``` + ## Miscellaneous metadata User-defined metadata can be added using the `misc` metadata. This can be queried diff --git a/src/ModelingToolkit.jl b/src/ModelingToolkit.jl index 98a9267e57..4491b1a445 100644 --- a/src/ModelingToolkit.jl +++ b/src/ModelingToolkit.jl @@ -339,6 +339,7 @@ export DynamicOptSolution @public AbstractSystem, CheckAll, CheckNone, CheckComponents, CheckUnits @public t, D, t_nounits, D_nounits, t_unitful, D_unitful @public SymbolicContinuousCallback, SymbolicDiscreteCallback +@public VariableType, MTKVariableTypeCtx for prop in [SYS_PROPS; [:continuous_events, :discrete_events]] getter = Symbol(:get_, prop) diff --git a/src/parameters.jl b/src/parameters.jl index de7a722af3..b53f7c6a76 100644 --- a/src/parameters.jl +++ b/src/parameters.jl @@ -1,5 +1,18 @@ import SymbolicUtils: symtype, term, hasmetadata, issym + +""" + @enum VariableType + +The type of the declared variable, used for automatic identification of +variables/parameters/brownians/etc. by the `System` constructor. +""" @enum VariableType VARIABLE PARAMETER BROWNIAN + +""" + $TYPEDEF + +The symbolic metadata key for storing the `VariableType`. +""" struct MTKVariableTypeCtx end getvariabletype(x, def = VARIABLE) = getmetadata(unwrap(x), MTKVariableTypeCtx, def) From 91942a542b5c1f570cddfd663d1765f2b452188f Mon Sep 17 00:00:00 2001 From: Aayush Sabharwal Date: Mon, 11 Aug 2025 06:54:31 +0530 Subject: [PATCH 06/12] refactor: mark several variable metadata keys as public --- docs/src/API/variables.md | 9 ++++++++ src/ModelingToolkit.jl | 4 +++- src/variables.jl | 46 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 58 insertions(+), 1 deletion(-) diff --git a/docs/src/API/variables.md b/docs/src/API/variables.md index 9724f3372b..d5662f4f16 100644 --- a/docs/src/API/variables.md +++ b/docs/src/API/variables.md @@ -56,6 +56,7 @@ help?> u ```@docs hasdescription getdescription +ModelingToolkit.VariableDescription ``` ## Connect @@ -83,6 +84,7 @@ getconnect(k) ```@docs hasconnect getconnect +ModelingToolkit.VariableConnectType ``` ```@docs; canonical=false @@ -112,6 +114,8 @@ isinput isoutput ModelingToolkit.setinput ModelingToolkit.setoutput +ModelingToolkit.VariableInput +ModelingToolkit.VariableOutput ``` ## Bounds @@ -144,6 +148,7 @@ hasbounds(x[2]) ```@docs hasbounds getbounds +ModelingToolkit.VariableBounds ``` ## Guess @@ -232,6 +237,7 @@ isirreducible(important_value) ```@docs isirreducible +ModelingToolkit.VariableIrreducible ``` ## State Priority @@ -245,6 +251,7 @@ state_priority(important_dof) ```@docs state_priority +ModelingToolkit.VariableStatePriority ``` ## Units @@ -261,6 +268,7 @@ getunit(speed) ```@docs hasunit getunit +ModelingToolkit.VariableUnit ``` ## Variable type @@ -286,6 +294,7 @@ getmisc(y) ```@docs hasmisc getmisc +ModelingToolkit.VariableMisc ``` ## Dumping metadata diff --git a/src/ModelingToolkit.jl b/src/ModelingToolkit.jl index 4491b1a445..a77b676ff0 100644 --- a/src/ModelingToolkit.jl +++ b/src/ModelingToolkit.jl @@ -339,7 +339,9 @@ export DynamicOptSolution @public AbstractSystem, CheckAll, CheckNone, CheckComponents, CheckUnits @public t, D, t_nounits, D_nounits, t_unitful, D_unitful @public SymbolicContinuousCallback, SymbolicDiscreteCallback -@public VariableType, MTKVariableTypeCtx +@public VariableType, MTKVariableTypeCtx, VariableBounds, VariableConnectType +@public VariableDescription, VariableInput, VariableIrreducible, VariableMisc +@public VariableOutput, VariableStatePriority, VariableUnit for prop in [SYS_PROPS; [:continuous_events, :discrete_events]] getter = Symbol(:get_, prop) diff --git a/src/variables.jl b/src/variables.jl index b61298eca2..051efd5853 100644 --- a/src/variables.jl +++ b/src/variables.jl @@ -1,10 +1,46 @@ +""" + $TYPEDEF + +Symbolic metadata key for storing the unit associated with a symbolic variable. +""" struct VariableUnit end +""" + $TYPEDEF + +Symbolic metadata key for storing the type of connector that a variable is. +""" struct VariableConnectType end struct VariableNoiseType end +""" + $TYPEDEF + +Symbolic metadata key for storing whether a symbolic variable is an input or not. +""" struct VariableInput end +""" + $TYPEDEF + +Symbolic metadata key for storing whether a symbolic variable is an output or not. +""" struct VariableOutput end +""" + $TYPEDEF + +Symbolic metadata key for storing whether a symbolic variable is irreducible or not. +""" struct VariableIrreducible end +""" + $TYPEDEF + +Symbolic metadata key for storing the priority a variable has for being selected during +state selection. +""" struct VariableStatePriority end +""" + $TYPEDEF + +Symbolic metadata key for storing miscellaneous information about a symbolic variable. +""" struct VariableMisc end # Metadata for renamed shift variables xₜ₋₁ struct VariableUnshifted end @@ -227,6 +263,11 @@ function default_toterm(x) end ## Bounds ====================================================================== +""" + $TYPEDEF + +Symbolic metadata key for specifying the bounds of a symbolic variable. +""" struct VariableBounds end Symbolics.option_to_metadata_type(::Val{:bounds}) = VariableBounds @@ -436,6 +477,11 @@ function getbounds(p::AbstractVector) end ## Description ================================================================= +""" + $TYPEDEF + +Symbolic metadata key for storing the description of a symbolic variable. +""" struct VariableDescription end Symbolics.option_to_metadata_type(::Val{:description}) = VariableDescription From e06c0294c7028440339c22cbcc331169ee07f3fb Mon Sep 17 00:00:00 2001 From: Aayush Sabharwal Date: Mon, 11 Aug 2025 07:50:11 +0530 Subject: [PATCH 07/12] refactor: remove `VariableNoiseType` --- src/systems/model_parsing.jl | 1 - src/variables.jl | 1 - 2 files changed, 2 deletions(-) diff --git a/src/systems/model_parsing.jl b/src/systems/model_parsing.jl index c24c063ee0..61edc394b2 100644 --- a/src/systems/model_parsing.jl +++ b/src/systems/model_parsing.jl @@ -186,7 +186,6 @@ function update_readable_metadata!(varclass_dict, meta::Dict, varname) (:description, VariableDescription), (:unit, VariableUnit), (:bounds, VariableBounds), - (:noise, VariableNoiseType), (:input, VariableInput), (:output, VariableOutput), (:irreducible, VariableIrreducible), diff --git a/src/variables.jl b/src/variables.jl index 051efd5853..46c9c95bc6 100644 --- a/src/variables.jl +++ b/src/variables.jl @@ -10,7 +10,6 @@ struct VariableUnit end Symbolic metadata key for storing the type of connector that a variable is. """ struct VariableConnectType end -struct VariableNoiseType end """ $TYPEDEF From 434b34aaf2377129dac1a270f58f95cbb8cedd6d Mon Sep 17 00:00:00 2001 From: Aayush Sabharwal Date: Mon, 11 Aug 2025 08:06:40 +0530 Subject: [PATCH 08/12] refactor: mark `collect_*` functions as public --- docs/src/API/System.md | 12 ++++++++++++ src/ModelingToolkit.jl | 3 ++- 2 files changed, 14 insertions(+), 1 deletion(-) diff --git a/docs/src/API/System.md b/docs/src/API/System.md index b5dd08bdc7..5160fa0b28 100644 --- a/docs/src/API/System.md +++ b/docs/src/API/System.md @@ -200,3 +200,15 @@ ModelingToolkit.CheckUnits ``` These can also be used by custom `AbstractSystem` subtypes. + +## Utility functions + +These utility functions can be useful when manipulating systems, especially when building +custom `AbstractSystem` subtypes. + +```@docs +ModelingToolkit.collect_scoped_vars! +ModelingToolkit.collect_var_to_name! +ModelingToolkit.collect_vars! +ModelingToolkit.eqtype_supports_collect_vars +``` diff --git a/src/ModelingToolkit.jl b/src/ModelingToolkit.jl index a77b676ff0..5abd639c37 100644 --- a/src/ModelingToolkit.jl +++ b/src/ModelingToolkit.jl @@ -341,7 +341,8 @@ export DynamicOptSolution @public SymbolicContinuousCallback, SymbolicDiscreteCallback @public VariableType, MTKVariableTypeCtx, VariableBounds, VariableConnectType @public VariableDescription, VariableInput, VariableIrreducible, VariableMisc -@public VariableOutput, VariableStatePriority, VariableUnit +@public VariableOutput, VariableStatePriority, VariableUnit, collect_scoped_vars! +@public collect_var_to_name!, collect_vars!, eqtype_supports_collect_vars for prop in [SYS_PROPS; [:continuous_events, :discrete_events]] getter = Symbol(:get_, prop) From 5c24fa12b6e2a18f2806ee1d80ea3db7f76b764f Mon Sep 17 00:00:00 2001 From: Aayush Sabharwal Date: Mon, 11 Aug 2025 08:22:55 +0530 Subject: [PATCH 09/12] refactor: mark variable default manipulation functions as public --- docs/src/API/variables.md | 11 +++++++++++ src/ModelingToolkit.jl | 3 ++- src/utils.jl | 15 +++++++++++++++ 3 files changed, 28 insertions(+), 1 deletion(-) diff --git a/docs/src/API/variables.md b/docs/src/API/variables.md index d5662f4f16..7ccaa2999f 100644 --- a/docs/src/API/variables.md +++ b/docs/src/API/variables.md @@ -18,6 +18,17 @@ Symbolic variables can have metadata attached to them. The defaults and guesses at variable construction time are examples of this metadata. ModelingToolkit also defines additional types of metadata. +## Variable defaults + +Variables can be assigned default values to avoid having to specify defaults to the +[`System`](@ref) constructor. + +```@docs +ModelingToolkit.hasdefault +ModelingToolkit.getdefault +ModelingToolkit.setdefault +``` + ## Variable descriptions Descriptive strings can be attached to variables using the `[description = "descriptive string"]` syntax: diff --git a/src/ModelingToolkit.jl b/src/ModelingToolkit.jl index 5abd639c37..3ad8d3f0d9 100644 --- a/src/ModelingToolkit.jl +++ b/src/ModelingToolkit.jl @@ -342,7 +342,8 @@ export DynamicOptSolution @public VariableType, MTKVariableTypeCtx, VariableBounds, VariableConnectType @public VariableDescription, VariableInput, VariableIrreducible, VariableMisc @public VariableOutput, VariableStatePriority, VariableUnit, collect_scoped_vars! -@public collect_var_to_name!, collect_vars!, eqtype_supports_collect_vars +@public collect_var_to_name!, collect_vars!, eqtype_supports_collect_vars, hasdefault +@public getdefault, setdefault for prop in [SYS_PROPS; [:continuous_events, :discrete_events]] getter = Symbol(:get_, prop) diff --git a/src/utils.jl b/src/utils.jl index 8ec9def5e9..c6f3777c2b 100644 --- a/src/utils.jl +++ b/src/utils.jl @@ -250,8 +250,23 @@ function iv_from_nested_derivative(x, op = Differential) end end +""" + $(TYPEDSIGNATURES) + +Check if the symbolic variable `v` has a default value. +""" hasdefault(v) = hasmetadata(v, Symbolics.VariableDefaultValue) +""" + $(TYPEDSIGNATURES) + +Return the default value of symbolic variable `v`. +""" getdefault(v) = value(Symbolics.getdefaultval(v)) +""" + $(TYPEDSIGNATURES) + +Set the default value of symbolic variable `v` to `val`. +""" function setdefault(v, val) val === nothing ? v : wrap(setdefaultval(unwrap(v), value(val))) end From 2c0aaa8e5154f8bbe871129b664bc9b27a420430 Mon Sep 17 00:00:00 2001 From: Aayush Sabharwal Date: Mon, 11 Aug 2025 08:26:29 +0530 Subject: [PATCH 10/12] refactor: mark `iscomplete`, `isparameter` as public --- docs/src/API/variables.md | 1 + src/ModelingToolkit.jl | 2 +- src/parameters.jl | 5 +++++ 3 files changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/src/API/variables.md b/docs/src/API/variables.md index 7ccaa2999f..99fd53372c 100644 --- a/docs/src/API/variables.md +++ b/docs/src/API/variables.md @@ -289,6 +289,7 @@ This metadata is used by the [`System`](@ref) constructor for automatically iden ```@docs ModelingToolkit.VariableType ModelingToolkit.MTKVariableTypeCtx +ModelingToolkit.isparameter ``` ## Miscellaneous metadata diff --git a/src/ModelingToolkit.jl b/src/ModelingToolkit.jl index 3ad8d3f0d9..c12384ea0d 100644 --- a/src/ModelingToolkit.jl +++ b/src/ModelingToolkit.jl @@ -343,7 +343,7 @@ export DynamicOptSolution @public VariableDescription, VariableInput, VariableIrreducible, VariableMisc @public VariableOutput, VariableStatePriority, VariableUnit, collect_scoped_vars! @public collect_var_to_name!, collect_vars!, eqtype_supports_collect_vars, hasdefault -@public getdefault, setdefault +@public getdefault, setdefault, iscomplete, isparameter for prop in [SYS_PROPS; [:continuous_events, :discrete_events]] getter = Symbol(:get_, prop) diff --git a/src/parameters.jl b/src/parameters.jl index b53f7c6a76..7633d8c1b7 100644 --- a/src/parameters.jl +++ b/src/parameters.jl @@ -17,6 +17,11 @@ struct MTKVariableTypeCtx end getvariabletype(x, def = VARIABLE) = getmetadata(unwrap(x), MTKVariableTypeCtx, def) +""" + $TYPEDEF + +Check if the variable contains the metadata identifying it as a parameter. +""" function isparameter(x) x = unwrap(x) From b002c9771831358d3692aed21aa5896f1bbe3e8f Mon Sep 17 00:00:00 2001 From: Aayush Sabharwal Date: Mon, 11 Aug 2025 09:08:26 +0530 Subject: [PATCH 11/12] refactor: mark `modified_unknowns!` as public --- docs/src/API/System.md | 1 + src/ModelingToolkit.jl | 2 +- src/problems/jumpproblem.jl | 7 +++++++ 3 files changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/src/API/System.md b/docs/src/API/System.md index 5160fa0b28..34b64345d0 100644 --- a/docs/src/API/System.md +++ b/docs/src/API/System.md @@ -211,4 +211,5 @@ ModelingToolkit.collect_scoped_vars! ModelingToolkit.collect_var_to_name! ModelingToolkit.collect_vars! ModelingToolkit.eqtype_supports_collect_vars +ModelingToolkit.modified_unknowns! ``` diff --git a/src/ModelingToolkit.jl b/src/ModelingToolkit.jl index c12384ea0d..4057d48921 100644 --- a/src/ModelingToolkit.jl +++ b/src/ModelingToolkit.jl @@ -343,7 +343,7 @@ export DynamicOptSolution @public VariableDescription, VariableInput, VariableIrreducible, VariableMisc @public VariableOutput, VariableStatePriority, VariableUnit, collect_scoped_vars! @public collect_var_to_name!, collect_vars!, eqtype_supports_collect_vars, hasdefault -@public getdefault, setdefault, iscomplete, isparameter +@public getdefault, setdefault, iscomplete, isparameter, modified_unknowns! for prop in [SYS_PROPS; [:continuous_events, :discrete_events]] getter = Symbol(:get_, prop) diff --git a/src/problems/jumpproblem.jl b/src/problems/jumpproblem.jl index 3bc0e11f61..32aa25182f 100644 --- a/src/problems/jumpproblem.jl +++ b/src/problems/jumpproblem.jl @@ -210,6 +210,13 @@ function get_variables!(dep, jump::MassActionJump, variables) end ### Functions to determine which unknowns are modified by a given jump + +""" + $(TYPEDSIGNATURES) + +Push to `munknowns` the variables modified by jump `jump`. `sts` is the list of unknowns of +the system. Return the modified `munknowns`. +""" function modified_unknowns!(munknowns, jump::Union{ConstantRateJump, VariableRateJump}, sts) for eq in jump.affect! st = eq.lhs From ba7ee6004f16b84bc82a89f20652ca995c6c9bf7 Mon Sep 17 00:00:00 2001 From: Aayush Sabharwal Date: Mon, 11 Aug 2025 09:13:16 +0530 Subject: [PATCH 12/12] refactor: mark `renamespace`, `namespace_equations` as public --- docs/src/API/System.md | 11 +++++++++++ src/ModelingToolkit.jl | 1 + src/systems/abstractsystem.jl | 16 ++++++++++++++++ 3 files changed, 28 insertions(+) diff --git a/docs/src/API/System.md b/docs/src/API/System.md index 34b64345d0..c7cf3cdd9b 100644 --- a/docs/src/API/System.md +++ b/docs/src/API/System.md @@ -213,3 +213,14 @@ ModelingToolkit.collect_vars! ModelingToolkit.eqtype_supports_collect_vars ModelingToolkit.modified_unknowns! ``` + +## Namepsace manipulation + +ModelingToolkit namespaces variables from subsystems when using them in a parent system to +disambiguate from identically named variables in other subsystems or the parent system. The +following functions are useful for manipulating namespacing functionality. + +```@docs +ModelingToolkit.renamespace +ModelingToolkit.namespace_equations +``` diff --git a/src/ModelingToolkit.jl b/src/ModelingToolkit.jl index 4057d48921..26efc0c7a9 100644 --- a/src/ModelingToolkit.jl +++ b/src/ModelingToolkit.jl @@ -344,6 +344,7 @@ export DynamicOptSolution @public VariableOutput, VariableStatePriority, VariableUnit, collect_scoped_vars! @public collect_var_to_name!, collect_vars!, eqtype_supports_collect_vars, hasdefault @public getdefault, setdefault, iscomplete, isparameter, modified_unknowns! +@public renamespace, namespace_equations for prop in [SYS_PROPS; [:continuous_events, :discrete_events]] getter = Symbol(:get_, prop) diff --git a/src/systems/abstractsystem.jl b/src/systems/abstractsystem.jl index 3fe04936d3..f9d9a196b4 100644 --- a/src/systems/abstractsystem.jl +++ b/src/systems/abstractsystem.jl @@ -1095,6 +1095,12 @@ end renamespace(sys, eq::Equation) = namespace_equation(eq, sys) renamespace(names::AbstractVector, x) = foldr(renamespace, names, init = x) + +""" + $(TYPEDSIGNATURES) + +Namespace `x` with the name of `sys`. +""" function renamespace(sys, x) sys === nothing && return x x = unwrap(x) @@ -1141,6 +1147,11 @@ function namespace_guesses(sys) Dict(unknowns(sys, k) => namespace_expr(v, sys) for (k, v) in guess) end +""" + $(TYPEDSIGNATURES) + +Return `equations(sys)`, namespaced by the name of `sys`. +""" function namespace_equations(sys::AbstractSystem, ivs = independent_variables(sys)) eqs = equations(sys) isempty(eqs) && return Equation[] @@ -1162,6 +1173,11 @@ function namespace_tstops(sys::AbstractSystem) end end +""" + $(TYPEDSIGNATURES) + +Namespace the given equation with the name of the given system `sys`. +""" function namespace_equation(eq::Equation, sys, n = nameof(sys);