Document public API coverage gaps

docs/src/API/System.md

@@ -52,6 +52,8 @@ ModelingToolkit.has_unknowns
 ModelingToolkit.get_unknowns
 unknowns
 ModelingToolkit.unknowns_toplevel
+irreducibles
+maybe_zeros
 ModelingToolkit.has_ps
 ModelingToolkit.get_ps
 parameters

docs/src/API/dynamic_opt.md

@@ -24,11 +24,13 @@ InfiniteOptCollocation(Ipopt.Optimizer, OrthogonalCollocation(3))
 ```
 
 ```@docs; canonical = false
+AbstractCollocation
 JuMPCollocation
 InfiniteOptCollocation
 CasADiCollocation
 PyomoCollocation
 CommonSolve.solve(::AbstractDynamicOptProblem)
+DynamicOptSolution
 ```
 
 ### Problem constructors

docs/src/API/variables.md

@@ -12,6 +12,7 @@ Symbolics.@variables
 @parameters
 @constants
 @brownians
+@brownian
 ```
 
 Symbolic variables can have metadata attached to them. The defaults and guesses assigned

docs/src/internals/structural_transformation.md

@@ -63,6 +63,7 @@ distribute_shift
 SystemStructure
 TearingState
 TransformationState
+mtkcompile!
 isdiffvar
 isdervar
 isalgvar
@@ -84,4 +85,4 @@ InducedCondensationGraph
 MatchedCondensationGraph
 Unassigned
 unassigned
-```
+```

lib/ModelingToolkitBase/src/ModelingToolkitBase.jl

@@ -150,6 +150,15 @@ abstract type AbstractSystem end
 # See `deprecations.jl`.
 abstract type IntermediateDeprecationSystem <: AbstractSystem end
 
+"""
+    independent_variable
+
+Generic function for querying the primary independent variable of a system-like object.
+
+Most users should call [`independent_variables`](@ref), which returns the independent
+variables as a vector. Packages that define custom system types may extend
+`independent_variable` when a scalar independent-variable interface is required.
+"""
 function independent_variable end
 
 # this has to be included early to deal with dependency issues
@@ -237,9 +246,36 @@ include("inputoutput.jl")
 
 include("deprecations.jl")
 
+"""
+    t_nounits
+
+Unitless default independent variable used by ModelingToolkit examples and constructors.
+
+# Examples
+
+```julia
+using ModelingToolkitBase
+
+t = ModelingToolkitBase.t_nounits
+```
+"""
 const t_nounits = let
     only(@independent_variables t)
 end
+
+"""
+    D_nounits
+
+Default unitless differential operator `Differential(t_nounits)`.
+
+# Examples
+
+```julia
+using ModelingToolkitBase
+
+D = ModelingToolkitBase.D_nounits
+```
+"""
 const D_nounits = Differential(t_nounits)
 
 export CompilerOptions

lib/ModelingToolkitBase/src/deprecations.jl

@@ -1,8 +1,34 @@
-@deprecate structural_simplify(sys; kwargs...) mtkcompile(sys; kwargs...)
-@deprecate structural_simplify(sys, io; kwargs...) mtkcompile(
-    sys; inputs = io[1], outputs = io[2], kwargs...
-)
+"""
+    structural_simplify(sys; kwargs...)
+    structural_simplify(sys, io; kwargs...)
 
+Deprecated alias for [`mtkcompile`](@ref).
+
+Use `mtkcompile(sys; kwargs...)` in new code.
+"""
+function structural_simplify(sys; kwargs...)
+    Base.depwarn(
+        "`structural_simplify(sys; kwargs...)` is deprecated. Use `mtkcompile(sys; kwargs...)` instead.",
+        :structural_simplify
+    )
+    return mtkcompile(sys; kwargs...)
+end
+
+function structural_simplify(sys, io; kwargs...)
+    Base.depwarn(
+        "`structural_simplify(sys, io; kwargs...)` is deprecated. Use `mtkcompile(sys; inputs = io[1], outputs = io[2], kwargs...)` instead.",
+        :structural_simplify
+    )
+    return mtkcompile(sys; inputs = io[1], outputs = io[2], kwargs...)
+end
+
+"""
+    @mtkbuild expr
+
+Deprecated alias for [`@mtkcompile`](@ref).
+
+Use `@mtkcompile` in new code.
+"""
 macro mtkbuild(exprs...)
     return quote
         Base.depwarn("`@mtkbuild` is deprecated. Use `@mtkcompile` instead.", :mtkbuild)
@@ -15,6 +41,13 @@ macro mtkbuild(exprs...)
     end |> esc
 end
 
+"""
+    ODESystem(args...; kwargs...)
+
+Deprecated alias for [`System`](@ref).
+
+Use `System(args...; kwargs...)` in new code.
+"""
 const ODESystem = IntermediateDeprecationSystem
 
 function IntermediateDeprecationSystem(args...; kwargs...)
@@ -202,6 +235,13 @@ for T in [
     end
 end
 
+"""
+    @brownian xs...
+
+Deprecated alias for [`@brownians`](@ref).
+
+Use `@brownians` in new code.
+"""
 macro brownian(xs...)
     return quote
         Base.depwarn(

lib/ModelingToolkitBase/src/systems/abstractsystem.jl

@@ -1829,6 +1829,34 @@ function state_priorities(sys::AbstractSystem)
     return sps
 end
 
+"""
+    irreducibles(sys::AbstractSystem)
+
+Return the variables in `sys` and its subsystems that are marked as irreducible.
+
+Irreducible variables are preserved as unknowns during simplification instead of being
+eliminated as observed variables when possible.
+
+# Arguments
+
+- `sys`: system to inspect recursively.
+
+# Returns
+
+An atomic set of symbolic variables, with subsystem variables namespaced into `sys`.
+
+# Examples
+
+```julia
+using ModelingToolkitBase
+using ModelingToolkitBase: t_nounits as t, D_nounits as D
+
+@variables x(t) [irreducible = true]
+@named sys = System([D(x) ~ -x], t)
+
+irreducibles(sys)
+```
+"""
 function irreducibles(sys::AbstractSystem)
     ircs = get_irreducibles(sys)
     systems = get_systems(sys)
@@ -1840,6 +1868,22 @@ function irreducibles(sys::AbstractSystem)
     return ircs
 end
 
+"""
+    maybe_zeros(sys::AbstractSystem)
+
+Return variables in `sys` and its subsystems that simplification may constrain to zero.
+
+This is primarily used by structural simplification to track variables introduced or
+retained while handling alias equations.
+
+# Arguments
+
+- `sys`: system to inspect recursively.
+
+# Returns
+
+An atomic set of symbolic variables, with subsystem variables namespaced into `sys`.
+"""
 function maybe_zeros(sys::AbstractSystem)
     dds = get_maybe_zeros(sys)
     systems = get_systems(sys)

lib/ModelingToolkitBase/src/systems/optimal_control_interface.jl

@@ -1,5 +1,25 @@
+"""
+    AbstractCollocation
+
+Abstract supertype for dynamic-optimization collocation method descriptors.
+
+Concrete collocation types are provided by backend extensions such as JuMP, InfiniteOpt,
+CasADi, and Pyomo.
+"""
 abstract type AbstractCollocation end
 
+"""
+    DynamicOptSolution(model, sol, input_sol)
+
+Solution wrapper returned by dynamic-optimization backends.
+
+# Fields
+
+- `model`: backend-specific optimization model.
+- `sol`: state trajectory as an `ODESolution`.
+- `input_sol`: controller/input trajectory as an `ODESolution`, or `nothing` when the
+  backend does not return one.
+"""
 struct DynamicOptSolution
     model::Any
     sol::ODESolution
@@ -518,9 +538,9 @@
     merge!(rules, subs)
     # Also add operator-level rules so that concrete time evaluations
     # like obs_var(1.0) from EvalAt are substituted correctly.
     # The operator lambda handles numeric time points (combine_fold can call it
     # when all args are Const). For symbolic time points like tf, we add
     # explicit rules since combine_fold won't call the lambda with symbolic args.
     iv = get_iv(sys)
     for (lhs, rhs) in subs
         op = operation(unwrap(lhs))

lib/ModelingToolkitBase/src/utils.jl

@@ -536,6 +536,20 @@ function collect_guesses!(guesses::SymmapT, vars::Vector{SymbolicT})
     return
 end
 
+"""
+    collect_var_to_name!(vars::Dict{Symbol, SymbolicT}, xs::Vector{SymbolicT})
+
+Populate `vars` with mappings from symbolic variable names to variables.
+
+# Arguments
+
+- `vars`: dictionary updated in place.
+- `xs`: symbolic variables to inspect.
+
+# Returns
+
+`nothing`. Throws `ArgumentError` if two distinct variables have the same name.
+"""
 function collect_var_to_name!(vars::Dict{Symbol, SymbolicT}, xs::Vector{SymbolicT})
     for x in xs
         SU.isconst(x) && continue

lib/ModelingToolkitBase/src/variables.jl

@@ -495,6 +495,32 @@ function hasnominal(x)
     return Symbolics.getmetadata_maybe_indexed(unwrap(x), VariableNominal, nothing) !== nothing
 end
 
+"""
+    setnominal(x, val)
+
+Return `x` with nominal-value metadata set to `val`.
+
+# Arguments
+
+- `x`: symbolic variable to annotate.
+- `val`: nominal value used for scaling and numerical conditioning.
+
+# Returns
+
+A symbolic variable equivalent to `x` with updated `VariableNominal` metadata.
+
+# Examples
+
+```julia
+using ModelingToolkitBase
+
+@variables x
+x = setnominal(x, 10.0)
+getnominal(x)
+```
+
+See also [`getnominal`](@ref) and [`hasnominal`](@ref).
+"""
 function setnominal(x::Num, val)
     return setmetadata(x, VariableNominal, val)
 end
@@ -705,6 +731,14 @@ isbrownian(s) = getvariabletype(s) === BROWNIAN
 $(SIGNATURES)
 
 Define one or more Brownian variables.
+
+# Examples
+
+```julia
+using ModelingToolkitBase
+
+@brownians B
+```
 """
 macro brownians(xs...)
     all(

src/ModelingToolkit.jl

@@ -167,6 +167,38 @@ export get_sensitivity_function, get_comp_sensitivity_function,
     get_looptransfer_function, get_sensitivity, get_comp_sensitivity, get_looptransfer
 export isolate_subsystem
 
+"""
+    FMIComponent(version; fmu, type, name, kwargs...)
+
+Construct a ModelingToolkit component from a Functional Mock-up Unit (FMU).
+
+# Arguments
+
+- `version`: a `Val` selecting the FMI major version, for example `Val(2)`.
+
+# Keyword Arguments
+
+- `fmu`: the loaded FMU object.
+- `type`: the FMI interface type, such as `:ME` for model exchange.
+- `name`: the component name used by `@named`.
+- `kwargs...`: additional FMI extension options.
+
+# Returns
+
+An `AbstractSystem` component representing the FMU interface.
+
+# Examples
+
+```julia
+using ModelingToolkit
+
+@named model = ModelingToolkit.FMIComponent(Val(2); fmu, type = :ME)
+```
+
+!!! note
+    `FMIComponent` is implemented by the FMI extension. Load the FMI dependency before
+    constructing FMU-backed components.
+"""
 function FMIComponent end
 
 @public linearize_symbolic, reorder_unknowns