Skip to main content
BlockEncoding provides classmethod constructors for common input representations. This page walks through a selection of them. More constructors are added over time, so check the SDK reference for the full, current list. Each constructor infers alpha, block_size, and data_size from its input, and (where possible) whether the resulting unitary is Hermitian — pass hermitian_be explicitly to override the inference. This value isn’t checked against the actual unitary, so it’s worth getting right (in particular, qubitize relies on it being accurate). All examples on this page import:

​
from_matrix

Block-encodes an arbitrary matrix. This is the most general constructor: use it when your matrix doesn’t have a special structure that a more specific constructor could exploit. Being diagonal, sparse, or already given as a Pauli sum are examples of such structure.
be.to_matrix() may not match matrix entrywise even though the encoding is correct. See Verifying with to_matrix for details.

​
from_sparse_pauli_op

Block-encodes a sum of weighted Pauli strings, given as a SparsePauliOp (see Measurements, Observables, and Hermitian Operators). This is more general than a Hamiltonian: the coefficients don’t need to be real, so the operator itself doesn’t need to be Hermitian. Set graycode=True to implement the LCU select operator with gray-code multiplexed rotations instead of the default unary iteration.
This block encoding has a scaling factor which is the Pauli 1-norm ∑j∣cj∣\sum_j \vert c_j \vert, and a block size given by max⁡(⌈log⁡2(#terms)⌉,1)\max(\lceil \log_2(\#\text{terms}) \rceil, 1).

​
from_constant_diags

Block-encodes a matrix whose diagonals each carry a single constant value across the whole diagonal, a common pattern for discretized differential operators. cyclic=False (the default) drops entries that would fall outside the matrix (open boundary); cyclic=True wraps them around the matrix edges (periodic boundary) instead.
be.to_matrix() prints: size is the number of data qubits (matrix dimension 2size2^{\text{size}}).

​
Next: combining encodings

Once you have one or more BlockEncoding instances, you can combine and transform them as described in Composing and Transforming Block Encodings.