From 96ad87981f252bc6e839e564b10abd2bfe1f46cb Mon Sep 17 00:00:00 2001 From: Herman Sletmoen Date: Wed, 17 Jul 2024 21:31:17 +0200 Subject: [PATCH] Add more documentation (based on #1822) --- src/constants.jl | 2 + src/parameters.jl | 2 + .../StructuralTransformations.jl | 2 + .../symbolics_tearing.jl | 8 ++ src/systems/abstractsystem.jl | 74 +++++++++++++++++-- 5 files changed, 81 insertions(+), 7 deletions(-) diff --git a/src/constants.jl b/src/constants.jl index bd2c6508fc..a0a38fd057 100644 --- a/src/constants.jl +++ b/src/constants.jl @@ -27,6 +27,8 @@ toconstant(s::Num) = wrap(toconstant(value(s))) $(SIGNATURES) Define one or more constants. + +See also [`@independent_variables`](@ref), [`@parameters`](@ref) and [`@variables`](@ref). """ macro constants(xs...) Symbolics._parse_vars(:constants, diff --git a/src/parameters.jl b/src/parameters.jl index f330942046..fb6b0b4d6e 100644 --- a/src/parameters.jl +++ b/src/parameters.jl @@ -54,6 +54,8 @@ tovar(s::Num) = Num(tovar(value(s))) $(SIGNATURES) Define one or more known parameters. + +See also [`@independent_variables`](@ref), [`@variables`](@ref) and [`@constants`](@ref). """ macro parameters(xs...) Symbolics._parse_vars(:parameters, diff --git a/src/structural_transformation/StructuralTransformations.jl b/src/structural_transformation/StructuralTransformations.jl index 2682f1f561..5b9c911928 100644 --- a/src/structural_transformation/StructuralTransformations.jl +++ b/src/structural_transformation/StructuralTransformations.jl @@ -50,6 +50,8 @@ using SparseArrays using SimpleNonlinearSolve +using DocStringExtensions + export tearing, partial_state_selection, dae_index_lowering, check_consistency export dummy_derivative export build_torn_function, build_observed_function, ODAEProblem diff --git a/src/structural_transformation/symbolics_tearing.jl b/src/structural_transformation/symbolics_tearing.jl index 6f6e89d86d..6e1bc5d148 100644 --- a/src/structural_transformation/symbolics_tearing.jl +++ b/src/structural_transformation/symbolics_tearing.jl @@ -86,6 +86,14 @@ function tearing_sub(expr, dict, s) s ? simplify(expr) : expr end +""" +$(TYPEDSIGNATURES) + +Like `equations(sys)`, but includes substitutions done by the tearing process. +These equations matches generated numerical code. + +See also [`equations`](@ref) and [`ModelingToolkit.get_eqs`](@ref). +""" function full_equations(sys::AbstractSystem; simplify = false) empty_substitutions(sys) && return equations(sys) substitutions = get_substitutions(sys) diff --git a/src/systems/abstractsystem.jl b/src/systems/abstractsystem.jl index 2798349ae6..acade88bdc 100644 --- a/src/systems/abstractsystem.jl +++ b/src/systems/abstractsystem.jl @@ -355,6 +355,13 @@ function independent_variables(sys::AbstractMultivariateSystem) return getfield(sys, :ivs) end +""" +$(TYPEDSIGNATURES) + +Get the independent variable(s) of the system `sys`. + +See also [`@independent_variables`](@ref) and [`ModelingToolkit.get_iv`](@ref). +""" function independent_variables(sys::AbstractSystem) @warn "Please declare ($(typeof(sys))) as a subtype of `AbstractTimeDependentSystem`, `AbstractTimeIndependentSystem` or `AbstractMultivariateSystem`." if isdefined(sys, :iv) @@ -649,11 +656,29 @@ for prop in [:eqs :split_idxs :parent :index_cache] - fname1 = Symbol(:get_, prop) - fname2 = Symbol(:has_, prop) + fname_get = Symbol(:get_, prop) + fname_has = Symbol(:has_, prop) @eval begin - $fname1(sys::AbstractSystem) = getfield(sys, $(QuoteNode(prop))) - $fname2(sys::AbstractSystem) = isdefined(sys, $(QuoteNode(prop))) + """ + $(TYPEDSIGNATURES) + + Get the internal field `$($(QuoteNode(prop)))` of a system `sys`. + It only includes `$($(QuoteNode(prop)))` local to `sys`; not those of its subsystems, + like `unknowns(sys)`, `parameters(sys)` and `equations(sys)` does. + This is equivalent to, but preferred over `sys.$($(QuoteNode(prop)))`. + + See also [`has_$($(QuoteNode(prop)))`](@ref). + """ + $fname_get(sys::AbstractSystem) = getfield(sys, $(QuoteNode(prop))) + + """ + $(TYPEDSIGNATURES) + + Returns whether the system `sys` has the internal field `$($(QuoteNode(prop)))`. + + See also [`get_$($(QuoteNode(prop)))`](@ref). + """ + $fname_has(sys::AbstractSystem) = isdefined(sys, $(QuoteNode(prop))) end end @@ -1003,6 +1028,14 @@ function namespace_expr( end end _nonum(@nospecialize x) = x isa Num ? x.val : x + +""" +$(TYPEDSIGNATURES) + +Get the unknown variables of the system `sys` and its subsystems. + +See also [`ModelingToolkit.get_unknowns`](@ref). +""" function unknowns(sys::AbstractSystem) sts = get_unknowns(sys) systems = get_systems(sys) @@ -1023,6 +1056,13 @@ function unknowns(sys::AbstractSystem) unique(nonunique_unknowns) end +""" +$(TYPEDSIGNATURES) + +Get the parameters of the system `sys` and its subsystems. + +See also [`@parameters`](@ref) and [`ModelingToolkit.get_ps`](@ref). +""" function parameters(sys::AbstractSystem) ps = get_ps(sys) if ps == SciMLBase.NullParameters() @@ -1131,6 +1171,15 @@ end flatten(sys::AbstractSystem, args...) = sys +""" +$(TYPEDSIGNATURES) + +Get the flattened equations of the system `sys` and its subsystems. +It may include some abbreviations and aliases of observables. +It is often the most useful way to inspect the equations of a system. + +See also [`full_equations`](@ref) and [`ModelingToolkit.get_eqs`](@ref). +""" function equations(sys::AbstractSystem) eqs = get_eqs(sys) systems = get_systems(sys) @@ -1145,6 +1194,13 @@ function equations(sys::AbstractSystem) end end +""" +$(TYPEDSIGNATURES) + +Get the initialization equations of the system `sys` and its subsystems. + +See also [`ModelingToolkit.get_initialization_eqs`](@ref). +""" function initialization_equations(sys::AbstractSystem) eqs = get_initialization_eqs(sys) systems = get_systems(sys) @@ -2500,8 +2556,10 @@ end """ $(TYPEDSIGNATURES) -extend the `basesys` with `sys`, the resulting system would inherit `sys`'s name +Extend the `basesys` with `sys`, the resulting system would inherit `sys`'s name by default. + +See also [`compose`](@ref). """ function extend(sys::AbstractSystem, basesys::AbstractSystem; name::Symbol = nameof(sys), gui_metadata = get_gui_metadata(sys)) @@ -2550,8 +2608,10 @@ end """ $(SIGNATURES) -compose multiple systems together. The resulting system would inherit the first +Compose multiple systems together. The resulting system would inherit the first system's name. + +See also [`extend`](@ref). """ function compose(sys::AbstractSystem, systems::AbstractArray; name = nameof(sys)) nsys = length(systems) @@ -2572,7 +2632,7 @@ end """ missing_variable_defaults(sys::AbstractSystem, default = 0.0; subset = unknowns(sys)) -returns a `Vector{Pair}` of variables set to `default` which are missing from `get_defaults(sys)`. The `default` argument can be a single value or vector to set the missing defaults respectively. +Returns a `Vector{Pair}` of variables set to `default` which are missing from `get_defaults(sys)`. The `default` argument can be a single value or vector to set the missing defaults respectively. """ function missing_variable_defaults( sys::AbstractSystem, default = 0.0; subset = unknowns(sys))