mehalter
/
Petri.jl
mirror of https://github.com/mehalter/Petri.jl.git
1
1
Fork 0
Code Issues Releases Activity
Browse Source

Documentation Update (#28) 

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

* Update README and docs
pull/29/head
Micah Halter 9 months ago
committed by GitHub
parent
ff25089876
commit
013075e6b9
No known key found for this signature in database GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 183 additions and 178 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 1
      .gitignore
  2. 104
      README.md
  3. 5
      docs/Project.toml
  4. 32
      docs/make.jl
  5. 11
      docs/src/assets/analytics.js
  6. 35
      docs/src/index.md
  7. 1
      examples/Project.toml
  8. 96
      examples/epidemiology.jl
  9. 76
      examples/epidemiologyModels.jl

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

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

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

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

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

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)
Write Preview
Loading…
Cancel
Save