SciML · ChrisRackauckas-Claude · Jul 8, 2026 · Jul 26, 2026 · Jul 26, 2026 · Jul 26, 2026
diff --git a/docs/make.jl b/docs/make.jl
@@ -35,8 +35,7 @@ makedocs(
     sitename = "ModelingToolkit.jl",
     authors = "Chris Rackauckas",
     modules = [ModelingToolkitBase, ModelingToolkit, MTKFMIExt],
-    clean = true, doctest = false, linkcheck = true,
-    warnonly = [:docs_block, :missing_docs, :cross_references],
+    clean = true, doctest = true, checkdocs = :exports, linkcheck = true,
     linkcheck_ignore = [
         "https://epubs.siam.org/doi/10.1137/0903023",
         # this link tends to fail linkcheck stochastically and often takes much longer to succeed

diff --git a/docs/src/API/variables.md b/docs/src/API/variables.md
@@ -11,6 +11,7 @@ ModelingToolkit to attach additional metadata.
 @parameters
 @constants
 @brownians
+@brownian
 ```
 
 Symbolic variables can have metadata attached to them. The defaults and guesses assigned

diff --git a/docs/src/internals/structural_transformation.md b/docs/src/internals/structural_transformation.md
@@ -85,4 +85,4 @@ InducedCondensationGraph
 MatchedCondensationGraph
 Unassigned
 unassigned
-```
+```
diff --git a/lib/ModelingToolkitBase/Project.toml b/lib/ModelingToolkitBase/Project.toml
@@ -177,6 +177,7 @@ SafeTestsets = "0.1"
 SciMLBase = "3.38"
 SciMLPublic = "1.0.0"
 SciMLStructures = "1.7"
+SciMLTesting = "2.4"
 Serialization = "1"
 Setfield = "1"
 SimpleNonlinearSolve = "2.11.1"
@@ -231,6 +232,7 @@ REPL = "3fa0cd96-eef1-5676-8a61-b3b8758bbffb"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 ReferenceTests = "324d217c-45ce-50fc-942e-d289b448e8cf"
 SafeTestsets = "1bc83da4-3b8d-516f-aca4-4fe02f6d838f"
+SciMLTesting = "09d9d899-5365-40a9-917a-5f67fddea283"
 StableRNGs = "860ef19b-820b-49d6-a774-d7a799459cd3"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 SteadyStateDiffEq = "9672c7b4-1e72-59bd-8a11-6ac3964bc41f"
@@ -239,4 +241,4 @@ Sundials = "c3572dad-4567-51f8-b174-8c6c989267f4"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["BenchmarkTools", "BoundaryValueDiffEqMIRK", "BoundaryValueDiffEqAscher", "ControlSystemsBase", "DataInterpolations", "DelayDiffEq", "NonlinearSolve", "ForwardDiff", "ModelingToolkitStandardLibrary", "NonlinearSolveBase", "Optimization", "OptimizationIpopt", "OptimizationOptimJL", "OrdinaryDiffEq", "OrdinaryDiffEqDefault", "REPL", "Random", "ReferenceTests", "SafeTestsets", "StableRNGs", "Statistics", "SteadyStateDiffEq", "Test", "StochasticDiffEq", "Sundials", "Pkg", "OrdinaryDiffEqNonlinearSolve", "Logging", "OptimizationBase", "LinearSolve", "Latexify", "Distributed", "DiffEqNoiseProcess", "DynamicQuantities", "OrdinaryDiffEqSDIRK", "OrdinaryDiffEqRosenbrock", "OrdinaryDiffEqBDF", "OrdinaryDiffEqFunctionMap", "OrdinaryDiffEqTsit5"]
+test = ["BenchmarkTools", "BoundaryValueDiffEqMIRK", "BoundaryValueDiffEqAscher", "ControlSystemsBase", "DataInterpolations", "DelayDiffEq", "NonlinearSolve", "ForwardDiff", "ModelingToolkitStandardLibrary", "NonlinearSolveBase", "Optimization", "OptimizationIpopt", "OptimizationOptimJL", "OrdinaryDiffEq", "OrdinaryDiffEqDefault", "REPL", "Random", "ReferenceTests", "SafeTestsets", "SciMLTesting", "StableRNGs", "Statistics", "SteadyStateDiffEq", "Test", "StochasticDiffEq", "Sundials", "Pkg", "OrdinaryDiffEqNonlinearSolve", "Logging", "OptimizationBase", "LinearSolve", "Latexify", "Distributed", "DiffEqNoiseProcess", "DynamicQuantities", "OrdinaryDiffEqSDIRK", "OrdinaryDiffEqRosenbrock", "OrdinaryDiffEqBDF", "OrdinaryDiffEqFunctionMap", "OrdinaryDiffEqTsit5"]
diff --git a/lib/ModelingToolkitBase/src/ModelingToolkitBase.jl b/lib/ModelingToolkitBase/src/ModelingToolkitBase.jl
@@ -155,9 +155,13 @@ abstract type AbstractSystem end
 abstract type IntermediateDeprecationSystem <: AbstractSystem end
 
 """
-    independent_variable(x)
+    independent_variable
 
-Return the independent variable associated with `x`.
+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
 
@@ -255,42 +259,42 @@ include("inputoutput.jl")
 
 include("deprecations.jl")
 
-const t_nounits = let
-    only(@independent_variables t)
-end
-const D_nounits = Differential(t_nounits)
-
-@doc """
-    t
-
-Default independent variable with units.
 """
-t
+    t_nounits
 
-@doc """
-    D
+Unitless default independent variable used by ModelingToolkit examples and constructors.
 
-Default differential operator with respect to [`t`](@ref).
-"""
-D
+# Examples
 
-@doc """
-    t_nounits
+```julia
+using ModelingToolkitBase
 
-Default independent variable without units.
+t = ModelingToolkitBase.t_nounits
+```
 """
-t_nounits
+const t_nounits = let
+    only(@independent_variables t)
+end
 
-@doc """
+"""
     D_nounits
 
-Default differential operator with respect to [`t_nounits`](@ref).
+Default unitless differential operator `Differential(t_nounits)`.
+
+# Examples
+
+```julia
+using ModelingToolkitBase
+
+D = ModelingToolkitBase.D_nounits
+```
 """
-D_nounits
+const D_nounits = Differential(t_nounits)
 
 export CompilerOptions
 export ODEFunction, convert_system_indepvar,
-    System, OptimizationSystem, JumpSystem, SDESystem, NonlinearSystem, ODESystem
+    System, OptimizationSystem, JumpSystem, SDESystem, NonlinearSystem, ODESystem,
+    DiscreteSystem, ImplicitDiscreteSystem
 export SDEFunction
 export DiscreteProblem, DiscreteFunction
 export ImplicitDiscreteProblem, ImplicitDiscreteFunction

diff --git a/lib/ModelingToolkitBase/src/deprecations.jl b/lib/ModelingToolkitBase/src/deprecations.jl
@@ -1,19 +1,33 @@
-@deprecate structural_simplify(sys; kwargs...) mtkcompile(sys; kwargs...)
-@deprecate structural_simplify(sys, io; kwargs...) mtkcompile(
-    sys; inputs = io[1], outputs = io[2], kwargs...
-)
-
-@doc """
+"""
     structural_simplify(sys; kwargs...)
+    structural_simplify(sys, io; kwargs...)
 
 Deprecated alias for [`mtkcompile`](@ref).
+
+Use `mtkcompile(sys; kwargs...)` in new code.
 """
-structural_simplify
+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; kwargs...)` instead.",
+        :structural_simplify,
+    )
+    return mtkcompile(sys; inputs = io[1], outputs = io[2], kwargs...)
+end
 
 """
-    @mtkbuild sys = Constructor(args...; kwargs...)
+    @mtkbuild expr
 
 Deprecated alias for [`@mtkcompile`](@ref).
+
+Use `@mtkcompile` in new code.
 """
 macro mtkbuild(exprs...)
     return quote
@@ -27,14 +41,14 @@ macro mtkbuild(exprs...)
     end |> esc
 end
 
-const ODESystem = IntermediateDeprecationSystem
-
-@doc """
+"""
     ODESystem(args...; kwargs...)
 
-Deprecated alias constructor for [`System`](@ref).
+Deprecated alias for [`System`](@ref).
+
+Use `System(args...; kwargs...)` in new code.
 """
-ODESystem
+const ODESystem = IntermediateDeprecationSystem
 
 function IntermediateDeprecationSystem(args...; kwargs...)
     Base.depwarn(
@@ -45,23 +59,47 @@ function IntermediateDeprecationSystem(args...; kwargs...)
     return System(args...; kwargs...)
 end
 
-for T in [:NonlinearSystem, :DiscreteSystem, :ImplicitDiscreteSystem]
-    @eval @deprecate $T(args...; kwargs...) System(args...; kwargs...)
+"""
+    NonlinearSystem(args...; kwargs...)
+
+Deprecated alias constructor for [`System`](@ref). Use `System(args...; kwargs...)` in
+new code.
+"""
+function NonlinearSystem(args...; kwargs...)
+    Base.depwarn(
+        "`NonlinearSystem(args...; kwargs...)` is deprecated, use `System(args...; kwargs...)` instead.",
+        :NonlinearSystem,
+    )
+    return System(args...; kwargs...)
 end
 
-@doc """
+"""
     DiscreteSystem(args...; kwargs...)
 
-Deprecated alias constructor for [`System`](@ref).
+Deprecated alias constructor for [`System`](@ref). Use `System(args...; kwargs...)` in
+new code.
 """
-DiscreteSystem
+function DiscreteSystem(args...; kwargs...)
+    Base.depwarn(
+        "`DiscreteSystem(args...; kwargs...)` is deprecated, use `System(args...; kwargs...)` instead.",
+        :DiscreteSystem,
+    )
+    return System(args...; kwargs...)
+end
 
-@doc """
+"""
     ImplicitDiscreteSystem(args...; kwargs...)
 
-Deprecated alias constructor for [`System`](@ref).
+Deprecated alias constructor for [`System`](@ref). Use `System(args...; kwargs...)` in
+new code.
 """
-ImplicitDiscreteSystem
+function ImplicitDiscreteSystem(args...; kwargs...)
+    Base.depwarn(
+        "`ImplicitDiscreteSystem(args...; kwargs...)` is deprecated, use `System(args...; kwargs...)` instead.",
+        :ImplicitDiscreteSystem,
+    )
+    return System(args...; kwargs...)
+end
 
 for T in [
         :ODEProblem, :DDEProblem, :SDEProblem, :SDDEProblem, :DAEProblem,
@@ -274,6 +312,8 @@ end
     @brownian xs...
 
 Deprecated alias for [`@brownians`](@ref).
+
+Use `@brownians` in new code.
 """
 macro brownian(xs...)
     return quote

diff --git a/lib/ModelingToolkitBase/src/discretedomain.jl b/lib/ModelingToolkitBase/src/discretedomain.jl
@@ -13,10 +13,10 @@ $(FIELDS)
 # Examples
 
 ```jldoctest
-julia> using Symbolics
+julia> using ModelingToolkitBase
 
-julia> Δ = Shift(t)
-(::Shift) (generic function with 2 methods)
+julia> Δ = Shift(ModelingToolkitBase.t_nounits)
+Shift(t, 1)
 ```
 """
 struct Shift <: Operator
@@ -220,12 +220,10 @@ $(FIELDS)
 # Examples
 
 ```jldoctest
-julia> using Symbolics
-
-julia> t = ModelingToolkit.t_nounits
+julia> using ModelingToolkitBase
 
 julia> Δ = Sample(0.01)
-(::Sample) (generic function with 2 methods)
+Sample(SciMLBase.PeriodicClock(0.01, 0.0))
 ```
 """
 struct Sample <: Operator

diff --git a/lib/ModelingToolkitBase/src/problems/bvproblem.jl b/lib/ModelingToolkitBase/src/problems/bvproblem.jl
@@ -1,3 +1,4 @@
+"""$(problem_docstring(SciMLBase.BVProblem, ODEFunction, true; init = false, extra_body = BV_EXTRA_BODY))"""
 @fallback_iip_specialize function SciMLBase.BVProblem{iip, spec}(
         sys::System, op, tspan;
         check_compatibility = true,

diff --git a/lib/ModelingToolkitBase/src/problems/daeproblem.jl b/lib/ModelingToolkitBase/src/problems/daeproblem.jl
@@ -1,3 +1,4 @@
+"""$(function_docstring(DAEFunction, true, [:jac, :tgrad]))"""
 @fallback_iip_specialize function SciMLBase.DAEFunction{iip, spec}(
         sys::System; u0 = nothing, p = nothing, tgrad = false, jac = false,
         t = nothing, eval_expression = false, eval_module = @__MODULE__,
@@ -80,6 +81,7 @@ function SciMLBase.DAEFunction{iip, spec}(
     return maybe_codegen_scimlfn(Val{E}, DAEFunction{iip, spec}, args; kwargs...)
 end
 
+"""$(problem_docstring(SciMLBase.DAEProblem, DAEFunction, true))"""
 @fallback_iip_specialize function SciMLBase.DAEProblem{iip, spec}(
         sys::System, op, tspan;
         callback = nothing, check_length = true, eval_expression = false,

diff --git a/lib/ModelingToolkitBase/src/problems/ddeproblem.jl b/lib/ModelingToolkitBase/src/problems/ddeproblem.jl
@@ -1,3 +1,4 @@
+"""$(function_docstring(DDEFunction, true, Symbol[]))"""
 @fallback_iip_specialize function SciMLBase.DDEFunction{iip, spec}(
         sys::System; u0 = nothing, p = nothing, t = nothing, eval_expression = false,
         eval_module = @__MODULE__, expression = Val{false}, checkbounds = false,
@@ -58,6 +59,7 @@ function SciMLBase.DDEFunction{iip, spec}(
     return maybe_codegen_scimlfn(Val{E}, DDEFunction{iip, spec}, args; kwargs...)
 end
 
+"""$(problem_docstring(SciMLBase.DDEProblem, DDEFunction, true))"""
 @fallback_iip_specialize function SciMLBase.DDEProblem{iip, spec}(
         sys::System, op, tspan;
         callback = nothing, check_length = true, checkbounds = false,

diff --git a/lib/ModelingToolkitBase/src/problems/discreteproblem.jl b/lib/ModelingToolkitBase/src/problems/discreteproblem.jl
@@ -1,3 +1,4 @@
+"""$(function_docstring(DiscreteFunction, true, Symbol[]))"""
 @fallback_iip_specialize function SciMLBase.DiscreteFunction{iip, spec}(
         sys::System; u0 = nothing, p = nothing, t = nothing,
         eval_expression = false, eval_module = @__MODULE__, expression = Val{false},
@@ -54,6 +55,7 @@ function SciMLBase.DiscreteFunction{iip, spec}(
     return maybe_codegen_scimlfn(Val{E}, DiscreteFunction{iip, spec}, args; kwargs...)
 end
 
+"""$(problem_docstring(SciMLBase.DiscreteProblem, DiscreteFunction, true))"""
 @fallback_iip_specialize function SciMLBase.DiscreteProblem{iip, spec}(
         sys::System, op, tspan;
         check_compatibility = true, expression = Val{false}, kwargs...