KSLCore/ksl.modeling.agent/GridProjection

GridProjection

class GridProjection<A : AgentLike> @JvmOverloads constructor(val context: AgentModel.Context<A>, val columns: Int, val rows: Int, val occupancy: GridOccupancy = GridOccupancy.MULTIPLE, val torus: Boolean = false, val name: String = "grid") : Projection<A> (source)

A 2D lattice projection: each agent in the context occupies an integer-coordinate Cell. The grid has fixed columns and rows; cells are addressed by (col, row) with col ∈ [0, columns) and row ∈ [0, rows).

Occupancy semantics:

GridOccupancy.MULTIPLE (default) — multiple agents may share a cell. Typical for swarm / crowd / movement models.
GridOccupancy.SINGLE — at most one agent per cell. placeAt throws if the target cell is already occupied by a different agent; use tryPlaceAt for the conditional case.

Boundary semantics:

Bounded (default) — coordinates outside [0, columns) × [0, rows) throw. Cells near the edge have fewer neighbors.
Torus (torus = true) — coordinates wrap; the top-left and top-right cells are neighbors. Useful for finite-but-edge-free models (Game of Life, infinite-plane approximations).

Spatial queries — neighborsOf, agentsAt, cellsWithin — do linear scans over the occupancy map. Performance is fine for typical agent counts; a future spatial index could swap in without changing this class's public API.

Constructors

GridProjection

@JvmOverloads

constructor(context: AgentModel.Context<A>, columns: Int, rows: Int, occupancy: GridOccupancy = GridOccupancy.MULTIPLE, torus: Boolean = false, name: String = "grid")

Types

Defaults

object Defaults

Mutable global defaults for GridProjection queries.

Properties

columns

val columns: Int

context

val context: AgentModel.Context<A>

name

open override val name: String

Display name for diagnostics.

occupancy

val occupancy: GridOccupancy

rows

val rows: Int

size

val size: Int

Number of agents currently placed on the grid.

torus

val torus: Boolean

Functions

agentsAt

fun agentsAt(cell: Cell): List<A>

All agents currently on cell. Empty list if the cell is unoccupied.

fun agentsAt(col: Int, row: Int): List<A>

agentsWithin

fun agentsWithin(cell: Cell, radius: Int, metric: GridMetric = GridMetric.CHEBYSHEV, includeCenter: Boolean = false): List<A>

All agents currently in cells within radius of cell under metric. Excludes occupants of cell itself unless includeCenter is true.

cellOf

fun cellOf(agent: A): Cell?

Cell currently occupied by agent, or null if not placed.

cellsWithin

fun cellsWithin(cell: Cell, radius: Int, metric: GridMetric = GridMetric.CHEBYSHEV, includeSelf: Boolean = false): List<Cell>

All cells within radius of cell under the given metric. Excludes cell itself unless includeSelf is true. Cells outside the bounds are dropped for non-torus grids.

isEmpty

fun isEmpty(cell: Cell): Boolean

True if cell has no occupants.

mooreNeighborhood

fun mooreNeighborhood(cell: Cell, includeSelf: Boolean = false): List<Cell>

The 8 cells in the Moore neighborhood (Chebyshev distance 1) around cell. If includeSelf is true, cell is included. Cells outside the bounds are dropped for non-torus grids; for torus grids the full 8 (or 9 with self) are always returned.

moveTo

fun moveTo(agent: A, cell: Cell)

Equivalent to placeAt; provided for symmetry with movement-style code.

fun moveTo(agent: A, col: Int, row: Int)

neighborsOf

fun neighborsOf(agent: A, radius: Int = Defaults.neighborhoodRadius, metric: GridMetric = GridMetric.CHEBYSHEV): List<A>

All other agents within radius of agent's cell. Excludes agent itself but includes any co-occupants of its cell.

onAgentLeft

open override fun onAgentLeft(agent: A)

Called by the AgentModel.Context when agent leaves. Default no-op — projections that track per-agent state (positions, edges) typically override to drop their bookkeeping for the departing agent.

placeAt

fun placeAt(agent: A, cell: Cell)

Place agent at the given cell. For GridOccupancy.SINGLE grids, throws if the target cell is already occupied by a different agent.

fun placeAt(agent: A, col: Int, row: Int)

tryPlaceAt

fun tryPlaceAt(agent: A, cell: Cell): Boolean

Conditional placement for single-occupancy grids: returns true if the cell was free (or already held this agent) and the placement succeeded; false if the cell was occupied by another agent. Always succeeds for multi-occupancy grids.

vonNeumannNeighborhood

fun vonNeumannNeighborhood(cell: Cell, includeSelf: Boolean = false): List<Cell>

The 4 cells in the Von Neumann neighborhood (Manhattan distance