Skip to content

Results are limited to Matrix Product State emulator (EMU_MPS) v1.2.7

Product news
You are reading Matrix Product State emulator (EMU_MPS) v1.2.7, an older version of this documentation. Go to the latest version (v2.11.0)

API specification

The emu-mps API is based on the specification here. Concretely, the classes are as follows:

Bases: Backend

A backend for emulating Pulser sequences using Matrix Product States (MPS), aka tensor trains.

Resume simulation from autosave file. Only resume simulations from data you trust! Unpickling of untrusted data is not safe.

Source code in emu_mps/mps_backend.py
def resume(self, autosave_file: str | pathlib.Path) -> Results:
"""
Resume simulation from autosave file.
Only resume simulations from data you trust!
Unpickling of untrusted data is not safe.
"""
if isinstance(autosave_file, str):
autosave_file = pathlib.Path(autosave_file)
if not autosave_file.is_file():
raise ValueError(f"Not a file: {autosave_file}")
with open(autosave_file, "rb") as f:
impl: MPSBackendImpl = pickle.load(f)
impl.autosave_file = autosave_file
impl.last_save_time = time.time()
impl.config.init_logging() # FIXME: might be best to take logger object out of config.
logging.getLogger("global_logger").warning(
f"Resuming simulation from file {autosave_file}\n"
f"Saving simulation state every {impl.config.autosave_dt} seconds"
)
return self._run(impl)

Emulates the given sequence.

PARAMETER DESCRIPTION
sequence

a Pulser sequence to simulate

TYPE: Sequence

mps_config

the backends config. Should be of type MPSConfig

TYPE: BackendConfig

RETURNS DESCRIPTION
Results

the simulation results

Source code in emu_mps/mps_backend.py
def run(self, sequence: Sequence, mps_config: BackendConfig) -> Results:
"""
Emulates the given sequence.
Args:
sequence: a Pulser sequence to simulate
mps_config: the backends config. Should be of type MPSConfig
Returns:
the simulation results
"""
assert isinstance(mps_config, MPSConfig)
self.validate_sequence(sequence)
impl = create_impl(sequence, mps_config)
impl.init() # This is separate from the constructor for testing purposes.
return self._run(impl)

Bases: BackendConfig

The configuration of the emu-ct MPSBackend. 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: State | None DEFAULT: None

dt

the timestep size that the solver uses. Note that observables are only calculated if the evaluation_times are divisible by dt.

TYPE: int DEFAULT: 10

precision

up to what precision the state is truncated

TYPE: float DEFAULT: 1e-05

max_bond_dim

the maximum bond dimension that the state is allowed to have.

TYPE: int DEFAULT: 1024

max_krylov_dim

the size of the krylov subspace that the Lanczos algorithm maximally builds

TYPE: int DEFAULT: 100

extra_krylov_tolerance

the Lanczos algorithm uses this*precision as the convergence tolerance

TYPE: float DEFAULT: 0.001

num_gpus_to_use

during the simulation, distribute the state over this many GPUs 0=all factors to cpu. As shown in the benchmarks, using multiple GPUs might alleviate memory pressure per GPU, but the runtime should be similar.

TYPE: int DEFAULT: DEVICE_COUNT

autosave_prefix

filename prefix for autosaving simulation state to file

TYPE: str DEFAULT: 'emu_mps_save_'

autosave_dt

minimum time interval in seconds between two autosaves Saving the simulation state is only possible at specific times, therefore this interval is only a lower bound.

TYPE: int DEFAULT: 600

kwargs

arguments that are passed to the base class

TYPE: Any DEFAULT: {}

Examples:

>>> num_gpus_to_use = 2 #use 2 gpus if available, otherwise 1 or cpu
>>> dt = 1 #this will impact the runtime
>>> precision = 1e-6 #smaller dt requires better precision, generally
>>> MPSConfig(num_gpus_to_use=num_gpus_to_use, dt=dt, precision=precision,
>>> with_modulation=True) #the last arg is taken from the base class
Source code in emu_mps/mps_config.py
def __init__(
self,
*,
initial_state: State | None = None,
dt: int = 10,
precision: float = 1e-5,
max_bond_dim: int = 1024,
max_krylov_dim: int = 100,
extra_krylov_tolerance: float = 1e-3,
num_gpus_to_use: int = DEVICE_COUNT,
autosave_prefix: str = "emu_mps_save_",
autosave_dt: int = 600, # 10 minutes
**kwargs: Any,
):
super().__init__(**kwargs)
self.initial_state = initial_state
self.dt = dt
self.precision = precision
self.max_bond_dim = max_bond_dim
self.max_krylov_dim = max_krylov_dim
self.num_gpus_to_use = num_gpus_to_use
self.extra_krylov_tolerance = extra_krylov_tolerance
if self.noise_model is not None:
if "doppler" in self.noise_model.noise_types:
raise NotImplementedError("Unsupported noise type: doppler")
if (
"amplitude" in self.noise_model.noise_types
and self.noise_model.amp_sigma != 0.0
):
raise NotImplementedError("Unsupported noise type: amp_sigma")
self.autosave_prefix = autosave_prefix
self.autosave_dt = autosave_dt
MIN_AUTOSAVE_DT = 10
assert (
self.autosave_dt > MIN_AUTOSAVE_DT
), f"autosave_dt must be larger than {MIN_AUTOSAVE_DT} seconds"

Bases: State

Matrix Product State, aka tensor train.

Each tensor has 3 dimensions ordered as such: (left bond, site, right bond).

Only qubits are supported.

This constructor creates a MPS directly from a list of tensors. It is for internal use only.

PARAMETER DESCRIPTION
factors

the tensors for each site WARNING: for efficiency in a lot of use cases, this list of tensors IS NOT DEEP-COPIED. Therefore, the new MPS object is not necessarily the exclusive owner of the list and its tensors. As a consequence, beware of potential external modifications affecting the list or the tensors. You are responsible for deciding whether to pass its own exclusive copy of the data to this constructor, or some shared objects.

TYPE: List[Tensor]

orthogonality_center

the orthogonality center of the MPS, or None (in which case it will be orthogonalized when needed)

TYPE: Optional[int] DEFAULT: None

config

the emu-mps config object passed to the run method

TYPE: Optional[MPSConfig] DEFAULT: None

num_gpus_to_use

distribute the factors over this many GPUs 0=all factors to cpu, None=keep the existing device assignment.

TYPE: Optional[int] DEFAULT: DEVICE_COUNT

Source code in emu_mps/mps.py
def __init__(
self,
factors: List[torch.Tensor],
/,
*,
orthogonality_center: Optional[int] = None,
config: Optional[MPSConfig] = None,
num_gpus_to_use: Optional[int] = DEVICE_COUNT,
):
"""
This constructor creates a MPS directly from a list of tensors. It is for internal use only.
Args:
factors: the tensors for each site
WARNING: for efficiency in a lot of use cases, this list of tensors
IS NOT DEEP-COPIED. Therefore, the new MPS object is not necessarily
the exclusive owner of the list and its tensors. As a consequence,
beware of potential external modifications affecting the list or the tensors.
You are responsible for deciding whether to pass its own exclusive copy
of the data to this constructor, or some shared objects.
orthogonality_center: the orthogonality center of the MPS, or None (in which case
it will be orthogonalized when needed)
config: the emu-mps config object passed to the run method
num_gpus_to_use: distribute the factors over this many GPUs
0=all factors to cpu, None=keep the existing device assignment.
"""
self.config = config if config is not None else MPSConfig()
assert all(
factors[i - 1].shape[2] == factors[i].shape[0] for i in range(1, len(factors))
), "The dimensions of consecutive tensors should match"
assert (
factors[0].shape[0] == 1 and factors[-1].shape[2] == 1
), "The dimension of the left (right) link of the first (last) tensor should be 1"
self.factors = factors
self.num_sites = len(factors)
assert self.num_sites > 1 # otherwise, do state vector
assert (orthogonality_center is None) or (
0 <= orthogonality_center < self.num_sites
), "Invalid orthogonality center provided"
self.orthogonality_center = orthogonality_center
if num_gpus_to_use is not None:
assign_devices(self.factors, min(DEVICE_COUNT, num_gpus_to_use))

Returns the sum of two MPSs, computed with a direct algorithm. The resulting MPS is orthogonalized on the first site and truncated up to self.config.precision.

PARAMETER DESCRIPTION
other

the other state

TYPE: State

RETURNS DESCRIPTION
MPS

the summed state

Source code in emu_mps/mps.py
def __add__(self, other: State) -> MPS:
"""
Returns the sum of two MPSs, computed with a direct algorithm.
The resulting MPS is orthogonalized on the first site and truncated
up to `self.config.precision`.
Args:
other: the other state
Returns:
the summed state
"""
assert isinstance(other, MPS), "Other state also needs to be an MPS"
new_tt = add_factors(self.factors, other.factors)
result = MPS(
new_tt,
config=self.config,
num_gpus_to_use=None,
orthogonality_center=None, # Orthogonality is lost.
)
result.truncate()
return result

Multiply an MPS by a scalar.

PARAMETER DESCRIPTION
scalar

the scale factor

TYPE: complex

RETURNS DESCRIPTION
MPS

the scaled MPS

Source code in emu_mps/mps.py
def __rmul__(self, scalar: complex) -> MPS:
"""
Multiply an MPS by a scalar.
Args:
scalar: the scale factor
Returns:
the scaled MPS
"""
which = (
self.orthogonality_center
if self.orthogonality_center is not None
else 0 # No need to orthogonalize for scaling.
)
factors = scale_factors(self.factors, scalar, which=which)
return MPS(
factors,
config=self.config,
num_gpus_to_use=None,
orthogonality_center=self.orthogonality_center,
)

apply(qubit_index, single_qubit_operator)

Section titled “ apply(qubit_index, single_qubit_operator) ”

Apply given single qubit operator to qubit qubit_index, leaving the MPS orthogonalized on that qubit.

Source code in emu_mps/mps.py
def apply(self, qubit_index: int, single_qubit_operator: torch.Tensor) -> None:
"""
Apply given single qubit operator to qubit qubit_index, leaving the MPS
orthogonalized on that qubit.
"""
self.orthogonalize(qubit_index)
self.factors[qubit_index] = torch.tensordot(
self.factors[qubit_index],
single_qubit_operator.to(self.factors[qubit_index].device),
([1], [1]),
).transpose(1, 2)

Computes expectation values for each qubit and each single qubit operator in the batched input tensor.

Returns a tensor T such that T[q, i] is the expectation value for qubit #q and operator single_qubit_operators[i].

Source code in emu_mps/mps.py
def expect_batch(self, single_qubit_operators: torch.Tensor) -> torch.Tensor:
"""
Computes expectation values for each qubit and each single qubit operator in
the batched input tensor.
Returns a tensor T such that T[q, i] is the expectation value for qubit #q
and operator single_qubit_operators[i].
"""
orthogonality_center = (
self.orthogonality_center
if self.orthogonality_center is not None
else self.orthogonalize(0)
)
result = torch.zeros(
self.num_sites, single_qubit_operators.shape[0], dtype=torch.complex128
)
center_factor = self.factors[orthogonality_center]
for qubit_index in range(orthogonality_center, self.num_sites):
temp = torch.tensordot(center_factor.conj(), center_factor, ([0, 2], [0, 2]))
result[qubit_index] = torch.tensordot(
single_qubit_operators.to(temp.device), temp, dims=2
)
if qubit_index < self.num_sites - 1:
_, r = torch.linalg.qr(center_factor.reshape(-1, center_factor.shape[2]))
center_factor = torch.tensordot(
r, self.factors[qubit_index + 1].to(r.device), dims=1
)
center_factor = self.factors[orthogonality_center]
for qubit_index in range(orthogonality_center - 1, -1, -1):
_, r = torch.linalg.qr(
center_factor.reshape(center_factor.shape[0], -1).mT,
)
center_factor = torch.tensordot(
self.factors[qubit_index],
r.to(self.factors[qubit_index].device),
([2], [1]),
)
temp = torch.tensordot(center_factor.conj(), center_factor, ([0, 2], [0, 2]))
result[qubit_index] = torch.tensordot(
single_qubit_operators.to(temp.device), temp, dims=2
)
return result

from_state_string(*, basis, nqubits, strings, **kwargs) staticmethod

Section titled “ from_state_string(*, basis, nqubits, strings, **kwargs) staticmethod ”

See the base class.

PARAMETER DESCRIPTION
basis

A tuple containing the basis states (e.g., ('r', 'g')).

TYPE: Iterable[str]

nqubits

the number of qubits.

TYPE: int

strings

A dictionary mapping state strings to complex or floats amplitudes.

TYPE: dict[str, complex]

RETURNS DESCRIPTION
MPS

The resulting MPS representation of the state.s

Source code in emu_mps/mps.py
@staticmethod
def from_state_string(
*,
basis: Iterable[str],
nqubits: int,
strings: dict[str, complex],
**kwargs: Any,
) -> MPS:
"""
See the base class.
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 MPS representation of the state.s
"""
basis = set(basis)
if basis == {"r", "g"}:
one = "r"
elif basis == {"0", "1"}:
one = "1"
else:
raise ValueError("Unsupported basis provided")
basis_0 = torch.tensor([[[1.0], [0.0]]], dtype=torch.complex128) # ground state
basis_1 = torch.tensor([[[0.0], [1.0]]], dtype=torch.complex128) # excited state
accum_mps = MPS(
[torch.zeros((1, 2, 1), dtype=torch.complex128)] * nqubits,
orthogonality_center=0,
**kwargs,
)
for state, amplitude in strings.items():
factors = [basis_1 if ch == one else basis_0 for ch in state]
accum_mps += amplitude * MPS(factors, **kwargs)
norm = accum_mps.norm()
if not math.isclose(1.0, norm, rel_tol=1e-5, abs_tol=0.0):
print("\nThe state is not normalized, normalizing it for you.")
accum_mps *= 1 / norm
return accum_mps

get_correlation_matrix(*, operator=n_operator)

Section titled “ get_correlation_matrix(*, operator=n_operator) ”
Efficiently compute the symmetric correlation matrix C_ij =in basis ("r", "g").
PARAMETER DESCRIPTION
operator

a 2x2 Torch tensor to use

TYPE: Tensor DEFAULT: n_operator

RETURNS DESCRIPTION
list[list[float]]

the corresponding correlation matrix

Source code in emu_mps/mps.py
def get_correlation_matrix(
self, *, operator: torch.Tensor = n_operator
) -> list[list[float]]:
"""
Efficiently compute the symmetric correlation matrix
C_ij =
in basis ("r", "g").
Args:
operator: a 2x2 Torch tensor to use
Returns:
the corresponding correlation matrix
"""
assert operator.shape == (2, 2)
result = [[0.0 for _ in range(self.num_sites)] for _ in range(self.num_sites)]
for left in range(0, self.num_sites):
self.orthogonalize(left)
accumulator = torch.tensordot(
self.factors[left],
operator.to(self.factors[left].device),
dims=([1], [0]),
)
accumulator = torch.tensordot(
accumulator, self.factors[left].conj(), dims=([0, 2], [0, 1])
)
result[left][left] = accumulator.trace().item().real
for right in range(left + 1, self.num_sites):
partial = torch.tensordot(
accumulator.to(self.factors[right].device),
self.factors[right],
dims=([0], [0]),
)
partial = torch.tensordot(
partial, self.factors[right].conj(), dims=([0], [0])
)
result[left][right] = (
torch.tensordot(
partial, operator.to(partial.device), dims=([0, 2], [0, 1])
)
.trace()
.item()
.real
)
result[right][left] = result[left][right]
accumulator = tensor_trace(partial, 0, 2)
return result

Return the max bond dimension of this MPS.

RETURNS DESCRIPTION
int

the largest bond dimension in the state

Source code in emu_mps/mps.py
def get_max_bond_dim(self) -> int:
"""
Return the max bond dimension of this MPS.
Returns:
the largest bond dimension in the state
"""
return max((x.shape[2] for x in self.factors), default=0)

Returns the number of MBs of memory occupied to store the state

RETURNS DESCRIPTION
float

the memory in MBs

Source code in emu_mps/mps.py
def get_memory_footprint(self) -> float:
"""
Returns the number of MBs of memory occupied to store the state
Returns:
the memory in MBs
"""
return ( # type: ignore[no-any-return]
sum(factor.element_size() * factor.numel() for factor in self.factors) * 1e-6
)

Compute the inner product between this state and other. Note that self is the left state in the inner product, so this function is linear in other, and anti-linear in self

PARAMETER DESCRIPTION
other

the other state

TYPE: State

RETURNS DESCRIPTION
float | complex

inner product

Source code in emu_mps/mps.py
def inner(self, other: State) -> float | complex:
"""
Compute the inner product between this state and other.
Note that self is the left state in the inner product,
so this function is linear in other, and anti-linear in self
Args:
other: the other state
Returns:
inner product
"""
assert isinstance(other, MPS), "Other state also needs to be an MPS"
assert (
self.num_sites == other.num_sites
), "States do not have the same number of sites"
acc = torch.ones(1, 1, dtype=self.factors[0].dtype, device=self.factors[0].device)
for i in range(self.num_sites):
acc = acc.to(self.factors[i].device)
acc = torch.tensordot(acc, other.factors[i].to(acc.device), dims=1)
acc = torch.tensordot(self.factors[i].conj(), acc, dims=([0, 1], [0, 1]))
return acc.item() # type: ignore[no-any-return]

make(num_sites, config=None, num_gpus_to_use=DEVICE_COUNT) classmethod

Section titled “ make(num_sites, config=None, num_gpus_to_use=DEVICE_COUNT) classmethod ”

Returns a MPS in ground state |000..0>.

PARAMETER DESCRIPTION
num_sites

the number of qubits

TYPE: int

config

the MPSConfig

TYPE: Optional[MPSConfig] DEFAULT: None

num_gpus_to_use

distribute the factors over this many GPUs 0=all factors to cpu

TYPE: int DEFAULT: DEVICE_COUNT

Source code in emu_mps/mps.py
@classmethod
def make(
cls,
num_sites: int,
config: Optional[MPSConfig] = None,
num_gpus_to_use: int = DEVICE_COUNT,
) -> MPS:
"""
Returns a MPS in ground state |000..0>.
Args:
num_sites: the number of qubits
config: the MPSConfig
num_gpus_to_use: distribute the factors over this many GPUs
0=all factors to cpu
"""
config = config if config is not None else MPSConfig()
if num_sites <= 1:
raise ValueError("For 1 qubit states, do state vector")
return cls(
[
torch.tensor([[[1.0], [0.0]]], dtype=torch.complex128)
for _ in range(num_sites)
],
config=config,
num_gpus_to_use=num_gpus_to_use,
orthogonality_center=0, # Arbitrary: every qubit is an orthogonality center.
)

Computes the norm of the MPS.

Source code in emu_mps/mps.py
def norm(self) -> float:
"""Computes the norm of the MPS."""
orthogonality_center = (
self.orthogonality_center
if self.orthogonality_center is not None
else self.orthogonalize(0)
)
return float(
torch.linalg.norm(self.factors[orthogonality_center].to("cpu")).item()
)

orthogonalize(desired_orthogonality_center=0)

Section titled “ orthogonalize(desired_orthogonality_center=0) ”

Orthogonalize the state on the given orthogonality center.

Returns the new orthogonality center index as an integer, this is convenient for type-checking purposes.

Source code in emu_mps/mps.py
def orthogonalize(self, desired_orthogonality_center: int = 0) -> int:
"""
Orthogonalize the state on the given orthogonality center.
Returns the new orthogonality center index as an integer,
this is convenient for type-checking purposes.
"""
assert (
0 <= desired_orthogonality_center < self.num_sites
), f"Cannot move orthogonality center to nonexistent qubit #{desired_orthogonality_center}"
lr_swipe_start = (
self.orthogonality_center if self.orthogonality_center is not None else 0
)
for i in range(lr_swipe_start, desired_orthogonality_center):
q, r = torch.linalg.qr(self.factors[i].reshape(-1, self.factors[i].shape[2]))
self.factors[i] = q.reshape(self.factors[i].shape[0], 2, -1)
self.factors[i + 1] = torch.tensordot(
r.to(self.factors[i + 1].device), self.factors[i + 1], dims=1
)
rl_swipe_start = (
self.orthogonality_center
if self.orthogonality_center is not None
else (self.num_sites - 1)
)
for i in range(rl_swipe_start, desired_orthogonality_center, -1):
q, r = torch.linalg.qr(
self.factors[i].reshape(self.factors[i].shape[0], -1).mT,
)
self.factors[i] = q.mT.reshape(-1, 2, self.factors[i].shape[2])
self.factors[i - 1] = torch.tensordot(
self.factors[i - 1], r.to(self.factors[i - 1].device), ([2], [1])
)
self.orthogonality_center = desired_orthogonality_center
return desired_orthogonality_center

sample(num_shots, p_false_pos=0.0, p_false_neg=0.0)

Section titled “ sample(num_shots, 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: int

p_false_pos

the rate at which a 0 is read as a 1

TYPE: float DEFAULT: 0.0

p_false_neg

teh rate at which a 1 is read as a 0

TYPE: float DEFAULT: 0.0

RETURNS DESCRIPTION
Counter[str]

the measured bitstrings, by count

Source code in emu_mps/mps.py
def sample(
self, num_shots: int, 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
"""
self.orthogonalize(0)
rnd_matrix = torch.rand(num_shots, self.num_sites).to(self.factors[0].device)
bitstrings: Counter[str] = Counter()
# Shots are performed in batches.
# Larger max_batch_size is faster but uses more memory.
max_batch_size = 32
shots_done = 0
while shots_done < num_shots:
batch_size = min(max_batch_size, num_shots - shots_done)
batched_accumulator = torch.ones(
batch_size, 1, dtype=torch.complex128, device=self.factors[0].device
)
batch_outcomes = torch.empty(batch_size, self.num_sites, dtype=torch.bool)
for qubit, factor in enumerate(self.factors):
batched_accumulator = torch.tensordot(
batched_accumulator.to(factor.device), factor, dims=1
)
# Probability of measuring qubit == 0 for each shot in the batch
probas = (
torch.linalg.vector_norm(batched_accumulator[:, 0, :], dim=1) ** 2
)
outcomes = (
rnd_matrix[shots_done : shots_done + batch_size, qubit].to(
factor.device
)
> probas
)
batch_outcomes[:, qubit] = outcomes
# Batch collapse qubit
tmp = torch.stack((~outcomes, outcomes), dim=1).to(dtype=torch.complex128)
batched_accumulator = (
torch.tensordot(batched_accumulator, tmp, dims=([1], [1]))
.diagonal(dim1=0, dim2=2)
.transpose(1, 0)
)
batched_accumulator /= torch.sqrt(
(~outcomes) * probas + outcomes * (1 - probas)
).unsqueeze(1)
shots_done += batch_size
for outcome in batch_outcomes:
bitstrings.update(["".join("0" if x == 0 else "1" for x in outcome)])
if p_false_neg > 0 or p_false_pos > 0:
bitstrings = apply_measurement_errors(
bitstrings,
p_false_pos=p_false_pos,
p_false_neg=p_false_neg,
)
return bitstrings

SVD based truncation of the state. Puts the orthogonality center at the first qubit. Calls orthogonalize on the last qubit, and then sweeps a series of SVDs right-left. Uses self.config for determining accuracy. An in-place operation.

Source code in emu_mps/mps.py
def truncate(self) -> None:
"""
SVD based truncation of the state. Puts the orthogonality center at the first qubit.
Calls orthogonalize on the last qubit, and then sweeps a series of SVDs right-left.
Uses self.config for determining accuracy.
An in-place operation.
"""
self.orthogonalize(self.num_sites - 1)
truncate_impl(self.factors, config=self.config)
self.orthogonality_center = 0

Wrapper around MPS.inner.

PARAMETER DESCRIPTION
left

the anti-linear argument

TYPE: MPS

right

the linear argument

TYPE: MPS

RETURNS DESCRIPTION
float | complex

the inner product

Source code in emu_mps/mps.py
def inner(left: MPS, right: MPS) -> float | complex:
"""
Wrapper around MPS.inner.
Args:
left: the anti-linear argument
right: the linear argument
Returns:
the inner product
"""
return left.inner(right)

Bases: Operator

Matrix Product Operator.

Each tensor has 4 dimensions ordered as such: (left bond, output, input, right bond).

PARAMETER DESCRIPTION
factors

the tensors making up the MPO

TYPE: List[Tensor]

Source code in emu_mps/mpo.py
def __init__(
self, factors: List[torch.Tensor], /, num_gpus_to_use: Optional[int] = None
):
self.factors = factors
self.num_sites = len(factors)
if not self.num_sites > 1:
raise ValueError("For 1 qubit states, do state vector")
if factors[0].shape[0] != 1 or factors[-1].shape[-1] != 1:
raise ValueError(
"The dimension of the left (right) link of the first (last) tensor should be 1"
)
assert all(
factors[i - 1].shape[-1] == factors[i].shape[0]
for i in range(1, self.num_sites)
)
if num_gpus_to_use is not None:
assign_devices(self.factors, min(DEVICE_COUNT, num_gpus_to_use))

Returns the sum of two MPOs, computed with a direct algorithm. The result is currently not truncated

PARAMETER DESCRIPTION
other

the other operator

TYPE: Operator

RETURNS DESCRIPTION
MPO

the summed operator

Source code in emu_mps/mpo.py
def __add__(self, other: Operator) -> MPO:
"""
Returns the sum of two MPOs, computed with a direct algorithm.
The result is currently not truncated
Args:
other: the other operator
Returns:
the summed operator
"""
assert isinstance(other, MPO), "MPO can only be added to another MPO"
sum_factors = add_factors(self.factors, other.factors)
return MPO(sum_factors)

Compose two operators. The ordering is that self is applied after other.

PARAMETER DESCRIPTION
other

the operator to compose with self

TYPE: Operator

RETURNS DESCRIPTION
MPO

the composed operator

Source code in emu_mps/mpo.py
def __matmul__(self, other: Operator) -> MPO:
"""
Compose two operators. The ordering is that
self is applied after other.
Args:
other: the operator to compose with self
Returns:
the composed operator
"""
assert isinstance(other, MPO), "MPO can only be applied to another MPO"
factors = zip_right(self.factors, other.factors)
return MPO(factors)

Applies this MPO to the given MPS. The returned MPS is:

- othogonal on the first site
- truncated up to `other.precision`
- distributed on the same devices of `other`
PARAMETER DESCRIPTION
other

the state to apply this operator to

TYPE: State

RETURNS DESCRIPTION
MPS

the resulting state

Source code in emu_mps/mpo.py
def __mul__(self, other: State) -> MPS:
"""
Applies this MPO to the given MPS.
The returned MPS is:
- othogonal on the first site
- truncated up to `other.precision`
- distributed on the same devices of `other`
Args:
other: the state to apply this operator to
Returns:
the resulting state
"""
assert isinstance(other, MPS), "MPO can only be multiplied with MPS"
factors = zip_right(
self.factors,
other.factors,
config=other.config,
)
return MPS(factors, orthogonality_center=0)

Multiply an MPO by scalar. Assumes the orthogonal centre is on the first factor.

PARAMETER DESCRIPTION
scalar

the scale factor to multiply with

TYPE: complex

RETURNS DESCRIPTION
MPO

the scaled MPO

Source code in emu_mps/mpo.py
def __rmul__(self, scalar: complex) -> MPO:
"""
Multiply an MPO by scalar.
Assumes the orthogonal centre is on the first factor.
Args:
scalar: the scale factor to multiply with
Returns:
the scaled MPO
"""
factors = scale_factors(self.factors, scalar, which=0)
return MPO(factors)

Compute the expectation value of self on the given state.

PARAMETER DESCRIPTION
state

the state with which to compute

TYPE: State

RETURNS DESCRIPTION
float | complex

the expectation

Source code in emu_mps/mpo.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, MPS
), "currently, only expectation values of MPSs are \
supported"
acc = torch.ones(
1, 1, 1, dtype=state.factors[0].dtype, device=state.factors[0].device
)
n = len(self.factors) - 1
for i in range(n):
acc = new_left_bath(acc, state.factors[i], self.factors[i]).to(
state.factors[i + 1].device
)
acc = new_left_bath(acc, state.factors[n], self.factors[n])
return acc.item() # type: ignore [no-any-return]

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: Iterable[str]

nqubits

how many qubits there are in the state

TYPE: int

operations

which bitstrings make up the state with what weight

TYPE: FullOp

operators

additional symbols to be used in operations

TYPE: dict[str, QuditOp] DEFAULT: {}

RETURNS DESCRIPTION
MPO

the operator in MPO form.

Source code in emu_mps/mpo.py
@staticmethod
def from_operator_string(
basis: Iterable[str],
nqubits: int,
operations: FullOp,
operators: dict[str, QuditOp] = {},
/,
**kwargs: Any,
) -> MPO:
"""
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.
"""
operators_with_tensors: dict[str, torch.Tensor | QuditOp] = dict(operators)
_validate_operator_targets(operations, nqubits)
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
).reshape(1, 2, 2, 1),
"gr": torch.tensor(
[[0.0, 0.0], [1.0, 0.0]], dtype=torch.complex128
).reshape(1, 2, 2, 1),
"rg": torch.tensor(
[[0.0, 1.0], [0.0, 0.0]], dtype=torch.complex128
).reshape(1, 2, 2, 1),
"rr": torch.tensor(
[[0.0, 0.0], [0.0, 1.0]], dtype=torch.complex128
).reshape(1, 2, 2, 1),
}
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
).reshape(1, 2, 2, 1),
"01": torch.tensor(
[[0.0, 0.0], [1.0, 0.0]], dtype=torch.complex128
).reshape(1, 2, 2, 1),
"10": torch.tensor(
[[0.0, 1.0], [0.0, 0.0]], dtype=torch.complex128
).reshape(1, 2, 2, 1),
"11": torch.tensor(
[[0.0, 0.0], [0.0, 1.0]], dtype=torch.complex128
).reshape(1, 2, 2, 1),
}
else:
raise ValueError("Unsupported basis provided")
mpos = []
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 tensor
def replace_operator_string(op: QuditOp | torch.Tensor) -> torch.Tensor:
if isinstance(op, torch.Tensor):
return op
result = torch.zeros(1, 2, 2, 1, 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
factors = [
torch.eye(2, 2, dtype=torch.complex128).reshape(1, 2, 2, 1)
] * nqubits
for op in tensorop:
factor = replace_operator_string(op[0])
for target_qubit in op[1]:
factors[target_qubit] = factor
mpos.append(coeff * MPO(factors, **kwargs))
return sum(mpos[1:], start=mpos[0])