New function: replicate! (#830)

CHANGELOG.md

@@ -1,5 +1,9 @@
 # main
 
+- 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.

Project.toml

@@ -1,7 +1,7 @@
 name = "Agents"
 uuid = "46ada45e-f475-11e8-01d0-f70cc89e6671"
 authors = ["George Datseris", "Tim DuBois", "Aayush Sabharwal", "Ali Vahdati", "Adriano Meligrana"]
-version = "5.16.0"
+version = "5.17.0"
 
 [deps]
 CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"

src/simulations/sample.jl

@@ -1,4 +1,4 @@
-export sample!
+export sample!, replicate!
 using StatsBase: sample, Weights
 
 """
@@ -55,3 +55,38 @@ function add_newids!(model, org_ids, newids)
         end
     end
 end
+
+"""
+    replicate!(agent, model; kwargs...) 
+
+Create a new agent at the same position of the given agent, copying the values
+of its fields. With the `kwargs` it is possible to override the values by specifying
+new ones for some fields. 
+Return the new agent instance.
+
+## Example
+```julia
+using Agents
+@agent A GridAgent{2} begin
+    k::Float64
+    w::Float64
+end
+
+model = ABM(A, GridSpace((5, 5)))
+a = A(1, (2, 2), 0.5, 0.5)
+b = replicate!(a, model; w = 0.8)
+```
+"""
+function replicate!(agent, model; kwargs...)
+    newagent = deepcopy(agent)
+    for (key, value) in kwargs
+        setfield!(newagent, key, value)
+    end
+    newagent.id = nextid(model)
+    add_agent_pos!(newagent, model)
+    return newagent
+end
+
+function Base.deepcopy(agent::A) where {A<:AbstractAgent}
+    return A((deepcopy(getfield(agent, name)) for name in fieldnames(A))...)
+end

test/api_tests.jl

@@ -281,3 +281,14 @@ end
     @test idx_second_filtered[15] == (7, 2)
     @test idx_second_filtered[end] == (9, 10)
 end
+
+@testset "replicate!" begin
+    model = ABM(Agent8, ContinuousSpace((5, 5)))
+    a = Agent8(1, (2.0, 2.0), true, 1)
+    b = replicate!(a, model)
+    @test b.pos == a.pos && b.f1 == a.f1 && b.f2 == a.f2
+    c = replicate!(a, model; f2 = 2)
+    @test c.pos == a.pos && c.f1 == a.f1 && c.f2 == 2
+    d = replicate!(a, model; f1 = false, f2 = 2)
+    @test d.pos == a.pos && d.f1 == false && d.f2 == 2
+end