Sum Hamiltonian terms on the full num_qubits-site tensor space.
LocalHamiltonian terms are embedded with to_full_hamiltonian, so
sites[0] is the first tensor factor and identities fill the remaining
sites. Full-domain Hamiltonian matrices are added as-is. All terms must
match a common Hilbert-space dimension (local_dim ** num_qubits for
locals, or the matrix size of bare terms).
Parameters:
-
hamiltonians
(list[Hamiltonian])
–
Non-empty list of Hamiltonian objects to sum.
-
num_qubits
(int)
–
Positive number of sites in the full system.
Returns:
-
NDArray[complexfloating]
–
Complex matrix of shape (d, d) equal to the sum of the (embedded)
-
NDArray[complexfloating]
–
terms, where d is the shared Hilbert-space dimension.
Raises:
-
ValueError
–
If LocalHamiltonian terms use mixed local_dim values,
if term dimensions disagree for the requested num_qubits, or if a
local term's sites do not fit in 0 .. num_qubits - 1.
-
AssertionError
–
If hamiltonians / num_qubits fail basic type and
positivity checks.
Examples:
Embed a single-site \(Z\) into a three-qubit chain and inspect the shape:
import numpy as np
from shadowsim.core import LocalHamiltonian
from shadowsim.core.combined_hamiltonian_matrix import combined_hamiltonian_matrix
local = LocalHamiltonian(np.diag([1.0, -1.0]), sites=[1], local_dim=2)
out = combined_hamiltonian_matrix([local], num_qubits=3)
print(out.shape)
Source code in shadowsim/core/combined_hamiltonian_matrix.py
| def combined_hamiltonian_matrix(
hamiltonians: list[Hamiltonian],
num_qubits: int,
) -> npt.NDArray[np.complexfloating]:
r"""Sum Hamiltonian terms on the full ``num_qubits``-site tensor space.
``LocalHamiltonian`` terms are embedded with ``to_full_hamiltonian``, so
``sites[0]`` is the first tensor factor and identities fill the remaining
sites. Full-domain ``Hamiltonian`` matrices are added as-is. All terms must
match a common Hilbert-space dimension (``local_dim ** num_qubits`` for
locals, or the matrix size of bare terms).
Args:
hamiltonians: Non-empty list of ``Hamiltonian`` objects to sum.
num_qubits: Positive number of sites in the full system.
Returns:
Complex matrix of shape ``(d, d)`` equal to the sum of the (embedded)
terms, where ``d`` is the shared Hilbert-space dimension.
Raises:
ValueError: If ``LocalHamiltonian`` terms use mixed ``local_dim`` values,
if term dimensions disagree for the requested ``num_qubits``, or if a
local term's sites do not fit in ``0 .. num_qubits - 1``.
AssertionError: If ``hamiltonians`` / ``num_qubits`` fail basic type and
positivity checks.
Examples:
Embed a single-site \(Z\) into a three-qubit chain and inspect the shape:
```python exec="1" source="above" result="text"
import numpy as np
from shadowsim.core import LocalHamiltonian
from shadowsim.core.combined_hamiltonian_matrix import combined_hamiltonian_matrix
local = LocalHamiltonian(np.diag([1.0, -1.0]), sites=[1], local_dim=2)
out = combined_hamiltonian_matrix([local], num_qubits=3)
print(out.shape)
```
"""
assert isinstance(hamiltonians, list), "hamiltonians must be a list"
assert all(isinstance(h, Hamiltonian) for h in hamiltonians), "all hamiltonians must be Hamiltonian objects"
assert isinstance(num_qubits, int), "num_qubits must be an integer"
assert num_qubits > 0, "num_qubits must be a positive integer"
assert len(hamiltonians) > 0, "hamiltonians must be a non-empty list"
local_dims = {h.local_dim for h in hamiltonians if isinstance(h, LocalHamiltonian)}
if len(local_dims) > 1:
raise ValueError(f"mixed local_dim in LocalHamiltonian terms is not supported: {sorted(local_dims)}")
target_dim: int | None = None
for h in hamiltonians:
if isinstance(h, LocalHamiltonian):
d = h.local_dim**num_qubits
else:
d = int(np.asarray(h.matrix).shape[0])
if target_dim is None:
target_dim = d
elif d != target_dim:
raise ValueError(f"Hamiltonian dimensions disagree: got {d} vs {target_dim}")
assert target_dim is not None, "hamiltonians must be a non-empty list"
H_tot = np.zeros((target_dim, target_dim), dtype=np.complex128)
for h in hamiltonians:
if isinstance(h, LocalHamiltonian):
H_tot += h.to_full_hamiltonian(num_qubits).matrix
else:
H_tot += np.asarray(h.matrix, dtype=np.complex128)
return H_tot
|