viridicle utilities

viridicle.cluster_geography(geo: viridicle.viridicle.Geography, out: Optional[numpy.ndarray] = None) → Tuple[numpy.ndarray, numpy.ndarray]

We define a cluster as a maximal connected subgraph, all of whose vertices have the same state. This function calculates clusters of the geography, and returns a numpy.ndarray of the same size and shape as the sites array whose entries are the cluster ids for the corresponding sites.

Parameters

  • geo (Geography) – The model to be processed.

  • out (optional, numpy.ndarray) – The numpy.ndarray to hold the cluster ids. If this is not provided, a new one is generated from scratch, but the user may specify this themselves if desired to stabilize memory use.

Returns

A pair of numpy.ndarray s. The first array is the same shape as the sites array, and each entry gives the cluster id of the corresponding entry in the sites array. The second array maps from the cluster id to the original state.

viridicle.grow_clusters(geo: viridicle.viridicle.Geography, num_steps: int, empty_state: int = 0) → viridicle.viridicle.Geography

Grows the clusters in a graph. Briefly, at every step, we look at every empty vertex that is adjacent to one or more non-empty vertices. If the adjacent non-empty vertices have only one state, then we set that vertex to that state. We then repeat for the desired number of steps. For example, on a 2-dimensional periodic lattice, which we run for only one step, we would see:

0000
0110
0002
0000

Become:

0110
1110
2102
0002
Parameters

  • geo (Geography) – The model to be processed.

  • num_steps (int) – Number of steps to grow clusters.

  • empty_state (int) – State to be used as the empty value. Default 0.

Returns

A new Geography of the same state with the underlying sites changed.

viridicle.merge_small_clusters(geo: viridicle.viridicle.Geography, min_size: int, merge_size: Optional[int] = None, empty_state: int = 0) → viridicle.viridicle.Geography

We define a cluster as a maximal connected subgraph, all of whose vertices have the same state. This function eliminates clusters that lie below a specified minimum number of vertices, in order to clean the graph for further processing. The cleaning process works in two stages:

  1. First, we identify all clusters that fall below the minimum size, and set them to an empty_state value.

  2. Second, we take this new graph and identify all clusters of the empty state which fall below the minimum size, and check if they are adjacent to more than one neighboring cluster. If they are adjacent to only one other cluster, we set them to that cluster’s value.

Parameters

  • geo (Geography) – The model to be processed.

  • min_size (int) – Minimum cluster size.

  • merge_size (int) – Empty areas below this size that are fully surrounded by another cluster will be set to that cluster’s state. If not set, defaults to min_size.

  • empty_state (int) – State to be used as the empty value. Default 0.

Returns

A new Geography of the same state with the underlying sites changed.