Documentation Update (#28)

* Updated docs to use Literate.jl to generate example notebooks * Update README and docs
6 months ago · 013075e6b9
--- a/.gitignore
+++ b/.gitignore
@ -16,6 +16,7 @@ deps/src/
 # Build artifacts for creating documentation generated by the Documenter package
 docs/build/
 docs/site/
 docs/src/examples/

 # File generated by Pkg, the package manager, based on a corresponding Project.toml
 # It records a fixed state of all packages used by the project. As such, it should not be
--- a/README.md
+++ b/README.md
@ -6,90 +6,26 @@


 `Petri.jl` is a Petri net modeling framework for the Julia programming language.

 ## Examples

 We need to include our dependencies. `Petri` is the only requirement to build the models. `OrdinaryDiffEq` is required for simulating the network with and ordinary differential equation. `Plots` can be used to plot the solutions generated by `OrdinaryDiffEq`. `LabelledArrays` can be used to make things more readable, but is not necessary. Lastly, `Catlab` is required for visualizing the models as graphviz diagrams.

 ```julia
 using Petri
 using LabelledArrays
 using OrdinaryDiffEq
 using Plots
 ```

 The SIR model represents the epidemiological dynamics of an infectious disease that causes immunity in its victims. There are three *states:* `Suceptible ,Infected, Recovered`. These states interact through two *transitions*. Infection has the form `S+I -> 2I` where a susceptible person meets an infected person and results in two infected people. The second transition is recovery `I -> R` where an infected person recovers spontaneously.


 ![The SIR model system shown as a Petri net with ODE formulas](/docs/src/img/sir_petri+ode.png?raw=true "SIR Model")

 ```julia
 # define the structure of the model
 sir = Petri.Model([:S,:I,:R],LVector(
                                inf=(LVector(S=1,I=1), LVector(I=2)),
                                rec=(LVector(I=1),     LVector(R=1))))

 # define the initial conditions
 u0 = LVector(S=100.0, I=1, R=0)

 # define the parameters of the model, each rate corresponds to a transition
 p = LVector(inf=0.05, rec=0.35)

 # this is regular OrdinaryDiffEq problem setup
 prob = ODEProblem(sir,u0,(0.0,365.0),p)
 sol = OrdinaryDiffEq.solve(prob,Tsit5())

 # generate a graphviz visualization of the model
 graph = Graph(sir)

 # visualize the solution
 plt = plot(sol)
 ```

 ![A solution to the SIR model system](/docs/src/img/sir_sol.png?raw=true "SIR Solution")


 Petri Nets are a simple language for describing reaction networks, you can make increasingly complex diseases. For example the `SEIR` model has an `Exposed` phase where people have the disease, but are not infectious yet.

 ![The SEIR model system shown as a Petri net](/docs/src/img/seir.png?raw=true "SEIR Model")

 ```julia
 seir = Petri.Model([:S,:E,:I,:R],LVector(
                                    exp=(LVector(S=1,I=1), LVector(I=1,E=1)),
                                    inf=(LVector(E=1),     LVector(I=1)),
                                    rec=(LVector(I=1),     LVector(R=1))))
 u0 = LVector(S=100.0, E=1, I=0, R=0)
 p = (exp=0.35, inf=0.05, rec=0.05)
 prob = ODEProblem(seir,u0,(0.0,365.0),p)
 sol = OrdinaryDiffEq.solve(prob,Tsit5())
 plt = plot(sol)
 ```

 ![A solution to the SEIR model system](/docs/src/img/seir_sol.png?raw=true "SEIR Solution")

 The previous models have transitory behavior, the infection spreads and then terminates as you end up with no infected people in the population. The following `SEIRS` model has a non-trivial steady state, because recovered people lose their immunity and become susceptible again.

 ![The SEIRS model system shown as a Petri net](/docs/src/img/seirs.png?raw=true "SEIR Model")

 ```julia
 seirs = Petri.Model([:S,:E,:I,:R],LVector(
                                    exp=(LVector(S=1,I=1), LVector(I=1,E=1)),
                                    inf=(LVector(E=1),     LVector(I=1)),
                                    rec=(LVector(I=1),     LVector(R=1)),
                                    deg=(LVector(R=1),     LVector(S=1))))
 u0 = LVector(S=100.0, E=1, I=0, R=0)
 p = LVector(exp=0.35, inf=0.05, rec=0.07, deg=0.3)
 prob = ODEProblem(seirs,u0,(0.0,365.0),p)
 sol = OrdinaryDiffEq.solve(prob,Tsit5())
 plt = plot(sol)
 ```

 ![A solution to the SEIRS model system](/docs/src/img/seirs_sol.png?raw=true "SEIRS Solution")
 `Petri` makes it easy to build complex reaction networks using a simple DSL.
 Once a model is defined, `Petri.jl` has support to generate ODE solutions and
 stochastic simulations using `DifferentialEquations.jl`. Examples and basic
 usage can be found in the documentation.

 ## Goals

 `Petri` makes it easy to build complex reaction networks using a simple DSL. This is related to the[DiffeqBiological](https://github.com/JuliaDiffEq/DiffEqBiological.jl "DiffEqBiological") Reaction DSL, but takes a different implementation approach. Instead of building our framework around symbolic algebra and standard chemical notion, we are working off the Applied Category Theory approach to reaction networks [[Baez Pollard, 2017](http://math.ucr.edu/home/baez/RxNet.pdf "baezpollard2017")].

 There are operations that are easy to do on the `Petri.Model` like "add a transition from R to S" that require simultaneously changing multiple parts of the algebraic formulation. Applied Category Theory gives a sound theoretical framework for manipulating Petri Nets as a model of chemical reactions. `Petri` is a Julia package primarily intended to investigate how we can operationalize this theory into practical scientific software.

 See [SemanticModels](https://github.com/jpfairbanks/SemanticModels.jl) for tools that work with Petri net models and manipulating them with higher level APIs based on ACT.
 This is related to the
 [DiffeqBiological](https://github.com/JuliaDiffEq/DiffEqBiological.jl) Reaction
 DSL, but takes a different implementation approach. Instead of building our
 framework around symbolic algebra and standard chemical notion, we are working
 off the Applied Category Theory approach to reaction networks [[Baez Pollard, 2017](http://math.ucr.edu/home/baez/RxNet.pdf)].

 There are operations that are easy to do on the `Petri.Model` like "add a
 transition from R to S" that require simultaneously changing multiple parts of
 the algebraic formulation. Applied Category Theory gives a sound theoretical
 framework for manipulating Petri Nets as a model in terms of the given domain.
 `Petri` is a Julia package primarily intended to investigate how we can
 operationalize this theory into practical scientific software.

 See [AlgebraicPetri](https://github.com/AlgebraicJulia/AlgebraicPetri.jl) for
 tools that work with Petri net models and manipulating them with higher level
 APIs based on Applied Category Theory.
--- a/docs/Project.toml
+++ b/docs/Project.toml
@ -1,3 +1,8 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 LabelledArrays = "2ee39098-c373-598a-b85f-a56591580800"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
 Petri = "4259d249-1051-49fa-8328-3f8ab9391c33"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 StochasticDiffEq = "789caeaf-c7a9-5a7d-9973-96adeb23e2a0"
--- a/docs/make.jl
+++ b/docs/make.jl
@ -1,18 +1,46 @@
 using Documenter
 using Literate

@info "Loading Petri"
 using Petri

 # Set Literate.jl config if not being compiled on recognized service.
 config = Dict{String,String}()
 if !(haskey(ENV, "GITHUB_ACTIONS") || haskey(ENV, "GITLAB_CI"))
  config["nbviewer_root_url"] = "https://nbviewer.jupyter.org/github/mehalter/Petri.jl/blob/gh-pages/dev"
  config["repo_root_url"] = "https://github.com/mehalter/Petri.jl/blob/master/docs"
 end

 const literate_dir = joinpath(@__DIR__, "..", "examples")
 const generated_dir = joinpath(@__DIR__, "src", "examples")

 for (root, dirs, files) in walkdir(literate_dir)
  out_dir = joinpath(generated_dir, relpath(root, literate_dir))
  for file in files
    f,l = splitext(file)
    if l == ".jl" && !startswith(f, "_")
      Literate.markdown(joinpath(root, file), out_dir;
        config=config, documenter=true, credit=false)
      Literate.notebook(joinpath(root, file), out_dir;
        execute=true, documenter=true, credit=false)
    end
  end
 end

@info "Building Documenter.jl docs"
 makedocs(
  modules   = [Petri],
  format    = Documenter.HTML(),
  format    = Documenter.HTML(
    assets = ["assets/analytics.js"],
  ),
  sitename  = "Petri.jl",
  doctest   = false,
  checkdocs = :none,
  pages     = Any[
    "Petri.jl" => "index.md",
    "Basic Usage" => "usage.md",
    "Examples" => Any[
      "examples/epidemiology.md",
    ],
    "Library Reference" => "api.md",
  ]
 )
--- a/docs/src/assets/analytics.js
+++ b/docs/src/assets/analytics.js
@ -0,0 +1,11 @@
 var _paq = window._paq || [];
 /* tracker methods like "setCustomDimension" should be called before "trackPageView" */
 _paq.push(['trackPageView']);
 _paq.push(['enableLinkTracking']);
 (function() {
  var u="https://matomo.mehalter.com/";
  _paq.push(['setTrackerUrl', u+'matomo.php']);
  _paq.push(['setSiteId', '4']);
  var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
  g.type='text/javascript'; g.async=true; g.defer=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);
 })();
--- a/docs/src/index.md
+++ b/docs/src/index.md
@ -5,21 +5,26 @@ CurrentModule = Petri
 ```

 `Petri.jl` is a Petri net modeling framework for the Julia programming language.
 `Petri` makes it easy to build complex reaction networks using a simple DSL.
 Once a model is defined, `Petri.jl` has support to generate ODE solutions and
 stochastic simulations using `DifferentialEquations.jl`.

 ## Goals

 `Petri` makes it easy to build complex reaction networks using a simple DSL. This is related to the[DiffeqBiological](https://github.com/JuliaDiffEq/DiffEqBiological.jl "DiffEqBiological") Reaction DSL, but takes a different implementation approach. Instead of building our framework around symbolic algebra and standard chemical notion, we are working off the Applied Category Theory approach to reaction networks [[Baez Pollard, 2017](http://math.ucr.edu/home/baez/RxNet.pdf "baezpollard2017")].

 There are operations that are easy to do on the `Petri.Model` like "add a transition from R to S" that require simultaneously changing multiple parts of the algebraic formulation. Applied Category Theory gives a sound theoretical framework for manipulating Petri Nets as a model of chemical reactions. `Petri` is a Julia package primarily intended to investigate how we can operationalize this theory into practical scientific software.

 See [AlgebraicPetri.jl](https://github.com/AlgebraicJulia/AlgebraicPetri.jl) for tools that work with Petri net models and manipulating them with higher level APIs based on ACT.

 ## Table of Contents
 ## Goals

 ```@contents
 Pages = [
    "usage.md",
    "api.md"
    ]
 Depth = 2
 ```
 This is related to the
 [DiffeqBiological](https://github.com/JuliaDiffEq/DiffEqBiological.jl) Reaction
 DSL, but takes a different implementation approach. Instead of building our
 framework around symbolic algebra and standard chemical notion, we are working
 off the Applied Category Theory approach to reaction networks [[Baez Pollard, 2017](http://math.ucr.edu/home/baez/RxNet.pdf)].

 There are operations that are easy to do on the `Petri.Model` like "add a
 transition from R to S" that require simultaneously changing multiple parts of
 the algebraic formulation. Applied Category Theory gives a sound theoretical
 framework for manipulating Petri Nets as a model in terms of the given domain.
 `Petri` is a Julia package primarily intended to investigate how we can
 operationalize this theory into practical scientific software.

 See [AlgebraicPetri](https://github.com/AlgebraicJulia/AlgebraicPetri.jl) for
 tools that work with Petri net models and manipulating them with higher level
 APIs based on Applied Category Theory.
--- a/examples/Project.toml
+++ b/examples/Project.toml
@ -1,5 +1,4 @@
 [deps]
 Catlab = "134e5e36-593f-5add-ad60-77f754baafbe"
 LabelledArrays = "2ee39098-c373-598a-b85f-a56591580800"
 OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
 Petri = "4259d249-1051-49fa-8328-3f8ab9391c33"
--- a/examples/epidemiology.jl
+++ b/examples/epidemiology.jl
@ -0,0 +1,96 @@
 # # [Basic Epidemiology Models](@id epidemiology_example)
 #
 #md # [![](https://img.shields.io/badge/show-nbviewer-579ACA.svg)](@__NBVIEWER_ROOT_URL__/examples/epidemiology.ipynb)

 using Petri
 using LabelledArrays
 using StochasticDiffEq
 using OrdinaryDiffEq
 using Plots

 # ### SIR Model
 #
 # The SIR model represents the epidemiological dynamics of an infectious disease
 # that causes immunity in its victims. There are three *states:* `Suceptible
 # ,Infected, Recovered`. These states interact through two *transitions*.
 # Infection has the form `S+I -> 2I` where a susceptible person meets an
 # infected person and results in two infected people. The second transition is
 # recovery `I -> R` where an infected person recovers spontaneously.

 S  = [:S,:I,:R]
 Δ  = LVector(
       inf=(LVector(S=1, I=1), LVector(I=2)),
       rec=(LVector(I=1),      LVector(R=1)),
     )
 sir = Petri.Model(S, Δ)

 Graph(sir)

 # Once a model is defined, we can define out initial parameters `u0`, a time
 # span `tspan`, and the transition rates of the interactions `β`

 u0 = LVector(S=10.0, I=1.0, R=0.0)
 tspan = (0.0,7.5)
 β = LVector(inf=0.4, rec=0.4);

 # Petri.jl provides interfaces to StochasticDiffEq.jl and OrdinaryDiffEq.jl
 # Here, we call the `SDEProblem` function that returns an StochasticDiffEq
 # problem object and an appropriate Callback set that can be passed to the
 # StochasticDiffEq solver which can then be plotted and visualized

 prob, cb = SDEProblem(sir, u0, tspan, β)

 sol = StochasticDiffEq.solve(prob,SRA1(),callback=cb)

 plot(sol)

 # Similarly, we can generated `ODEProblem` statements that can be used with
 # OrdinOrdinaryDiffEq solvers

 prob = ODEProblem(sir, u0, tspan, β)
 sol = OrdinaryDiffEq.solve(prob,Tsit5(),reltol=1e-8,abstol=1e-8)

 plot(sol)

 # ### SEIR Model

 S = [:S,:E,:I,:R]
 Δ = LVector(
      exp=(LVector(S=1, I=1), LVector(I=1, E=1)),
      inf=(LVector(E=1),      LVector(I=1)),
      rec=(LVector(I=1),      LVector(R=1)),
    )
 seir = Petri.Model(S, Δ)

 Graph(seir)
 #-
 u0 = LVector(S=10.0, E=1.0, I=0.0, R=0.0)
 tspan = (0.0,15.0)
 β = LVector(exp=0.9, inf=0.2, rec=0.5)

 prob, cb = SDEProblem(seir, u0, tspan, β)
 sol = StochasticDiffEq.solve(prob,SRA1(),callback=cb)

 plot(sol)

 # ### SEIRD Model

 S = [:S,:E,:I,:R, :D]
 Δ = LVector(
      exp=(LVector(S=1, I=1), LVector(I=1, E=1)),
      inf=(LVector(E=1),      LVector(I=1)),
      rec=(LVector(I=1),      LVector(R=1)),
      die=(LVector(I=1),      LVector(D=1)),
    )
 seird = Petri.Model(S, Δ)

 Graph(seird)
 #-
 u0 = LVector(S=10.0, E=1.0, I=0.0, R=0.0, D=0.0)
 tspan = (0.0,15.0)
 β = LVector(exp=0.9, inf=0.2, rec=0.5, die=0.1)

 prob, cb = SDEProblem(seird, u0, tspan, β)
 sol = StochasticDiffEq.solve(prob,SRA1(),callback=cb)

 plot(sol)
--- a/examples/epidemiologyModels.jl
+++ b/examples/epidemiologyModels.jl
@ -1,76 +0,0 @@
 # -*- coding: utf-8 -*-
 using Petri
 using LabelledArrays
 using StochasticDiffEq
 using OrdinaryDiffEq
 using Plots

@show "SIR"

 S  = [:S,:I,:R]
 Δ  = LVector(
      inf=(LVector(S=1, I=1), LVector(I=2)),
      rec=(LVector(I=1),      LVector(R=1)),
     )
 sir = Petri.Model(S, Δ)

 u0 = LVector(S=10.0, I=1.0, R=0.0)
 tspan = (0.0,7.5)
 β = LVector(inf=0.4, rec=0.4)


 prob, cb = SDEProblem(sir, u0, tspan, β)

 sol = StochasticDiffEq.solve(prob,SRA1(),callback=cb)

 plot(sol)

 prob = ODEProblem(sir, u0, tspan, β)
 sol = OrdinaryDiffEq.solve(prob,Tsit5(),reltol=1e-8,abstol=1e-8)

 plot(sol)

 Graph(sir)

@show "SEIR"

 S2 = [:S,:E,:I,:R]
 Δ2 = LVector(
     exp=(LVector(S=1, I=1), LVector(I=1, E=1)),
     inf=(LVector(E=1),      LVector(I=1)),
     rec=(LVector(I=1),      LVector(R=1)),
    )
 seir = Petri.Model(S2, Δ2)

 u0 = LVector(S=10.0, E=1.0, I=0.0, R=0.0)
 tspan = (0.0,15.0)
 β = LVector(exp=0.9, inf=0.2, rec=0.5)

 prob, cb = SDEProblem(seir, u0, tspan, β)
 sol = StochasticDiffEq.solve(prob,SRA1(),callback=cb)

 plot(sol)

 Graph(seir)

@show "SEIRD"

 S3 = [:S,:E,:I,:R, :D]
 Δ3 = LVector(
     exp=(LVector(S=1, I=1), LVector(I=1, E=1)),
     inf=(LVector(E=1),      LVector(I=1)),
     rec=(LVector(I=1),      LVector(R=1)),
     die=(LVector(I=1),      LVector(D=1)),
    )
 seird = Petri.Model(S3, Δ3)

 u0 = LVector(S=10.0, E=1.0, I=0.0, R=0.0, D=0.0)
 tspan = (0.0,15.0)
 β = LVector(exp=0.9, inf=0.2, rec=0.5, die=0.1)

 prob, cb = SDEProblem(seird, u0, tspan, β)
 sol = StochasticDiffEq.solve(prob,SRA1(),callback=cb)

 plot(sol)

 Graph(seird)