BAM Operations#

Array operations for custom events.

This module provides NumPy-free operations for writing custom events, allowing economics researchers to work with BAM Engine without deep Python/NumPy knowledge.

Design Notes#

The operations mirror NumPy’s functionality but with:

Safe defaults: Division by zero prevention (eps=1e-10)
Consistent naming: Verb-based (multiply, divide vs * and /)
In-place operations: Support out= parameter for performance
Type hints: Better IDE support with Float, Int, Bool types

Operation Categories#

Arithmetic: add, subtract, multiply, divide
Comparisons: equal, less, greater, etc.
Logical: logical_and, logical_or, logical_not
Conditional: where (if-then-else)
Element-wise: maximum, minimum, clip
Aggregation: sum, mean, any, all
Array creation: zeros, ones, full, empty, arange, asarray, array
Mathematical: log, exp
Utilities: unique, bincount, isin, argsort, sort
Random: uniform (requires RNG)
Assignment: assign (in-place array modification)

Examples

Basic arithmetic operations:

>>> from bamengine import ops
>>> import numpy as np
>>> a = np.array([1.0, 2.0, 3.0])
>>> b = np.array([4.0, 5.0, 6.0])
>>> ops.add(a, b)
array([5., 7., 9.])
>>> ops.multiply(a, 2.0)
array([2., 4., 6.])

Safe division (handles zeros):

>>> wages = np.array([10.0, 12.0, 11.0])
>>> productivity = np.array([2.0, 3.0, 0.0])  # One zero!
>>> unit_cost = ops.divide(wages, productivity)  # No error
>>> unit_cost[2] > 1e9  # Zero productivity handled
True

In-place operations for performance:

>>> out = np.zeros(3)
>>> result = ops.add(a, b, out=out)
>>> result is out  # Same object
True

Conditional logic without NumPy:

>>> has_inventory = ops.greater(inventory, 0)
>>> new_price = ops.where(has_inventory, price * 0.95, price * 1.05)

Create a custom pricing event:

>>> from bamengine import event, ops
>>>
>>> @event
... class MarkupPricing:
...     def execute(self, sim):
...         prod = sim.get_role("Producer")
...         emp = sim.get_role("Employer")
...         # Calculate unit cost (safe division)
...         unit_cost = ops.divide(emp.wage_offered, prod.labor_productivity)
...         # Apply 20% markup
...         new_prices = ops.multiply(unit_cost, 1.2)
...         ops.assign(prod.price, new_prices)

Advanced Usage#

For users comfortable with NumPy, direct NumPy operations can be mixed with bamengine.ops for flexibility:

>>> import numpy as np
>>> # Mix ops and NumPy as needed
>>> from bamengine import event, ops
>>> @event
... class CustomEvent:
...     def execute(self, sim):
...         # Use ops for safety
...         unit_cost = ops.divide(wages, productivity)
...         log_prices = ops.log(prices)
...         # Use NumPy directly for complex operations not in ops
...         weighted_avg = np.average(prices, weights=market_share)
```

See also

typing: Type aliases (Float, Int, Bool, Agent)
numpy: Underlying array library

Arithmetic

`add`	Add two arrays or array and scalar.
`subtract`	Subtract two arrays or array and scalar.
`multiply`	Multiply two arrays or array and scalar.
`divide`	Divide two arrays or array and scalar (safe - avoids division by zero).

Assignment

assign

Assign value to target array (in-place operation).

Comparisons

`equal`	Element-wise equality comparison.
`not_equal`	Element-wise inequality comparison.
`less`	Element-wise less than comparison.
`less_equal`	Element-wise less than or equal comparison.
`greater`	Element-wise greater than comparison.
`greater_equal`	Element-wise greater than or equal comparison.

Logical

`logical_and`	Element-wise logical AND.
`logical_or`	Element-wise logical OR.
`logical_not`	Element-wise logical NOT.

Conditional

where

Vectorized if-then-else (ternary operator).

Element-wise

`maximum`	Element-wise maximum of array elements.
`minimum`	Element-wise minimum of array elements.
`clip`	Clip (limit) values to range [min_val, max_val].

Aggregation

`sum`	Sum array elements, optionally over axis or subset.
`mean`	Calculate mean, optionally over axis or subset.
`std`	Calculate standard deviation, optionally over axis or subset.
`min`	Return minimum value of array elements.
`max`	Return maximum value of array elements.
`any`	Test whether any array element is True.
`all`	Test whether all array elements are True.

Array creation

`zeros`	Create array of zeros.
`ones`	Create array of ones.
`full`	Create array filled with constant value.
`empty`	Create uninitialized array (for performance when values will be overwritten).
`arange`	Create array with evenly spaced values within interval.
`array`	Create a new numpy array from input data.
`asarray`	Convert input to a numpy array.

Mathematical

`log`	Natural logarithm of array elements.
`exp`	Exponential of array elements (e^x).

Utilities

`unique`	Find unique elements in array.
`bincount`	Count occurrences of each value in array of non-negative ints.
`isin`	Test whether each element is in test_elements.
`argsort`	Return indices that would sort the array.
`sort`	Return sorted copy of array.

Random

uniform

Draw samples from uniform distribution.