Type System#

Type aliases for BAM Engine.

Provides both internal types (Float1D, Int1D, etc.) used in bamengine code and user-friendly type aliases (Float, Int, etc.) for defining custom roles.

Design Notes#

  • Internal types (Float1D, Int1D, Bool1D, Idx1D): Used in bamengine roles

  • User-friendly types (Float, Int, Bool, Agent): Recommended for custom roles

  • All types are actually NDArray with specific dtypes for type safety

  • AgentId type uses np.intp for platform-independent integer indexing

Type Mapping#

  • Float → Float1D → NDArray[np.float64] (prices, quantities, rates)

  • Int → Int1D → NDArray[np.int64] (counts, periods, durations)

  • Bool → Bool1D → NDArray[np.bool_] (flags, conditions, masks)

  • Agent → Idx1D → NDArray[np.intp] (agent IDs, -1 for unassigned)

Examples

Define a custom role using user-friendly types:

>>> from bamengine import role, Float, Int, Bool, Agent
>>>
>>> @role
... class Inventory:
...     goods_on_hand: Float
...     reorder_point: Float
...     supplier_id: Agent
...     days_until_delivery: Int
...     needs_reorder: Bool

Use in bamengine internal code (Float1D for precision):

>>> from dataclasses import dataclass
>>> from bamengine.core import Role
>>> from bamengine.typing import Float1D, Int1D, Bool1D
>>>
>>> @dataclass(slots=True)
... class Producer(Role):
...     price: Float1D
...     production: Float1D
...     inventory: Float1D
...     labor_productivity: Float1D

See also

bamengine.role

Role base class for defining components

bamengine.ops

Operations on these array types

Type Aliases#

The following type aliases are available for defining custom roles without needing to import NumPy directly:

Type

Description

Float

Array of floating-point values (prices, quantities, rates, etc.)

Int

Array of integer values (counts, periods, durations, etc.)

Bool

Array of boolean values (flags, conditions, masks)

AgentId

Array of agent IDs (integer indices, -1 for unassigned)

Rng

Random number generator (alias for numpy.random.Generator)

Detailed Reference#

bamengine.Float: type alias = NDArray[np.float64]#

1-D array of 64-bit floats. Used for prices, quantities, rates, and other continuous values.

bamengine.Int: type alias = NDArray[np.int64]#

1-D array of 64-bit integers. Used for counts, periods, durations, and other discrete values.

bamengine.Bool: type alias = NDArray[np.bool\_]#

1-D array of booleans. Used for flags, conditions, and masks.

bamengine.AgentId: type alias = NDArray[np.intp]#

1-D array of agent IDs (platform-native integers). Convention: -1 means unassigned.

bamengine.Rng: type alias = numpy.random.Generator#

Random number generator instance. All simulation randomness flows through this type to ensure deterministic reproducibility.