Skip to content

Refactor Quantity and Tensor annotations to be protocols - #475

Draft
brocksam wants to merge 4 commits into
mainfrom
quantity-tensor-operator-typing
Draft

brocksam wants to merge 4 commits into
mainfrom
quantity-tensor-operator-typing

Conversation

@brocksam

@brocksam brocksam commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Quantity and tensor annotations as protocols

A port annotation answers two independent questions: does the value carry a unit, and must it be a tensor? Until now the answer was spelt by choosing among four concrete classes and unions of them. So the same intent was written differently on a system field (Quantity | QuantityTensor) and in an equation (Quantity), every dimension needed an alias pair (PointwiseMass / Mass), and arithmetic on the union failed to type-check.

The four public names are now protocols that state each answer directly:

Any shape Must be a tensor
Units Quantity QuantityTensor
No units Number Tensor

One alias per dimension now serves systems, equations and transforms:

type Length = Annotated[Quantity, LENGTH]

Changes

  • Operator typing. Arithmetic, powers, reductions and selections on QuantityTensor keep the unit for type checkers. Mixing a scalar quantity and a tensor gives a QuantityTensor.
  • Protocols. Quantity, QuantityTensor and Tensor are runtime-checkable protocols. Number is float | Tensor.
    • A QuantityTensor is a Quantity. It is not a unitless Tensor or Number, so type checkers now reject a unit-bearing tensor at a unitless port.
    • The concrete classes are private (_Quantity, _Tensor, _QuantityTensor).
    • 2.0 * kilogram and tensor(...) return the publi the public names.
  • Annotation parsing.
    • Annotated[Quantity, DIM] accepts a scalar or a te | QuantityTensor` normalises to it. Scalar-only portsare removed.
    • A dimension Bilt cannot read now raises BiltPortDe being silently dropped. This covers dimensions inside aunion (Annotated[...] | None), inside a generic, or in a subscripted generic alias (Length[Quantity]`).
  • Migration. Tests, benchmarks and docs use `Quantiof the old unions, with one alias per dimension.
  • Docs.
    • The quantity annotations reference is rewritten arocuted examples.
    • The units and tensors guides, API pages and worked examples are updated to match.

Breaking changes

  • Quantity(value, unit) no longer constructs a quantity. Write value * unit (an int times a unit now works too). Tensor(...)
    and Tensor.scalar(...) are replaced by tensor(...).
  • In transform bodies, degrees * absolute_celsius replaces Quantity(degrees, absolute_celsius).
  • **Annotated[Quantity, DIM] on a system field acceptcalar-only quantity annotation.
  • .value on a Quantity is a Number. A transform that returns x.convert_to(unit).value is annotated -> Number.
  • Unreadable annotations raise. Dimensions in the fon parsing now raise BiltPortDeclarationError.

Existing Quantity | QuantityTensor and `float | Tensog.

Testing

  • New typing tests check:
    • that each concrete class satisfies its protocols;
    • the expected rejections, for example a scalar quanttyTensoris required, or a unit-bearing tensor passed as aNumber`;
    • operator results at both the concrete and the proto
  • The negative typing fixture has been updated.
  • New tests cover dimensions that Bilt cannot read, now
  • Locally, the full CI set passes, except benchmarks/test_nested_coupled_plan_search.py::test_nested_coupled_plan_search[coupled]. That test fails identically on main (1b1b1fa), so it pre

QuantityTensor arithmetic, powers, reductions and selections now return QuantityTensor at the type level, and mixing a scalar Quantity with a tensor gives a QuantityTensor. Arithmetic on the Quantity | QuantityTensor union now type-checks. Runtime behaviour is unchanged.
The concrete classes become private (_Quantity, _Tensor, _QuantityTensor). Values are created with number * unit and tensor(...), which return the public types; Quantity(value, unit) construction is removed, including in transform bodies. QuantityTensor satisfies Quantity but not the unitless Tensor. Number is float | Tensor.
@brocksam
brocksam marked this pull request as draft November 18, 2026 19:11
Annotated[Quantity, DIM] now accepts a scalar or a tensor; Quantity | QuantityTensor normalises to it and scalar-only ports are removed. A dimensionality Bilt cannot read (in a union, a generic, or a subscripted generic type alias) now raises instead of being silently dropped. Tests and benchmarks use Quantity and Number in place of the old unions, with one alias per dimension.
The quantity annotations reference opens with the 2x2 grid (Quantity, QuantityTensor, Number, Tensor) and one alias per dimension; the units and tensors guides, API pages and worked examples drop the Pointwise alias pairs, the old unions and Quantity(value, unit). Tensors print with their public names.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant