State-vector simulation
Applicable version · ArcQML 0.1.0
On this page
StateVectorSimulator: stateful and stateless interfaces
| Interface | State effect | Returns | Main use |
|---|---|---|---|
new / from_state_tensor |
Creates the initial state | Simulator | Default zero state or imported normalized custom state. |
apply_gate / apply_operation |
Changes current state |
&mut Self |
Stepwise execution of fixed-parameter Gate/Operation. |
apply_circuit |
Changes current state |
&mut Self |
Read current Circuit parameters and execute gate by gate. |
run |
Leaves current state unchanged |
Differentiable F64 scalar Tensor |
Training and functional forward passes. |
amplitudes |
The method itself does not change state | Shared handle to the current C64 Tensor |
Read amplitudes while retaining existing graph connections. |
sample_counts |
Read-only | BTreeMap<String, usize> |
Terminal sampling of all qubits in the current state. |
apply_circuit and run have different semantics. The former changes the simulator state, so repeated calls continue evolving the already evolved state. The latter copies the current caller state into a forward buffer and returns an expectation without changing self. To repeatedly execute from the zero state, use a new simulator or call reset before apply_circuit. Training loops normally use run.
The shared Tensor returned by Rust amplitudes() is not an independent numerical copy. In-place writes to its storage affect the original state and may violate normalization or version constraints of an existing graph. Python numpy() instead produces an independent array copy.
Importing and validating initial states
Single-state from_state_tensor accepts a contiguous, CPU, Dense, one-dimensional C64 Tensor with shape exactly [d]. The batch version requires [B, d], a nonzero batch size, and rowwise normalization. Here d is the state-space dimension; both interfaces use the normalization tolerance specified in that section.
For NumPy imports, a single state requires a C-contiguous one-dimensional complex128 array, while a batch requires a C-contiguous two-dimensional complex128 array. The binding first checks Python dimensions, copies to a FlatC64 Tensor, and lets the Rust simulator perform the same normalization and layout validation.
BatchStateVectorSimulator
BatchStateVectorSimulator stores state with shape [batch_size, d], one independent pure state per row. apply_circuit applies the same circuit to each row; run returns an F64 Tensor of shape [batch_size]. Runtime interprets states in row-major order. With the parallel feature enabled, the public Rust layer uses Rayon for outer batch scheduling, so thread count, batch size, state dimension, and memory bandwidth all affect performance.
Meaning of batch A batch is a collection of independent initial states sharing one Circuit and one SparsePauliOp, not parallel branches within one quantum state. It cannot represent different gate topologies or qubit counts for individual samples. Batch execution is useful when adapting classical machine-learning tasks with larger datasets.