major doc update

ChrisRackauckas · ChrisRackauckas · commit 89beb2a646ba · 2021-02-27T11:48:45.000-05:00
diff --git a/docs/make.jl b/docs/make.jl
@@ -16,8 +16,12 @@ makedocs(
             "tutorials/nonlinear.md",
             "tutorials/modelingtoolkitize.md",
         ],
-        "Systems" => Any[
-            "systems/AbstractSystem.md",
+        "Basics" => Any[
+            "basics/AbstractSystem.md",
+            "basics/ContextualVariables.md",
+            "basics/DependencyGraphs.md"
+        ],
+        "Systems Types" => Any[
             "systems/ODESystem.md",
             "systems/SDESystem.md",
             "systems/JumpSystem.md",
@@ -26,7 +30,6 @@ makedocs(
             "systems/ControlSystem.md",
             "systems/ReactionSystem.md",
             "systems/PDESystem.md",
-            "systems/DependencyGraphs.md"
         ]
     ]
 )
diff --git a/docs/src/basics/AbstractSystem.md b/docs/src/basics/AbstractSystem.md
@@ -1,95 +1,114 @@
-# The AbstractSystem Interface
-
-## Overview
-
-The `AbstractSystem` interface is the core of the system level of ModelingToolkit.jl.
-It establishes a common set of functionality that is used between systems
-from ODEs and chemical reactions, allowing users to have a common framework for
-model manipulation and compilation.
-
-## Composition and Accessor Functions
-
-Each `AbstractSystem` has lists of variables in context, such as distinguishing
-parameters vs states. In addition, an `AbstractSystem` also can hold other
-`AbstractSystem` types. Direct accessing of the values, such as `sys.states`,
-gives the immediate list, while the accessor functions `states(sys)` gives the
-total set, which includes that of all systems held inside.
-
-The values which are common to all `AbstractSystem`s are:
-
-- `equations(sys)`: All equations that define the system and its subsystems.
-- `states(sys)`: All the states in the system and its subsystems.
-- `parameters(sys)`: All parameters of the system and its subsystems.
-- `nameof(sys)`: The name of the current-level system.
-- `get_eqs(sys)`: Equations that define the current-level system.
-- `get_states(sys)`: States that are in the current-level system.
-- `get_ps(sys)`: Parameters that are in the current-level system.
-- `get_systems(sys)`: Subsystems of the current-level system.
-
-Optionally, a system could have:
-
-- `observed(sys)`: All observed equations of the system and its subsystems.
-- `get_observed(sys)`: Observed equations of the current-level system.
-- `get_default_u0(sys)`: A `Dict` that maps states into their default initial
-  condition.
-- `get_default_p(sys)`: A `Dict` that maps parameters into their default value.
-- `independent_variable(sys)`: The independent variable of a system.
-- `get_noiseeqs(sys)`: Noise equations of the current-level system.
-
-Note that there's `get_iv(sys)`, but it is not advised to use, since it errors
-when the system has no field `iv`. `independent_variable(sys)` returns `nothing`
-for `NonlinearSystem`s.
-
-A system could also have caches:
-
-- `get_jac(sys)`: The Jacobian of a system.
-- `get_tgrad(sys)`: The gradient with respect to time of a system.
-
-## Transformations
-
-Transformations are functions which send a valid `AbstractSystem` definition to
-another `AbstractSystem`. These are passes, like optimizations (e.g., Block-Lower
-Triangle transformations), or changes to the representation, which allow for
-alternative numerical methods to be utilized on the model (e.g., DAE index reduction).
-
-## Function Calculation and Generation
-
-The calculation and generation functions allow for calculating additional
-quantities to enhance the numerical methods applied to the resulting system.
-The calculations, like `calculate_jacobian`, generate ModelingToolkit IR for
-the Jacobian of the system, while the generations, like `generate_jacobian`,
-generate compiled output for the numerical solvers by applying `build_function`
-to the generated code. Additionally, many systems have function-type outputs,
-which cobble together the generation functionality for a system, for example,
-`ODEFunction` can be used to generate a DifferentialEquations-based `ODEFunction`
-with compiled version of the ODE itself, the Jacobian, the mass matrix, etc.
-
-Below are the possible calculation and generation functions:
-
-```@docs
-calculate_tgrad
-calculate_gradient
-calculate_jacobian
-calculate_factorized_W
-calculate_hessian
-generate_tgrad
-generate_gradient
-generate_jacobian
-generate_factorized_W
-generate_hessian
-```
-
-Additionally, `jacobian_sparsity(sys)` and `hessian_sparsity(sys)`
-exist on the appropriate systems for fast generation of the sparsity
-patterns via an abstract interpretation without requiring differentiation.
-
-## Problem Constructors
-
-At the end, the system types have `DEProblem` constructors, like `ODEProblem`,
-which allow for directly generating the problem types required for numerical
-methods. The first argument is always the `AbstractSystem`, and the proceeding
-arguments match the argument order of their original constructors. Whenever an
-array would normally be provided, such as `u0` the initial condition of an
-`ODEProblem`, it is instead replaced with a variable map, i.e., an array of
-pairs `var=>value`, which allows the user to designate the values without having
-to know the order that ModelingToolkit is internally using.
+# The AbstractSystem Interface
+
+## Overview
+
+The `AbstractSystem` interface is the core of the system level of ModelingToolkit.jl.
+It establishes a common set of functionality that is used between systems
+from ODEs and chemical reactions, allowing users to have a common framework for
+model manipulation and compilation.
+
+## Constructors and Naming
+
+The `AbstractSystem` interface has a consistent method for constructing systems.
+Generally it follows the order of:
+
+1. Equations
+2. Independent Variables
+3. Dependent Variables (or States)
+4. Parameters
+
+All other pieces are handled via keyword arguments. `AbstractSystem`s share the
+same keyword arguments, which are:
+
+- `system`: This is used for specifying subsystems for hierarchical modeling with
+  reusable components. For more information, see the [components page](@ref components)
+- Defaults: Keyword arguments like `default_u0` are used for specifying default
+  values which are used. If a value is not given at the `SciMLProblem` construction
+  time, its numerical value will be the default.
+
+## Composition and Accessor Functions
+
+Each `AbstractSystem` has lists of variables in context, such as distinguishing
+parameters vs states. In addition, an `AbstractSystem` also can hold other
+`AbstractSystem` types. Direct accessing of the values, such as `sys.states`,
+gives the immediate list, while the accessor functions `states(sys)` gives the
+total set, which includes that of all systems held inside.
+
+The values which are common to all `AbstractSystem`s are:
+
+- `equations(sys)`: All equations that define the system and its subsystems.
+- `states(sys)`: All the states in the system and its subsystems.
+- `parameters(sys)`: All parameters of the system and its subsystems.
+- `nameof(sys)`: The name of the current-level system.
+- `get_eqs(sys)`: Equations that define the current-level system.
+- `get_states(sys)`: States that are in the current-level system.
+- `get_ps(sys)`: Parameters that are in the current-level system.
+- `get_systems(sys)`: Subsystems of the current-level system.
+
+Optionally, a system could have:
+
+- `observed(sys)`: All observed equations of the system and its subsystems.
+- `get_observed(sys)`: Observed equations of the current-level system.
+- `get_default_u0(sys)`: A `Dict` that maps states into their default initial
+  condition.
+- `get_default_p(sys)`: A `Dict` that maps parameters into their default value.
+- `independent_variable(sys)`: The independent variable of a system.
+- `get_noiseeqs(sys)`: Noise equations of the current-level system.
+
+Note that there's `get_iv(sys)`, but it is not advised to use, since it errors
+when the system has no field `iv`. `independent_variable(sys)` returns `nothing`
+for `NonlinearSystem`s.
+
+A system could also have caches:
+
+- `get_jac(sys)`: The Jacobian of a system.
+- `get_tgrad(sys)`: The gradient with respect to time of a system.
+
+## Transformations
+
+Transformations are functions which send a valid `AbstractSystem` definition to
+another `AbstractSystem`. These are passes, like optimizations (e.g., Block-Lower
+Triangle transformations), or changes to the representation, which allow for
+alternative numerical methods to be utilized on the model (e.g., DAE index reduction).
+
+## Function Calculation and Generation
+
+The calculation and generation functions allow for calculating additional
+quantities to enhance the numerical methods applied to the resulting system.
+The calculations, like `calculate_jacobian`, generate ModelingToolkit IR for
+the Jacobian of the system, while the generations, like `generate_jacobian`,
+generate compiled output for the numerical solvers by applying `build_function`
+to the generated code. Additionally, many systems have function-type outputs,
+which cobble together the generation functionality for a system, for example,
+`ODEFunction` can be used to generate a DifferentialEquations-based `ODEFunction`
+with compiled version of the ODE itself, the Jacobian, the mass matrix, etc.
+
+Below are the possible calculation and generation functions:
+
+```@docs
+calculate_tgrad
+calculate_gradient
+calculate_jacobian
+calculate_factorized_W
+calculate_hessian
+generate_tgrad
+generate_gradient
+generate_jacobian
+generate_factorized_W
+generate_hessian
+```
+
+Additionally, `jacobian_sparsity(sys)` and `hessian_sparsity(sys)`
+exist on the appropriate systems for fast generation of the sparsity
+patterns via an abstract interpretation without requiring differentiation.
+
+## Problem Constructors
+
+At the end, the system types have `DEProblem` constructors, like `ODEProblem`,
+which allow for directly generating the problem types required for numerical
+methods. The first argument is always the `AbstractSystem`, and the proceeding
+arguments match the argument order of their original constructors. Whenever an
+array would normally be provided, such as `u0` the initial condition of an
+`ODEProblem`, it is instead replaced with a variable map, i.e., an array of
+pairs `var=>value`, which allows the user to designate the values without having
+to know the order that ModelingToolkit is internally using.
diff --git a/docs/src/basics/Composition.md b/docs/src/basics/Composition.md
@@ -0,0 +1 @@
+# [Composing Models and Building Reusable Components](@ref components)
diff --git a/docs/src/basics/ContextualVariables.md b/docs/src/basics/ContextualVariables.md
@@ -0,0 +1,43 @@
+# Contextual Variable Types
+
+ModelingToolkit.jl has a system of contextual variable types which allows for
+helping the system transformation machinery do complex manipulations and
+automatic detection. The standard variable definition in ModelingToolkit.jl is
+the `@variable` which is defined by
+[Symbolics.jl](https://github.com/JuliaSymbolics/Symbolics.jl). For example:
+
+```julia
+@variabes x y(x)
+```
+
+This is used for the "normal" variable of a given system, like the states of a
+differential equation or objective function. All of the macros below support
+the same syntax as `@variables`.
+
+## Parameters
+
+All modeling projects have some form of parameters. `@parameters` marks a variable
+as being the parameter of some system, which allows automatic detection algorithms
+to ignore such variables when attempting to find the states of a system.
+
+## Flow Variables (TODO)
+
+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
+voltage which does not. Or in thermal models you have heat flows. In these cases,
+the `connect` statement enforces conservation of flow between all of the connected
+components.
+
+For example, the following specifies that `x` is a 2x2 matrix of flow variables:
+
+```julia
+@variables x[1:2,1:2] type=flow
+```
+
+## Stream Variables
+
+TODO
+
+## Brownian Variables
+
+TODO
diff --git a/docs/src/basics/DependencyGraphs.md b/docs/src/basics/DependencyGraphs.md
@@ -1,21 +1,24 @@
 # Dependency Graphs
 
 # Types
+
 ```@docs
 BipartiteGraph
 ```
 
 # Utility functions for `BiPartiteGraph`s
+
 ```@docs
 Base.isequal
 ```
 
 # Functions for calculating dependency graphs
+
 ```@docs
 equation_dependencies
 asgraph
 variable_dependencies
 asdigraph
 eqeq_dependencies
 varvar_dependencies
-```
+```
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -41,11 +41,13 @@ before generating code.
   efficiently numerically handling large-scale systems of equations
 - The ability to use the entire Symbolics.jl Computer Algebra System (CAS) as
   part of the modeling process.
+- Import models from common formats like SBML, CellML, BioNetGen, and more.
 - Extendability: the whole system is written in pure Julia, so adding new
   functions, simplification rules, and model transformations has no barrier.
 
 For information on how to use the Symbolics.jl CAS system that ModelingToolkit.jl
-is built on, consult the [Symbolics.jl documentation](https://github.com/JuliaSymbolics/Symbolics.jl)
+is built on, consult the
+[Symbolics.jl documentation](https://github.com/JuliaSymbolics/Symbolics.jl)
 
 ### Equation Types
 
@@ -78,6 +80,15 @@ Below is an incomplete list of extension libraries one may want to be aware of:
 - [MomentClosure.jl](https://github.com/augustinas1/MomentClosure.jl): Automatic transformation of ReactionSystems into deterministic systems
     - Generates ODESystems for the moment closures
     - Allows for geometrically-distributed random reaction rates
+- [ReactionMechanismSimulator.jl](https://github.com/ReactionMechanismGenerator/ReactionMechanismSimulator.jl): simulating and analyzing large chemical reaction mechanisms
+    - Ideal gas and dilute liquid phases.
+    - Constant T and P and constant V adiabatic ideal gas reactors.
+    - Constant T and V dilute liquid reactors.
+    - Diffusion limited rates. Sensitivity analysis for all reactors.
+    - Flux diagrams with molecular images (if molecular information is provided).
+
+## Model Import Formats
+
 - [CellMLToolkit.jl](https://github.com/SciML/CellMLToolkit.jl): Import [CellML](https://www.cellml.org/) models into ModelingToolkit
     - Repository of more than a thousand pre-made models
     - Focus on biomedical models in areas such as: Calcium Dynamics,
@@ -88,12 +99,6 @@ Below is an incomplete list of extension libraries one may want to be aware of:
       Protein Modules, Signal Transduction, and Synthetic Biology.
 - [SbmlInterface.jl](https://github.com/paulflang/SbmlInterface.jl): Import [SBML](http://sbml.org/Main_Page) models into ModelingToolkit
     - Uses the robust libsbml library for parsing and transforming the SBML
-- [ReactionMechanismSimulator.jl](https://github.com/ReactionMechanismGenerator/ReactionMechanismSimulator.jl): simulating and analyzing large chemical reaction mechanisms
-    - Ideal gas and dilute liquid phases.
-    - Constant T and P and constant V adiabatic ideal gas reactors.
-    - Constant T and V dilute liquid reactors.
-    - Diffusion limited rates. Sensitivity analysis for all reactors.
-    - Flux diagrams with molecular images (if molecular information is provided).
 - [ReactionNetworkImporters.jl](https://github.com/isaacsas/ReactionNetworkImporters.jl): Import various models into ModelingToolkit
     - Supports the BioNetGen `.net` file
     - Supports importing networks specified by stoichiometric matrices

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+# [Composing Models and Building Reusable Components](@ref components)`