Browse Source

Documentation Update (#28)

* Updated docs to use Literate.jl to generate example notebooks

* Update README and docs
pull/29/head
Micah Halter 6 months ago
committed by GitHub
parent
commit
013075e6b9
No known key found for this signature in database GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 183 additions and 178 deletions
  1. +1
    -0
      .gitignore
  2. +20
    -84
      README.md
  3. +5
    -0
      docs/Project.toml
  4. +30
    -2
      docs/make.jl
  5. +11
    -0
      docs/src/assets/analytics.js
  6. +20
    -15
      docs/src/index.md
  7. +0
    -1
      examples/Project.toml
  8. +96
    -0
      examples/epidemiology.jl
  9. +0
    -76
      examples/epidemiologyModels.jl

+ 1
- 0
.gitignore View File

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


+ 20
- 84
README.md View File

@ -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.

+ 5
- 0
docs/Project.toml View File

@ -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"

+ 30
- 2
docs/make.jl View File

@ -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",
]
)


+ 11
- 0
docs/src/assets/analytics.js View File

@ -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);
})();

+ 20
- 15
docs/src/index.md View File

@ -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.

+ 0
- 1
examples/Project.toml View File

@ -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"


+ 96
- 0
examples/epidemiology.jl View File

@ -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)

+ 0
- 76
examples/epidemiologyModels.jl View File

@ -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)

Loading…
Cancel
Save