Merge pull request #1 from AlgebraicJulia/retry

Basic functionality

.gitignore

@@ -27,3 +27,7 @@ Manifest.toml
 .DS_Store
 .vscode
 .ipynb_checkpoints
+
+cache/
+
+figures/SIRSDiscretetrajectory.png

Project.toml

@@ -1,11 +1,19 @@
-name = "AlgebraicABMS"
-uuid = "1301f41b-2c8a-4430-9d85-ab97d23a62cd"
+name = "AlgebraicABMs"
+uuid = "5a5e3447-9604-46e6-8d91-cb86f5f51721"
 license = "MIT"
-authors = ["AlgebraicJulia Developer <[email protected]>"]
+authors = ["Kris Brown <[email protected]>"]
 version = "0.0.1"
 
 [deps]
+AlgebraicPetri = "4f99eebe-17bf-4e98-b6a1-2c4f205a959b"
+AlgebraicRewriting = "725a01d3-f174-5bbd-84e1-b9417bad95d9"
 Catlab = "134e5e36-593f-5add-ad60-77f754baafbe"
+DataStructures = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"
+Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
+Fleck = "5bb9b785-358c-4fee-af0f-b94a146244a8"
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+Reexport = "189a3867-3050-52da-a836-e630ba90ab69"
+SpecialFunctions = "276daf66-3868-5448-9aa4-cd146d93841b"
 
 [compat]
 Catlab = "^0.16"

README.md

@@ -1,42 +1,37 @@
-# AlgebraicABMS.jl
+# AlgebraicABMs.jl
 
-[![Stable Documentation](https://img.shields.io/badge/docs-stable-blue.svg)](https://AlgebraicJulia.github.io/AlgebraicABMS.jl/stable)
-[![Development Documentation](https://img.shields.io/badge/docs-dev-blue.svg)](https://AlgebraicJulia.github.io/AlgebraicABMS.jl/dev)
-[![Code Coverage](https://codecov.io/gh/AlgebraicJulia/AlgebraicABMS.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/AlgebraicJulia/AlgebraicABMS.jl)
-[![CI/CD](https://github.com/AlgebraicJulia/AlgebraicABMS.jl/actions/workflows/julia_ci.yml/badge.svg)](https://github.com/AlgebraicJulia/AlgebraicABMS.jl/actions/workflows/julia_ci.yml)
+[![Stable Documentation](https://img.shields.io/badge/docs-stable-blue.svg)](https://AlgebraicJulia.github.io/AlgebraicABMs.jl/stable)
+[![Development Documentation](https://img.shields.io/badge/docs-dev-blue.svg)](https://AlgebraicJulia.github.io/AlgebraicABMs.jl/dev)
+[![Code Coverage](https://codecov.io/gh/AlgebraicJulia/AlgebraicABMs.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/AlgebraicJulia/AlgebraicABMs.jl)
+[![CI/CD](https://github.com/AlgebraicJulia/AlgebraicABMs.jl/actions/workflows/julia_ci.yml/badge.svg)](https://github.com/AlgebraicJulia/AlgebraicABMs.jl/actions/workflows/julia_ci.yml)
 
-A template repository for making a new AlgebraicJulia package.
+Important example files: `docs/literate/petri_example.jl` and `test/ABMs.jl`
 
-## 🛠️ Usage
+## Caveats
+
+[Fleck.jl](https://github.com/adolgert/Fleck.jl) is not officially released, so you must clone that repo and `dev` it.
 
-1. Use the "Use this template" dropdown to select "Create a new repository"
-2. In the new page select "AlgebraicJulia" as the owner, give the repository a name, and create a new repository from the template
-3. Set up Codecov credentials for code coverage (If you have trouble, reach out to an AlgebraicJulia organization owner to help with this)
+This will need to be addressed before the tests can be run / documentation can be built automatically by Github actions.
+
+## 🛠️ Usage
 
-   1. Log into [Codecov](https://codecov.io) with your GitHub account (this requires that you are a member of the AlgebraicJulia organization)
-   2. Navigate to the [AlgebraicJulia organization](https://app.codecov.io/gh/AlgebraicJulia)
-   3. Select your new repository from the list (e.x. "AlgebraicX")
-   4. Note down the `CODECOV_TOKEN` value (It may be in the "Settings" tab if it doesn't show up immediately)
-   5. Navigate back to your new GitHub repository and go to the Settings tab
-   6. Go to "Security", "Secrets and variables", and "Actions" and click the "New repository secret" button
-   7. Give the secret name `CODECOV_TOKEN` and the Secret value is the value you noted from the Codecov settings
-   8. Click "Add secret"
+To locally build the documentation and the literate code examples, run the following in the command line:
+```
+julia --project=docs -e "using AlgebraicABMs, LiveServer; servedocs(literate_dir=\"docs/literate\",skip_dir=\"docs/src/generated\")"
+```
 
-4. Clone the new repository, for example in the terminal:
-   ```sh
-   git clone https://github.com/AlgebraicJulia/AlgebraicX.jl.git
-   cd AlgebraicX.jl
-   ```
-5. Inspect for yourself and run `init.sh` with the new repository name and (optional) UUID are parameters. This script will substitute all instances of `AlgebraicX` with your new repository name and the default UUID with a new one or, if available, the UUID provided.
-6. Go back to your repository and wait until the tests have passed, you can check the status by going to the "Actions" tab in the repository
+To locally run the test suite, run the following command
+```
+julia --project=test test/runtests.jl
+```
 
-### Buildkite
+### To-do: Buildkite
 
 AlgebraicJulia uses [Buildkite](https://buildkite.com/) to submit resource-intensive processes such as building documentation and executing tests to the [HiPerGator](https://www.rc.ufl.edu/about/hipergator/) computing cluster.
 
 While this template comes with a preconfigured `.buildkite/pipeline.yml` file, this repository is not integrated with Buildkite by default. If you would like your repository to use Buildkite to run processes on HiPerGator, tag an issue with @AlgebraicJulia/SysAdmins. 
 
-### 📔 Set Up GitHub Pages (Public Repos Only)
+### 📔 To-do: Set Up GitHub Pages (Public Repos Only)
 
 1. Follow the Usage steps above to set up a new template, make sure all initial GitHub Actions have passed
 2. Navigate to the repository settings and go to "Code and automation", "Pages"
@@ -45,21 +40,3 @@ While this template comes with a preconfigured `.buildkite/pipeline.yml` file, t
 5. Go back to the main page of your repository and click the gear to the right of the "About" section in the right side column
 6. Under "Website" check the checkbox that says "Use your GitHub Pages website" and click "Save changes"
 7. You will now see a URL in the "About" section that will link to your package's documentation
-
-### 🛡️ Set Up Branch Protection (Public Repos Only)
-
-1. Follow the Usage steps above to set up a new template, make sure all initial GitHub Actions have passed
-2. Navigate to the repository settings and go to "Code and automation", "Branches"
-3. Click "Add branch protection rule" to start adding branch protection
-4. Under "Branch name pattern" put `main`, this will add protection to the main branch
-5. Make sure to set the following options:
-   - Check the "Require a pull request before merging"
-   - Check the "Request status checks to pass before merging" and make sure the following status checks are added to the required list:
-     - CI / Documentation
-     - CI / Julia 1 - ubuntu-latest - x64 - push
-     - CI / Julia 1 - ubuntu-latest - x86 - push
-     - CI / Julia 1 - windows-latest - x64 - push
-     - CI / Julia 1 - windows-latest - x86 - push
-     - CI / Julia 1 - macOS-latest - x64 - push
-   - Check the "Restrict who can push to matching branches" and add `algebraicjuliabot` to the list of people with push access
-6. Click "Save changes" to enable the branch protection

docs/Project.toml

@@ -1,4 +1,11 @@
 [deps]
-AlgebraicABMS = "1301f41b-2c8a-4430-9d85-ab97d23a62cd"
+AlgebraicABMs = "5a5e3447-9604-46e6-8d91-cb86f5f51721"
+AlgebraicPetri = "4f99eebe-17bf-4e98-b6a1-2c4f205a959b"
+AlgebraicRewriting = "725a01d3-f174-5bbd-84e1-b9417bad95d9"
+CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
+Catlab = "134e5e36-593f-5add-ad60-77f754baafbe"
+Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
+LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589"
+Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"

docs/literate/game_of_life.jl

@@ -0,0 +1,41 @@
+# # Petri Net rewriting
+#
+# First we want to load our package with `using`
+
+using AlgebraicABMs
+using Catlab, AlgebraicPetri # for declaring model building blocks 
+using Distributions # for defining hazard rates
+
+# ## Schema 
+# 
+# We create a regular grid
+
+@present SchLife(FreeSchema) begin 
+  Cell::Ob 
+  (N,E,W,S)::Hom(Cell,Cell)
+  Life::Ob
+  live::Hom(Life,Cell)
+end
+
+# We define a network of cells
+
+@present SchLifeGraph <: SchSymmetricGraph begin 
+  Life::Ob
+  live::Hom(Life,V)
+end
+
+@acset_type Life(SchLifeGraph) <: AbstractSymmetricGraph
+
+function living_neighbors(n::Int; alive=false)
+  X = Life(1)
+  alive && add_part!(X, :Live, live=1)
+  for _ in 1:n
+    v = add_part!(X, :V)
+    add_part!(X, :Life, live=v)
+    add_edge!(X, v, 1)
+  end
+  X
+end
+
+living_neighbors(2)
+

docs/literate/petri_example.jl

@@ -0,0 +1,68 @@
+# # Petri Net rewriting
+#
+# First we want to load our package with `using`
+
+using AlgebraicABMs
+using Catlab, AlgebraicPetri # for declaring model building blocks 
+using Distributions # for defining hazard rates
+using Makie, CairoMakie # visualization
+
+# ## Petri-net based model
+#
+# We define an SIRS model with birth and death
+
+sir_pn= @acset LabelledPetriNet begin
+  S=3; sname=[:S,:I,:R]
+  T=7; tname=[:inf,:rec,:birth,:deathS,:deathI,:deathR,:wane]
+  I=7; it=[1,1,2,4,5,6,7]; is=[1,2,2,1,2,3,3]
+  O=5; ot=[1,1,2,3,7]; os=[2,2,3,1,1]
+end
+
+to_graphviz(sir_pn)
+
+# A "state of the world" in this model is just a finite set of Susceptible, Infected, and Recovered people. Thus we can specify a model with 3 integers.
+
+init = PetriNetCSet(sir_pn, S=100, I=5); # Initial state
+
+
+# We declare parameters to specify the random waiting times
+pS, pI, pR = 95,5,0
+pop = 100
+lifespan = 65*365
+μ = 1/lifespan
+β = 0.001
+wane = 60;
+
+# We associate with each transition a function which takes a time point and return a distribution of waiting times
+clockdists = Dict{Symbol,Function}();
+
+## the Exponential clocks (Markov)
+clockdists[:inf] = (t) -> Exponential(1 / β)
+clockdists[:birth] = (t) -> Exponential(1 / (μ*pop))
+clockdists[:deathS] = (t) -> Exponential(1 / μ)
+clockdists[:deathI] = (t) -> Exponential(1 / μ)
+clockdists[:deathR] = (t) -> Exponential(1 / μ)
+clockdists[:wane] = (t) -> Exponential(wane)
+
+## the Weibull clock (non-Markov)
+α, θ = weibullpar(30, 5)
+clockdists[:rec] = (t) -> Weibull(α, θ);
+
+# We make a reporting function that extracts information from each time step.
+count(acs::ACSet) = 
+  NamedTuple(Dict([o => nparts(acs, o) for o in ob(acset_schema(acs))]));
+
+
+# We simulate a model
+sirout = run!(sir_pn, clockdists, init; save=count, maxevent=2000)
+X = first.(sirout)
+SIR = [getindex.(last.(sirout), x) for x in 1:3]
+f = Figure();
+Legend(f[1, 2], lines!.(Ref(Axis(f[1,1])), Ref(X), SIR), ["S", "I","R"])
+
+## We can also save the figure to the filesystem.
+isdir("figures") || mkdir("figures");
+Makie.save("figures/SIRSDiscretetrajectory.png", f, px_per_unit=1, size=(800,600));
+
+f
+

docs/make.jl

@@ -1,11 +1,11 @@
 using Documenter
 using Literate
 
-const literate_dir = joinpath(@__DIR__, "literate")
-const generated_dir = joinpath(@__DIR__, "src", "generated")
+const LITERATE_INPUT = joinpath(@__DIR__, "literate")
+const LITERATE_OUTPUT = joinpath(@__DIR__, "src", "generated")
 
-@info "Loading AlgebraicABMS"
-using AlgebraicABMS
+@info "Loading AlgebraicABMs"
+using AlgebraicABMs
 
 const no_literate = "--no-literate" in ARGS
 if !no_literate
@@ -14,35 +14,47 @@ if !no_literate
   # 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/AlgebraicJulia/AlgebraicABMS.jl/blob/gh-pages/dev"
-    config["repo_root_url"] = "https://github.com/AlgebraicJulia/AlgebraicABMS.jl/blob/main/docs"
+    config["nbviewer_root_url"] = "https://nbviewer.jupyter.org/github/AlgebraicJulia/AlgebraicABMs.jl/blob/gh-pages/dev"
+    config["repo_root_url"] = "https://github.com/AlgebraicJulia/AlgebraicABMs.jl/blob/main/docs"
   end
 
-  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
+  # 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
+
+  for (root, _, files) ∈ walkdir(LITERATE_INPUT), file ∈ files
+    # ignore non julia files
+    splitext(file)[2] == ".jl" || continue
+    # full path to a literate script
+    ipath = joinpath(root, file)
+    # generated output path
+    opath = splitdir(replace(ipath, LITERATE_INPUT=>LITERATE_OUTPUT))[1]
+    # generate the markdown file calling Literate
+    Literate.markdown(ipath, opath)
   end
+
 end
 
 @info "Building Documenter.jl docs"
 makedocs(
-  modules=[AlgebraicABMS],
+  modules=[AlgebraicABMs],
   format=Documenter.HTML(),
-  sitename="AlgebraicABMS.jl",
+  sitename="AlgebraicABMs.jl",
   doctest=false,
   checkdocs=:none,
   pages=Any[
-    "AlgebraicABMS.jl"=>"index.md",
+    "AlgebraicABMs.jl"=>"index.md",
     "Examples"=>Any[
-      "generated/literate_example.md",
+      "generated/petri_example.md",
     ],
     "Library Reference"=>"api.md",
   ]
@@ -51,6 +63,6 @@ makedocs(
 @info "Deploying docs"
 deploydocs(
   target="build",
-  repo="github.com/AlgebraicJulia/AlgebraicABMS.jl.git",
+  repo="github.com/AlgebraicJulia/AlgebraicABMs.jl.git",
   branch="gh-pages"
 )

docs/src/api.md

@@ -1,5 +1,9 @@
 # Library Reference
 
 ```@autodocs
-Modules = [AlgebraicABMS]
+Modules = [
+  AlgebraicABMs.Distributions,
+  AlgebraicABMs.PetriInterface,
+  AlgebraicABMs.RewriteSemiMarkov
+]
 ```

docs/src/index.md

@@ -1,7 +1,10 @@
-# AlgebraicABMS.jl
+# AlgebraicABMs.jl
 
 ```@meta
-CurrentModule = AlgebraicABMS
+CurrentModule = AlgebraicABMs
 ```
 
-`AlgebraicABMS.jl` is a Julia library for...
+`AlgebraicABMs.jl` is a Julia library for creating agent-based models. We ultimate want to provide capabilities on par with software like AnyLogic, NetLogo, and Agents.jl - all while offering a mostly declarative interface such that: 
+- The model's logic is transparent (rather than hidden away in complicated interactions of code blocks)
+- Models can be built compositionally (we can naturally 'glue' models together at a high level, without worrying about implementation details and edge-cases)
+- Models can be _migrated_ at a high level, whether interpersonally (collaboration with others who have a different ontology/vocabulary) or intrapersonally (one updates one's own model of the of world and wishes to reuse one's old model under new assumptions, without having to manually refactor code and dig into implementation details).

init.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 
-DEFAULT_REPO='AlgebraicABMS'
-DEFAULT_UUID='1301f41b-2c8a-4430-9d85-ab97d23a62cd' 
+DEFAULT_REPO='AlgebraicABMs'
+DEFAULT_UUID='5A5E3447-9604-46E6-8D91-CB86F5F51721' 
 
 usage="This script is for initializing the template with the new repository name and UUID. Please provide the new repository name and UUID in that order. The repository name cannot be 'Test.'\n
 Example:\n