Skip to content

Commit a033042

Browse files
AayushSabharwalAayushSabharwal
committed
feat: add new API docs
1 parent d78aecb commit a033042

File tree

3 files changed

+376
-0
lines changed

3 files changed

+376
-0
lines changed

‎docs/src/API/System.md‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
# [The `System` type](@id System_type)
2+
3+
ModelingToolkit.jl uses `System` to symbolically represent all types of numerical problems.
4+
Users create `System`s representing the problem they want to solve and `mtkcompile` transforms
5+
them into a format ModelingToolkit.jl can generate code for (alongside performing other
6+
optimizations).
7+
8+
```@docs
9+
System
10+
```
11+
12+
## Utility constructors
13+
14+
Several utility constructors also exist to easily construct alternative system formulations.
15+
16+
```@docs
17+
NonlinearSystem
18+
SDESystem
19+
JumpSystem
20+
OptimizationSystem
21+
```
22+
23+
## Accessor functions
24+
25+
Several accessor functions exist to query systems for the information they contain. In general,
26+
for every field `x` there exists a `has_x` function which checks if the system contains the
27+
field and a `get_x` function for obtaining the value in the field. Note that fields of a system
28+
cannot be accessed via `getproperty` - that is reserved for accessing variables, subsystems
29+
or analysis points of the hierarchical system.
30+
31+
```@docs
32+
ModelingToolkit.has_eqs
33+
ModelingToolkit.get_eqs
34+
equations
35+
equations_toplevel
36+
ModelingToolkit.has_noise_eqs
37+
ModelingToolkit.get_noise_eqs
38+
ModelingToolkit.has_jumps
39+
ModelingToolkit.get_jumps
40+
jumps
41+
ModelingToolkit.has_constraints
42+
ModelingToolkit.get_constraints
43+
constraints
44+
ModelingToolkit.has_costs
45+
ModelingToolkit.get_costs
46+
costs
47+
ModelingToolkit.has_consolidate
48+
ModelingToolkit.get_consolidate
49+
ModelingToolkit.has_unknowns
50+
ModelingToolkit.get_unknowns
51+
unknowns
52+
unknowns_toplevel
53+
ModelingToolkit.has_ps
54+
ModelingToolkit.get_ps
55+
parameters
56+
parameters_toplevel
57+
ModelingToolkit.has_brownians
58+
ModelingToolkit.get_brownians
59+
brownians
60+
ModelingToolkit.has_iv
61+
ModelingToolkit.get_iv
62+
ModelingToolkit.has_observed
63+
ModelingToolkit.get_observed
64+
observed
65+
observables
66+
ModelingToolkit.has_name
67+
ModelingToolkit.get_name
68+
nameof
69+
ModelingToolkit.has_description
70+
ModelingToolkit.get_description
71+
ModelingToolkit.has_defaults
72+
ModelingToolkit.get_defaults
73+
defaults
74+
ModelingToolkit.has_guesses
75+
ModelingToolkit.get_guesses
76+
guesses
77+
ModelingToolkit.has_initialization_eqs
78+
ModelingToolkit.get_initialization_eqs
79+
initialization_equations
80+
ModelingToolkit.has_continuous_events
81+
ModelingToolkit.get_continuous_events
82+
continuous_events
83+
continuous_events_toplevel
84+
ModelingToolkit.has_discrete_events
85+
ModelingToolkit.get_discrete_events
86+
discrete_events_toplevel
87+
ModelingToolkit.has_assertions
88+
ModelingToolkit.get_assertions
89+
assertions
90+
ModelingToolkit.has_metadata
91+
ModelingToolkit.get_metadata
92+
SymbolicUtils.getmetadata(::ModelingToolkit.AbstractSystem, ::DataType, ::Any)
93+
SymbolicUtils.setmetadata(::ModelingToolkit.AbstractSystem, ::DataType, ::Any)
94+
ModelingToolkit.has_is_dde
95+
ModelingToolkit.get_is_dde
96+
ModelingToolkit.is_dde
97+
ModelingToolkit.has_tstops
98+
ModelingToolkit.get_tstops
99+
ModelingToolkit.symbolic_tstops
100+
ModelingToolkit.has_tearing_state
101+
ModelingToolkit.get_tearing_state
102+
ModelingToolkit.does_namespacing
103+
toggle_namespacing
104+
ModelingToolkit.iscomplete
105+
ModelingToolkit.has_preface
106+
ModelingToolkit.get_preface
107+
ModelingToolkit.preface
108+
ModelingToolkit.has_parent
109+
ModelingToolkit.get_parent
110+
ModelingToolkit.has_initializesystem
111+
ModelingToolkit.get_initializesystem
112+
ModelingToolkit.is_initializesystem
113+
```
114+
115+
## `getproperty` syntax
116+
117+
ModelingToolkit allows obtaining in a system using `getproperty`. For a system `sys` with a
118+
subcomponent `inner` containing variable `var`, `sys.inner.var` will obtain the appropriately
119+
namespaced version of `var`. Note that this can also be used to access subsystems (`sys.inner`)
120+
or analysis points.
121+
122+
!!! note
123+
124+
By default, top-level systems not marked as `complete` will apply their namespace. Systems
125+
marked as `complete` will not do this namespacing. This namespacing behavior can be toggled
126+
independently of whether the system is completed using [`toggle_namespacing`](@ref) and the
127+
current namespacing behavior can be queried via [`ModelingToolkit.does_namespacing`](@ref).
128+
129+
```@docs
130+
Base.getproperty(::ModelingToolkit.AbstractSystem, ::Symbol)
131+
```
132+
133+
## Functions for querying system equations
134+
135+
```@docs
136+
has_diff_eqs
137+
has_alg_eqs
138+
get_diff_eqs
139+
get_alg_eqs
140+
has_diff_equations
141+
has_alg_equations
142+
diff_equations
143+
alg_equations
144+
is_alg_equation
145+
is_diff_equation
146+
```
147+
148+
## String parsing
149+
150+
ModelingToolkit can parse system variables from strings.
151+
152+
```@docs
153+
ModelingToolkit.parse_variable
154+
```
155+
156+
## Dumping system data
157+
158+
```@docs
159+
ModelingToolkit.dump_unknowns
160+
ModelingToolkit.dump_parameters
161+
ModelingToolkit.dump_variable_metadata
162+
```
163+
164+
## Debugging utilities
165+
166+
```@docs
167+
debug_system
168+
```

‎docs/src/API/model_building.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# Model building reference
2+
3+
This page lists functionality and utilities related to building hierarchical models. It is
4+
recommended to read the page on the [`System`](@ref System_type) before this.
5+
6+
## Hierarchical model composition
7+
8+
The `System` data structure can represent a tree-like hierarchy of systems for building models
9+
from composable blocks. The [`ModelingToolkit.get_systems`](@ref) function can be used for
10+
querying the subsystems of a system. The `@component` macro should be used when writing
11+
building blocks for model composition.
12+
13+
```@docs
14+
@component
15+
```
16+
17+
### Scoping of variables
18+
19+
When building hierarchical systems, is is often necessary to pass variables from a parent system
20+
to the subsystems. If done naively, this will result in the child system assuming it "owns" the
21+
variables passed to it and any occurrences of those variables in the child system will be
22+
namespaced. To prevent this, ModelingToolkit has the concept of variable scope. The scope allows
23+
specifying which system a variable belongs to relative to the system in which it is used.
24+
25+
```@docs
26+
LocalScope
27+
ParentScope
28+
GlobalScope
29+
```
30+
31+
Note that the scopes must be applied to _individual variables_ and not expressions. For example,
32+
`ParentScope(x + y)` is incorrect. Instead, `ParentScope(x) + ParentScope(y)` is the correct usage.
33+
Applying the same scope (more generally, the same function) to all variables in an expression is a
34+
common task, and ModelingToolkit exposes a utility for the same:
35+
36+
```@docs
37+
ModelingToolkit.apply_to_variables
38+
```
39+
40+
It is still tedious to manually use `apply_to_variables` on any symbolic expression passed to a
41+
subsystem. The `@named` macro automatically wraps all symbolic arguments in `ParentScope` and
42+
uses the identifier being assigned as the name of the system.
43+
44+
```@docs
45+
@named
46+
```
47+
48+
### Exploring the tree structure
49+
50+
The `System` type implements the `AbstractTrees` interface. This can be used to explore the
51+
hierarchical structure.
52+
53+
```@docs
54+
hierarchy
55+
```
56+
57+
### Connection semantics
58+
59+
ModelingToolkit implements connection semantics similar to those in the [Modelica specification](https://specification.modelica.org/maint/3.6/connectors-and-connections.html).
60+
We do not support the concept of `inner` and `outer` elements or `expandable` connectors.
61+
Connectors in ModelingToolkit are systems with the appropriate metadata added via the `@connector`
62+
macro.
63+
64+
```@docs
65+
Symbolics.connect
66+
domain_connect
67+
@connector
68+
```
69+
70+
Connections can be expanded using `expand_connections`.
71+
72+
```@docs
73+
expand_connections
74+
```
75+
76+
Similar to the `stream` and `flow` keyword arguments in the specification, ModelingToolkit
77+
allows specifying how variables in a connector behave in a connection.
78+
79+
```@docs
80+
Equality
81+
Stream
82+
Flow
83+
```
84+
85+
These are specified using the `connect` metadata. ModelingToolkit also supports `instream`
86+
87+
```@docs
88+
instream
89+
```
90+
91+
### System composition utilities
92+
93+
```@docs
94+
extend
95+
compose
96+
substitute_component
97+
```
98+
99+
### Flattening systems
100+
101+
The hierarchical structure can be flattened. This operation is performed during simplification.
102+
103+
```@docs
104+
flatten
105+
```
106+
107+
## System simplification
108+
109+
`System`s can be simplified to reformulate them in a way that enables it to be solved numerically,
110+
and also perform other optimizations. This is done via the `mtkcompile` function. Connection expansion
111+
and flattening are preprocessing steps of simplification.
112+
113+
```@docs
114+
mtkcompile
115+
@mtkcompile
116+
```
117+
118+
It is also possible (though not always advisable) to build numerical problems from systems without
119+
passing them through `mtkcompile`. To do this, the system must first be marked as "complete" via
120+
the `complete` function. This process is used to indicate that a system will not be modified
121+
further and allows ModelingToolkit to perform any necessary preprocessing to it. `mtkcompile`
122+
calls `complete` internally.
123+
124+
```@docs
125+
complete
126+
```

‎docs/src/API/problems.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# Building and solving numerical problems
2+
3+
Systems are numerically solved by building and solving the appropriate problem type.
4+
Numerical solvers expect to receive functions taking a predefeined set of arguments
5+
and returning specific values. This format of argument and return value depends on
6+
the function and the problem. ModelingToolkit is capable of compiling and generating
7+
code for a variety of such numerical problems.
8+
9+
## Dynamical systems
10+
11+
```@docs
12+
ODEFunction(::System, args...)
13+
ODEProblem(::System, args...)
14+
DAEFunction(::System, args...)
15+
DAEProblem(::System, args...)
16+
SDEFunction(::System, args...)
17+
SDEProblem(::System, args...)
18+
DDEFunction(::System, args...)
19+
DDEProblem(::System, args...)
20+
SDDEFunction(::System, args...)
21+
SDDEProblem(::System, args...)
22+
JumpProblem(::System, args...)
23+
BVProblem(::System, args...)
24+
DiscreteProblem(::System, args...)
25+
ImplicitDiscreteProblem(::System, args...)
26+
```
27+
28+
## Nonlinear systems
29+
30+
```@docs
31+
NonlinearFunction(::System, args...)
32+
NonlinearProblem(::System, args...)
33+
SCCNonlinearProblem(::System, args...)
34+
NonlinearLeastSquaresProblem(::System, args...)
35+
SteadyStateProblem(::System, args...)
36+
IntervalNonlinearFunction(::System, args...)
37+
IntervalNonlinearProblem(::System, args...)
38+
```
39+
40+
## Optimization and optimal control
41+
42+
```@docs
43+
OptimizationFunction(::System, args...)
44+
OptimizationProblem(::System, args...)
45+
ODEInputFunction(::System, args...)
46+
JuMPDynamicOptProblem(::System, args...)
47+
InfiniteOptDynamicOptProblem,(::System, args...)
48+
CasADiDynamicOptProblem(::System, args...)
49+
DynamicOptSolution
50+
```
51+
52+
## Linear analysis
53+
54+
```@docs
55+
linearization_function
56+
LinearizationProblem
57+
linearize
58+
CommonSolve.solve(::LinearizationProblem)
59+
linearize_symbolic
60+
```
61+
62+
There are also utilities for manipulating the results of these analyses in a symbolic context.
63+
64+
```@docs
65+
ModelingToolkit.similarity_transform
66+
ModelingToolkit.reorder_unknnowns
67+
```
68+
69+
### Analysis point transformations
70+
71+
Linear analysis can also be done using analysis points to perform several common
72+
workflows.
73+
74+
```@docs
75+
get_sensitivity_function
76+
get_sensitivity
77+
get_comp_sensitivity_function
78+
get_comp_sensitivity
79+
get_looptransfer_function
80+
get_looptransfer
81+
open_loop
82+
```

0 commit comments

Comments
 (0)