docs: overhaul documentation for v10

Project.toml

@@ -51,6 +51,7 @@ Reexport = "189a3867-3050-52da-a836-e630ba90ab69"
 RuntimeGeneratedFunctions = "7e49a35a-f44a-4d26-94aa-eba1b4ca6b47"
 SCCNonlinearSolve = "9dfe8606-65a1-4bb3-9748-cb89d1561431"
 SciMLBase = "0bca4576-84f4-4d90-8ffe-ffa030f20462"
+SciMLPublic = "431bcebd-1456-4ced-9d72-93c2757fff0b"
 SciMLStructures = "53ae85a6-f571-4167-b2af-e1d143709226"
 Serialization = "9e88b42a-f829-5b0c-bbe9-9e923198166b"
 Setfield = "efcf1570-3423-57d1-acb7-fd33fddbac46"
@@ -145,6 +146,7 @@ Reexport = "0.2, 1"
 RuntimeGeneratedFunctions = "0.5.9"
 SCCNonlinearSolve = "1.0.0"
 SciMLBase = "2.91.1"
+SciMLPublic = "1.0.0"
 SciMLStructures = "1.7"
 Serialization = "1"
 Setfield = "0.7, 0.8, 1"

docs/src/API/System.md

@@ -0,0 +1,174 @@
+# [The `System` type](@id System_type)
+
+ModelingToolkit.jl uses `System` to symbolically represent all types of numerical problems.
+Users create `System`s representing the problem they want to solve and `mtkcompile` transforms
+them into a format ModelingToolkit.jl can generate code for (alongside performing other
+optimizations).
+
+```@docs
+System
+```
+
+## Utility constructors
+
+Several utility constructors also exist to easily construct alternative system formulations.
+
+```@docs
+NonlinearSystem
+SDESystem
+JumpSystem
+OptimizationSystem
+```
+
+## Accessor functions
+
+Several accessor functions exist to query systems for the information they contain. In general,
+for every field `x` there exists a `has_x` function which checks if the system contains the
+field and a `get_x` function for obtaining the value in the field. Note that fields of a system
+cannot be accessed via `getproperty` - that is reserved for accessing variables, subsystems
+or analysis points of the hierarchical system.
+
+```@docs
+ModelingToolkit.has_eqs
+ModelingToolkit.get_eqs
+equations
+equations_toplevel
+full_equations
+ModelingToolkit.has_noise_eqs
+ModelingToolkit.get_noise_eqs
+ModelingToolkit.has_jumps
+ModelingToolkit.get_jumps
+jumps
+ModelingToolkit.has_constraints
+ModelingToolkit.get_constraints
+constraints
+ModelingToolkit.has_costs
+ModelingToolkit.get_costs
+costs
+ModelingToolkit.has_consolidate
+ModelingToolkit.get_consolidate
+ModelingToolkit.has_unknowns
+ModelingToolkit.get_unknowns
+unknowns
+unknowns_toplevel
+ModelingToolkit.has_ps
+ModelingToolkit.get_ps
+parameters
+parameters_toplevel
+tunable_parameters
+ModelingToolkit.has_brownians
+ModelingToolkit.get_brownians
+brownians
+ModelingToolkit.has_iv
+ModelingToolkit.get_iv
+ModelingToolkit.has_observed
+ModelingToolkit.get_observed
+observed
+observables
+ModelingToolkit.has_name
+ModelingToolkit.get_name
+nameof
+ModelingToolkit.has_description
+ModelingToolkit.get_description
+ModelingToolkit.description
+ModelingToolkit.has_defaults
+ModelingToolkit.get_defaults
+defaults
+ModelingToolkit.has_guesses
+ModelingToolkit.get_guesses
+guesses
+ModelingToolkit.has_initialization_eqs
+ModelingToolkit.get_initialization_eqs
+initialization_equations
+ModelingToolkit.has_continuous_events
+ModelingToolkit.get_continuous_events
+continuous_events
+continuous_events_toplevel
+ModelingToolkit.has_discrete_events
+ModelingToolkit.get_discrete_events
+discrete_events_toplevel
+ModelingToolkit.has_assertions
+ModelingToolkit.get_assertions
+assertions
+ModelingToolkit.has_metadata
+ModelingToolkit.get_metadata
+SymbolicUtils.getmetadata(::ModelingToolkit.AbstractSystem, ::DataType, ::Any)
+SymbolicUtils.setmetadata(::ModelingToolkit.AbstractSystem, ::DataType, ::Any)
+ModelingToolkit.has_is_dde
+ModelingToolkit.get_is_dde
+ModelingToolkit.is_dde
+ModelingToolkit.has_tstops
+ModelingToolkit.get_tstops
+ModelingToolkit.symbolic_tstops
+ModelingToolkit.has_tearing_state
+ModelingToolkit.get_tearing_state
+ModelingToolkit.does_namespacing
+toggle_namespacing
+ModelingToolkit.iscomplete
+ModelingToolkit.has_preface
+ModelingToolkit.get_preface
+ModelingToolkit.preface
+ModelingToolkit.has_parent
+ModelingToolkit.get_parent
+ModelingToolkit.has_initializesystem
+ModelingToolkit.get_initializesystem
+ModelingToolkit.is_initializesystem
+```
+
+## `getproperty` syntax
+
+ModelingToolkit allows obtaining in a system using `getproperty`. For a system `sys` with a
+subcomponent `inner` containing variable `var`, `sys.inner.var` will obtain the appropriately
+namespaced version of `var`. Note that this can also be used to access subsystems (`sys.inner`)
+or analysis points.
+
+!!! note
+
+    By default, top-level systems not marked as `complete` will apply their namespace. Systems
+    marked as `complete` will not do this namespacing. This namespacing behavior can be toggled
+    independently of whether the system is completed using [`toggle_namespacing`](@ref) and the
+    current namespacing behavior can be queried via [`ModelingToolkit.does_namespacing`](@ref).
+
+```@docs
+Base.getproperty(::ModelingToolkit.AbstractSystem, ::Symbol)
+```
+
+## Functions for querying system equations
+
+```@docs
+has_diff_eqs
+has_alg_eqs
+get_diff_eqs
+get_alg_eqs
+has_diff_equations
+has_alg_equations
+diff_equations
+alg_equations
+is_alg_equation
+is_diff_equation
+```
+
+## String parsing
+
+ModelingToolkit can parse system variables from strings.
+
+```@docs
+ModelingToolkit.parse_variable
+```
+
+## Dumping system data
+
+```@docs
+ModelingToolkit.dump_unknowns
+ModelingToolkit.dump_parameters
+```
+
+```@docs; canonical = false
+ModelingToolkit.dump_variable_metadata
+```
+
+## Debugging utilities
+
+```@docs
+debug_system
+```

docs/src/API/codegen.md

@@ -0,0 +1,43 @@
+# Code generation utilities
+
+These are lower-level functions that ModelingToolkit leverages to generate code for
+building numerical problems.
+
+```@docs
+ModelingToolkit.generate_rhs
+ModelingToolkit.generate_diffusion_function
+ModelingToolkit.generate_jacobian
+ModelingToolkit.generate_tgrad
+ModelingToolkit.generate_hessian
+ModelingToolkit.generate_W
+ModelingToolkit.generate_dae_jacobian
+ModelingToolkit.generate_history
+ModelingToolkit.generate_boundary_conditions
+ModelingToolkit.generate_cost
+ModelingToolkit.generate_cost_gradient
+ModelingToolkit.generate_cost_hessian
+ModelingToolkit.generate_cons
+ModelingToolkit.generate_constraint_jacobian
+ModelingToolkit.generate_constraint_hessian
+ModelingToolkit.generate_control_jacobian
+ModelingToolkit.build_explicit_observed_function
+```
+
+For functions such as jacobian calculation which require symbolic computation, there
+are `calculate_*` equivalents to obtain the symbolic result without building a function.
+
+```@docs
+ModelingToolkit.calculate_tgrad
+ModelingToolkit.calculate_jacobian
+ModelingToolkit.jacobian_sparsity
+ModelingToolkit.jacobian_dae_sparsity
+ModelingToolkit.calculate_hessian
+ModelingToolkit.hessian_sparsity
+ModelingToolkit.calculate_massmatrix
+ModelingToolkit.W_sparsity
+ModelingToolkit.calculate_W_prototype
+ModelingToolkit.calculate_cost_gradient
+ModelingToolkit.calculate_cost_hessian
+ModelingToolkit.cost_hessian_sparsity
+ModelingToolkit.calculate_control_jacobian
+```