> ## Documentation Index
> Fetch the complete documentation index at: https://docs.haiqu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Block-wise Vector Loading

#### Haiqu.block\_vector\_loading(data, num\_blocks=None, target\_num\_qubits=None, overlap=None, num\_layers=2, truncation\_cutoff=1e-06, fine\_tuning\_iterations=20, max\_time=900, name=None)

Generate a block-wise quantum circuit that prepares an arbitrary vector or matrix.

Given a vector or matrix of real or complex data, this method creates a Data Loading job that runs in the Haiqu cloud. The
result of this job is a circuit which can be used to supply the data to a quantum algorithm for processing.

Unlike [`vector_loading()`](../index.md#haiqu.sdk.quantum_haiqu.Haiqu.vector_loading), which uses the fewest qubits possible to encode the data, the block-wise strategy in
[`block_vector_loading()`](../index.md#haiqu.sdk.quantum_haiqu.Haiqu.block_vector_loading) trades circuit depth for width. If additional qubits are available, they can be exploited to
split the problem into several blocks, each of which is simpler. This reduces the overall depth of the circuit, making it
more amenable to execution on noisy devices.

Exactly one of `num_blocks` and `target_num_qubits` must be specified, which will determine how the vector or matrix
is decomposed into blocks.

The complexity and quality of the generated circuit can be controlled by the `num_layers`, `truncation_cutoff`, and
`fine_tuning_iterations` parameters.

* **Parameters:**
  * **data** (*Sequence* \*\[\**Number* *]*  *|* *Sequence* \*\[\**Sequence* \*\[\**Number* *]* *]*) -- The vector or matrix with data to encode.
  * **num\_blocks** (*int* *|* *Sequence* \*\[\**int* *]*  *|* *None*) -- The number of blocks into which to split the data. It must be a single number
    in one dimension and a pair of numbers (rows and columns) in two dimensions.
    If `None` (default), the number of blocks is inferred from
    `target_num_qubits`, which must be specified.
    In result each block must be of size not larger than 20 qubits.
  * **target\_num\_qubits** (*int* *|* *None*) -- The qubit budget to assume when automatically determining the number of blocks. If
    `None` (default), the number of qubits depends on `num_blocks`, which must be
    specified.
  * **overlap** (*int* *|* *float* *|* *None*) -- The overlap blocks have with each other.
    An integer indicates the exact number of overlapping indices between consecutive blocks.
    A float in \[0, 1) indicates fractional overlap between consecutive blocks.
    If `None` (default), the blocks do not overlap.
  * **num\_layers** (*int*) -- The number of layers in the generated circuit (from 1 to 15 layers).
    More layers can improve the quality of the circuit
    blocks at the cost of a deeper circuit. Defaults to 2.
  * **truncation\_cutoff** (*Real*) -- The entanglement cutoff for later layers. Increasing this threshold may result in a smaller
    (but more approximate) circuit. Defaults to `1e-6`.
  * **fine\_tuning\_iterations** (*int*) -- The maximum number of fine-tuning iterations to perform after each layer is added.
    Increasing this limit may improve the quality of the circuit by using more classical
    resources. Defaults to 20, maximal is 200.
  * **max\_time** (*int* *|* *float*) -- Soft time limit for the job (in seconds).
    The data loading job will first always produce the initial result and then limit the fine-tuning
    stage by the remaining time left. If time limit exceeds during the fine-tuning - the best
    current result will be returned. Defaults to 900
    (15 min). Max allowed job time is 15 min.
    The job can take more wall clock time than user specified max\_time due to latency,
    initialization overheads or if the initial result already takes more time. This time limit
    will be evenly split across generation of each block.
  * **name** (*str* *|* *None*) -- The name for the job and the produced circuit. If `None` (default), a name will be automatically
    generated.
* **Returns:**
  The Data Loading job that will generate the block-wise circuit for the data.
  : Call `job.result()` to retrieve a Qiskit-compatible gate (`HaiquCircuitGate`) implementing the block-wise
  data preparation. `job.quality` is the achieved (mean) state fidelity across blocks; `job.info` exposes
  per-block metadata (`num_blocks`, `num_qubits_per_block`, `fidelity_per_block`, `mean_fidelity`,
  `global_fidelity`).
  Run `help(job.result)` for the full description of result and `info` contents.
* **Return type:**
  DataLoadingJobModel

#### Examples

```python theme={null}
>>> vector = [0.5, 0.2, 1, 14, 0.3, 5, 0.2, 0.6]  # 8 elements (will split into 2 two-qubit blocks)
>>> job = haiqu.block_vector_loading(data=vector, num_blocks=2, name="Block Vector Loading")
>>> bvl_gate = job.result()  # bvl_gate is a Qiskit-compatible gate
>>> fidelity = job.quality
>>> print(f"Block vector was loaded with average fidelity {fidelity:.6f}")
Block vector was loaded with average fidelity 1.000000
>>> print(f"Block vector loading used {job.num_qubits} qubits")
Block vector loading used 4 qubits
>>> circuit = qiskit.QuantumCircuit(job.num_qubits)
>>> circuit.append(bvl_gate, range(job.num_qubits))
>>> circuit.draw()
     ┌────────────────────────────────────────────────────────────┐
q_0: ┤0                                                           ├
     │                                                            │
q_1: ┤1                                                           ├
     │  Haiqucircuit(circ-12345678-1234-5678-1234-567812345678,4) │
q_2: ┤2                                                           ├
     │                                                            │
q_3: ┤3                                                           ├
     └────────────────────────────────────────────────────────────┘
```