QHAM

oracq.algorithms.input_model.qham

QCL row rules to modular register BEs, plus scale-preserving QODE inputs.

class oracq.algorithms.input_model.qham.PortBinding(encoding, arity)[source]

Bases: object

Binding result of a QHAM elementary port: a rectangular operator encoding and its tensor arity.

Variables:

  • encoding (oracq.algorithms.input_model.operators.BlockEncoding) – Block encoding of the port operator, with target width max(1, arity) * state_width.

  • arity (int) – Number of input tensor factors consumed by the port; 0 for constant injection, 1 for a linear map, r for a degree-r nonlinear port.

encoding
arity
class oracq.algorithms.input_model.qham.QHAMBindings(state_width, ports, initial, initial_norm)[source]

Bases: object

All port and initial-value bindings of one QHAM problem.

Variables:

  • state_width (int) – Bit width of the physical state register, corresponding to the 2**state_width-dimensional discrete space.

  • ports (tuple[tuple[str, oracq.algorithms.input_model.qham.PortBinding], ...]) – (port name, PortBinding) tuples; the set of port names must match the PDE ports of the plan.

  • initial (oracq.algorithms.input_model.oracles.StatePreparation) – Preparation oracle of the physical initial state.

  • initial_norm (float) – Euclidean norm of the classical initial vector.

state_width
ports
initial
initial_norm
validate(plan)[source]

Validate that the bindings match the port set and register layout of the QCL plan.

Parameters:

plan – QCL plan object providing the pde.ports port specifications.

Returns:

self once validation passes, for chaining.

Return type:

QHAMBindings

Raises:

ValidationError – The state bit width or initial-value width is illegal, the norm is not a finite nonnegative number, the port name set does not match, or some port’s arity or encoding width disagrees with the specification.

classmethod declare(plan, state_width, port_specs, *, initial_norm, initial_work=0, prefix='Qham')[source]

Construct open port and initial-value bindings via abstract declarations.

Generates an unimplemented block encoding declaration for each PDE port, writes the QCL plan serialization, port name, and input rank into the module attributes; the initial value likewise stays an abstract preparation, and validate runs over the whole after construction.

Parameters:

  • plan – QCL plan object providing the pde.ports port specifications.

  • state_width – Bit width of the physical state register.

  • port_specs – Mapping from port name to (alpha, signal), giving each port’s BE norm bound and signal bit count.

  • initial_norm – Euclidean norm of the classical initial vector.

  • initial_work – Work bit width reserved by the initial-value preparation declaration.

  • prefix – Prefix of the abstract declaration names; each port declaration name and the initial-value declaration name derive from this prefix.

Returns:

The open binding set that passed validate.

Return type:

QHAMBindings

Raises:

ValidationError – The port specification set disagrees with the plan, or the subsequent validate check fails.

oracq.algorithms.input_model.qham.gate_bindings(discretization, initial, *, max_port_qubits=5)[source]

Materialize only small elementary ports, without building the whole lifted matrix G.

Parameters:

  • discretization – Discretization object carrying port and dimension information.

  • initial – Finite initial vector encoded under the full register layout.

  • max_port_qubits – Maximum bit count allowed for gate implementations of elementary ports.

Returns:

Bindings made of small-port gate implementations and the initial state preparation.

Return type:

QHAMBindings

oracq.algorithms.input_model.qham.place_port(binding, state_width, source_rank, position)[source]

Place an elementary port onto the given slots of the tensor word, returning the rank-contracted block encoding.

The port acts on the arity consecutive slots of the source_rank-fold input tensor starting at position, with identity on the remaining slots; for arity 0 an empty slot is first swapped into position for constant injection, and for arity greater than 1 the surplus consumed slots are permuted to the end, giving output tensor rank source_rank - arity + 1.

Parameters:

  • binding – The PortBinding of the port.

  • state_width – Bit width of each tensor slot.

  • source_rank – Rank of the input tensor.

  • position – Starting slot of the port’s input window.

Returns:

The lifted encoding with target width max(source_rank, source_rank - arity + 1) * state_width; alpha is inherited from the elementary port, with input/output rank and tensor position attributes attached.

Return type:

BlockEncoding

Raises:

ValidationError – source_rank is smaller than the port arity, or position is outside the output rank range.

oracq.algorithms.input_model.qham.embed_rectangular(local, global_width, row_offset, column_offset, input_width, output_width)[source]

Constrain both the input and output windows, preventing rectangular zero padding from polluting neighboring blocks.

Parameters:

  • local – Block encoding of the local block.

  • global_width – Bit width of the global target register.

  • row_offset – Row offset of the output window in the global layout.

  • column_offset – Column offset of the input window in the global layout.

  • input_width – Bit count of the input window.

  • output_width – Bit count of the output window.

Returns:

The window-constrained block encoding in the global bit layout, with alpha inherited from local.

Return type:

BlockEncoding

oracq.algorithms.input_model.qham.generator_encoding(plan, bindings, eta, *, max_blocks=256, max_terms=4096)[source]

Explicitly assemble the block encoding of the lifted generator from the row rules of the QCL plan.

Enumerates the row couplings of each block, expressing every nonzero coupling as an LCU term after port placement plus rectangular embedding; placements with the same (operator, column rank, tensor position) are cached and reused.

Parameters:

  • plan – QCL plan object.

  • bindings – Port/initial-value bindings matching the plan.

  • eta – HAM homotopy parameter; terms whose coefficient evaluates to zero after substitution into the coupling weights are dropped.

  • max_blocks – Maximum number of blocks enumerated explicitly.

  • max_terms – Maximum number of explicit LCU coupling terms.

Returns:

Encoding of the whole lifted generator G, degenerating to the zero encoding with no couplings; module attributes record the plan, HAM order, explicit coupling count, and more.

Return type:

BlockEncoding

Raises:

ValidationError – Binding validation fails, the lifted register exceeds 64 bits, or the explicit coupling count exceeds the budget.

oracq.algorithms.input_model.qham.lifted_initial(plan, bindings)[source]

Build the initial state preparation on the lifted tensor space and its logarithmic norm.

Branch weights preserve the relative norms r, r, r**2, …, r**K of the lifted blocks (with forcing, the constant component is 1): first prepare the selector label from the scaled weights, then within each branch invoke the initial-value oracle repeatedly by block rank and shift the result to the block offset, and finally recompute the selector label from the address intervals; preparations with known zero input all restore the work bits to zero.

Parameters:

  • plan – QCL plan object.

  • bindings – Port/initial-value bindings.

Returns:

(StatePreparation, log_initial_norm), the latter being the natural logarithm of the overall norm of the lifted initial state.

Return type:

tuple

Raises:

ValidationError – The lifted register exceeds 64 bits, or the initial value is zero with no forcing so no nonzero vector can be prepared.

class oracq.algorithms.input_model.qham.QHAMInputModel(plan, generator, initial, state_width, eta, log_initial_norm, growth_shift=0.0)[source]

Bases: object

The QODE input model assembled by QHAM.

The system being solved is the lifted linear system Y' = G Y; the inhomogeneous forcing has been homogenized through the constant component, and G is not the QLSS matrix to be inverted.

Variables:

  • plan (object) – QCL plan object that generated this model.

  • generator (oracq.algorithms.input_model.operators.BlockEncoding) – Block encoding of the lifted generator G.

  • initial (oracq.algorithms.input_model.oracles.StatePreparation) – Preparation of the lifted initial state.

  • state_width (int) – Bit width of the physical state register.

  • eta (complex) – HAM homotopy parameter.

  • log_initial_norm (float) – Natural logarithm of the lifted initial state norm.

  • growth_shift (float) – Accumulated explicit dissipation shift, growing linearly in time as the logarithmic factor for magnitude recovery.

plan
generator
initial
state_width
eta
log_initial_norm
growth_shift = 0.0
solve(qode, time)[source]

Evolve the lifted system with the given QODE protocol and select the physical output block.

Parameters:

  • qode – Three-argument linear solver protocol (generator, initial, time) -> StateOracle.

  • time – Evolution duration.

Returns:

The normalized truncated HAM sum over the first physical block; the physical magnitude still requires the norm recovery information of the chosen protocol, and the module attributes record the plan, logarithmic initial norm, and shift factor.

Return type:

StateOracle

dissipative_shift(shift=None)[source]

Explicit adaptation for LCHS/CBMD; the whole lifted vector is uniformly multiplied by exp(-shift*t).

Parameters:

shift – Explicit dissipation shift; defaults to the generator’s alpha and must not be smaller than it.

Returns:

New input model whose generator becomes G − shift·I.

Return type:

QHAMInputModel

oracq.algorithms.input_model.qham.qham_input_model(plan, bindings, *, eta=-1.0, max_blocks=256, max_terms=4096)[source]

Assemble an explicit QHAM input model: the lifted generator block encoding plus the lifted initial state.

Parameters:

  • plan – QCL plan object.

  • bindings – Port/initial-value bindings matching the plan.

  • eta – HAM homotopy parameter, which must be a finite complex number.

  • max_blocks – Maximum number of blocks enumerated explicitly.

  • max_terms – Maximum number of explicit LCU coupling terms.

Returns:

The input model ready to be solved by a QODE protocol.

Return type:

QHAMInputModel

Raises:

ValidationError – eta is non-finite, or a check fails while assembling the generator or initial state.

oracq.algorithms.input_model.qham.open_qham_input(plan, bindings, *, generator_alpha, generator_signal, eta=-1.0, name='QhamGenerator')[source]

Explicitly keep the whole lifted generator unimplemented; do not fake an empty body for it.

Parameters:

  • plan – QCL plan object.

  • bindings – Port/initial-value bindings matching the plan.

  • generator_alpha – Norm bound of the open generator declaration.

  • generator_signal – Signal bit width of the open generator declaration.

  • eta – HAM homotopy parameter, which must be a finite complex number.

  • name – Name of the open generator declaration, QhamGenerator by default.

Returns:

Input model whose generator stays an open declaration awaiting later binding.

Return type:

QHAMInputModel

oracq.algorithms.input_model.qham.taylor_qode(generator, initial, time, *, degree=2)[source]

A plain closable finite Taylor candidate; no Hermitian or dissipative assumption, and no efficiency is promised.

Parameters:

  • generator – Block encoding of the generator.

  • initial – Initial state preparation.

  • time – Evolution duration, which must be a finite real number.

  • degree – Taylor truncation order, a nonnegative integer.

Returns:

Output state oracle after evolution by the truncated Taylor polynomial.

Return type:

StateOracle