repast4py.value_layer module

class repast4py.value_layer.ReadWriteValueLayer(comm, bounds, borders, buffer_size, init_value, dtype=torch.float64)

Bases: object

Encapsulates two repast4py.value_layer.SharedValueLayer, one of which functions as a read layer, and the other as the write layer. A ValueLayer is cross-process shared N-dimensional raster type matrix where each discrete integer coordinate contains a numeric value. A SharedValueLayer is shared over all the ranks in the specified communicator.

All write operations will be performed on the write layer, and all read operations on the read layer. The two can be swapped using the swap_layers() method. The intention is to present all agents with the equivalent value layer state, such that they all read from the read layer, but when making changes to the value layer, these changes are not available via a read until the layers are swapped. This removes any ordering effects such as a “first mover advantage.”

A SharedValueLayer is shared over all the ranks in the specified communicator by sub-dividing the global bounds into some number of smaller value layers, one for each rank. For example, given a global size of 100 x 25 and 2 ranks, the global space will be split along the x dimension such that the SharedValueLayer in the first MPI rank covers 0-50 x 0-25 and the second rank 50-100 x 0-25. Each rank’s SharedValueLayer contains a buffer of the specified size that duplicates or “ghosts” an adjacent area of the neighboring rank’s SharedValueLayer. In the above example, the rank 1 space buffers the area from 50-52 x 0-25 in rank 2, and rank 2 buffers 48-50 x 0-25 in rank 1. Be sure to specify a buffer size appropriate to any agent behavior. For example, if an agent can “see” 3 units away and take some action based on what it perceives, then the buffer size should be at least 3, insuring that an agent can properly see beyond the local borders of its own SharedValueLayer.

The read and write SharedValueLayers delegate their matrix storage to a pytorch tensor, accessible via the ValueLayer.grid property. The read and write ValueLayers can be initialized with a specified value or with ‘random’ to initialize the matrix with a random value.

Note: 3D SharedValueLayers are not yet supported and will raise an Exception.

Parameters:

  • comm (mpi4py.MPI.Intracomm) – the communicator containing all the ranks over which this SharedValueLayer is shared.

  • bounds (BoundingBox) – the dimensions of the ValueLayer

  • borders (BorderType) – the border semantics - BorderType.Sticky or BorderType.Periodic.

  • buffer_size (int) – the size of the ValueLayers’ buffered areas. This single value is used for all dimensions.

  • init_value – the initial value of each cell in the read and write ValueLayers: either a numeric value or 'random' to specify a random initialization.

  • dtype (torch.dtype) – the numeric type of this ValueLayer. Defaults to torch.float64.

property bounds

Gets the dimensions of the read and write layers.

Type:

BoundingBox

get(pt)

Gets the value at the specified point from the read layer.

Parameters:

pt (DiscretePoint) – the location to get the value of

Returns:

The value at the specified location.

get_nghs(pt)

Gets the neighboring values and locations around the specified point.

Parameters:

pt – the point whose neighbors to get

Returns:

A two elelment tuple consisting of the neighboring values as a pytorch tensor, and the neighboring locations as a np.array: (values, ngh_locations). The first value in the values tensor is the value of the first location in the ngh_locations array, and so forth.

Return type:

Tuple

property read_grid

Gets the pytorch tensor that stores the values in the read layer. Note that the tensor is not addressed in x, y, z order so see the pytorch docs when using the tensor directly.

Type:

pytorch.tensor

set(pt, val)

Sets the value at the specified location on the write layer.

Parameters:

  • pt (DiscretePoint) – the location to set the value of

  • val – the value to set the location to

swap_layers()

Swaps the two layers. The write layer becomes the read and the read becomes the write

property write_grid

Gets the pytorch tensor that stores the values in the write layer. Note that the tensor is not addressed in x, y, z order so see the pytorch docs when using the tensor directly.

Type:

pytorch.tensor

class repast4py.value_layer.SharedValueLayer(comm, bounds, borders, buffer_size, init_value, dtype=torch.float64)

Bases: ValueLayer

A cross-process shared N-dimensional raster type matrix where each discrete integer coordinate contains a numeric value.

A SharedValueLayer is shared over all the ranks in the specified communicator by sub-dividing the global bounds into some number of smaller value layers, one for each rank. For example, given a global size of 100 x 25 and 2 ranks, the global space will be split along the x dimension such that the SharedValueLayer in the first MPI rank covers 0-50 x 0-25 and the second rank 50-100 x 0-25. Each rank’s SharedValueLayer contains a buffer of the specified size that duplicates or “ghosts” an adjacent area of the neighboring rank’s SharedValueLayer. In the above example, the rank 1 space buffers the area from 50-52 x 0-25 in rank 2, and rank 2 buffers 48-50 x 0-25 in rank 1. Be sure to specify a buffer size appropriate to any agent behavior. For example, if an agent can “see” 3 units away and take some action based on what it perceives, then the buffer size should be at least 3, insuring that an agent can properly see beyond the local borders of its own SharedValueLayer.

A SharedValueLayer delegates its matrix storage to a pytorch tensor, accessible via the ValueLayer.grid property.

Note: 3D SharedValueLayers are not yet supported and will raise an Exception.

Parameters:

  • comm (mpi4py.MPI.Intracomm) – the communicator containing all the ranks over which this SharedValueLayer is shared.

  • bounds (BoundingBox) – the dimensions of the ValueLayer

  • borders (BorderType) – the border semantics: BorderType.Sticky or BorderType.Periodic.

  • buffer_size (int) – the size of this ValueLayers’s buffered area. This single value is used for all dimensions.

  • init_value – the initial value of each cell in this ValueLayer: either a numeric value or ‘random’ to specify a random initialization.

  • dtype (torch.dtype) – the numeric type of this ValueLayer. Defaults to torch.float64.

class repast4py.value_layer.ValueLayer(bounds, borders, init_value, dtype=torch.float64)

Bases: object

N-dimensional raster type matrix where each discrete integer coordinate contains a numeric value.

A ValueLayer delegates its matrix storage to a pytorch tensor. The grid property provides access to this tensor. A ValueLayer can be initialized with a specified value or with 'random' to initialize the matrix with a random value.

Parameters:

  • bounds (BoundingBox) – the dimensions of the ValueLayer

  • borders (BorderType) – the border semantics: BorderType.Sticky or BorderType.Periodic.

  • init_value – the initial value of each cell in this ValueLayer: either a numeric value or 'random' to specify a random initialization.

  • dtype (torch.dtype) – the numeric type of this ValueLayer. Defaults to torch.float64.

property bounds

Gets the dimensions of this ValueLayer.

Type:

BoundingBox

get(pt)

Gets the value at the specified point

Parameters:

pt (DiscretePoint) – the location to get the value of

Returns:

The value at the specified location.

get_nghs(pt)

Gets the neighboring values and locations around the specified point.

Parameters:

pt (DiscretePoint) – the point whose neighbors to get

Returns:

A two elelment tuple consisting of the neighboring values as a pytorch tensor, and the neighboring locations as a np.array: (values, ngh_locations). The first value in the values tensor is the value of the first location in the ngh_locations array, and so forth.

Return type:

Tuple

property grid

Gets the pytorch tensor that stores the values in this ValueLayer. Note that the tensor is not addressed in x, y, z order so see the pytorch docs when using the tensor directly.

Type:

pytorch.tensor

set(pt, val)

Sets the value at the specified location

Parameters:

  • pt (DiscretePoint) – the location to set the value of

  • val – the value to set the location to