JuliaDynamics · Datseris · Oct 5, 2023 · Sep 25, 2023 · Sep 26, 2023 · Sep 26, 2023
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,21 +1,31 @@
-# v6
-- The `@agent` macro has been rewritten to support fields with default and const values. The old version still works but it's deprecated. Since now the macro supports these features, using `@agent` is the only supported way to create agent types for Agents.jl.
-- Manually setting or altering the ids of agents is no longer allowed. The agent id is now considered a read-only field, and is set internally by Agents.jl to enable hidden optimizations in the future. As a consequence, `add_agent!(agent::AbstractAgent, pos::ValidPos, model::ABM)`  and `add_agent!(agent::AbstractAgent, model::ABM)`  have been deprecated. See issue #861 for more.
-- Agent types in `ContinuousSpace` now use `SVector` for their `pos` and `vel` fields rather than `NTuple`. 
-- Two new functions `random_id_in_position` and `random_agent_in_position` can be used to select a random id/agent in a position in discrete spaces (even with filtering). 
+# v6 - New Major release!
+
+## Major and/or BREAKING
+
+_We tried to deprecate every major change, resulting in practically no breakage from v5 to v6. However, in version v6.2 we will remove all deprecations (and hence un-updated code will break)_
+
+- Deprecations that were in place in v5 (see section `# v5` of this CHANGELOG) have been removed.
+- The way the evolution rule (`agent_step!, model_step!`) is handled has changed. Now, the stepping functions must be given to the agent based model during construction of the model instead of given to `step!, run!, abmplot, ...`. This change is important and allows us to:
+  - Have Agents.jl have the same mental model as DifferentialEquations.jl, DynamicalSystems.jl, and other dynamical modelling packages, where the evolution rules are part of the central simulation struct.
+  - Allows us to develop new types of models that may have rules that are defined differently, without being based on e.g., two particular functions.
+  - Allows us to develop (in the future) a new model type that is optimized for multi-agent simulations.
+- The `@agent` macro has been rewritten to support fields with default and const values. It has a new usage syntax now that parallelizes more Julia's native `struct` declaration. The old macro version still works but it's deprecated. Since now the macro supports these features, using `@agent` is the only supported way to create agent types for Agents.jl.
+- Manually setting or altering the ids of agents is no longer allowed. The agent id is now considered a read-only field, and is set internally by Agents.jl to enable hidden optimizations in the future. As a consequence, `add_agent!(agent::AbstractAgent, pos::ValidPos, model::ABM)`  and `add_agent!(agent::AbstractAgent, model::ABM)` have been deprecated. See issue #861 for more.
+- Agent types in `ContinuousSpace` now use `SVector` for their `pos` and `vel` fields rather than `NTuple`. `NTuple` usage in `ContinuousSpace` is officially deprecated, but backward compatibility is *mostly* maintained. Known breakages include the comparison of agent position and/or velocity with user-defined tuples, e.g., doing `agent.pos == (0.5, 0.5)`. This will always be `false` in v6 as `agent.pos` is an `SVector`. The rest of the functionality should all work without problems, such as moving agents to tuple-based positions etc.
+
+## New features
+
+- Two new functions `random_id_in_position` and `random_agent_in_position` can be used to select a random id/agent in a position in discrete spaces (even with filtering).
 - A new argument `alloc` can be used to select a more performant version in relation to the expensiveness of the filtering for all random methods selecting ids/agents/positions.
 - The `sample!` function is up to 2x faster than before.
-- All spaces support boundaries with mixed periodicity, specified by tuples with a `Bool` value for each dimension, e.g. `GridSpace((5,5); periodic=(true,false))` is periodic along the first dimension but not along the second.
-
-## BREAKING
-- `NTuple` in `ContinuousSpace` is officially deprecated, but backward compatibility is *mostly* maintained. Known breakages include the comparison of agent position and/or velocity with user-defined tuples, e.g., doing `agent.pos == (0.5, 0.5)`. This will always be `false` in v6 as `agent.pos` is an `SVector`. The rest of the functionality should all work without problems, such as moving agents to tuple-based positions etc.
+- Grid and continuous spaces support boundaries with mixed periodicity, specified by tuples with a `Bool` value for each dimension, e.g. `GridSpace((5,5); periodic=(true,false))` is periodic along the first dimension but not along the second.
 
 # v5.17
 
 - New function `replicate!` allows to create a new instance of a given agent at the same position with the possibility to specify some
   fields with new values.
 - The `sample!` function is 3x faster than before.
-  
+
 # v5.16
 
 - New function `offline_run!` allows writing data to file at predefined intervals during `run!` instead of storing it in memory. Currently supports [CSV](https://csv.juliadata.org/stable/) and [Arrow](https://apache.github.io/arrow-julia/stable/) files.

diff --git a/docs/Project.toml b/docs/Project.toml
@@ -27,6 +27,3 @@ SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
 StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 CellListMap = "69e1c6dd-3888-40e6-b3c8-31ac5f578864"
-
-[compat]
-Documenter = "0.24.6"
diff --git a/docs/logo/example_zoo.jl b/docs/logo/example_zoo.jl
@@ -385,7 +385,7 @@ function forest_fire(; density = 0.7, griddims = (100, 100), seed = 2)
     ## Empty = 0, Green = 1, Burning = 2, Burnt = 3
     forest = ABM(GridAgent{2}, space; rng, properties = (trees = zeros(Int, griddims),))
     for I in CartesianIndices(forest.trees)
-        if rand(forest.rng) < density
+        if rand(abmrng(forest)) < density
             ## Set the trees at the left edge on fire
             forest.trees[I] = I[1] == 1 ? 2 : 1
         end

diff --git a/docs/src/api.md b/docs/src/api.md
@@ -3,9 +3,11 @@
 The API of Agents.jl is defined on top of the fundamental structures [`AgentBasedModel`](@ref), [Space](@ref Space), [`AbstractAgent`](@ref) which are described in the [Tutorial](@ref) page.
 In this page we list the remaining API functions, which constitute the bulk of Agents.jl functionality.
 
-## [Concrete ABM implementations](@id ABM_Implementations)
+## [More ABM implementations](@id ABM_Implementations)
+
+Besides the generic interface of [`AgentBasedModel`](@ref), and the [`StandardABM`](@ref), highlighted in the tutorial, there is also:
+
 ```@docs
-StandardABM
 UnremovableABM
 ```