From 66961d851c2a287616fa53e3a0290e1831b5830f Mon Sep 17 00:00:00 2001 From: Valentin Kaisermayer Date: Thu, 9 Jun 2022 17:10:28 +0200 Subject: [PATCH 1/3] adds doctests --- docs/make.jl | 4 ++++ docs/src/tutorials/custom_component.md | 16 ++++++++++------ docs/src/tutorials/rc_circuit.md | 6 +++--- 3 files changed, 17 insertions(+), 9 deletions(-) diff --git a/docs/make.jl b/docs/make.jl index b3e12acfa..3e0d17cda 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -14,6 +14,10 @@ makedocs( authors="Julia Computing", clean=true, doctest=false, + strict=[ + :doctest, + :example_block, + ], modules=[ModelingToolkitStandardLibrary, ModelingToolkitStandardLibrary.Blocks, ModelingToolkitStandardLibrary.Mechanical, diff --git a/docs/src/tutorials/custom_component.md b/docs/src/tutorials/custom_component.md index 2ec641cbd..0436807c0 100644 --- a/docs/src/tutorials/custom_component.md +++ b/docs/src/tutorials/custom_component.md @@ -4,7 +4,7 @@ The circuit is a simple circuit that shows chaotic behaviour. Except for a non-linear resistor every other component already is part of `ModelingToolkitStandardLibrary.Electrical`. First we need to make some imports. -```julia +```@example components using ModelingToolkit using ModelingToolkitStandardLibrary.Electrical using ModelingToolkitStandardLibrary.Electrical: OnePort @@ -27,7 +27,7 @@ equation end NonlinearResistor; ``` this can almost be directly translate it to the syntax of `ModelingToolkit`. -```julia +```@example components @parameters t function NonlinearResistor(;name, Ga, Gb, Ve) @@ -45,6 +45,7 @@ function NonlinearResistor(;name, Ga, Gb, Ve) ] extend(ODESystem(eqs, t, [], pars; name=name), oneport) end +nothing # hide ``` ### Explanation @@ -74,7 +75,7 @@ extend(ODESystem(eqs, t, [], pars; name=name), oneport) ## Building the Model The final model can now be created with the components from the library and the new custom component. -```julia +```@example components @named L = Inductor(L=18) @named Ro = Resistor(R=12.5e-3) @named G = Conductor(G=0.565) @@ -99,24 +100,27 @@ connections = [ ] @named model = ODESystem(connections, t, systems=[L, Ro, G, C1, C2, Nr]) +nothing # hide ``` ## Simulating the Model Now the model can be simulated. First `structural_simplify` is called on the model and a `ODEProblem` is build from the result. Since the initial voltage of the first capacitor was already specified via `v_start`, no initial condition is given and an empty pair is supplied. -```julia +```@example components sys = structural_simplify(model) prob = ODEProblem(sys, Pair[], (0, 5e4), saveat=0.01) sol = solve(prob, Rodas4()) Plots.plot(sol[C1.v], sol[C2.v], title="Chaotic Attractor", label="", ylabel="C1 Voltage in V", xlabel="C2 Voltage in V") Plots.savefig("chua_phase_plane.png") +nothing # hide Plots.plot(sol; vars=[C1.v, C2.v, L.i], labels=["C1 Voltage in V" "C1 Voltage in V" "Inductor Current in A"]) Plots.savefig("chua.png") +nothing # hide ``` -![Time series plot of C1.v, C2.v and L.i](https://user-images.githubusercontent.com/50108075/169712569-9ae5a074-ca1a-4801-b666-75a2f6e21bf5.png) +![Time series plot of C1.v, C2.v and L.i](chua_phase_plane.png) -![Phase plane plot of C1.v and C2.v](https://user-images.githubusercontent.com/50108075/169712578-b3f314f6-3310-4471-a31e-af7fac3c0fbc.png) \ No newline at end of file +![Phase plane plot of C1.v and C2.v](chua.png) \ No newline at end of file diff --git a/docs/src/tutorials/rc_circuit.md b/docs/src/tutorials/rc_circuit.md index 0b7112181..85cfa1614 100644 --- a/docs/src/tutorials/rc_circuit.md +++ b/docs/src/tutorials/rc_circuit.md @@ -6,7 +6,7 @@ In that tutorial, the full RC circuit is built from scratch. Here, we will use t components of the `Electrical` model in the ModelingToolkit Standard Library to simply connect pre-made components and simulate the model. -```julia +```@example using ModelingToolkit, OrdinaryDiffEq, Plots using ModelingToolkitStandardLibrary.Electrical @@ -32,7 +32,7 @@ sol = solve(prob, Tsit5()) plot(sol, vars = [capacitor.v,resistor.i], title = "RC Circuit Demonstration", labels = ["Capacitor Voltage" "Resistor Current"]) -savefig("plot.png") +savefig("plot.png"); nothing # hide ``` -![](https://user-images.githubusercontent.com/1814174/164912983-c3f73628-0e19-4e42-b085-4f62ba6f23d1.png) \ No newline at end of file +![](plot.png) \ No newline at end of file From 48bc6e52aefc70bb5fc76789a527debbeac2d4e5 Mon Sep 17 00:00:00 2001 From: Valentin Kaisermayer Date: Thu, 9 Jun 2022 19:26:54 +0200 Subject: [PATCH 2/3] adds missing deps --- README.md | 11 +++++++---- docs/Project.toml | 5 +++++ docs/src/tutorials/rc_circuit.md | 9 ++++++--- 3 files changed, 18 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index dff7ba5f5..5ce173669 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ [![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](http://mtkstdlib.sciml.ai/stable/) [![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](http://mtkstdlib.sciml.ai/dev/) -The ModelingToolkit Standard Library is standard library of components to model the world and beyond. +The ModelingToolkit Standard Library is a standard library of components to model the world and beyond. ![](https://user-images.githubusercontent.com/1814174/172000112-3579f5cf-c370-48c2-8047-558fbc46aeb6.png) @@ -41,6 +41,7 @@ The following is the [RC Circuit Demonstration](http://mtkstdlib.sciml.ai/dev/tu ```julia using ModelingToolkit, OrdinaryDiffEq, Plots using ModelingToolkitStandardLibrary.Electrical +using ModelingToolkitStandardLibrary.Blocks: Constant R = 1.0 C = 1.0 @@ -48,20 +49,22 @@ V = 1.0 @variables t @named resistor = Resistor(R=R) @named capacitor = Capacitor(C=C) -@named source = ConstantVoltage(V=V) +@named source = Voltage() +@named constant = Constant(k=V) @named ground = Ground() rc_eqs = [ + connect(constant.output, source.V) connect(source.p, resistor.p) connect(resistor.n, capacitor.p) connect(capacitor.n, source.n, ground.g) ] -@named rc_model = ODESystem(rc_eqs, t, systems=[resistor, capacitor, source, ground]) +@named rc_model = ODESystem(rc_eqs, t, systems=[resistor, capacitor, constant, source, ground]) sys = structural_simplify(rc_model) prob = ODAEProblem(sys, Pair[], (0, 10.0)) sol = solve(prob, Tsit5()) -plot(sol, vars = [capacitor.v,resistor.i], +plot(sol, vars = [capacitor.v, resistor.i], title = "RC Circuit Demonstration", labels = ["Capacitor Voltage" "Resistor Current"]) savefig("plot.png") diff --git a/docs/Project.toml b/docs/Project.toml index 1bc937b99..cd22addc9 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -1,5 +1,10 @@ [deps] Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" +IfElse = "615f187c-cbe4-4ef1-ba3b-2fcf58d6d173" +ModelingToolkit = "961ee093-0014-501f-94e3-6117800e7a78" +ModelingToolkitStandardLibrary = "16a59e39-deab-5bd0-87e4-056b12336739" +OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed" +Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80" [compat] Documenter = "0.26, 0.27" diff --git a/docs/src/tutorials/rc_circuit.md b/docs/src/tutorials/rc_circuit.md index 85cfa1614..6e8303761 100644 --- a/docs/src/tutorials/rc_circuit.md +++ b/docs/src/tutorials/rc_circuit.md @@ -9,6 +9,7 @@ connect pre-made components and simulate the model. ```@example using ModelingToolkit, OrdinaryDiffEq, Plots using ModelingToolkitStandardLibrary.Electrical +using ModelingToolkitStandardLibrary.Blocks: Constant R = 1.0 C = 1.0 @@ -16,20 +17,22 @@ V = 1.0 @variables t @named resistor = Resistor(R=R) @named capacitor = Capacitor(C=C) -@named source = ConstantVoltage(V=V) +@named source = Voltage() +@named constant = Constant(k=V) @named ground = Ground() rc_eqs = [ + connect(constant.output, source.V) connect(source.p, resistor.p) connect(resistor.n, capacitor.p) connect(capacitor.n, source.n, ground.g) ] -@named rc_model = ODESystem(rc_eqs, t, systems=[resistor, capacitor, source, ground]) +@named rc_model = ODESystem(rc_eqs, t, systems=[resistor, capacitor, constant, source, ground]) sys = structural_simplify(rc_model) prob = ODAEProblem(sys, Pair[], (0, 10.0)) sol = solve(prob, Tsit5()) -plot(sol, vars = [capacitor.v,resistor.i], +plot(sol, vars = [capacitor.v, resistor.i], title = "RC Circuit Demonstration", labels = ["Capacitor Voltage" "Resistor Current"]) savefig("plot.png"); nothing # hide From 1541500631b43659a8733da862b1ad680d672dae Mon Sep 17 00:00:00 2001 From: Valentin Kaisermayer Date: Thu, 9 Jun 2022 19:30:48 +0200 Subject: [PATCH 3/3] spelling and minor changes --- docs/src/tutorials/custom_component.md | 20 ++++++++++---------- docs/src/tutorials/rc_circuit.md | 2 +- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/src/tutorials/custom_component.md b/docs/src/tutorials/custom_component.md index 0436807c0..a6fea63d9 100644 --- a/docs/src/tutorials/custom_component.md +++ b/docs/src/tutorials/custom_component.md @@ -1,9 +1,9 @@ # Custom Component -In this tutorial the creation of a custom component is demonstrated via the [Chua's circuit](https://en.wikipedia.org/wiki/Chua%27s_circuit). +In this tutorial, the creation of a custom component is demonstrated via the [Chua's circuit](https://en.wikipedia.org/wiki/Chua%27s_circuit). The circuit is a simple circuit that shows chaotic behaviour. Except for a non-linear resistor every other component already is part of `ModelingToolkitStandardLibrary.Electrical`. -First we need to make some imports. +First, we need to make some imports. ```@example components using ModelingToolkit using ModelingToolkitStandardLibrary.Electrical @@ -26,7 +26,7 @@ equation i = if (v < -Ve) then Gb*(v + Ve) - Ga*Ve else if (v > Ve) then Gb*(v - Ve) + Ga*Ve else Ga*v; end NonlinearResistor; ``` -this can almost be directly translate it to the syntax of `ModelingToolkit`. +this can almost be directly translated to the syntax of `ModelingToolkit`. ```@example components @parameters t @@ -49,13 +49,13 @@ nothing # hide ``` ### Explanation -All components in `ModelingToolkit` are created via a function that serves as the constructor and returns some form of system, in this case a `ODESystem`. +All components in `ModelingToolkit` are created via a function that serves as the constructor and returns some form of system, in this case, an `ODESystem`. Since the non-linear resistor is essentially a standard electrical component with two ports, we can extend from the `OnePort` component of the library. ```julia @named oneport = OnePort() ``` This creates a `OnePort` with the `name = :oneport`. -For easier notation we can unpack the states of the component +For easier notation, we can unpack the states of the component ```julia @unpack v, i = oneport ``` @@ -63,12 +63,12 @@ It might be a good idea to create parameters for the constants of the `Nonlinear ```julia pars = @parameters Ga=Ga Gb=Gb Ve=Ve ``` -The syntax looks funny but it simply creates symbolic parameters with the name `Ga` where it's default value is set from the function's argument `Ga`. -While this is not strictly necessary it allows the user to `remake` the problem easily with different parameters or allow for auto-tuning or parameter optimization without having to do all costly steps that may be involved with building and simplifying a model. +The syntax looks funny but it simply creates symbolic parameters with the name `Ga` where its default value is set from the function's argument `Ga`. +While this is not strictly necessary it allows the user to `remake` the problem easily with different parameters or allow for auto-tuning or parameter optimization without having to do all the costly steps that may be involved with building and simplifying a model. The non-linear (in this case piece-wise constant) equation for the current can be implemented using `IfElse.ifelse`. Finally, the created `oneport` component is extended with the created equations and parameters. -In this case no extra state variables are added, hence an empty vector is supplied. -The independent variable `t` needs to be supplied as second argument. +In this case, no extra state variables are added, hence an empty vector is supplied. +The independent variable `t` needs to be supplied as the second argument. ```julia extend(ODESystem(eqs, t, [], pars; name=name), oneport) ``` @@ -105,7 +105,7 @@ nothing # hide ## Simulating the Model Now the model can be simulated. -First `structural_simplify` is called on the model and a `ODEProblem` is build from the result. +First, `structural_simplify` is called on the model and an `ODEProblem` is built from the result. Since the initial voltage of the first capacitor was already specified via `v_start`, no initial condition is given and an empty pair is supplied. ```@example components sys = structural_simplify(model) diff --git a/docs/src/tutorials/rc_circuit.md b/docs/src/tutorials/rc_circuit.md index 6e8303761..a038a7ade 100644 --- a/docs/src/tutorials/rc_circuit.md +++ b/docs/src/tutorials/rc_circuit.md @@ -1,7 +1,7 @@ # RC Circuit Model This tutorial is a simplified version of the [RC circuit tutorial in the -ModelingToolkit.jl documentation](https://mtk.sciml.ai/dev/tutorials/acausal_components/). +`ModelingToolkit.jl` documentation](https://mtk.sciml.ai/dev/tutorials/acausal_components/). In that tutorial, the full RC circuit is built from scratch. Here, we will use the components of the `Electrical` model in the ModelingToolkit Standard Library to simply connect pre-made components and simulate the model.