SciML · TorkelE · Sep 25, 2023 · Sep 25, 2023 · Sep 25, 2023 · Sep 26, 2023
diff --git a/.gitignore b/.gitignore
@@ -4,3 +4,5 @@
 Manifest.toml
 .vscode
 .vscode/*
+docs/src/assets/Project.toml
+docs/src/assets/Manifest.toml
diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "ModelingToolkit"
 uuid = "961ee093-0014-501f-94e3-6117800e7a78"
 authors = ["Yingbo Ma <[email protected]>", "Chris Rackauckas <[email protected]> and contributors"]
-version = "8.71.1"
+version = "8.72.2"
 
 [deps]
 AbstractTrees = "1520ce14-60c1-5f80-bbc7-55ef81b5835c"
@@ -51,9 +51,11 @@ UnPack = "3a884ed6-31ef-47d7-9d2a-63182c4928ed"
 Unitful = "1986cc42-f94f-5a68-af5c-568840ba703d"
 
 [weakdeps]
+BifurcationKit = "0f109fa4-8a5d-4b75-95aa-f515264e7665"
 DeepDiffs = "ab62b9b5-e342-54a8-a765-a90f495de1a6"
 
 [extensions]
+MTKBifurcationKitExt = "BifurcationKit"
 MTKDeepDiffsExt = "DeepDiffs"
 
 [compat]
@@ -100,6 +102,7 @@ julia = "1.6"
 
 [extras]
 AmplNLWriter = "7c4d4715-977e-5154-bfe0-e096adeac482"
+BifurcationKit = "0f109fa4-8a5d-4b75-95aa-f515264e7665"
 BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
 ControlSystemsMTK = "687d7614-c7e5-45fc-bfc3-9ee385575c88"
 DeepDiffs = "ab62b9b5-e342-54a8-a765-a90f495de1a6"
@@ -123,4 +126,4 @@ Sundials = "c3572dad-4567-51f8-b174-8c6c989267f4"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["AmplNLWriter", "BenchmarkTools", "ControlSystemsMTK", "NonlinearSolve", "ForwardDiff", "Ipopt", "Ipopt_jll", "ModelingToolkitStandardLibrary", "Optimization", "OptimizationOptimJL", "OptimizationMOI", "Random", "ReferenceTests", "SafeTestsets", "StableRNGs", "Statistics", "SteadyStateDiffEq", "Test", "StochasticDiffEq", "Sundials", "StochasticDelayDiffEq"]
+test = ["AmplNLWriter", "BifurcationKit", "BenchmarkTools", "ControlSystemsMTK", "NonlinearSolve", "ForwardDiff", "Ipopt", "Ipopt_jll", "ModelingToolkitStandardLibrary", "Optimization", "OptimizationOptimJL", "OptimizationMOI", "Random", "ReferenceTests", "SafeTestsets", "StableRNGs", "Statistics", "SteadyStateDiffEq", "Test", "StochasticDiffEq", "Sundials", "StochasticDelayDiffEq"]
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -1,5 +1,6 @@
 [deps]
 BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
+BifurcationKit = "0f109fa4-8a5d-4b75-95aa-f515264e7665"
 DifferentialEquations = "0c46a032-eb83-5123-abaf-570d42b7fbaa"
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"

diff --git a/docs/pages.jl b/docs/pages.jl
@@ -5,8 +5,10 @@ pages = [
         "tutorials/nonlinear.md",
         "tutorials/optimization.md",
         "tutorials/modelingtoolkitize.md",
+        "tutorials/programmatically_generating.md",
         "tutorials/stochastic_diffeq.md",
         "tutorials/parameter_identifiability.md",
+        "tutorials/bifurcation_diagram_computation.md",
         "tutorials/domain_connections.md"],
     "Examples" => Any["Basic Examples" => Any["examples/higher_order.md",
             "examples/spring_mass.md",

diff --git a/docs/src/basics/ContextualVariables.md b/docs/src/basics/ContextualVariables.md
@@ -48,7 +48,7 @@ for which its arguments must be specified each time it is used. This is useful w
 PDEs for example, where one may need to use `u(t, x)` in the equations, but will
 need to be able to write `u(t, 0.0)` to define a boundary condition at `x = 0`.
 
-## Variable metadata [Experimental/TODO]
+## Variable metadata
 
 In many engineering systems, some variables act like “flows” while others do not.
 For example, in circuit models you have current which flows, and the related
@@ -69,15 +69,17 @@ the metadata. One can get and set metadata by
 ```julia
 julia> @variables x [unit = u"m^3/s"];
 
-julia> hasmetadata(x, Symbolics.option_to_metadata_type(Val(:unit)))
+julia> hasmetadata(x, VariableUnit)
 true
 
-julia> getmetadata(x, Symbolics.option_to_metadata_type(Val(:unit)))
+julia> ModelingToolkit.get_unit(x)
 m³ s⁻¹
 
-julia> x = setmetadata(x, Symbolics.option_to_metadata_type(Val(:unit)), u"m/s")
+julia> x = setmetadata(x, VariableUnit, u"m/s")
 x
 
-julia> getmetadata(x, Symbolics.option_to_metadata_type(Val(:unit)))
+julia> ModelingToolkit.get_unit(x)
 m s⁻¹
 ```
+
+See [Symbolic Metadata](@ref symbolic_metadata) for more details on variable metadata.
diff --git a/docs/src/basics/MTKModel_Connector.md b/docs/src/basics/MTKModel_Connector.md
@@ -1,6 +1,23 @@
-# Defining components with `@mtkmodel`
+# [Components and Connectors](@id mtkmodel_connector)
 
-`@mtkmodel` is a convenience macro to define ModelingToolkit components. It returns `ModelingToolkit.Model`, which includes a constructor that returns an ODESystem, a `structure` dictionary with metadata and flag `isconnector` which is set to `false`.
+## MTK Model
+
+MTK represents components and connectors with `Model`.
+
+```@docs
+ModelingToolkit.Model
+```
+
+## Components
+
+Components are models from various domains. These models contain states and their
+equations.
+
+### [Defining components with `@mtkmodel`](@id mtkmodel)
+
+`@mtkmodel` is a convenience macro to define components. It returns
+`ModelingToolkit.Model`, which includes a constructor that returns the ODESystem, a
+`structure` dictionary with metadata, and flag `isconnector` which is set to `false`.
 
 ## What can an MTK-Model definition have?
 
@@ -56,9 +73,9 @@ end
 
   - Parameters and variables are declared with respective begin blocks.
   - Variables must be functions of an independent variable.
-  - Optionally, default values and metadata can be specified for these parameters and variables. See `ModelB` in the above example.
+  - Optionally, initial guess and metadata can be specified for these parameters and variables. See `ModelB` in the above example.
   - Along with creating parameters and variables, keyword arguments of same name with default value `nothing` are created.
-  - Whenever a parameter or variable has default value, for example `v(t) = 0.0`, a symbolic variable named `v` with default value 0.0 and a keyword argument `v`, with default value `nothing` are created. <br> This way, users can optionally pass new value of `v` while creating a component.
+  - Whenever a parameter or variable has initial value, for example `v(t) = 0.0`, a symbolic variable named `v` with initial value 0.0 and a keyword argument `v`, with default value `nothing` are created. <br> This way, users can optionally pass new value of `v` while creating a component.
 
 ```julia
 julia > @named model_c = ModelC(; v = 2.0);
@@ -72,7 +89,7 @@ julia > ModelingToolkit.getdefault(model_c.v)
   - This block is for non symbolic input arguements. These are for inputs that usually are not meant to be part of components; but influence how they are defined. One can list inputs like boolean flags, functions etc... here.
   - Whenever default values are specified, unlike parameters/variables, they are reflected in the keyword argument list.
 
-### `@extend` block
+#### `@extend` begin block
 
 To extend a partial system,
 
@@ -86,7 +103,8 @@ julia> @named model_c = ModelC(; p1 = 2.0)
 
 ```
 
-However, as `p2` isn't listed in the model definition, its default can't be modified by users.
+However, as `p2` isn't listed in the model definition, its initial guess can't
+specified while creating an instance of `ModelC`.
 
 ### `@components` begin block
 
@@ -110,13 +128,26 @@ And as `k2` isn't listed in the sub-component definition of `ModelC`, its defaul
 
   - Any other Julia operations can be included with dedicated begin blocks.
 
-## Defining connectors with `@connector`
+## Connectors
+
+Connectors are special models that can be used to connect different components together.
+MTK provides 3 distinct connectors:
+
+  - `DomainConnector`: A connector which has only one state which is of `Flow` type,
+    specified by `[connect = Flow]`.
+  - `StreamConnector`: A connector which has atleast one stream variable, specified by
+    `[connect = Stream]`. A `StreamConnector` must have exactly one flow variable.
+  - `RegularConnector`: Connectors that don't fall under above categories.
 
-`@connector` returns `ModelingToolkit.Model`. It includes a constructor that returns a connector ODESystem, a `structure` dictionary with metadata and flag `isconnector` which is set to `true`.
+### [Defining connectors with `@connector`](@id connector)
+
+`@connector` returns `ModelingToolkit.Model`. It includes a constructor that returns
+a connector ODESystem, a `structure` dictionary with metadata, and flag `isconnector`
+which is set to `true`.
 
 A simple connector can be defined with syntax similar to following example:
 
-```julia
+```@example connector
 using ModelingToolkit
 
 @connector Pin begin
@@ -125,16 +156,47 @@ using ModelingToolkit
 end
 ```
 
-  - Variables (as function of independent variable) are listed out in the definition. These variables can optionally have default values and metadata like `descrption`, `connect` and so on.
+Variables (as functions of independent variable) are listed out in the definition. These variables can optionally have initial values and metadata like `description`, `connect` and so on. For more details on setting metadata, check out [Symbolic Metadata](@ref symbolic_metadata).
 
-`@connector`s accepts begin blocks of `@components`, `@equations`, `@extend`, `@parameters`, `@structural_parameters`, `@variables`. These keywords mean the same as described above for `@mtkmodel`.
+Similar to `@mtkmodel`, `@connector` accepts begin blocks of `@components`, `@equations`, `@extend`, `@parameters`, `@structural_parameters`, `@variables`. These keywords mean the same as described above for `@mtkmodel`.
+For example, the following `HydraulicFluid` connector is defined with parameters, variables and equations.
+
+```@example connector
+@connector HydraulicFluid begin
+    @parameters begin
+        ρ = 997
+        β = 2.09e9
+        μ = 0.0010016
+        n = 1
+        let_gas = 1
+        ρ_gas = 0.0073955
+        p_gas = -1000
+    end
+    @variables begin
+        dm(t) = 0.0, [connect = Flow]
+    end
+    @equations begin
+        dm ~ 0
+    end
+end
+```
 
 !!! note
+
     For more examples of usage, checkout [ModelingToolkitStandardLibrary.jl](https://github.com/SciML/ModelingToolkitStandardLibrary.jl/)
 
-### What's a `structure` dictionary?
+## More on `Model.structure`
+
+`structure` stores metadata that describes composition of a model. It includes:
 
-For components defined with `@mtkmodel` or `@connector`, a dictionary with metadata is created. It lists `:components` (sub-component list), `:extend` (the extended states and base system), `:parameters`, `:variables`, ``:kwargs`` (list of keyword arguments), `:independent_variable`, `:equations`.
+  - `:components`: List of sub-components in the form of [[name, sub_component_name],...].
+  - `:extend`: The list of extended states, name given to the base system, and name of the base system.
+  - `:structural_parameters`: Dictionary of structural parameters mapped to their default values.
+  - `:parameters`: Dictionary of symbolic parameters mapped to their metadata.
+  - `:variables`: Dictionary of symbolic variables mapped to their metadata.
+  - `:kwargs`: Dictionary of keyword arguments mapped to their default values.
+  - `:independent_variable`: Independent variable, which is added while generating the Model.
+  - `:equations`: List of equations (represented as strings).
 
 For example, the structure of `ModelC` is:
 

diff --git a/docs/src/basics/Variable_metadata.md b/docs/src/basics/Variable_metadata.md
@@ -1,4 +1,4 @@
-# Symbolic metadata
+# [Symbolic Metadata](@id symbolic_metadata)
 
 It is possible to add metadata to symbolic variables, the metadata will be displayed when calling help on a variable.
 
@@ -39,6 +39,22 @@ help?> u
   Symbolics.VariableSource: (:variables, :u)
 ```
 
+## Connect
+
+Variables in connectors can have `connect` metadata which describes the type of connections.
+
+`Flow` is used for variables that represent physical quantities that "flow" ex:
+current in a resistor. These variables sum up to zero in connections.
+
+`Stream` can be specified for variables that flow bi-directionally.
+
+```@example connect
+using ModelingToolkit
+
+@variables t, i(t) [connect = Flow]
+@variables k(t) [connect = Stream]
+```
+
 ## Input or output
 
 Designate a variable as either an input or an output using the following

diff --git a/docs/src/index.md b/docs/src/index.md
@@ -173,13 +173,16 @@ system:
 
   - Please refer to the
     [SciML ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://github.com/SciML/ColPrac/blob/master/README.md)
-    for guidance on PRs, issues, and other matters relating to contributing to ModelingToolkit.
+    for guidance on PRs, issues, and other matters relating to contributing to SciML.
 
+  - See the [SciML Style Guide](https://github.com/SciML/SciMLStyle) for common coding practices and other style decisions.
   - There are a few community forums:
 
-      + The #diffeq-bridged channel in the [Julia Slack](https://julialang.org/slack/)
-      + [JuliaDiffEq](https://gitter.im/JuliaDiffEq/Lobby) on Gitter
-      + On the Julia Discourse forums (look for the [modelingtoolkit tag](https://discourse.julialang.org/tag/modelingtoolkit))
+      + The #diffeq-bridged and #sciml-bridged channels in the
+        [Julia Slack](https://julialang.org/slack/)
+      + The #diffeq-bridged and #sciml-bridged channels in the
+        [Julia Zulip](https://julialang.zulipchat.com/#narrow/stream/279055-sciml-bridged)
+      + On the [Julia Discourse forums](https://discourse.julialang.org)
       + See also [SciML Community page](https://sciml.ai/community/)
 
 ## Reproducibility

diff --git a/docs/src/systems/DiscreteSystem.md b/docs/src/systems/DiscreteSystem.md
@@ -23,7 +23,7 @@ DiscreteSystem
 
 ```@docs
 DiscreteFunction(sys::ModelingToolkit.DiscreteSystem, args...)
-DiscreteProblem(sys::ModelingToolkit.DiscreteSystem, args...)
+DiscreteProblem(sys::ModelingToolkit.DiscreteSystem, u0map, tspan)
 ```
 
 ## Expression Constructors

diff --git a/docs/src/systems/JumpSystem.md b/docs/src/systems/JumpSystem.md
@@ -15,15 +15,17 @@ JumpSystem
 
 ## Transformations
 
-```@docs
+```@docs; canonical=false
 structural_simplify
 ```
 
 ## Analyses
 
 ## Problem Constructors
 
+```@docs; canonical=false
+DiscreteProblem(sys::ModelingToolkit.DiscreteSystem, u0map, tspan)
+```
 ```@docs
-SciMLBase.DiscreteProblem(sys::JumpSystem,args...)
-JumpProcesses.JumpProblem(sys::JumpSystem,args...)
+JumpProblem(sys::JumpSystem, prob, aggregator)
 ```
diff --git a/docs/src/systems/NonlinearSystem.md b/docs/src/systems/NonlinearSystem.md
@@ -15,22 +15,22 @@ NonlinearSystem
 
 ## Transformations
 
-```@docs
+```@docs; canonical=false
 structural_simplify
 alias_elimination
 tearing
 ```
 
 ## Analyses
 
-```@docs
+```@docs; canonical=false
 ModelingToolkit.isaffine
 ModelingToolkit.islinear
 ```
 
 ## Applicable Calculation and Generation Functions
 
-```julia
+```@docs; canonical=false
 calculate_jacobian
 generate_jacobian
 jacobian_sparsity

diff --git a/docs/src/systems/ODESystem.md b/docs/src/systems/ODESystem.md
@@ -35,7 +35,7 @@ ModelingToolkit.isaffine
 
 ## Applicable Calculation and Generation Functions
 
-```julia
+```@docs; canonical=false
 calculate_jacobian
 calculate_tgrad
 calculate_factorized_W
@@ -56,7 +56,7 @@ SteadyStateProblem(sys::ModelingToolkit.AbstractODESystem, args...)
 ## Torn Problem Constructors
 
 ```@docs
-ODAEProblem(sys::ModelingToolkit.AbstractODESystem, args...)
+ODAEProblem
 ```
 
 ## Expression Constructors

diff --git a/docs/src/systems/SDESystem.md b/docs/src/systems/SDESystem.md
@@ -22,17 +22,19 @@ sde = SDESystem(ode, noiseeqs)
 
 ## Transformations
 
-```@docs
+```@docs; canonical=false
 structural_simplify
 alias_elimination
-Girsanov_transform
+```
+```@docs
+ModelingToolkit.Girsanov_transform
 ```
 
 ## Analyses
 
 ## Applicable Calculation and Generation Functions
 
-```julia
+```@docs; canonical=false
 calculate_jacobian
 calculate_tgrad
 calculate_factorized_W