HexGrid

phasic.HexGrid(boundary, hex_size, orientation='pointy')

Hexagonal grid within a geographic boundary.

Creates a hex grid sized to cover a boundary geometry. Provides row_property and col_property as regular :class:Property objects for composition into a :class:StateIndexer.

Parameters

boundary : BaseGeometry

Shapely geometry defining the area to cover.

hex_size : float

Circumradius of hexagonal cells (in boundary CRS units).

orientation : str = 'pointy'

"pointy" (pointy-top, default) or "flat" (flat-top).

Examples

>>> from shapely.geometry import Point
>>> boundary = Point(0, 0).buffer(5)
>>> grid = HexGrid(boundary, hex_size=1.0)
>>> grid.n_rows, grid.n_cols
(8, 7)
>>> grid.row_property
Property(name='row', max_value=7, min_value=0, offset=0)

Attributes

Name	Description
boundary	Shapely boundary geometry.
col_property	Column Property for use in a StateIndexer PropertySet.
hex_size	Circumradius of hexagonal cells.
n_cols	Number of columns in the grid.
n_rows	Number of rows in the grid.
orientation	Grid orientation: "pointy" or "flat".
row_property	Row Property for use in a StateIndexer PropertySet.
valid_mask	Boolean mask of valid cells, shape (n_rows, n_cols).

Methods

Name	Description
all_coords	Coordinates for all grid cells.
build_graph	Build a phasic Graph by iterating valid hex cells.
cell	Get a :class:HexCell for the given (row, col).
center_cell	(row, col) of the cell nearest to the boundary centroid.
coords_to_rowcol	Find the nearest valid cell to real-world coordinates.
from_shapefile	Create hex grid from a shapefile.
is_valid	Whether the cell at (row, col) is inside the boundary.
map_to_grid	Map graph vertex values to a (n_rows, n_cols) grid.
neighbors	First-order valid neighbor (row, col) pairs.
neighbors_within	All valid neighbors within distance hex steps (BFS).
properties	Return [row_property, col_property] for easy composition.
rowcol_to_coords	Convert (row, col) to real-world (x, y) coordinates.
valid_cells	All (row, col) pairs inside the boundary.

all_coords

phasic.HexGrid.all_coords()

Coordinates for all grid cells.

Returns

: np.ndarray

Shape (n_rows, n_cols, 2) array of (x, y) coordinates.

build_graph

phasic.HexGrid.build_graph(
    transition_fn,
    property_set,
    start_cell=None,
    parameterized=False,
    **graph_kwargs,
)

Build a phasic Graph by iterating valid hex cells.

The resulting Graph is a standard phasic Graph, fully compatible with serialize, FFI, JAX (jit/grad/vmap/pmap), SVGD, etc.

Parameters

transition_fn : callable

Pure function (state, grid) -> transitions where state is a numpy array (PropertySet flat index) and grid is this HexGrid. Returns list of transitions: - Non-parameterized: [(next_state, rate), ...] - Parameterized: [(next_state, coefficients), ...]

property_set : PropertySet

The PropertySet containing row/col properties (and possibly other properties). Used to determine state_length.

start_cell : tuple of (int, int) = None

(row, col) of starting cell. Defaults to :meth:center_cell.

parameterized : bool = False

Whether edges are parameterized (default False).

****graph_kwargs** : = {}

Passed to Graph constructor.

Returns

: Graph

Standard phasic Graph.

cell

phasic.HexGrid.cell(row, col)

Get a :class:HexCell for the given (row, col).

Parameters

row : int

Grid coordinates.

col : int

Grid coordinates.

Returns

: HexCell

center_cell

phasic.HexGrid.center_cell()

(row, col) of the cell nearest to the boundary centroid.

Returns

: tuple of (int, int)

coords_to_rowcol

phasic.HexGrid.coords_to_rowcol(x, y)

Find the nearest valid cell to real-world coordinates.

Parameters

x : float

Real-world coordinates.

y : float

Real-world coordinates.

Returns

: tuple of (int, int)

(row, col) of the nearest valid cell.

Raises

: ValueError

If no valid cells exist in the grid.

from_shapefile

phasic.HexGrid.from_shapefile(path, hex_size, **kwargs)

Create hex grid from a shapefile.

Requires geopandas (imported lazily).

Parameters

path : str

Path to shapefile.

hex_size : float

Circumradius of hexagonal cells.

****kwargs** : = {}

Passed to :class:HexGrid constructor.

Returns

: HexGrid

is_valid

phasic.HexGrid.is_valid(row, col)

Whether the cell at (row, col) is inside the boundary.

Parameters

row : int

Grid coordinates.

col : int

Grid coordinates.

Returns

: bool

map_to_grid

phasic.HexGrid.map_to_grid(graph, property_set, values, prop_filter=None)

Map graph vertex values to a (n_rows, n_cols) grid.

Parameters

graph : Graph

The phasic Graph (vertices carry PropertySet flat indices as state vectors).

property_set : PropertySet

The PropertySet containing row/col properties.

values : np.ndarray

Values indexed by graph vertex index (e.g., from graph.state_probability()).

prop_filter : dict = None

Fixed non-grid property values to filter on, e.g., {'population': 1}. If None and extra properties exist, sums over all combinations.

Returns

: np.ndarray

Shape (n_rows, n_cols) array.

neighbors

phasic.HexGrid.neighbors(row, col)

First-order valid neighbor (row, col) pairs.

Parameters

row : int

Grid coordinates of the cell.

col : int

Grid coordinates of the cell.

Returns

: list of (int, int)

Neighboring cells that are within bounds and inside the boundary.

neighbors_within

phasic.HexGrid.neighbors_within(row, col, distance)

All valid neighbors within distance hex steps (BFS).

Parameters

row : int

Grid coordinates of the center cell.

col : int

Grid coordinates of the center cell.

distance : int

Maximum number of hex steps.

Returns

: list of (int, int)

All reachable cells within distance steps.

properties

phasic.HexGrid.properties()

Return [row_property, col_property] for easy composition.

Example

indexer = StateIndexer( … lineage=grid.properties() + [Property(‘allele’, max_value=1)] … )

rowcol_to_coords

phasic.HexGrid.rowcol_to_coords(row, col)

Convert (row, col) to real-world (x, y) coordinates.

Parameters

row : int

Grid coordinates.

col : int

Grid coordinates.

Returns

: tuple of (float, float)

(x, y) coordinates of the cell center.

valid_cells

phasic.HexGrid.valid_cells()

All (row, col) pairs inside the boundary.

Returns

: list of (int, int)