diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6275bff231..2309271b5e 100644 --- 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 index 3e4f498ac9..8954718ea4 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,4 @@ Manifest.toml /.benchmarkci *.osm.cache src/update_* +agents_visualizations.md \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 8d99496179..468c4e333d 100644 --- 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 index 2f60095185..944f833412 100644 --- 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}, } \ No newline at end of file diff --git a/Project.toml b/Project.toml index c8dda3216f..075e0d72f4 100644 --- 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 index 7e29e8f621..ac8503312f 100644 --- 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 index cdf2e4a774..ea2b895fd0 100644 --- 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" \ No newline at end of file diff --git a/docs/make.jl b/docs/make.jl index b06a07cb2a..b141062435 100644 --- 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 index f34d93885d..c78d7a3cd4 100644 --- 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 index 4b92bac304..9f2d787773 100644 --- 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 deleted file mode 100644 index 512ec3726d..0000000000 --- a/docs/src/interact.md +++ /dev/null @@ -1,51 +0,0 @@ -# Plotting and interactive application -Plotting and interaction functionality comes from [`InteractiveDynamics`](https://juliadynamics.github.io/InteractiveDynamics.jl/dev/), another package of JuliaDynamics, which uses Makie.jl. - -Plotting, and the interactive application of Agents.jl, are _model-agnostic_ and _simple to use_. Defining simple functions that map agents to colors, and shapes, is the only thing you need to do. If you have already defined an ABM and functions for stepping the model, you typically need to write only an extra couple of lines of code to get your visualizations going. All models in the Examples showcase plotting. - -You need to install both `InteractiveDynamics`, as well as a plotting backend (we recommend `GLMakie`) to use the following functions. - -The version of `InteractiveDynamics` used in the docs is: -```@example versions -using Pkg -Pkg.status("InteractiveDynamics") -``` - -Some parts of Agents.jl cannot be plotted yet in Makie.jl, and therefore alternatives are provided. However in the near future we hope to have moved everything to plotting with Makie.jl and not necessitate usage of Plots.jl or other libraries. - -## Plotting -The following functions allow you to plot an ABM, animate it via play/pause buttons, or directly export the time evolution into a video. At the moment these functions support 2D continuous and discrete space. - -```@docs -InteractiveDynamics.abm_plot -InteractiveDynamics.abm_play -InteractiveDynamics.abm_video -``` - -## Interactive application - -```@docs -InteractiveDynamics.abm_data_exploration -``` - -Here is an example application made with [`InteractiveDynamics.abm_data_exploration`](@ref) from the [Daisyworld](@ref) example. - -## Graph plotting -To plot agents existing of a [`GraphSpace`](@ref) we can't use `InteractiveDynamics` because Makie.jl does not support plotting on graphs (yet). We provide the following function in this case, which comes into scope when `using Plots`. See also the [SIR model for the spread of COVID-19](@ref) example for an application. -```@docs -abm_plot_on_graph -``` - -## Open Street Map plotting -Plotting an open street map is also not possible with Makie.jl at the moment, but there is a Julia package that does this kind of plotting, OpenStreetMapXPlots.jl. Its usage is demonstrated in the [Zombie Outbreak](@ref) example page. - -## Plots.jl Recipes -Whilst the primary method for plotting agents models is through `InteractiveDynamics`, the following Plots recipes can also be used if you prefer the Plots.jl ecosystem. - -Notice that these methods will emit a warning. Pass `warn = false` to suppress it. - -```@docs -plotabm -plotabm! -``` - diff --git a/examples/flock.jl b/examples/flock.jl index 6c92d343ae..8fdcdeb59e 100644 --- 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 index 05980645b9..3b1cc0e3b5 100644 --- a/examples/rabbit_fox_hawk.jl +++ b/examples/rabbit_fox_hawk.jl @@ -1,10 +1,11 @@ # # Rabbit, Fox, Hawk # ```@raw html -#