tbp.monty.attention#

tbp.monty.attention.attention_system#

class AttentionSystem(*args, **kwargs)[source]#

Bases: Protocol

__init__(*args, **kwargs)#

reset() → None[source]#

Return type:: None

state_dict() → Mapping[str, Any][source]#

Return type:: Mapping[str, Any]

step(goals: Sequence[Goal], regions: Sequence[AttentionRegion]) → list[Goal][source]#

class DefaultAttentionSystem(voxel_size: float = 0.05, weight_pooler: WeightPooler = <function negative_priority_max_pool>, decay: VoxelGridWeightDecay | None = None, merge: VoxelGridMerge | None = None, goal_filter: GoalFilter | None = None, telemetry: AttentionSystemTelemetry | None = None) → None[source]#

Bases: AttentionSystem

__init__(voxel_size: float = 0.05, weight_pooler: WeightPooler = <function negative_priority_max_pool>, decay: VoxelGridWeightDecay | None = None, merge: VoxelGridMerge | None = None, goal_filter: GoalFilter | None = None, telemetry: AttentionSystemTelemetry | None = None) → None[source]#

classmethod expire(grid: VoxelGrid) → VoxelGrid[source]#

Returns the grid removing voxels with weights close enough to zero.

Return type:: VoxelGrid

reset() → None[source]#

Return type:: None

state_dict() → Mapping[str, Any][source]#

Return type:: Mapping[str, Any]

step(goals: Sequence[Goal], regions: Sequence[AttentionRegion]) → list[Goal][source]#

WEIGHT_EXPIRATION_TOLERANCE: ClassVar[float] = 1e-06#: Voxels whose weight magnitude falls below this are expired from the grid.

class NoopAttentionSystem(*args, **kwargs)[source]#

Bases: AttentionSystem

reset() → None[source]#

Nothing to reset.

Return type:: None

state_dict() → Mapping[str, Any][source]#

Return type:: Mapping[str, Any]

step(goals: Sequence[Goal], regions: Sequence[AttentionRegion]) → list[Goal][source]#

tbp.monty.attention.decay#

class LinearWeightDecay(rate: float = 0.1) → None[source]#

Bases: VoxelGridWeightDecay

Move each voxel weight toward zero by a fixed amount.

Decay is applied in place to the grid’s weights. Weights that fall within [-rate, +rate] get clamped to zero.

__init__(rate: float = 0.1) → None[source]#

Initialize the decay.

Parameters:: rate (float) – How much a weight moves toward zero per step.
Raises:: ValueError – If the rate is negative.

class NoopDecay(*args, **kwargs)[source]#

Bases: VoxelGridWeightDecay

Leave every voxel weight untouched.

class VoxelGridWeightDecay(*args, **kwargs)[source]#

Bases: Protocol

__init__(*args, **kwargs)#

DEFAULT_LINEAR_WEIGHT_DECAY_RATE = 0.1#: Default per-step decay toward zero for linear decay.

tbp.monty.attention.goal_filter#

class GoalFilter(*args, **kwargs)[source]#

Bases: Protocol

__init__(*args, **kwargs)#

class HardGoalFilter(*args, **kwargs)[source]#

Bases: GoalFilter

Keep only the goals that fall within a positively weighted voxel.

Rules:

If the attention grid is empty, let all goals through. Otherwise…
If all voxels are inhibited (negative-weighted), allow all goals to pass
that do not land in negative voxels.
If a goal does not fall within a voxel, filter it out. Otherwise…
If the goals’ voxel weight is <= 0, filter the goal out. Otherwise,
let it through.

class NoopGoalFilter(*args, **kwargs)[source]#

Bases: GoalFilter

Pass every goal through unchanged.

tbp.monty.attention.merge#

class Union(*args, **kwargs)[source]#

Bases: VoxelGridMerge

Merge grid_b into grid_a, taking the union of their voxels.

Every voxel occupied in either grid is occupied in the result. Where the grids overlap, grid_b’s weight wins.

class VoxelGridMerge(*args, **kwargs)[source]#

Bases: Protocol

__init__(*args, **kwargs)#

tbp.monty.attention.telemetry#

class AttentionSystemTelemetry(*args, **kwargs)[source]#

Bases: Protocol

__init__(*args, **kwargs)#

grid(grid: VoxelGrid) → None[source]#

Return type:: None

proposed_grid(grid: VoxelGrid) → None[source]#

Return type:: None

reset() → None[source]#

Return type:: None

state_dict() → Mapping[str, Any][source]#

Return type:: Mapping[str, Any]

class DefaultAttentionSystemTelemetry → None[source]#

Bases: AttentionSystemTelemetry

__init__() → None[source]#

grid(grid: VoxelGrid) → None[source]#

Return type:: None

proposed_grid(grid: VoxelGrid) → None[source]#

Return type:: None

reset() → None[source]#

Return type:: None

state_dict() → Mapping[str, Any][source]#

Return type:: Mapping[str, Any]

class NoopAttentionSystemTelemetry(*args, **kwargs)[source]#

Bases: AttentionSystemTelemetry

grid(grid: VoxelGrid) → None[source]#

Return type:: None

proposed_grid(grid: VoxelGrid) → None[source]#

Return type:: None

reset() → None[source]#

Return type:: None

state_dict() → Mapping[str, Any][source]#

Return type:: Mapping[str, Any]

tbp.monty.attention.voxel_grid#

class VoxelGrid(voxel_size: float, voxels: list[Voxel], weights: npt.NDArray[np.floating]) → None[source]#

Bases: object

A sparse grid of per-voxel features over 3D space.

Backed by a pandas DataFrame whose rows are the occupied voxels – an (x, y, z) integer MultiIndex of voxel coordinates (lower corners) – and a “weight” column.

__init__(voxel_size, voxels, weights)[source]#

Initialize the voxel grid.

Parameters:

voxel_size – Edge length of a voxel.
voxels – The occupied voxels.
weights – The weights of the occupied voxels.

classmethod empty(voxel_size: float) → VoxelGrid[source]#

Return type:: VoxelGrid

classmethod from_pandas(voxel_size: float, data: pandas.DataFrame) → VoxelGrid[source]#

Create a voxel grid from a pandas DataFrame.

Parameters:

voxel_size (float) – Edge length of a voxel.
data (DataFrame) – A DataFrame with a MultiIndex of (x, y, z) voxel coordinates and a
column. ("weight") –

Return type:

VoxelGrid

Returns:

A voxel grid.

to_pandas() → pandas.DataFrame[source]#

Return the backing frame, not a copy.

Return type:: DataFrame

weights() → numpy.typing.NDArray.numpy.floating[source]#

Return the weights of the occupied voxels.

Return type:: floating

weights_at_points(points: numpy.typing.NDArray.numpy.floating, fill_value: float = numpy.nan) → numpy.typing.NDArray.numpy.floating[source]#

Look up voxel’s weight at each point.

Parameters:

points (floating) – A (N, 3) array of points.
fill_value (float) – The value reported for points whose voxel is not in the grid; defaults to NaN.

Return type:

floating

Returns:

An (N,) array of weights; fill_value is used for any points in unoccupied voxels.

property voxel_size: float#: Edge length of a voxel.

encode_voxel_grid(grid: VoxelGrid) → dict[source]#

Encode a voxel grid into a JSON-encodable dictionary.

Parameters:: grid (VoxelGrid) – The grid to encode.
Return type:: dict
Returns:: A dictionary with the grid’s voxel_size, its occupied voxels as a (V, 3) array, and their weight as a (V,) array.

validate_dataframe(df: pandas.DataFrame) → None[source]#

Validate the structure of the voxel grid DataFrame.

Parameters:: df (DataFrame) – The DataFrame to validate.
Raises:: ValueError – If - df does not have a MultiIndex with level names (‘x’, ‘y’, ‘z’). - df’s index is not unique. - df does not have a “weight” column. - df’s “weight” column is not 1D.
Return type:: None

voxelize_and_bin_points(voxel_size: float, points: numpy.typing.NDArray.numpy.floating, weights: numpy.typing.NDArray.numpy.floating) → pandas.DataFrame[source]#

Tabulate each point’s voxel alongside its weight.

The table is the input to per-voxel aggregation: grouping it by voxel bins the points, with each group’s index giving the indices of the points inside that voxel.

Parameters:

voxel_size (float) – Edge length of a voxel.
points (floating) – An (N, 3) array of points.
weights (floating) – An (N,) array of weights, aligned with points.

Raises:

ValueError – If weights is not an (N,) array.

Return type:

DataFrame

Returns:

A frame with one row per point, holding the point’s voxel and weight.

voxelize_points(voxel_size: float, points: npt.NDArray[np.floating]) → list[Voxel][source]#

Find the voxel containing each point.

Voxels are half-open: a point on the face shared by two voxels belongs to the one with the larger coordinate, i.e. voxel v spans [v, v + 1) along each axis, in units of voxel_size.

Parameters:

points – An (N, 3) array of points.
voxel_size – Edge length of a voxel.

Returns:

The voxel of each point, in point order.

Raises:

ValueError – If points is not an (N, 3) array.

VOXEL_LEVELS = ('x', 'y', 'z')#: Names of the row index levels. This is for a pandas DataFrame MultiIndex.

tbp.monty.attention.weight_pooler#

class WeightPooler(*args, **kwargs)[source]#

Bases: Protocol

__init__(*args, **kwargs)#

negative_priority_max_pool(values: Sequence[float]) → float[source]#

Inhibition-dominating weight pooler.

Parameters:: values (Sequence[float]) – A sequence of float values.
Return type:: float
Returns:: The maximum value if all are non-negative, otherwise the most negative value.