API specification
The emu-sv API is based on the specification here. Concretely, the classes are as follows:
SVBackend
Section titled “SVBackend”
Bases: Backend
A backend for emulating Pulser sequences using state vectors and sparse matrices.
run(sequence, sv_config)
Section titled “
run(sequence, sv_config)
”Emulates the given sequence.
| PARAMETER | DESCRIPTION |
|---|---|
sequence
|
a Pulser sequence to simulate
TYPE:
|
sv_config
|
the backends config. Should be of type SVConfig
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Results
|
the simulation results |
Source code in emu_sv/sv_backend.py
def run(self, sequence: Sequence, sv_config: BackendConfig) -> Results: """ Emulates the given sequence.
Args: sequence: a Pulser sequence to simulate sv_config: the backends config. Should be of type SVConfig
Returns: the simulation results """ assert isinstance(sv_config, SVConfig)
self.validate_sequence(sequence)
results = Results()
data = PulserData(sequence=sequence, config=sv_config, dt=sv_config.dt) omega, delta, phi = data.omega, data.delta, data.phi
target_times = data.target_times
nsteps = omega.shape[0] nqubits = omega.shape[1] device = "cuda" if sv_config.gpu and DEVICE_COUNT > 0 else "cpu"
if sv_config.initial_state is not None: state = deepcopy(sv_config.initial_state) state.vector = state.vector.to(device) else: state = StateVector.make(nqubits, gpu=sv_config.gpu)
for step in range(nsteps): start = time() dt = target_times[step + 1] - target_times[step]
state.vector, H = do_time_step( dt * _TIME_CONVERSION_COEFF, omega[step], delta[step], phi[step], data.full_interaction_matrix, state.vector, sv_config.krylov_tolerance, )
for callback in sv_config.callbacks: callback( sv_config, target_times[step + 1], state, H, # type: ignore[arg-type] results, )
end = time() self.log_step_statistics( results, step=step, duration=end - start, timestep_count=nsteps, state=state, sv_config=sv_config, )
return resultsSVConfig
Section titled “SVConfig”
Bases: BackendConfig
The configuration of the emu-sv SVBackend. The kwargs passed to this class are passed on to the base class. See the API for that class for a list of available options.
| PARAMETER | DESCRIPTION |
|---|---|
initial_state
|
the initial state to use in the simulation
TYPE:
|
dt
|
the timestep size that the solver uses. Note that observables are only calculated if the evaluation_times are divisible by dt.
TYPE:
|
max_krylov_dim
|
the size of the krylov subspace that the Lanczos algorithm maximally builds
TYPE:
|
krylov_tolerance
|
the Lanczos algorithm uses this as the convergence tolerance
TYPE:
|
gpu
|
Use 1 gpu if True, and a GPU is available, otherwise, cpu. Will cause errors if True when a gpu is not available
TYPE:
|
kwargs
|
arguments that are passed to the base class
TYPE:
|
Examples:
>>> gpu = True>>> dt = 1 #this will impact the runtime>>> krylov_tolerance = 1e-8 #the simulation will be faster, but less accurate>>> SVConfig(gpu=gpu, dt=dt, krylov_tolerance=krylov_tolerance,>>> with_modulation=True) #the last arg is taken from the base classSource code in emu_sv/sv_config.py
def __init__( self, *, initial_state: StateVector | None = None, dt: int = 10, max_krylov_dim: int = 100, krylov_tolerance: float = 1e-10, gpu: bool = True, **kwargs: Any,): super().__init__(**kwargs)
self.initial_state = initial_state self.dt = dt self.max_krylov_dim = max_krylov_dim self.gpu = gpu self.krylov_tolerance = krylov_tolerance
for num, obs in enumerate(self.callbacks): # monkey patch obs_copy = copy.deepcopy(obs) if isinstance(obs, QubitDensity): obs_copy.apply = MethodType( # type: ignore[method-assign] qubit_density_sv_impl, obs ) self.callbacks[num] = obs_copy elif isinstance(obs, EnergyVariance): obs_copy.apply = MethodType( # type: ignore[method-assign] energy_variance_sv_impl, obs ) self.callbacks[num] = obs_copy elif isinstance(obs, SecondMomentOfEnergy): obs_copy.apply = MethodType( # type: ignore[method-assign] second_moment_sv_impl, obs ) self.callbacks[num] = obs_copy elif isinstance(obs, CorrelationMatrix): obs_copy.apply = MethodType( # type: ignore[method-assign] correlation_matrix_sv_impl, obs ) self.callbacks[num] = obs_copyStateVector
Section titled “StateVector”
Bases: State
Represents a quantum state vector in a computational basis.
This class extends the State class to handle state vectors,
providing various utilities for initialization, normalization,
manipulation, and measurement. The state vector must have a length
that is a power of 2, representing 2ⁿ basis states for n qubits.
| ATTRIBUTE | DESCRIPTION |
|---|---|
vector |
1D tensor representation of a state vector.
|
gpu |
store the vector on GPU if True, otherwise on CPU
|
Source code in emu_sv/state_vector.py
def __init__( self, vector: torch.Tensor, *, gpu: bool = True,): # NOTE: this accepts also zero vectors.
assert math.log2( len(vector) ).is_integer(), "The number of elements in the vector should be power of 2"
device = "cuda" if gpu and DEVICE_COUNT > 0 else "cpu" self.vector = vector.to(dtype=dtype, device=device)
__add__(other)
Section titled “
__add__(other)
”Sum of two state vectors
| PARAMETER | DESCRIPTION |
|---|---|
other
|
the vector to add to this vector
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
StateVector
|
The summed state |
Source code in emu_sv/state_vector.py
def __add__(self, other: State) -> StateVector: """Sum of two state vectors
Args: other: the vector to add to this vector
Returns: The summed state """ assert isinstance( other, StateVector ), "Other state also needs to be a StateVector" result = self.vector + other.vector return StateVector(result)
__rmul__(scalar)
Section titled “
__rmul__(scalar)
”Scalar multiplication
| PARAMETER | DESCRIPTION |
|---|---|
scalar
|
the scalar to multiply with
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
StateVector
|
The scaled state |
Source code in emu_sv/state_vector.py
def __rmul__(self, scalar: complex) -> StateVector: """Scalar multiplication
Args: scalar: the scalar to multiply with
Returns: The scaled state """ result = scalar * self.vector
return StateVector(result)
from_state_string(*, basis, nqubits, strings, **kwargs)
staticmethod
Section titled “
from_state_string(*, basis, nqubits, strings, **kwargs)
staticmethod
”Transforms a state given by a string into a state vector.
Construct a state from the pulser abstract representation https://pulser.readthedocs.io/en/stable/conventions.html
| PARAMETER | DESCRIPTION |
|---|---|
basis
|
A tuple containing the basis states (e.g., ('r', 'g')).
TYPE:
|
nqubits
|
the number of qubits.
TYPE:
|
strings
|
A dictionary mapping state strings to complex or floats amplitudes.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
StateVector
|
The resulting state. |
Examples:
>>> basis = ("r","g")>>> n = 2>>> st=StateVector.from_state_string(basis=basis,nqubits=n,strings={"rr":1.0,"gg":1.0})>>> print(st)tensor([0.7071+0.j, 0.0000+0.j, 0.0000+0.j, 0.7071+0.j], dtype=torch.complex128)Source code in emu_sv/state_vector.py
@staticmethoddef from_state_string( *, basis: Iterable[str], nqubits: int, strings: dict[str, complex], **kwargs: Any,) -> StateVector: """Transforms a state given by a string into a state vector.
Construct a state from the pulser abstract representation https://pulser.readthedocs.io/en/stable/conventions.html
Args: basis: A tuple containing the basis states (e.g., ('r', 'g')). nqubits: the number of qubits. strings: A dictionary mapping state strings to complex or floats amplitudes.
Returns: The resulting state.
Examples: >>> basis = ("r","g") >>> n = 2 >>> st=StateVector.from_state_string(basis=basis,nqubits=n,strings={"rr":1.0,"gg":1.0}) >>> print(st) tensor([0.7071+0.j, 0.0000+0.j, 0.0000+0.j, 0.7071+0.j], dtype=torch.complex128) """
basis = set(basis) if basis == {"r", "g"}: one = "r" elif basis == {"0", "1"}: one = "1" else: raise ValueError("Unsupported basis provided")
accum_state = StateVector.zero(num_sites=nqubits, **kwargs)
for state, amplitude in strings.items(): bin_to_int = int( state.replace(one, "1").replace("g", "0"), 2 ) # "0" basis is already in "0" accum_state.vector[bin_to_int] = torch.tensor([amplitude])
accum_state._normalize()
return accum_state
inner(other)
Section titled “
inner(other)
”Compute
| PARAMETER | DESCRIPTION |
|---|---|
other
|
the other state
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
float | complex
|
the inner product |
Source code in emu_sv/state_vector.py
def inner(self, other: State) -> float | complex: """ Compute <self, other>. The type of other must be StateVector.
Args: other: the other state
Returns: the inner product """ assert isinstance( other, StateVector ), "Other state also needs to be a StateVector" assert ( self.vector.shape == other.vector.shape ), "States do not have the same number of sites"
return torch.vdot(self.vector, other.vector).item()
make(num_sites, gpu=True)
classmethod
Section titled “
make(num_sites, gpu=True)
classmethod
”Returns a State vector in ground state |000..0>. The vector in the output of StateVector has the shape (2,)*number of qubits
| PARAMETER | DESCRIPTION |
|---|---|
num_sites
|
the number of qubits
TYPE:
|
gpu
|
whether gpu or cpu
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
StateVector
|
The described state |
Examples:
>>> StateVector.make(2)tensor([1.+0.j, 0.+0.j, 0.+0.j, 0.+0.j], dtype=torch.complex128)Source code in emu_sv/state_vector.py
@classmethoddef make(cls, num_sites: int, gpu: bool = True) -> StateVector: """ Returns a State vector in ground state |000..0>. The vector in the output of StateVector has the shape (2,)*number of qubits
Args: num_sites: the number of qubits gpu: whether gpu or cpu
Returns: The described state
Examples: >>> StateVector.make(2) tensor([1.+0.j, 0.+0.j, 0.+0.j, 0.+0.j], dtype=torch.complex128) """
result = cls.zero(num_sites=num_sites, gpu=gpu) result.vector[0] = 1.0 return result
norm()
Section titled “
norm()
”Returns the norm of the state
| RETURNS | DESCRIPTION |
|---|---|
float | complex
|
the norm of the state |
Source code in emu_sv/state_vector.py
def norm(self) -> float | complex: """Returns the norm of the state
Returns: the norm of the state """ norm: float | complex = torch.linalg.vector_norm(self.vector).item() return norm
sample(num_shots=1000, p_false_pos=0.0, p_false_neg=0.0)
Section titled “
sample(num_shots=1000, p_false_pos=0.0, p_false_neg=0.0)
”Samples bitstrings, taking into account the specified error rates.
| PARAMETER | DESCRIPTION |
|---|---|
num_shots
|
how many bitstrings to sample
TYPE:
|
p_false_pos
|
the rate at which a 0 is read as a 1
TYPE:
|
p_false_neg
|
teh rate at which a 1 is read as a 0
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Counter[str]
|
the measured bitstrings, by count |
Source code in emu_sv/state_vector.py
def sample( self, num_shots: int = 1000, p_false_pos: float = 0.0, p_false_neg: float = 0.0) -> Counter[str]: """ Samples bitstrings, taking into account the specified error rates.
Args: num_shots: how many bitstrings to sample p_false_pos: the rate at which a 0 is read as a 1 p_false_neg: teh rate at which a 1 is read as a 0
Returns: the measured bitstrings, by count """
probabilities = torch.abs(self.vector) ** 2
outcomes = torch.multinomial(probabilities, num_shots, replacement=True)
# Convert outcomes to bitstrings and count occurrences counts = Counter([self._index_to_bitstring(outcome) for outcome in outcomes])
# NOTE: false positives and negatives return counts
zero(num_sites, gpu=True)
classmethod
Section titled “
zero(num_sites, gpu=True)
classmethod
”Returns a zero uninitialized "state" vector. Warning, this has no physical meaning as-is!
| PARAMETER | DESCRIPTION |
|---|---|
num_sites
|
the number of qubits
TYPE:
|
gpu
|
whether gpu or cpu
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
StateVector
|
The zero state |
Examples:
>>> StateVector.zero(2)tensor([0.+0.j, 0.+0.j, 0.+0.j, 0.+0.j], dtype=torch.complex128)Source code in emu_sv/state_vector.py
@classmethoddef zero(cls, num_sites: int, gpu: bool = True) -> StateVector: """ Returns a zero uninitialized "state" vector. Warning, this has no physical meaning as-is!
Args: num_sites: the number of qubits gpu: whether gpu or cpu
Returns: The zero state
Examples: >>> StateVector.zero(2) tensor([0.+0.j, 0.+0.j, 0.+0.j, 0.+0.j], dtype=torch.complex128) """
device = "cuda" if gpu and DEVICE_COUNT > 0 else "cpu" vector = torch.zeros(2**num_sites, dtype=dtype, device=device) return cls(vector, gpu=gpu)Wrapper around StateVector.inner.
| PARAMETER | DESCRIPTION |
|---|---|
left
|
StateVector argument
TYPE:
|
right
|
StateVector argument
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Tensor
|
the inner product |
Examples:
>>> factor = math.sqrt(2.0)>>> basis = ("r","g")>>> nqubits = 2>>> string_state1 = {"gg":1.0,"rr":1.0}>>> state1 = StateVector.from_state_string(basis=basis,>>> nqubits=nqubits,strings=string_state1)>>> string_state2 = {"gr":1.0/factor,"rr":1.0/factor}>>> state2 = StateVector.from_state_string(basis=basis,>>> nqubits=nqubits,strings=string_state2)>>> inner(state1,state2).item()(0.4999999999999999+0j)Source code in emu_sv/state_vector.py
def inner(left: StateVector, right: StateVector) -> torch.Tensor: """ Wrapper around StateVector.inner.
Args: left: StateVector argument right: StateVector argument
Returns: the inner product
Examples: >>> factor = math.sqrt(2.0) >>> basis = ("r","g") >>> nqubits = 2 >>> string_state1 = {"gg":1.0,"rr":1.0} >>> state1 = StateVector.from_state_string(basis=basis, >>> nqubits=nqubits,strings=string_state1) >>> string_state2 = {"gr":1.0/factor,"rr":1.0/factor} >>> state2 = StateVector.from_state_string(basis=basis, >>> nqubits=nqubits,strings=string_state2) >>> inner(state1,state2).item() (0.4999999999999999+0j) """
assert (left.vector.shape == right.vector.shape) and ( left.vector.dim() == 1 ), "Shape of a and b should be the same and both needs to be 1D tesnor" return torch.inner(left.vector, right.vector)DenseOperator
Section titled “DenseOperator”
Bases: Operator
Operators in EMU-SV are dense matrices
Source code in emu_sv/dense_operator.py
def __init__( self, matrix: torch.Tensor, *, gpu: bool = True,): device = "cuda" if gpu and DEVICE_COUNT > 0 else "cpu" self.matrix = matrix.to(dtype=dtype, device=device)
__add__(other)
Section titled “
__add__(other)
”Returns the sum of two matrices
| PARAMETER | DESCRIPTION |
|---|---|
other
|
the other operator
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
DenseOperator
|
the summed operator |
Source code in emu_sv/dense_operator.py
def __add__(self, other: Operator) -> DenseOperator: """ Returns the sum of two matrices
Args: other: the other operator
Returns: the summed operator """ assert isinstance(other, DenseOperator), "MPO can only be added to another MPO"
return DenseOperator(self.matrix + other.matrix)
__matmul__(other)
Section titled “
__matmul__(other)
”Apply this operator to a other. The ordering is that self is applied after other.
| PARAMETER | DESCRIPTION |
|---|---|
other
|
the operator to compose with self
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
DenseOperator
|
the composed operator |
Source code in emu_sv/dense_operator.py
def __matmul__(self, other: Operator) -> DenseOperator: """ Apply this operator to a other. The ordering is that self is applied after other.
Args: other: the operator to compose with self
Returns: the composed operator """ assert isinstance( other, DenseOperator ), "DenseOperator can only be multiplied with Operator"
return DenseOperator(self.matrix @ other.matrix)
__mul__(other)
Section titled “
__mul__(other)
”Applies this DenseOperator to the given StateVector.
| PARAMETER | DESCRIPTION |
|---|---|
other
|
the state to apply this operator to
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
StateVector
|
the resulting state |
Source code in emu_sv/dense_operator.py
def __mul__(self, other: State) -> StateVector: """ Applies this DenseOperator to the given StateVector.
Args: other: the state to apply this operator to
Returns: the resulting state """ assert isinstance( other, StateVector ), "DenseOperator can only be applied to another DenseOperator"
return StateVector(self.matrix @ other.vector)
__rmul__(scalar)
Section titled “
__rmul__(scalar)
”Multiply a DenseOperator by scalar.
| PARAMETER | DESCRIPTION |
|---|---|
scalar
|
the scale factor to multiply with
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
DenseOperator
|
the scaled MPO |
Source code in emu_sv/dense_operator.py
def __rmul__(self, scalar: complex) -> DenseOperator: """ Multiply a DenseOperator by scalar.
Args: scalar: the scale factor to multiply with
Returns: the scaled MPO """
return DenseOperator(self.matrix * scalar)
expect(state)
Section titled “
expect(state)
”Compute the expectation value of self on the given state.
| PARAMETER | DESCRIPTION |
|---|---|
state
|
the state with which to compute
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
float | complex
|
the expectation |
Source code in emu_sv/dense_operator.py
def expect(self, state: State) -> float | complex: """ Compute the expectation value of self on the given state.
Args: state: the state with which to compute
Returns: the expectation """ assert isinstance( state, StateVector ), "currently, only expectation values of StateVectors are \ supported"
return torch.vdot(state.vector, self.matrix @ state.vector).item()
from_operator_string(basis, nqubits, operations, operators={}, /, **kwargs)
staticmethod
Section titled “
from_operator_string(basis, nqubits, operations, operators={}, /, **kwargs)
staticmethod
”See the base class
| PARAMETER | DESCRIPTION |
|---|---|
basis
|
the eigenstates in the basis to use e.g. ('r', 'g')
TYPE:
|
nqubits
|
how many qubits there are in the state
TYPE:
|
operations
|
which bitstrings make up the state with what weight
TYPE:
|
operators
|
additional symbols to be used in operations
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
DenseOperator
|
the operator in MPO form. |
Source code in emu_sv/dense_operator.py
@staticmethoddef from_operator_string( basis: Iterable[str], nqubits: int, operations: FullOp, operators: dict[str, QuditOp] = {}, /, **kwargs: Any,) -> DenseOperator: """ See the base class
Args: basis: the eigenstates in the basis to use e.g. ('r', 'g') nqubits: how many qubits there are in the state operations: which bitstrings make up the state with what weight operators: additional symbols to be used in operations
Returns: the operator in MPO form. """
_validate_operator_targets(operations, nqubits)
operators_with_tensors: dict[str, torch.Tensor | QuditOp] = dict(operators)
basis = set(basis) if basis == {"r", "g"}: # operators_with_tensors will now contain the basis for single qubit ops, # and potentially user defined strings in terms of these operators_with_tensors |= { "gg": torch.tensor([[1.0, 0.0], [0.0, 0.0]], dtype=torch.complex128), "gr": torch.tensor([[0.0, 0.0], [1.0, 0.0]], dtype=torch.complex128), "rg": torch.tensor([[0.0, 1.0], [0.0, 0.0]], dtype=torch.complex128), "rr": torch.tensor([[0.0, 0.0], [0.0, 1.0]], dtype=torch.complex128), } elif basis == {"0", "1"}: # operators_with_tensors will now contain the basis for single qubit ops, # and potentially user defined strings in terms of these operators_with_tensors |= { "00": torch.tensor([[1.0, 0.0], [0.0, 0.0]], dtype=torch.complex128), "01": torch.tensor([[0.0, 0.0], [1.0, 0.0]], dtype=torch.complex128), "10": torch.tensor([[0.0, 1.0], [0.0, 0.0]], dtype=torch.complex128), "11": torch.tensor([[0.0, 0.0], [0.0, 1.0]], dtype=torch.complex128), } else: raise ValueError("Unsupported basis provided")
accum_res = torch.zeros(2**nqubits, 2**nqubits, dtype=torch.complex128) for coeff, tensorop in operations: # this function will recurse through the operators_with_tensors, # and replace any definitions in terms of strings by the computed matrix def replace_operator_string(op: QuditOp | torch.Tensor) -> torch.Tensor: if isinstance(op, torch.Tensor): return op
result = torch.zeros(2, 2, dtype=torch.complex128) for opstr, coeff in op.items(): tensor = replace_operator_string(operators_with_tensors[opstr]) operators_with_tensors[opstr] = tensor result += tensor * coeff return result
total_op_per_qubit = [torch.eye(2, 2, dtype=torch.complex128)] * nqubits
for op in tensorop: factor = replace_operator_string(op[0]) for target_qubit in op[1]: total_op_per_qubit[target_qubit] = factor
dense_op = total_op_per_qubit[0] for single_qubit_operator in total_op_per_qubit[1:]: dense_op = torch.kron(dense_op, single_qubit_operator)
accum_res += coeff * dense_op return DenseOperator(accum_res)