Skip to main content

Documentation Index

Fetch the complete documentation index at: https://tsim.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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

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

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

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

to_complex() -> jax.Array
Convert to complex number.

​
class HalfPiPhases

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

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

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

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

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

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

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

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

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

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).