Merge pull request #31 from SimonEnsemble/update_to_makie

Update to makie
SimonEnsemble · Jan 3, 2022 · 3f2c946 · 3f2c946
2 parents 8df2e08 + 5eceb90
commit 3f2c946
Show file tree

Hide file tree

Showing 32 changed files with 659 additions and 940 deletions.
diff --git a/.github/workflows/TagBot.yml b/.github/workflows/TagBot.yml
diff --git a/.github/workflows/ci_testing.yml b/.github/workflows/ci_testing.yml
@@ -0,0 +1,43 @@
+name: build
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: 'Controlz'
+  cancel-in-progress: true
+
+jobs:
+  unit-and-doc-tests:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - name: checkout commit
+        uses: actions/checkout@main
+
+      - name: set up Julia
+        uses: julia-actions/setup-julia@latest
+        with:
+          version: '1.7.1'
+
+      - name: build package
+        uses: julia-actions/julia-buildpkg@latest
+
+      - name: run tests
+        run: julia --project --color=yes -e 'import Pkg; Pkg.test()'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
+
+      - name: set up documenter
+        run: julia --project -e 'import Pkg; Pkg.add("Documenter")'
+
+      - name: build and deploy docs
+        run: julia --project --color=yes ./docs/make.jl
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
diff --git a/Project.toml b/Project.toml
@@ -1,31 +1,38 @@
 name = "Controlz"
 uuid = "e034abe6-471a-4d54-96dd-ecd1f4022419"
 authors = ["SimonEnsemble <[email protected]>"]
-version = "0.2.1"
+version = "0.3.0"
 
 [deps]
 DifferentialEquations = "0c46a032-eb83-5123-abaf-570d42b7fbaa"
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 Interpolations = "a98d9a8b-a2ab-59e6-89dd-64a1c18fca59"
 Polynomials = "f27b6e38-b328-58d1-80ce-0feddd5e7a45"
 Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
-PyPlot = "d330b81b-6aea-500a-939a-2ce795aea3ee"
 Roots = "f2b01f46-fcfa-551c-844a-d8ac1e96c665"
+CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
+ColorSchemes = "35d6a980-a343-548e-a6ea-1d62b119f2f4"
+Colors = "5ae59095-9a9b-59fe-a467-6f913c188581"
 
 [compat]
-DifferentialEquations = "^6.16.0"
-DataFrames = "^0.22.1"
-Interpolations = "^0.13.1"
-Polynomials = "^0.6.1"
-PyPlot = "^2.9.0"
-julia = "^1.5"
-Roots = "0.8.4"
+DifferentialEquations = "^7.0.0"
+DataFrames = "^1.3.1"
+Interpolations = "^0.13.5"
+Polynomials = "^2.0.22"
+julia = "^1.7"
+Roots = "^1.3.13"
+CairoMakie = "^0.6.6"
+ColorSchemes = "^3.15.0"
+Colors = "^0.12.8"
 
 [extras]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 Polynomials = "f27b6e38-b328-58d1-80ce-0feddd5e7a45"
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
+Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
+InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
 
 [targets]
-test = ["Test", "Documenter", "Polynomials"]
+test = ["Test", "Documenter", "Polynomials", "Markdown", "InteractiveUtils", "Pkg"]
diff --git a/docs/make.jl b/docs/make.jl
@@ -1,6 +1,9 @@
 using Documenter
 using Controlz
 
+# using Controlz before all docstrings
+DocMeta.setdocmeta!(Controlz, :DocTestSetup, :(using Controlz); recursive=true)
+
 makedocs(
     root = joinpath(dirname(pathof(Controlz)), "..", "docs"),
     modules = [Controlz],

diff --git a/docs/src/FOPTD_step_response.png b/docs/src/FOPTD_step_response.png
diff --git a/docs/src/SO_underdamped_step_response.png b/docs/src/SO_underdamped_step_response.png
diff --git a/docs/src/SO_underdamped_step_resposne.png b/docs/src/SO_underdamped_step_resposne.png
diff --git a/docs/src/closed_loop_servo_time_delay.png b/docs/src/closed_loop_servo_time_delay.png
diff --git a/docs/src/example_bode.png b/docs/src/example_bode.png
diff --git a/docs/src/example_nyquist.png b/docs/src/example_nyquist.png
diff --git a/docs/src/example_poles_and_zeros.png b/docs/src/example_poles_and_zeros.png
diff --git a/docs/src/example_root_locus.png b/docs/src/example_root_locus.png
diff --git a/docs/src/faq.md b/docs/src/faq.md
@@ -10,12 +10,14 @@ yes, `Controlz.jl` is free and open. see the associated MIT license [here](https
 
 **I'm completely new to Julia and don't know where to start.**
 
-Julia is a free and open-source, high-performance, dynamic programming language designed especially for numerical computing. See [here](https://julialang.org/learning/) for resources on learning Julia. I recommend [Jupyter Lab or Jupyter Notebook](https://jupyter.org/) as an interactive development environment for Julia.
+Julia is a free and open-source, high-performance, dynamic programming language designed especially for numerical computing. see [here](https://julialang.org/learning/) for resources on learning Julia. I recommend the interactive [Pluto Notebook](https://github.com/fonsp/Pluto.jl) as an interactive development environment for Julia.
 
 **I found a bug.**
 
 please post an issue [here](https://github.com/SimonEnsemble/Controlz.jl/issues).
 
 **may I contribute to the package?**
 
-absolutely! especially for fixing bugs, making documentation clearer, providing examples, etc. as for new features, please post an issue with your plan for a pull request first.
+absolutely! especially for fixing bugs, making documentation clearer, providing examples, etc. 
+
+as for new features or significant changes, please post an issue with your plan for a pull request first so I can approve.
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -1,6 +1,6 @@
 # Controlz.jl
 
-`Controlz.jl` is a [Julia](https://julialang.org/) package to analyze and simulate process dynamics and control systems using transfer function representations.
+`Controlz.jl` is a pure-[Julia](https://julialang.org/) package to analyze and simulate process dynamics and control systems using transfer function representations.
 
 for example, to simulate the unit step response of a second-order, underdamped system characterized by the transfer function
 
@@ -24,7 +24,6 @@ viz_response(data, plot_title="SO underdamped step response")
 
 # install the `Controlz.jl` package in Julia
 
-* in the Julia REPL: go into package mode by typing `]`. then `add Controlz`. then `Backspace` to exit package mode.
-* in a Jupyter or Pluto Notebook: `using Pkg; Pkg.add("Controlz")`. (this way also works in the REPL)
+`Controlz.jl` is an officially registered Julia package. install in the Julia REPL by typing `]` to go into package mode, then `add Controlz`.
 
-for visualizations, `Controlz.jl` relies on `PyPlot.jl`, a Julia interface to matplotlib in Python. see [here](https://github.com/JuliaPy/PyPlot.jl) if you have trouble installing `PyPlot.jl`.
+I recommend interactive [Pluto notebooks](https://github.com/fonsp/Pluto.jl) for coding in Julia, whose automatic package manager installs `Controlz.jl` upon running `using Controlz`.
diff --git a/docs/src/sim.md b/docs/src/sim.md
@@ -12,18 +12,18 @@ pass the output $Y(s)$ in the frequency domain into the function `simulate` to i
 ```julia
 g = 4 / (4 * s ^ 2 + 0.8 * s + 1) # second order transfer function, underdamped
 
-U = 1 / s # unit step input
-Y = g * U # system output
+U = 1 / s                         # unit step input
+Y = g * U                         # system output
 
-data = simulate(Y, 50.0) # simulate until t = 50, returns DataFrame
-data[:, :t]      # array of times, tᵢ's
-data[:, :output] # array of outputs, yᵢ's ≈ y(tᵢ)'s
+data = simulate(Y, 50.0)          # simulate until t = 50, returns DataFrame
+data[:, :t]                       # array of times, tᵢ's
+data[:, :output]                  # array of outputs, yᵢ's ≈ y(tᵢ)'s
 ```
 
-we can then plot the time series via:
+then plot the time series via:
 
 ```julia
-viz_response(data, plot_title="SO underdamped step response")
+viz_response(data, title="SO underdamped step response")
 ```
 
 ![](SO_underdamped_step_response.png)
@@ -41,7 +41,7 @@ Y = g * U
 
 data = simulate(Y, 15.0) # simulate until t = 15
 
-viz_response(data, plot_title="FOPTD step response")
+viz_response(data, title="FOPTD step response")
 ```
 
 ![](FOPTD_step_response.png)
@@ -60,7 +60,7 @@ U = (s^2 - a^2) / (s^2 + a^2) ^ 2
 
 data = simulate(U, 8.0, nb_time_points=300) # simulate until t=8, use 300 time points for high resolution
 
-viz_response(data, plot_title=L"inverting an input $U(s)$", plot_ylabel=L"$u(t)$")
+viz_response(data, title="inverting an input U(s)", ylabel="u(t)")
 ```
 
 the `nb_time_points` argument allows us to return a time series with a higher resolution in time. if the plot of the response appears jagged, likely you need to increase `nb_time_points`.

diff --git a/docs/src/simple_servo_response.png b/docs/src/simple_servo_response.png
diff --git a/docs/src/tcosat.png b/docs/src/tcosat.png
diff --git a/docs/src/tfs.md b/docs/src/tfs.md
@@ -1,3 +1,8 @@
+```@meta
+DocTestSetup = quote
+    using Controlz
+end
+```
 # transfer functions
 
 the response [output $Y(s)$] of a linear, time-invariant system to any input [$U(s)$] is characterized by a transfer function $g(s)=Y(s)/U(s)$.
@@ -9,13 +14,21 @@ $$g(s)=\dfrac{5s+1}{s^2 + 4s+5}$$.
 
 we can construct $g(s)$ in an intuitive way that resembles the algebraic expression:
 
-```julia
+```jldoctest; output=false
 g = (5 * s + 1) / (s ^ 2 + 4 * s + 5) # way 1
+# output
+     5.0*s + 1.0
+---------------------
+1.0*s^2 + 4.0*s + 5.0
 ```
 
 alternatively, we can construct a `TransferFunction` using the coefficients associated with the powers of $s$ in the polynomials composing the numerator and denominator, respectively, of $g(s)$. The coefficients of the highest powers of $s$ go first.
-```julia
+```jldoctest; output=false
 g = TransferFunction([5, 1], [1, 4, 5]) # way 2
+# output
+     5.0*s + 1.0
+---------------------
+1.0*s^2 + 4.0*s + 5.0
 ```
 
 note that, under the hood, we defined `s` such that `s == TransferFunction([1, 0], [1])`.

diff --git a/docs/src/viz.md b/docs/src/viz.md
@@ -1,5 +1,7 @@
 # Visualization
 
+the visualizations rely on [`CairoMakie.jl`](https://github.com/JuliaPlots/Makie.jl).
+
 ## poles and zeros of a transfer function
 
 ```julia
@@ -52,20 +54,32 @@ root_locus(g_ol)
 
 ![](example_root_locus.png)
 
-## hipster plot theme
+## modifying the figures
+
+all visualization functions return a `Figure` object from `CairoMakie.jl` that can be further modified. for example:
+
+```julia
+g_ol = 4 / (s + 3) / (s + 2) / (s + 1)
+fig = root_locus(g_ol)
+ax = current_axis(fig)
+xlims!(ax, -15, 5)
+ax.xlabel = "real numbers"
+```
 
-invoke the hipster plot theme used to make plots for this documentation by:
+## cool plot theme
 
+the custom plot theme can be invoked in `CairoMakie.jl` for other plots via:
 ```julia
-using PyPlot
-PyPlot.matplotlib.style.use("https://raw.githubusercontent.com/SimonEnsemble/Controlz.jl/master/src/hipster.mplstyle")
+using Controlz, CairoMakie
+set_theme!(cool_theme)
 ```
+more, `CairoMakie.jl` offers other themes [here](https://makie.juliaplots.org/dev/documentation/theming/predefined_themes/).
 
 ## detailed docs
 
 ```@docs
-    viz_poles_and_zeros
     viz_response
+    viz_poles_and_zeros
     nyquist_diagram
     bode_plot
     root_locus

diff --git a/examples/examples.ipynb b/examples/examples.ipynb