Skip to content

Commit

Permalink
Merge pull request #2286 from ven-k/vkb/mtkmodel-examples
Browse files Browse the repository at this point in the history
Refactor docs with `@mtkmodel`
  • Loading branch information
ChrisRackauckas authored Oct 8, 2023
2 parents 7949761 + 2ef4752 commit 3034c9f
Show file tree
Hide file tree
Showing 7 changed files with 540 additions and 252 deletions.
12 changes: 7 additions & 5 deletions docs/src/basics/ContextualVariables.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
87 changes: 74 additions & 13 deletions docs/src/basics/MTKModel_Connector.md
Original file line number Diff line number Diff line change
@@ -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?

Expand Down Expand Up @@ -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);
Expand All @@ -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,

Expand All @@ -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

Expand All @@ -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
Expand All @@ -125,17 +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:

Expand Down
18 changes: 17 additions & 1 deletion docs/src/basics/Variable_metadata.md
Original file line number Diff line number Diff line change
@@ -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.

Expand Down Expand Up @@ -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
Expand Down
Loading

0 comments on commit 3034c9f

Please sign in to comment.