Tensor API¶

Import tensor helpers from bilt. See Domains and tensors for an introduction and Units API for physical units.

Construction and inspection¶

from bilt import dim, domain, tensor

time = dim("time")
values = tensor([1.0, 3.0, 5.0], over=time)
assert values.domain == domain(time)
assert values.shape == (3,)

Array rank must match the number of dimensions. During evaluation, shared dimensions must have equal lengths. Missing dimensions broadcast; shared ones align by name. Result axes follow the evaluation's dimension binding order.

Units¶

Use Annotated[Tensor, LENGTH], for example, for a unit-aware tensor port. Bare Tensor ports are outside the physical unit system. Computed declared quantities use coherent units; convert returned tensors for display.

Reductions¶

Use these methods in decorated relationships. Each takes one named dimension present in the operand's domain and removes it from the result's domain.

In unit-aware equations, mean/sum/min/max retain dimensionality and tags. prod requires a dimensionless operand; sum refuses absolute readings. Reducing the last dimension gives a scalar domain. Unit-aware Tensor-declared outputs remain rank-zero tensors; other scalar-domain outputs are numerical scalars or declared quantities.

Transforms: use a single return statement, applying reductions directly to named parameters with a dimension captured by a global or closure name:

from bilt import Tensor, transform


@transform
def averaged(values: Tensor) -> Tensor:
    return values.mean(time) * 2.0

Indexing¶

Use selection in equations; .isel() and .sel() are not lowered in transforms. Both select one element along a dimension and remove that dimension from the result.

isel delegates bounds handling to the backend; invalid-index behaviour may differ. sel requires a matching label. Coordinates may be strings, integers, floats, datetime.date or datetime.datetime; float matches allow rounding tolerance.

Coordinate axes¶

Creating an axis does not bind it. Currently, bind coordinates through the internal evaluation context before requesting calculated outputs:

from bilt import coordinate_axis
from bilt.core._evaluation_context import EvaluationContext

with EvaluationContext() as evaluation:
    evaluation.domains.bind(coordinate_axis(time, (2024, 2025, 2026)))
    # Request a model output using values.sel(time, 2025).

Intermediate values¶

Selection works on named intermediate ports over known dimensions. Dimensions, extents and coordinate axes must be established before calculation; Bilt cannot infer new dimensions or changed extents on the fly.

Arithmetic and reduction/selection results are plain symbolic expressions without tensor methods. To apply another reduction or selection, expose the intermediate as a Tensor parameter in a separate relationship:

from bilt import Tensor, equation


@equation
def doubling(doubled: Tensor, values: Tensor) -> bool:
    return doubled == values * 2.0


@equation
def selecting(selected: Tensor, doubled: Tensor) -> bool:
    return selected == doubled.isel(time, 1)

The same pattern supports repeated reductions. Concrete tensor methods are model-only: calling them directly on a returned Tensor raises TypeError. Outside models, work with t.values for numerical operations.

Errors¶

Import exceptions from bilt.errors.