unitaria.ProxyNode

class unitaria.ProxyNode(dimension_in: int, dimension_out: int)

Bases: Node

Abstract class for nodes that are defined in terms of other nodes

This is useful when the given definition is used in the construction of the circuit or QubitMaps, but a simpler representation is avilable for compute. Additionally, the simpler structure is used for printing and serialization.

For an example of how to use this class see Add and Mul.

_circuit(target: Sequence[int], clean_ancillae: Sequence[int], borrowed_ancillae: Sequence[int]) → Circuit

Method for computing circuit.

To be implemented in all subclasses of Node.

_normalization() → float

Method for computing normalization.

To be implemented in all subclasses of Node.

_subspace_in() → Subspace

Method for computing subspace_in.

To be implemented in all subclasses of Node.

_subspace_out() → Subspace

Method for computing subspace_out.

To be implemented in all subclasses of Node.

adjoint()

borrowed_ancilla_count() → int

Returns the number of borrowed ancillae used by the circuit of this node, i.e. qubits that can be in any state and will be returned to this state by the end of the circuit.

children() → list[Node]

The children nodes of this node

Mostly used for serialization and systematic verification of the computational graph. Children and parameters together should fully define the matrix encoded by any node.

circuit(target: Sequence[int] = None, clean_ancillae: Sequence[int] = None, borrowed_ancillae: Sequence[int] = None) → Circuit

The circuit corresponding to the unitary of the block encoding.

Qubit indices for the target and ancillae can be passed via arguments, otherwise the default is simply use the indices 0, 1, … in the order target, clean_ancillae, borrowed_ancillae. If indices are passed, the length of the ancillae needs to match the values returned by clean_ancillae_count() and borrowed_ancillae_count().

clean_ancilla_count() → int

Returns the number of borrowed ancillae used by the circuit of this node, i.e. qubits that must be in state |0> at the beginning of the circuit and will be returned to this state by the end of the circuit.

compute(input: ndarray | None) → ndarray

Apply the action of this nodes matrix to the input.

If this node encodes a vector, then input = None is valid, in which case the method should simply return the encoded vector.

Input may be a vector or a higher order tensor. If it is a vector it will have dimension equal to the dimension of qubits_in. If it is a tensor, the last dimension will be equal to the dimension of qubits_in. In this case, the operation should be applied to all vectors input[i, j, ..., k, :] in parallel. The shape of the returned array should match the input shape in all but the last dimension.

compute_adjoint(input: ndarray | None) → ndarray

Apply the adjoint action of this nodes matrix to the input.

See compute for input and output formats.

compute_norm(input: np.array | None = None) → float

Method to compute the norm of this vector given the arithmetic definition of this node using compute.

abstractmethod definition() → Node

The definition of this node.

This is used to implement all other abstract methods of Node. The other methods can be overwritten to give a more efficient implementation.

draw(verbose: bool = False) → str

Rich text output of the computational graph

Parameters:

verbose – if set to True, the definition of any ProxyNode is inserted into the

get_definition() → Node

No-index:

is_guaranteed_unitary() → bool

If this returns true, the matrix the node represents divided by its normalization must be unitary.

This must be ensured by the implementor of this method. A unitary node is useful, since it avoids having to use projections in multiplications.

is_vector() → bool

Tests whether this node encodes a vector or a matrix.

parameters() → dict

The parameters of this graph

Mostly used for serialization and systematic verification of the computational graph. Children and parameters together should fully define the matrix encoded by any node.

simulate(input: int | None = None) → ndarray

Returns a numpy array representing this node, as given by simulate.

When input is None, the output of this method should match compute, which can be checked using verify.

Parameters:

input – The index of the optional initial state, with which this node should be simulated. Should be a number between 0 and node.dimension_out - 1

simulate_norm(input: int | None = None) → float

Method to simulate the norm of the encoded vector in the subspace using a circuit.

When calling this function on a node encoding a matrix, input has to be a vector. In this case the norm of the matrix applied to input is given.

Parameters:

input – A vector to which the encoded matrix is applied before computing the norm.

target_qubit_count() → int

toarray(force_matrix: bool = False) → ndarray

Returns a numpy array representing this node, as given by compute.

The output of this method should match simulate, which can be checked using verify.

By default this will return a one-dimension array if the node represents a vector. However, this behaviour can be suppressed by setting force_matrix = True

Parameters:

force_matrix – Force the method to return a two-dimensional array, even when the node corresponds to a vector.

tree(verbose: bool = False, tree: Tree | None = None, holes: list[Node] = []) → Tree

Method for rich text output of the computational graph.

Typically you should call draw instead of this method.

tree_label(verbose: bool = False)

Label by which this node should be represented in textual (debug) output.

Defaults to the name of the nodes class plus its parameters.

_cached_circuit

Calls _circuit with target, clean_ancillae and borrowed_ancillae being the qubits 0, 1, … so that the result can be cached. This is then mapped by circuit to the actually requested qubit indices.

_definition: Node | None = None

normalization

Normalization of the block encoding.

Non-negative number, which has to be multiplied with the outputs of the circuit to ensure proper scaling of the result.

subspace_in

The embedding of the input vectorspace.

Specifically this specifies how the vectorspace is included in state space nodes circuit, which has dimension 2^n where n is the number of qubits. In other words, this defines whether a particular basis state is “valid” or “invalid”.

In the formalism of block encodings this corresponds to the projection \Pi_1.

subspace_out

The embedding of the output vectorspace.

Specifically this specifies how the vectorspace is included in state space nodes circuit, which has dimension 2^n where n is the number of qubits. In other words, this defines whether a particular basis state is “valid” or “invalid”.

In the formalism of block encodings this corresponds to the projection \Pi_2.