> ## Documentation Index
> Fetch the complete documentation index at: https://tsim.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# terms

> Term-family modules for compiled scalar graphs.

Each compiled ZX scalar is the product of four term families plus a global
phase and a floatfactor. This module defines the four families as
`equinox.Module` records, bundles the shared phase tables, and gives each
family an `evaluate` method that turns a batch of binary parameter values
into an `ExactScalarArray`.

Downstream, `compile.py` builds instances of these classes from
`pyzx_param` scalars, and `evaluate.py` orchestrates the products.

## class `ExactScalarArray`

```python theme={null}
ExactScalarArray(coeffs: Array, power: Array | None = None)
```

Exact scalar array for ZX-calculus phase arithmetic using dyadic representation.

Represents values of the form (c\_0 + c\_1·ω + c\_2·ω² + c\_3·ω³) × 2^power
where ω = e^(iπ/4). This enables exact computation without floating-point errors.

### `prod`

```python theme={null}
prod(axis: int = -1) -> ExactScalarArray
```

Compute product along the specified axis using associative scan.

Returns identity (1+0i with power 0) for empty reductions.

**Parameters:**

* `axis` (`int`) — The axis along which to compute the product.

**Returns:**

* `ExactScalarArray` — ExactScalarArray with the product computed along the axis.

### `sum`

```python theme={null}
sum(axis: int = -1) -> ExactScalarArray
```

Sum elements along the specified axis using normalized pairwise adds.

**Parameters:**

* `axis` (`int`) — The axis along which to sum.

**Returns:**

* `ExactScalarArray` — ExactScalarArray with the sum computed along the axis.

### `to_complex`

```python theme={null}
to_complex() -> jax.Array
```

Convert to complex number.

## class `HalfPiPhases`

```python theme={null}
HalfPiPhases()
```

Sum of `exp(i·j·π·⊕params / 2)` terms with `j ∈ \{1, 3\}`.

Terms sharing a parameter bitstring have been combined to a single stored
coefficient `j' ∈ \{1, 2, 3\}` (see `_compile_halfpi_phases`). Coefficients
are stored in eighth-turn units — i.e. as `2·j'` — so the evaluator can
reuse the `ω = e^(iπ/4)` phase table.

Padded slots use `0` (the additive identity for phase sums), so padded
entries contribute nothing to the summed exponent.

Shapes are `(num_graphs, max_terms)` except `params` which is
`(num_graphs, max_terms, n_params)`.

### `evaluate`

```python theme={null}
evaluate(param_vals: Array) -> ExactScalarArray
```

Evaluate ω^(Σ coeffs · parity) per graph, batched over param\_vals.

**Parameters:**

* `param_vals` (`Array`) — Binary parameter values, shape `(batch, n_params)`.

**Returns:**

* `ExactScalarArray` — `ExactScalarArray` of shape `(batch, num_graphs)`.

## class `NodePhases`

```python theme={null}
NodePhases()
```

Product of `1 + exp(i·(α + ⊕params)·π)` terms, one factor per stored term.

Padded slots use `0` for both `phases` and `params`; the evaluator masks
padded slots to the multiplicative identity using `counts`.

Shapes are `(num_graphs, max_terms)` except `params` which is
`(num_graphs, max_terms, n_params)`.

### `evaluate`

```python theme={null}
evaluate(param_vals: Array) -> ExactScalarArray
```

Evaluate Π (1 + ω^(4·parity + phase)) per graph, batched over param\_vals.

**Parameters:**

* `param_vals` (`Array`) — Binary parameter values, shape `(batch, n_params)`.

**Returns:**

* `ExactScalarArray` — `ExactScalarArray` of shape `(batch, num_graphs)`.

## class `PhasePairs`

```python theme={null}
PhasePairs()
```

Product of `1 + e^(iα) + e^(iβ) − e^(i(α+β))` terms.

Each of `α` and `β` combines a constant phase with a parameter parity.
Padded slots use `0` and are masked to the multiplicative identity using
`counts`.

Shapes are `(num_graphs, max_terms)` except `*_params` which are
`(num_graphs, max_terms, n_params)`.

### `evaluate`

```python theme={null}
evaluate(param_vals: Array) -> ExactScalarArray
```

Evaluate Π (1 + ω^α + ω^β - ω^(α+β)) per graph, batched.

**Parameters:**

* `param_vals` (`Array`) — Binary parameter values, shape `(batch, n_params)`.

**Returns:**

* `ExactScalarArray` — `ExactScalarArray` of shape `(batch, num_graphs)`.

## class `PiProducts`

```python theme={null}
PiProducts()
```

Product of `(-1)^(ψ · φ)` terms, with ψ and φ each a parity expression.

Each side is encoded as a constant bit plus a parameter bitmask. Padded slots
use `0` everywhere; a padded term contributes `(-1)^0 = 1` to the product.

Shapes are `(num_graphs, max_terms)` except `*_params` which are
`(num_graphs, max_terms, n_params)`.

### `evaluate`

```python theme={null}
evaluate(param_vals: Array) -> ExactScalarArray
```

Evaluate Π (-1)^(ψ·φ) per graph as a real ±1 exact scalar.

**Parameters:**

* `param_vals` (`Array`) — Binary parameter values, shape `(batch, n_params)`.

**Returns:**

* `ExactScalarArray` — `ExactScalarArray` of shape `(batch, num_graphs)`, with values
* `ExactScalarArray` — in \{+1, -1} represented exactly.

## class `ScalarPrefactor`

```python theme={null}
ScalarPrefactor()
```

Per-graph static scalar prefactor — independent of parameter values.

Each graph's amplitude is the product of the four term families times the
prefactor `ω^phase_index · floatfactor · 2^power2`, with an additional
complex `approximate_floatfactor` multiplied in when any graph's phase
had a denominator outside `\{1, 2, 4\}` and was folded into float form.

This class is pure data; the final fold-in with the term-family product
(which requires branching on `has_approximate_floatfactors`) lives in
`evaluate.py`.

## `matmul_gf2`

```python theme={null}
matmul_gf2(a: Array, b: Array) -> Array
```

Compute binary dot products mod 2 as `a_GTP x b_BP -\> b_BGT`.

Uses float32 matmul (integer matmul does not have BLAS support on CPU)
then casts back to uint8.

**Parameters:**

* `a` (`Array`) — Parameter bit-masks, shape `(G, T, P)` — G graphs, T terms, P parameters.
* `b` (`Array`) — Binary parameter values, shape `(B, P)` — B batch elements.

**Returns:**

* `Array` — Binary row-sums mod 2, shape `(B, G, T)`.