move to v5 (#591)

* move to v5 * add more changelog stuff * Update CHANGELOG, remove accidental JLD2 file * lways test in latest stable julia * use latest for of .bib * Add deprecations * Add to CHANGELOG * use agents.jl as bibentry name * state v5 in homepage * correct link to example zoo * Change names to new plotting names * wip update to final InteractiveDynamics * fix return `missing` in `move_along_route!` * add TODO that try-catch is bad for performance * limit code to 92 chars * correctly use `nearest_road` in zombies * add depwarnings inside the package * add latlon in changelog * add pre-recorded video of rabit hawk, it freezes build with CairoMakie * fix Graph integration Co-authored-by: Aayush Sabharwal <aayush.sabharwal@gmail.com>
JuliaDynamics · Mar 21, 2022 · b1cd6a8 · b1cd6a8
1 parent 5d1182d
commit b1cd6a8
Show file tree

Hide file tree

Showing 24 changed files with 225 additions and 352 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -56,7 +56,7 @@ jobs:
       fail-fast: false
       matrix:
         version:
-          - '1.6'
+          - '1'
         os:
           - ubuntu-18.04
         arch:

diff --git a/.gitignore b/.gitignore
@@ -9,3 +9,4 @@ Manifest.toml
 /.benchmarkci
 *.osm.cache
 src/update_*
+agents_visualizations.md
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,17 @@
+# v5
+- Agents.jl + InteractiveDynamics.jl now support native plotting for
+  open street map spaces, which is integrated in all interactive apps as well!
+- Most examples have been moved to AgentsExampleZoo.jl. Additional examples will now be added there.
+
+## BREAKING
+- Plotting, animating, and interacting GUIs based on InteractiveDynamics.jl have changed. Please see online docs for the new format.
+- LightGraphs.jl dependency is now replaced by Graphs.jl
+- OpenStreetMapX.jl dependency now replaced by LightOSM.jl. This mean initializing the space is different, and some API methods have changed. Check documentation for more details. Note that this also means checkpoints using the old `OpenStreetMapSpace` cannot be read in this version.
+- Functions for planning and moving along routes have had their names unified across Pathfinding and OpenStreetMap modules. The names now are `plan_route!` and `move_along_route!` and are accessible from the top level scope.
+- `OSM.intersection` is renamed to `OSM.nearest_node`
+- `OSM.road` is renamed to `OSM.nearest_road`
+- `latlon` is removed in favor of `OSM.lonlat`
+
 # v4.5.4
 - Previously `nearby_ids` with `r=0` for `GraphSpace` was undefined. Now it returns ids only in the same position as given.
 

diff --git a/CITATION.bib b/CITATION.bib
@@ -1,12 +1,13 @@
 @article{Agents.jl,
-author = {George Datseris and Ali R. Vahdati and Timothy C. DuBois},
-title ={Agents.jl: a performant and feature-full agent-based modeling software of minimal code complexity},
-journal = {SIMULATION},
-volume = {0},
-number = {0},
-pages = {00375497211068820},
-year = {0},
-doi = {10.1177/00375497211068820},
-URL = {https://doi.org/10.1177/00375497211068820},
-eprint = {https://doi.org/10.1177/00375497211068820},
+  doi = {10.1177/00375497211068820},
+  url = {https://doi.org/10.1177/00375497211068820},
+  year = {2022},
+  month = jan,
+  publisher = {{SAGE} Publications},
+  pages = {003754972110688},
+  author = {George Datseris and Ali R. Vahdati and Timothy C. DuBois},
+  title = {Agents.jl: a performant and feature-full agent-based modeling software of minimal code complexity},
+  journal = {{SIMULATION}},
+  volume = {0},
+  number = {0},
 }
diff --git a/Project.toml b/Project.toml
@@ -9,7 +9,6 @@ DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 DataStructures = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"
 Distributed = "8ba89e20-285c-5b6f-9357-94700520ee1b"
 Downloads = "f43a241f-c20a-4ad4-852c-f6b1247861c6"
-GraphRecipes = "bd48cda9-67a9-57be-86fa-5b3c104eda73"
 Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
 JLD2 = "033835bb-8acc-5ee8-8aae-3f567f8a3819"
 LazyArtifacts = "4af54fe1-eca0-43a8-85a7-787d91b784e3"
@@ -18,7 +17,6 @@ LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
 ProgressMeter = "92933f4c-e287-5a05-a399-4b506db050ca"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
-RecipesBase = "3cdcf5f2-1ef4-517c-9805-6587b60abb01"
 Requires = "ae029012-a4dd-5104-9daa-d747884805df"
 Scratch = "6c6a2e73-6563-6170-7368-637461726353"
 StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
@@ -27,13 +25,11 @@ StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
 CSV = "0.9.7, 0.10"
 DataFrames = "0.21, 0.22, 1"
 DataStructures = "0.18"
-GraphRecipes = "0.5"
 Graphs = "1.4"
 JLD2 = "0.4"
 LazyArtifacts = "1.3.0"
 LightOSM = "0.1.19"
 ProgressMeter = "1.5"
-RecipesBase = "1"
 Requires = "0.5, 0.6, 0.7, 1.0, 1.1"
 Scratch = "1"
 StatsBase = "0.32, 0.33"

diff --git a/README.md b/README.md
@@ -23,16 +23,17 @@ Any contribution to Agents.jl is welcome! For example you can:
 
 If you use this package in a publication, please cite the paper below:
 ```
-@article{Agents2021,
-author = {George Datseris and Ali R. Vahdati and Timothy C. DuBois},
-title ={Agents.jl: a performant and feature-full agent-based modeling software of minimal code complexity},
-journal = {SIMULATION},
-volume = {0},
-number = {0},
-pages = {00375497211068820},
-year = {0},
-doi = {10.1177/00375497211068820},
-URL = {https://doi.org/10.1177/00375497211068820},
-eprint = {https://doi.org/10.1177/00375497211068820},
+@article{Agents.jl,
+  doi = {10.1177/00375497211068820},
+  url = {https://doi.org/10.1177/00375497211068820},
+  year = {2022},
+  month = jan,
+  publisher = {{SAGE} Publications},
+  pages = {003754972110688},
+  author = {George Datseris and Ali R. Vahdati and Timothy C. DuBois},
+  title = {Agents.jl: a performant and feature-full agent-based modeling software of minimal code complexity},
+  journal = {{SIMULATION}},
+  volume = {0},
+  number = {0},
 }
 ```
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -25,3 +25,6 @@ RecipesBase = "3cdcf5f2-1ef4-517c-9805-6587b60abb01"
 SimpleWeightedGraphs = "47aef6b3-ad0c-573a-a1e2-d07658019622"
 SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
 StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
+
+[compat]
+Documenter = "0.24.6"
diff --git a/docs/make.jl b/docs/make.jl
@@ -27,6 +27,12 @@ for file in readdir(indir)
     Literate.markdown(joinpath(indir, file), outdir; credit = false)
 end
 
+# Also bring in visualizations from interactive dynamics docs:
+using Literate
+infile = joinpath(pkgdir(InteractiveDynamics), "docs", "src", "agents.jl")
+outdir = joinpath(@__DIR__, "src")
+Literate.markdown(infile, outdir; credit = false, name = "agents_visualizations")
+
 # %%
 # download the themes
 println("Theme-ing")
@@ -89,7 +95,7 @@ makedocs(
             "More Examples for Agents.jl" => "examples.md"
         ],
         "API" => "api.md",
-        "Plotting and interactive application" => "interact.md",
+        "Plotting and Interactivity" => "agents_visualizations.md",
         "Ecosystem Integration" => [
             "BlackBoxOptim.jl" => "examples/optim.md",
             "DifferentialEquations.jl" => "examples/diffeq.md",

diff --git a/docs/src/examples.md b/docs/src/examples.md
@@ -1,2 +1,2 @@
 # More Examples for Agents.jl
-In order to keep the documentation of Agents.jl lean and focused, the majority of model examples for Agents.jl are not hosted in this documentation, but rather in a different one: [Agents.jl Example Zoo]([More Examples for Agents.jl](https://juliadynamics.github.io/AgentsExampleZoo.jl/dev/)). Any kind of user-written example is welcomed to be contributed there as well!
+In order to keep the documentation of Agents.jl lean and focused, the majority of model examples for Agents.jl are not hosted in this documentation, but rather in a different one: [Agents.jl Example Zoo](https://juliadynamics.github.io/AgentsExampleZoo.jl/dev/). Any kind of user-written example is welcomed to be contributed there as well!
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -8,8 +8,11 @@ To get started, please read the [Tutorial](@ref) page.
     If you have found this package useful, please consider starring it on [GitHub](https://github.com/JuliaDynamics/Agents.jl).
     This gives us an accurate lower bound of the (satisfied) user count.
 
-!!! tip "Latest news: Agents.jl v4.5.7"
-      * The [Tutorial](@ref) page is now also available as a YouTube video: https://youtu.be/fgwAfAa4kt0 
+!!! tip "Latest news: Agents.jl v5"
+    New Major release with a lot of improvements!
+    * New packages used for Graph and OpenStreetMap spaces: Graphs.jl and LightOSM.jl.
+    * Native plotting of `OpenStreetMapSpace` through InteractiveDynamics.jl! This includes the interactive apps!
+    * Please see the [CHANGELOG.md](https://github.com/JuliaDynamics/Agents.jl/blob/master/CHANGELOG.md) for more details!
 
 
 ## Features
@@ -91,16 +94,17 @@ You're looking for support for Agents.jl? Look no further! Here's the three thin
 If you use this package in work that leads to a publication, then please cite the paper below:
 
 ```
-@article{Agents2021,
-author = {George Datseris and Ali R. Vahdati and Timothy C. DuBois},
-title ={Agents.jl: a performant and feature-full agent-based modeling software of minimal code complexity},
-journal = {SIMULATION},
-volume = {0},
-number = {0},
-pages = {00375497211068820},
-year = {0},
-doi = {10.1177/00375497211068820},
-URL = {https://doi.org/10.1177/00375497211068820},
-eprint = {https://doi.org/10.1177/00375497211068820},
+@article{Agents.jl,
+  doi = {10.1177/00375497211068820},
+  url = {https://doi.org/10.1177/00375497211068820},
+  year = {2022},
+  month = jan,
+  publisher = {{SAGE} Publications},
+  pages = {003754972110688},
+  author = {George Datseris and Ali R. Vahdati and Timothy C. DuBois},
+  title = {Agents.jl: a performant and feature-full agent-based modeling software of minimal code complexity},
+  journal = {{SIMULATION}},
+  volume = {0},
+  number = {0},
 }
 ```
diff --git a/docs/src/interact.md b/docs/src/interact.md
diff --git a/examples/flock.jl b/examples/flock.jl
@@ -115,27 +115,27 @@ using InteractiveDynamics
 using CairoMakie
 CairoMakie.activate!() # hide
 
-# The great thing about [`abm_plot`](@ref) is its flexibility. We can incorporate the
+# The great thing about [`abmplot`](@ref) is its flexibility. We can incorporate the
 # direction of the birds when plotting them, by making the "marker" function `am`
 # create a `Polygon`: a triangle with same orientation as the bird's velocity.
 # It is as simple as defining the following function:
 
-const bird_polygon = Polygon(Point2f0[(-0.5, -0.5), (1, 0), (-0.5, 0.5)])
+const bird_polygon = Polygon(Point2f[(-0.5, -0.5), (1, 0), (-0.5, 0.5)])
 function bird_marker(b::Bird)
     φ = atan(b.vel[2], b.vel[1]) #+ π/2 + π
     scale(rotate2D(bird_polygon, φ), 2)
 end
 
 # Where we have used the utility functions `scale` and `rotate2D` to act on a
-# predefined polygon. We now give `bird_marker` to `abm_plot`, and notice how
+# predefined polygon. We now give `bird_marker` to `abmplot`, and notice how
 # the `as` keyword is meaningless when using polygons as markers.
 
 model = initialize_model()
-figure, = abm_plot(model; am = bird_marker)
+figure, = abmplot(model; am = bird_marker)
 figure
 
 # And let's also do a nice little video for it:
-abm_video(
+abmvideo(
     "flocking.mp4", model, agent_step!;
     am = bird_marker,
     framerate = 20, frames = 100,

diff --git a/examples/rabbit_fox_hawk.jl b/examples/rabbit_fox_hawk.jl
@@ -1,10 +1,11 @@
 # # Rabbit, Fox, Hawk
 # ```@raw html
-# <video width="auto" controls autoplay loop>
-# <source src="../rabbit_fox_hawk.mp4" type="video/mp4">
+# <video width="100%" height="auto" controls autoplay loop>
+# <source src="https://raw.githubusercontent.com/JuliaDynamics/JuliaDynamics/master/videos/agents/rabbit_fox_hawk.mp4?raw=true" type="video/mp4">
 # </video>
 # ```
-# This model is much more advanced version of the [Predator-prey dynamics](https://juliadynamics.github.io/AgentsExampleZoo.jl/dev/examples/predator_prey_fast/) example. 
+
+# This model is much more advanced version of the [Predator-prey dynamics](https://juliadynamics.github.io/AgentsExampleZoo.jl/dev/examples/predator_prey_fast/) example.
 # It uses a 3-dimensional
 # [`ContinuousSpace`](@ref), a realistic terrain for the agents, and pathfinding (with multiple
 # pathfinders). It should be considered an advanced example for showcasing pathfinding.
@@ -29,11 +30,12 @@ mutable struct Animal <: AbstractAgent
     energy::Float64
 end
 
-## Some utility functions to create specific types of agents, and find the norm of a vector
+## Some utility functions to create specific types of agents,
+# and find the euclidean norm of a vector
 Rabbit(id, pos, energy) = Animal(id, pos, :rabbit, energy)
 Fox(id, pos, energy) = Animal(id, pos, :fox, energy)
 Hawk(id, pos, energy) = Animal(id, pos, :hawk, energy)
-norm(vec) = √sum(vec .^ 2)
+eunorm(vec) = √sum(vec .^ 2)
 
 # The environment is generated from a heightmap: a 2D matrix, where each value denotes the
 # height of the terrain at that point. We segregate the model into 4 regions based on the
@@ -226,15 +228,15 @@ function rabbit_step!(rabbit, model)
             all(away_direction .≈ 0.) && continue
             ## Add this to the overall direction, scaling inversely with distance.
             ## As a result, closer predators contribute more to the direction to move in
-            direction = direction .+ away_direction ./ norm(away_direction) ^ 2
+            direction = direction .+ away_direction ./ eunorm(away_direction) ^ 2
         end
         ## If the only predator is right on top of the rabbit
         if all(direction .≈ 0.)
             ## Move anywhere
             chosen_position = random_walkable(rabbit.pos, model, model.landfinder, model.rabbit_vision)
         else
             ## Normalize the resultant direction, and get the ideal position to move it
-            direction = direction ./ norm(direction)
+            direction = direction ./ eunorm(direction)
             ## Move to a random position in the general direction of away from predators
             position = rabbit.pos .+ direction .* (model.rabbit_vision / 2.)
             chosen_position = random_walkable(position, model, model.landfinder, model.rabbit_vision / 2.)
@@ -370,9 +372,10 @@ end
 # The agents are color-coded according to their `type`, to make them easily identifiable in
 # the visualization.
 
-using InteractiveDynamics
-using GLMakie
-GLMakie.activate!() # hide
+# ```julia
+# using InteractiveDynamics
+# using GLMakie # CairoMakie doesn't do 3D plots
+# ```
 
 animalcolor(a) =
     if a.type == :rabbit
@@ -403,22 +406,22 @@ heightmap_url =
     "JuliaDynamics/master/videos/agents/rabbit_fox_hawk_heightmap.png"
 model = initialize_model(heightmap_url)
 
-abm_video(
-    "rabbit_fox_hawk.mp4",
-    model,
-    animal_step!,
-    model_step!;
-    resolution = (700, 700),
-    frames = 300,
-    framerate = 20,
-    ac = animalcolor,
-    as = 1.0,
-    static_preplot!
-)
+# ```juia
+# abmvideo(
+#     "rabbit_fox_hawk.mp4",
+#     model, animal_step!, model_step!;
+#     figure = (resolution = (800, 700),),
+#     frames = 300,
+#     framerate = 15,
+#     ac = animalcolor,
+#     as = 1.0,
+#     static_preplot!,
+#     title = "Rabbit Fox Hawk with pathfinding"
+# )
+# ```
 
-nothing # hide
 # ```@raw html
-# <video width="auto" controls autoplay loop>
-# <source src="../rabbit_fox_hawk.mp4" type="video/mp4">
+# <video width="100%" height="auto" controls autoplay loop>
+# <source src="https://raw.githubusercontent.com/JuliaDynamics/JuliaDynamics/master/videos/agents/rabbit_fox_hawk.mp4?raw=true" type="video/mp4">
 # </video>
 # ```
-Original file line number
+Diff line change
@@ Expand Up / @@ -56,7 +56,7 @@ jobs: @@
           fail-fast: false
           matrix:
             version:
-              - '1.6'
+              - '1'
             os:
               - ubuntu-18.04
             arch:
@@ Expand Down @@