diff --git a/README.md b/README.md index c1c78de..ba48ab8 100644 --- a/README.md +++ b/README.md @@ -53,7 +53,9 @@ cellular automata, one and two dimensional. - **Update schemes**: `Synchronous` (default) and `Stochastic(rate)` for per-cell probabilistic updates, given an explicit `rng`. - **Neighborhoods**: `Moore` (default, square) and `VonNeumann` (diamond) shapes - for `Life`, extensible to custom `AbstractNeighborhood` subtypes. + for `Life`, plus a weighted, circular `Kernel` shape (groundwork for future + convolution-based rules such as Lenia); extensible to custom + `AbstractNeighborhood` subtypes. - **Functional core** (`next_state`, `rollout`): non-mutating, AD/GPU-friendly building blocks for custom or neural cellular automata, alongside the stateful `CellularAutomaton` wrapper. diff --git a/docs/src/api/twodim.md b/docs/src/api/twodim.md index 8a27e16..b109ad0 100644 --- a/docs/src/api/twodim.md +++ b/docs/src/api/twodim.md @@ -9,5 +9,7 @@ AbstractNeighborhood Moore VonNeumann + Kernel neighborhood_offsets + neighborhood_weight ``` diff --git a/src/CellularAutomata.jl b/src/CellularAutomata.jl index cfca5ea..956bc38 100644 --- a/src/CellularAutomata.jl +++ b/src/CellularAutomata.jl @@ -15,7 +15,7 @@ include("random.jl") export AbstractCellularAutomaton, AbstractCellularAutomatonRule export AbstractBoundaryCondition, Periodic, Reflecting, ConstantBoundary export AbstractUpdateScheme, Synchronous, Stochastic -export AbstractNeighborhood, Moore, VonNeumann +export AbstractNeighborhood, Moore, VonNeumann, Kernel export AbstractDiscreteCellularAutomatonRule export AbstractContinuousCellularAutomatonRule export AbstractTotalisticCellularAutomatonRule @@ -23,7 +23,8 @@ export AbstractLifeLikeCellularAutomatonRule export CellularAutomaton export next_state, rollout, spatial_dimensions export cellular_automaton_rule, evolution_history, generation_count -export neighborhood_offsets, neighborhood_radius, rule_lookup_table, cell_state_count +export neighborhood_offsets, neighborhood_radius, neighborhood_weight +export rule_lookup_table, cell_state_count export DCA export CCA export TCA diff --git a/src/generics.jl b/src/generics.jl index 47b2dfc..e8d35b7 100644 --- a/src/generics.jl +++ b/src/generics.jl @@ -87,7 +87,8 @@ Supertype for two-dimensional neighborhood shapes, used to enumerate the cells around a given cell (excluding the cell itself). Subtypes must implement [`neighborhood_offsets`](@ref) and -[`neighborhood_radius`](@ref). +[`neighborhood_radius`](@ref); [`neighborhood_weight`](@ref) is optional and defaults +to `1` for every offset. """ abstract type AbstractNeighborhood end @@ -170,6 +171,58 @@ function neighborhood_radius end neighborhood_radius(neighborhood::Moore) = neighborhood.radius neighborhood_radius(neighborhood::VonNeumann) = neighborhood.radius +""" + Kernel(radius, weight) + +Circular, weighted neighborhood: every cell within Euclidean distance `radius` of the +center (excluding the center itself) is weighted by `weight(distance / radius)`, a +function of the normalized distance in `(0, 1]`. This is the neighborhood shape used +by Lenia-style continuous cellular automata, where `weight` is the kernel's radial +profile. No built-in rule consumes [`neighborhood_weight`](@ref) yet; `Kernel` combined +with an existing rule such as [`Life`](@ref) only affects which cells are counted, not +their contribution. +""" +struct Kernel{F} <: AbstractNeighborhood + radius::Int + weight::F + function Kernel{F}(radius::Int, weight::F) where {F} + radius >= 1 || throw(ArgumentError("radius must be at least 1")) + return new{F}(radius, weight) + end +end + +Kernel(radius::Int, weight::F) where {F} = Kernel{F}(radius, weight) + +function Base.show(io::IO, neighborhood::Kernel) + return print(io, "Kernel(", neighborhood.radius, ", ", neighborhood.weight, ")") +end + +function neighborhood_offsets(neighborhood::Kernel) + radius = neighborhood.radius + return ( + (row, column) + for row in (-radius):radius, column in (-radius):radius + if !(row == 0 && column == 0) && row^2 + column^2 <= radius^2 + ) +end + +neighborhood_radius(neighborhood::Kernel) = neighborhood.radius + +""" + neighborhood_weight(neighborhood::AbstractNeighborhood, row_offset, column_offset) + +Return the weight applied to the cell at `(row_offset, column_offset)` in +`neighborhood`. Defaults to `1` for every offset, matching unweighted neighborhoods +such as [`Moore`](@ref) and [`VonNeumann`](@ref); [`Kernel`](@ref) overrides this to +return its radial weight profile. +""" +neighborhood_weight(::AbstractNeighborhood, row_offset, column_offset) = 1 + +function neighborhood_weight(neighborhood::Kernel, row_offset, column_offset) + distance = sqrt(row_offset^2 + column_offset^2) / neighborhood.radius + return neighborhood.weight(distance) +end + """ AbstractUpdateScheme diff --git a/test/neighborhood_test.jl b/test/neighborhood_test.jl index 08e48eb..f1ee840 100644 --- a/test/neighborhood_test.jl +++ b/test/neighborhood_test.jl @@ -12,8 +12,10 @@ CellularAutomata.neighborhood_offsets(::HorizontalNeighborhood) = ((0, -1), (0, @testset "constructor validation" begin @test neighborhood_radius(Moore(2)) == 2 @test neighborhood_radius(VonNeumann(; radius = 2)) == 2 + @test neighborhood_radius(Kernel(2, identity)) == 2 @test_throws ArgumentError Moore(-1) @test_throws ArgumentError VonNeumann(-1) + @test_throws ArgumentError Kernel(0, identity) @test_throws ArgumentError Life(((3,), (2, 3)); radius = 0) @test_throws ArgumentError Life(((3,), (2, 3)); neighborhood = VonNeumann(0)) end @@ -21,6 +23,7 @@ end @testset "show methods" begin @test repr(Moore(1)) == "Moore(1)" @test repr(VonNeumann(2)) == "VonNeumann(2)" + @test repr(Kernel(1, identity)) == "Kernel(1, identity)" @test repr(Life(((3,), (2, 3)))) == "Life(((3,), (2, 3)); radius=1)" @test repr(Life(((3,), (2, 3)); neighborhood = VonNeumann(1))) == "Life(((3,), (2, 3)); neighborhood=VonNeumann(1))" @@ -37,6 +40,33 @@ end @test (0, 0) ∉ vonneumann_offsets @test (1, 1) ∉ vonneumann_offsets @test (1, 0) ∈ vonneumann_offsets + + kernel_offsets = Set(neighborhood_offsets(Kernel(2, identity))) + @test (0, 0) ∉ kernel_offsets + @test (1, 0) ∈ kernel_offsets + @test (2, 2) ∉ kernel_offsets # outside the circular radius, unlike Moore + @test kernel_offsets == Set([ + (row, column) + for row in -2:2, column in -2:2 + if !(row == 0 && column == 0) && row^2 + column^2 <= 4 + ]) + @test all(row^2 + column^2 <= 4 for (row, column) in kernel_offsets) +end + +@testset "neighborhood_weight" begin + @test neighborhood_weight(Moore(1), 1, 1) == 1 + @test neighborhood_weight(VonNeumann(1), 1, 0) == 1 + + kernel = Kernel(2, r -> 1 - r) + @test neighborhood_weight(kernel, 2, 0) ≈ 0 + @test neighborhood_weight(kernel, 1, 0) ≈ 0.5 + # symmetric under sign flips: weight depends only on Euclidean distance + @test neighborhood_weight(kernel, -1, 0) ≈ neighborhood_weight(kernel, 1, 0) + @test neighborhood_weight(kernel, 0, -1) ≈ neighborhood_weight(kernel, 1, 0) + @test all( + 0 <= neighborhood_weight(kernel, row, column) <= 1 + for (row, column) in neighborhood_offsets(kernel) + ) end @testset "VonNeumann and Moore neighborhoods can disagree" begin