encoding
¶
Prepare a normalized quantum state from classical data.
encode returns a State that any simulator accepts as initial_state.
load_encoding_data reads a 1D vector from a .npy, .txt, or .csv file.
AmplitudeEncoding
¶
Bases: StateEncoder
Prepare a state whose amplitudes are a normalized classical vector.
Let \(a\) be a non-zero vector of length \(m\). It is zero-padded to length
and then divided by its Euclidean norm. That norm is real and non-negative, so the global phase of \(a\) is unchanged. The prepared state uses \(n = \log_2 d\) qubits, and index \(k\) of the padded vector is the amplitude of computational-basis state \(\lvert k\rangle\).
Examples:
A length-3 vector is padded to four amplitudes:
import numpy as np
from shadowsim.encoding import AmplitudeEncoding
state = AmplitudeEncoding().encode([1.0, 1.0, 0.0])
print(state.get_num_qubits())
print(np.round(state.to_numpy(), decimals=8))
Source code in shadowsim/encoding/amplitude.py
encode
¶
encode(data: ArrayLike) -> State
Return the normalized, zero-padded amplitude state.
Parameters:
-
data(ArrayLike) –Non-zero 1D vector of finite real or complex amplitudes.
Returns:
-
State–Normalized state on \(\log_2 d\) qubits.
Raises:
-
ValueError–If
datais empty, not 1D, non-finite, or all zeros.
Source code in shadowsim/encoding/amplitude.py
AngleEncoding
¶
Bases: StateEncoder
Prepare \(\bigotimes_i R_y(\theta_i)\lvert 0\rangle\) from one angle per qubit.
Each angle is a rotation in radians. On a single qubit,
Angles are not amplitudes: they are not normalized. The first angle is the
first factor of tensor, so it is the most
significant qubit. The number of qubits is the length of data.
Examples:
A \(\pi/2\) rotation prepares the equal superposition:
import numpy as np
from shadowsim.encoding import AngleEncoding
state = AngleEncoding().encode([np.pi / 2])
print(np.round(state.to_numpy(), decimals=8))
Source code in shadowsim/encoding/angle.py
encode
¶
encode(data: ArrayLike) -> State
Return the product state for one Y rotation per qubit.
Parameters:
-
data(ArrayLike) –One finite real angle, in radians, per qubit.
Returns:
-
State–Normalized product state on
len(data)qubits.
Raises:
-
ValueError–If
datais not a non-empty 1D array of finite real numbers.
Source code in shadowsim/encoding/angle.py
ComputationalBasisEncoding
¶
Bases: StateEncoder
Prepare a computational-basis state \(\lvert k\rangle\).
An integer \(k\) in \(0 .. 2^n - 1\) becomes the one-hot vector with a 1
at index \(k\). A length-\(n\) sequence of bits \(b_0, b_1, \ldots, b_{n-1}\)
uses the same layout as tensor: \(b_0\) is
the most significant qubit, and
So [1, 0] on two qubits is \(\lvert 10\rangle\), index 2.
Parameters:
-
num_qubits(int) –Number of qubits \(n\). Must be a non-negative integer.
Examples:
from shadowsim.encoding import ComputationalBasisEncoding
encoder = ComputationalBasisEncoding(2)
print(encoder.encode(2).to_numpy())
print(encoder.encode([1, 0]).to_numpy())
Source code in shadowsim/encoding/computational_basis.py
__init__
¶
Store the number of qubits this encoding prepares.
Source code in shadowsim/encoding/computational_basis.py
encode
¶
encode(data: ArrayLike) -> State
Return the computational-basis state for an index or a bit string.
Parameters:
-
data(ArrayLike) –Integer index \(k\), or a length-
num_qubitssequence of bits 0 and 1. The first bit is the most significant qubit.
Returns:
-
State–One-hot state \(\lvert k\rangle\).
Raises:
-
ValueError–If
datais not an in-range index or a valid bit string.
Source code in shadowsim/encoding/computational_basis.py
GrayEncoding
¶
Bases: StateEncoder
Prepare the computational-basis state at the Gray code of \(k\).
An integer \(k\) in \(0 .. 2^n - 1\), or a length-\(n\) bit string read as that integer with the first bit most significant, is mapped by the binary-reflected Gray code
The prepared state is the one-hot vector with a 1 at index \(g(k)\). Consecutive integers therefore land on basis states at Hamming distance 1.
On two qubits, \(k = 0, 1, 2, 3\) prepares
\(\lvert 00\rangle, \lvert 01\rangle, \lvert 11\rangle, \lvert 10\rangle\).
So [1, 0] is the binary integer 2 and prepares \(\lvert 11\rangle\).
Parameters:
-
num_qubits(int) –Number of qubits \(n\). Must be a non-negative integer.
Examples:
from shadowsim.encoding import GrayEncoding
encoder = GrayEncoding(2)
print(encoder.encode(2).to_numpy())
print(encoder.encode([1, 0]).to_numpy())
Source code in shadowsim/encoding/gray.py
__init__
¶
Store the number of qubits this encoding prepares.
Source code in shadowsim/encoding/gray.py
encode
¶
encode(data: ArrayLike) -> State
Return the Gray-labeled computational-basis state for an index or a bit string.
Parameters:
-
data(ArrayLike) –Integer index \(k\), or a length-
num_qubitssequence of bits 0 and 1. The first bit is the most significant qubit, and the sequence is read as a standard binary integer.
Returns:
-
State–One-hot state \(\lvert g(k)\rangle\), where \(g(k) = k \oplus (k \gg 1)\).
Raises:
-
ValueError–If
datais not an in-range index or a valid bit string.
Source code in shadowsim/encoding/gray.py
StateEncoder
¶
Bases: ABC
Prepare a normalized State from classical data.
Subclasses define which classical inputs they accept. Every encoding returns
a state vector that simulators can take as initial_state.
Source code in shadowsim/encoding/state_encoder.py
load_encoding_data
¶
Load a non-empty 1D vector from an encoding data file.
.npy files are read with allow_pickle=False and may contain finite
real or complex numbers. .txt and .csv files are one column of
finite real numbers. Complex values belong in .npy. The returned array
is passed to an encoder such as AmplitudeEncoding, AngleEncoding,
or ComputationalBasisEncoding.
Parameters:
-
path(str | PathLike[str]) –Path to a
.npy,.txt, or.csvfile. The suffix match is case-insensitive.
Returns:
-
NDArray[number[Any]]–The file's vector. A
.npyarray keeps its dtype. Text files are -
NDArray[number[Any]]–returned as
float64.
Raises:
-
ValueError–If the suffix is not supported, the path is missing, is a directory, or is empty, or the contents are not a non-empty 1D array of finite numbers. Pickle payloads are rejected and not executed.
Examples:
import tempfile
from pathlib import Path
import numpy as np
from shadowsim.encoding import AmplitudeEncoding, load_encoding_data
amplitudes = np.array([1.0, 1.0j, 0.0])
with tempfile.TemporaryDirectory() as directory:
path = Path(directory) / "amplitudes.npy"
np.save(path, amplitudes)
state = AmplitudeEncoding().encode(load_encoding_data(path))
print(state.get_num_qubits())