cutqc2.core package

Submodules

cutqc2.core.compute_graph module

class cutqc2.core.compute_graph.ComputeGraph

Bases: object

add_edge(u_for_edge, v_for_edge, attributes)

add_node(subcircuit_idx, attributes)

draw()

property effective_qubits

get_edges(from_node, to_node)

Get edges in the graph based on some given conditions: 1. If from_node is given. Only retain edges from the node. 2. If to_node is given. Only retain edges to the node.

incoming_to_outgoing_graph()

Get a more compact representation of the Compute Graph as a dict of 2-tuples to 2-tuples: (to_subcircuit, to_subcircuit_qubit) => (from_subcircuit, from_subcircuit_qubit)

Any “holes” in indexing are plugged, so that the indices of both the incoming qubits as well as the outgoing qubits are continuous, and start at 0.

Return type:

dict[tuple[int, int], tuple[int, int]]

cutqc2.core.cut_circuit module

cutqc2.core.dag module

class cutqc2.core.dag.DAGEdge(first, second)

Bases: object

Represents an edge in a quantum circuit DAG, connecting two DagNodes.

source

The source node of the edge.

Type:

DagNode

dest

The destination node of the edge.

Type:

DagNode

classmethod from_string(edge_str)

Create a DAGEdge from a string representation.

Parameters:

edge_str (str) – The string representation of the edge in the format ‘source dest’.

Returns:

The created DAGEdge instance.

Return type:

DAGEdge

weight()

Calculate the weight of the edge, defined by the number of inputs directly connected to the source or destination node.

Return type:

int

class cutqc2.core.dag.DagNode(wire_index, gate_index)

Bases: object

Represents a node in a quantum circuit DAG (Directed Acyclic Graph), corresponding to a specific gate on a specific wire (qubit/register).

Since only inter-wire gates are important for the cut algorithm, any mention of gate_index refers to the index wrt inter-wire gates only.

wire_index

The index of the wire (qubit/register).

Type:

int

gate_index

The index of the gate on the wire. Note: gate_index assumes that only inter-wire gates are considered.

Type:

int

classmethod from_string(s)

Create a DagNode from a string representation.

Parameters:

s (str) – The string representation of the node in the format ‘[wire_index]gate_index’.

Returns:

The created DagNode instance.

Return type:

DagNode

locate(dag_circuit)

Locate the position of the DagNode in the DAGCircuit. :type dag_circuit: DAGCircuit :param dag_circuit: The DAGCircuit containing the node. :type dag_circuit: DAGCircuit

Returns:

A tuple containing the Qubit and the index of the gate on that wire.

Return type:

tuple[Qubit, int]

Raises:

ValueError – If the node cannot be found in the DAGCircuit.

cutqc2.core.dynamic_definition module

class cutqc2.core.dynamic_definition.Bin(qubit_spec, probabilities)

Bases: object

A Bin represents a collection of qubits with a specific configuration (given by qubit_spec) and the associated probabilities.

class cutqc2.core.dynamic_definition.DynamicDefinition(num_qubits, capacity, prob_fn, epsilon=0.0001)

Bases: object

DynamicDefinition is a class that implements the dynamic definition algorithm for quantum probability distribution reconstruction. It recursively zooms-in on qubits (initially “merged”) that have a high probability mass.

plot(plot_bins=False, prob_mass_threshold=0.9, max_bars=20, ax=None, full_states=None)

pop()

Return type:

Bin

probabilities(full_states=None)

Return type:

ndarray

push(bin)

run(max_recursion=10, **kwargs)

Return type:

ndarray

cutqc2.core.mip module

class cutqc2.core.mip.MIPCutSearcher(*, n_vertices, edges, id_to_dag_edge, num_subcircuit, max_subcircuit_width, num_qubits, max_cuts)

Bases: object

add_constraints()

Add all optimization variable constraints to the model. We follow the same notation is in section 4.1 of the CutQc paper

add_variables()

Add all optimization variables to the model. We follow the same notation is in section 4.1 of the CutQc paper

static check_graph(n_vertices, edges)

Check that the incoming vertices and edges are valid.

1. edges must include all vertices

2. all (u, v) must be ordered and smaller than n_vertices

solve(threads=48, time_limit=30)

Return type:

bool

cutqc2.core.utils module

cutqc2.core.utils.attribute_shots(subcircuit_measured_probs, subcircuit_entries)

Aggregate measured probabilities for symbolic subcircuit entries by linear combination of their contributing instances.

Each entry key maps to a list of terms (coefficient, instance_key). The function forms entry_prob = sum_i coefficient_i * subcircuit_measured_probs[instance_key_i] for every entry.

Parameters:

• subcircuit_measured_probs (dict) – Mapping from (init, meas) instance keys to measured probability vectors (or scalars).

• subcircuit_entries (dict) – Mapping from entry keys to a list of (coefficient, instance_key) terms.

Returns:

Mapping from entry keys to aggregated probability vectors (or scalars).

Return type:

dict

cutqc2.core.utils.chunked(gen, chunk_size)

Yield lists of length chunk_size from generator gen.

cutqc2.core.utils.measure_prob(unmeasured_prob, meas)

Project a probability vector from mixed measurement bases onto the computational subspace defined by entries equal to “comp”.

If all bases are computational (or unmeasured_prob is a scalar), the input is returned unchanged. Otherwise, for each full state index, the state is mapped to an effective computational-basis index using measure_state and accumulated with the appropriate sign.

Parameters:

• unmeasured_prob (np.ndarray | float) – Probability vector over all 2^n basis states (MSB-to-LSB convention) or a scalar probability.

• meas (Sequence[str]) – Per-qubit measurement basis labels (e.g., “comp”, “X”, “Y”, “I”).

Returns:

Measured probability vector over 2^k states, where k is the number of entries equal to “comp” in meas. If the input is a scalar or meas is entirely computational, the input is returned.

Return type:

np.ndarray | float

cutqc2.core.utils.measure_state(full_state, meas)

Map a full-basis state index to an effective computational-basis index under mixed-basis measurement, and compute the accumulated sign.

The sign flips (sigma *= -1) whenever the measured bit is 1 and the basis is not in {“I”, “comp”}. Bits with basis “comp” contribute to the effective computational index; bits with bases in {“I”, “X”, “Y”} are marginalized out from the index (but may affect sign).

Parameters:

• full_state (int) – Index of the n-bit computational basis state.

• meas (Sequence[str]) – Per-qubit measurement bases (length n).

Returns:

A pair (sigma, effective_state) where sigma in {+1, -1} and effective_state is the integer index in the compressed space spanned by qubits with basis “comp”.

Return type:

tuple[int, int]

cutqc2.core.utils.merge_prob_vector(unmerged_prob_vector, qubit_spec, qubit_spec_lsb_first=False)

Compress quantum probability vector by merging specified qubits and conditioning on fixed qubit values.

Parameters:

• unmerged_prob_vector (np.ndarray) – Original probability vector (2^num_qubits,)

• qubit_spec (str) – String of length num_qubits, MSB to LSB, with each character indicating: - “A”: qubit is preserved in output - “M”: qubit is summed over - “0”/”1”: qubit is fixed to that value

• qubit_spec_lsb_first (bool) – If True, qubit_spec is given LSB to MSB instead of MSB to LSB.

Returns:

Compressed probability vector (2^num_active,) with marginalization and conditioning applied.

Return type:

np.ndarray

cutqc2.core.utils.modify_subcircuit_instance(subcircuit, init, meas)

Create a runnable instance of subcircuit with specified initialization and measurement-basis rotations applied.

For each qubit i, the corresponding entry in init determines the state preparation inserted at the front of the circuit DAG.

For each qubit i, the corresponding entry in meas determines a basis rotation appended to the back of the circuit so that subsequent computational basis measurement is equivalent to measuring in that basis.

Parameters:

• subcircuit (qiskit.QuantumCircuit) – Base subcircuit to modify.

• init (Sequence[str]) – Per-qubit initialization labels. Length must equal the number of qubits in subcircuit.

• meas (Sequence[str]) – Per-qubit measurement basis labels. Length must equal the number of qubits in subcircuit.

Returns:

A new circuit with the requested preparations and basis rotations applied.

Return type:

qiskit.QuantumCircuit

cutqc2.core.utils.mutate_measurement_basis(meas)

Expand a measurement-basis specification by replacing identity entries with both identity and Z bases.

If all entries are non-identity (no “I” present), the function returns a singleton list containing the original meas. Otherwise, for each qubit position with basis “I”, it generates two alternatives: “I” and “Z”. The Cartesian product across positions yields all mutated basis tuples.

Parameters:

meas (Sequence[str]) – Per-qubit measurement bases (e.g., “comp”, “X”, “Y”, “I”).

Returns:

All mutated measurement-basis tuples. If no mutation is needed, this is [meas].

Return type:

list[tuple[str, …]]

cutqc2.core.utils.permute_bits(arr, permutation, n_bits)

Return type:

ndarray

cutqc2.core.utils.run_subcircuit_instances(subcircuit, subcircuit_instance_init_meas, backend='statevector_simulator', max_workers=1)

Evaluate a set of subcircuit instances under different initializations and measurement bases, returning their measured probability distributions.

The function iterates over provided (init, meas) specifications, creates a runnable subcircuit instance via modify_subcircuit_instance, simulates it using evaluate_circ, and then projects the resulting state/probabilities into the requested measurement bases. If a measurement specification contains “Z”, that instance is skipped. Any identity basis entries “I” are expanded into both “I” and “Z” via mutate_measurement_basis and each mutation is measured separately.

Parameters:

• subcircuit (QuantumCircuit) – Base subcircuit to instantiate and simulate.

• subcircuit_instance_init_meas (list[tuple[tuple[str], tuple[str]]]) –

  A list of (init, meas) pairs, where: - init is a tuple of state labels per qubit (e.g., “zero”, “one”,

  ”plus”, “minus”, “plusI”, “minusI”).

  • meas is a tuple of measurement basis labels per qubit (e.g., “comp”, “X”, “Y”, “I”). If any entry is “Z”, the instance is skipped.

• backend (str, optional) – Backend identifier passed to evaluate_circ (default is “statevector_simulator”).

• max_workers (int, optional) – Maximum number of parallel threads to use (default is 1, i.e., no parallelism).

Returns:

A mapping from (init, meas) to the measured probability vector (or a scalar if the circuit evaluates to a single probability). The meas key in the mapping reflects any mutated basis produced by mutate_measurement_basis.

Return type:

dict[tuple[tuple[str], tuple[str]], np.ndarray | float]

cutqc2.core.utils.unmerge_prob_vector(merged_prob_vector, qubit_spec, full_states=None, qubit_spec_lsb_first=False)

Expand a merged quantum probability vector back to a full vector by evenly distributing over merged qubits and conditioning on fixed ones.

Parameters:

• merged_prob_vector (np.ndarray) – Compressed probability vector (2^num_active,)

• qubit_spec (str) – String of length num_qubits, MSB to LSB, with each character indicating: - “A”: active (preserved) - “M”: merged (marginalized out) - “0”/”1”: fixed bits

• full_states (np.ndarray or None) – Array of full states to fill in. If None, all 2**|num_qubits| states are filled-in.

• qubit_spec_lsb_first (bool) – If True, qubit_spec is given LSB to MSB instead of MSB to LSB.

Return type:

None

Module contents