Top-level Functions

This section documents the public functions available at the top level (i.e., importable directly via from ttheom import ...).

High-level simulation interface

prepareTTs(**kwargs)[source]

Build and initialize the tensor-train data structures for a simulation.

Parameters:

fileNamestr: Base name for the output CSV file.
directorystr or None, optional: Output directory.
qcqiskit.QuantumCircuit: Quantum circuit to be simulated.
numQint: Number of qubits.
freqQlist of float: Qubit frequencies in GHz.
rhoIninumpy.ndarray: Initial density matrix of shape (2**numQ, 2**numQ).
gateTimelist of float: Gate times in ns.
idlingTimefloat: Idling time in ns.
Tfloat or list of float: Temperature(s) in mK.
T1float or list of float: Energy-relaxation time(s) in µs.
omegaCfloat or list of float: Bath cutoff frequency(ies).
expfloat or list of float: Spectral-density exponent(s).
tolfloat or list of float: AAA tolerance(s) for the bath decomposition.
dtFBfloat: Integration time step in ps.
depthlist of int: FP-HEOM hierarchy depths, one per qubit.
bondDimint: Maximum MPS bond dimension.
strideTimefloat: Time between successive outputs in ns.
useRFPlusbool, optional: Use the Redfield+ method. Default False.
isRK13bool, optional: Use the 13-stage Runge-Kutta scheme. Default False.

Returns:

TTsTTs.TTs: Initialized MPS/MPO object with compiled pulse sequences.
paramsdict: Simulation parameter dictionary (saved to the qpy file metadata).

calcTimeEvo(**kwargs)[source]

Build the TT structure and run the full time evolution.

Parameters:

fileNamestr: Base name for the output CSV file.
directorystr or None, optional: Output directory.
qcqiskit.QuantumCircuit: Quantum circuit to be simulated.
numQint: Number of qubits.
freqQlist of float: Qubit frequencies in GHz.
rhoIninumpy.ndarray: Initial density matrix of shape (2**numQ, 2**numQ).
gateTimelist of float: Gate times in ns.
idlingTimefloat: Idling time in ns.
Tfloat or list of float: Temperature(s) in mK.
T1float or list of float: Energy-relaxation time(s) in µs.
omegaCfloat or list of float: Bath cutoff frequency(ies).
expfloat or list of float: Spectral-density exponent(s).
tolfloat or list of float: AAA tolerance(s) for the bath decomposition.
dtFBfloat: Integration time step in ps.
depthlist of int: FP-HEOM hierarchy depths, one per qubit.
bondDimint: Maximum MPS bond dimension.
strideTimefloat: Time between successive outputs in ns.
useRFPlusbool, optional: Use the Redfield+ method. Default False.
isRK13bool, optional: Use the 13-stage Runge-Kutta scheme. Default False.

calcTimeEvoHPC(submissionParams, **kwargs)[source]

Build the TT structure and submit the full time evolution to HPC.

Parameters:

submissionParamsdict: Submission parameters for the HPC job. User will be prompted to provide OTP.
fileNamestr: Base name for the output CSV file.
directorystr or None, optional: Output directory.
qcqiskit.QuantumCircuit: Quantum circuit to be simulated.
numQint: Number of qubits.
freqQlist of float: Qubit frequencies in GHz.
rhoIninumpy.ndarray: Initial density matrix of shape (2**numQ, 2**numQ).
gateTimelist of float: Gate times in ns.
idlingTimefloat: Idling time in ns.
Tfloat or list of float: Temperature(s) in mK.
T1float or list of float: Energy-relaxation time(s) in µs.
omegaCfloat or list of float: Bath cutoff frequency(ies).
expfloat or list of float: Spectral-density exponent(s).
tolfloat or list of float: AAA tolerance(s) for the bath decomposition.
dtFBfloat: Integration time step in ps.
depthlist of int: FP-HEOM hierarchy depths, one per qubit.
bondDimint: Maximum MPS bond dimension.
strideTimefloat: Time between successive outputs in ns.
useRFPlusbool, optional: Use the Redfield+ method. Default False.
isRK13bool, optional: Use the 13-stage Runge-Kutta scheme. Default False.

Returns:

jobIDstr or int: The job ID returned from the HPC submission.

Physical-unit helpers

prepareParams(**kwargs)[source]

Assemble all internal arguments needed to build the TT structure.

Parameters:

numQint: Number of qubits.
freqQlist of float: Qubit frequencies in GHz.
gateTimelist of float: Gate times in ns.
Tfloat or list of float: Temperature(s) in mK.
T1float or list of float: Energy-relaxation time(s) in µs.
omegaCfloat or list of float: Bath cutoff frequency(ies).
expfloat or list of float: Spectral-density exponent(s).
tolfloat or list of float: AAA tolerance(s).
rhoIninumpy.ndarray: Initial density matrix.
idlingTimefloat: Idling time in ns.
dtFBfloat: Integration time step in fs.
depthlist of int: FP-HEOM hierarchy depths.
bondDimint: Maximum MPS bond dimension.

Returns:

paramsdict: Internal parameter dictionary with keys 'omegaQmax', 'rho', 'gateList', 'idlingTime', 'bath', 'dtFB', 'depth', 'bondDim', 'stride', 'isRK13', 'useRFPlus', and 'V'.

prepareSystemParams(numQ, freqQ, rhoIni, gateTime, idlingTime)[source]

Build the system dictionary and normalize qubit frequencies.

Parameters:

numQint: Number of qubits.
freqQlist of float: Qubit frequencies in GHz.
rhoIninumpy.ndarray, optional: Initial density matrix of shape (2**numQ, 2**numQ). Defaults to the ground state |0><0|.
idlingTimefloat, optional: Idling time (unused; reserved for future use).
gateTimelist of float, optional: Gate times (unused; reserved for future use).

Returns:

omegaQmaxfloat: Maximum qubit angular frequency (rad/ns).
rhodict: System dictionary with keys 'numQ', 'rhoIni', 'omegaQ'.

prepareBathParams(rho, omegaQmax, T, T1, omegaC, exp, tol)[source]

Convert physical bath parameters to the internal bath dictionary format.

Parameters:

rhodict: System dictionary; rho['numQ'] gives the number of qubits.
omegaQmaxfloat: Maximum qubit angular frequency (GHz), used for unit conversion.
Tfloat or list of float: Temperature(s) in mK.
T1float or list of float: Energy-relaxation time(s) in µs.
omegaCfloat or list of float: Bath cutoff frequency(ies).
expfloat or list of float: Spectral-density exponent(s).
tolfloat or list of float: AAA tolerance(s) for the bath decomposition.

Returns:

bathlist of dict: List of bath parameter dictionaries, one per qubit.

getKwargs(directory, fileName)[source]

Reconstruct user-facing simulation kwargs from a saved QPY file.

Parameters:

directorystr: Directory containing the QPY file.
fileNamestr: Base name of the file (without extension).

Returns:

kwargsdict: Parameter dictionary in physical units with keys 'directory', 'fileName', 'numQ', 'freqQ', 'rhoIni', 'gateTime', 'idlingTime', 'T', 'T1', 'omegaC', 'exp', 'tol', 'dtFB', 'depth', 'bondDim', 'strideTime', 'useRFPlus', 'isRK13', and 'qc'.

getSystemKwargs(rho, omegaQmax, gateList, idlingTime)[source]

Convert internal system parameters back to physical units.

Parameters:

omegaQmaxfloat: Maximum qubit angular frequency (rad/ns).
rhodict: Internal system dictionary with keys 'numQ', 'omegaQ', 'rhoReal', 'rhoImag'.

Returns:

numQint: Number of qubits.
freqQlist of float: Qubit frequencies in GHz.
rhoIninumpy.ndarray: Initial density matrix (complex).

getBathKwargs(omegaQmax, bath)[source]

Convert internal bath parameters back to physical units.

Parameters:

omegaQmaxfloat: Maximum qubit angular frequency (rad/ns).
bathlist of dict: List of internal bath parameter dictionaries.

Returns:

Tnumpy.ndarray: Temperatures in mK.
T1numpy.ndarray: Energy-relaxation times in µs.
omegaClist: Cutoff frequencies.
explist: Spectral-density exponents.
tollist: AAA tolerances.

I/O utilities

saveQC(qcFilePath, qc, params)[source]

Serialise a quantum circuit and its simulation parameters to a QPY file.

Parameters:

qcFilePathstr: Destination file path (should end in .qpy).
qcqiskit.QuantumCircuit: Circuit to save.
paramsdict: Internal parameter dictionary produced by prepareParams.

Returns:

metadatadict: The metadata dict that was stored in qc.metadata.

loadQC(qcFilePath)[source]

Load a quantum circuit and its simulation parameters from a QPY file.

Parameters:

qcFilePathstr: Path to the QPY file written by saveQC.

Returns:

qcqiskit.QuantumCircuit: The deserialized quantum circuit.
paramsdict: Internal parameter dictionary with 'rhoIni' and 'V' reconstructed as complex NumPy arrays.

getResult(directory, fileName)[source]

Load simulation results from a saved CSV file.

Parameters:

directorystr: Directory containing the CSV file.
fileNamestr: Base name of the file (without extension).

Returns:

resultsnumpy.ndarray: Array of shape (numSteps, 2**numQ, 2**numQ) containing the reduced density matrices at each time step.

loadCSV(csvFilePath)[source]

Load timesteps and density matrices from a CSV file.

Parameters:

csvFilePathstr: Path to the CSV file. The first column is time; the remaining columns hold real and imaginary parts of the density-matrix entries in row-major order (alternating real, imaginary).

Returns:

timesnumpy.ndarray: 1-D array of time points.
rhoslist of numpy.ndarray: List of density matrices, one per time step.

Bath decomposition

getBathParams(bathParams)[source]

Compute the pole–residue decomposition of a bath correlation function for FP-HEOM.

The bath correlation function is assumed to admit an exponential decomposition of the form

\[\begin{split}\begin{aligned} C(t) &= \langle X(t) X(0) \rangle_R, \\[4pt] C(t) &= \sum_{k=1}^{K} d_k\, e^{-z_k t}, \end{aligned}\end{split}\]

where \(z_k\) and \(d_k\) denote the complex decay rates and coefficients, respectively.

This routine samples the bath spectral function on a symmetric logarithmic frequency grid, constructs a rational approximation using the AAA algorithm, and converts the resulting poles and residues into the \((z_k, d_k)\) representation required by FP-HEOM.

Currently, the bath spectral function is constructed for the "broadband" bath type via broadbandNoise.

Parameters:

bathParamsdict

Bath parameter dictionary. Required keys:

'type' (str): Bath type identifier. Currently supports 'broadband'.
'tol' (float): Tolerance passed to the AAA algorithm.

Additional keys may be required depending on bathParams['type'] (e.g., broadband noise parameters used by broadbandNoise).

Returns:

nunumpy.ndarray: Complex frequencies \(z_k\) (derived from the AAA poles).
coeffnumpy.ndarray: Complex coefficients \(d_k\) (derived from the AAA residues).

Notes

A symmetric grid \(x \in [-10^{3}, -10^{-6}] \cup [10^{-6}, 10^{3}]\) with NUM_SAMPLE = 80000 is used.
Only poles with negative imaginary part are retained before the FP-HEOM mapping.

The mapping applied is:

nu    = -1j * pol
coeff = -2j * np.pi * res

Examples

>>> bathParams = {'type': 'broadband', 'beta':5, 'kappa':0.004 / 2 / np.pi, 'omegaC':50, 'exp':1, 'tol':1e-6}
>>> z, d = getBathParams(bathParams)

broadbandNoise(bathParams, x)[source]

Compute the broadband spectral noise power \(S(\omega)\).

The bath noise spectrum \(S(\omega)\) is defined as

\[S(\omega) = J(\omega)\,[1 + n(\omega)].\]

Here \(n(\omega)\) denotes the Bose–Einstein distribution

\[n(\omega) = \frac{1}{e^{\beta \omega} - 1},\]

and \(J(\omega)\) denotes the broadband spectral density

\[J(\omega) = \operatorname{sgn}(\omega)\, \frac{\kappa\,|\omega|^{s}}{\left[1 + \left(\omega/\omega_c\right)^2\right]^2}.\]

Parameters:

bathParamsdict

Bath parameters with the following keys:

'beta' (float): Inverse temperature \(\beta\).
'omegaC' (float): Cutoff frequency \(\omega_c\).
'kappa' (float): Coupling strength \(\kappa\).
'exp' (float): Spectral exponent \(s\).

xnumpy.ndarray

Frequency points \(\omega\) at which \(S(\omega)\) is evaluated.

Returns:

numpy.ndarray: Spectral noise power \(S(\omega)\) evaluated at x.

Examples

>>> bathParams = {'beta':5, 'kappa':0.004 / 2 / np.pi, 'omegaC':50, 'exp':1}
>>> w = np.linspace(0.0, 50.0, 2000)
>>> S = broadbandNoise(bathParams, w)

Evaluation and analysis

getFidelity(rho, sigma)[source]

Compute the quantum state fidelity between two density matrices.

Parameters:

rhonumpy.ndarray: Density matrix; Hermitian, positive semidefinite.
sigmanumpy.ndarray: Density matrix; Hermitian, positive semidefinite.

Returns:

float: Fidelity \(F(\rho, \sigma) = \left(\operatorname{tr}\sqrt{\sqrt{\rho}\,\sigma\sqrt{\rho}}\right)^2\).

getConcurrence(rho)[source]

Compute the concurrence of a two-qubit density matrix.

Parameters:

rhonumpy.ndarray: Two-qubit density matrix of shape (4, 4); Hermitian, positive semidefinite.

Returns:

float: Concurrence \(C(\rho) \in [0, 1]\), where 0 means separable and 1 means maximally entangled.

getLogarithmicNegativity(rho, transposeQIdx)[source]

Compute the logarithmic negativity of a multi-qubit density matrix.

Parameters:

rhonumpy.ndarray: Density matrix of shape (2**N, 2**N). Row/column ordering: qubit N-1 is the most significant index, qubit 0 is the least significant.
transposeQIdxlist of int: Indices of qubits on which the partial transpose is performed.

Returns:

float: Logarithmic negativity \(E_N(\rho) = \log_2 \|\rho^{T_A}\|_1\).

plotPulseSeq(fig=None, ax=None, **kwargs)[source]

Plot the pulse sequences for the transpiled quantum circuit.

Displays Rabi frequency, phase, and interaction strength for each qubit (and each qubit pair for multi-qubit systems).

Parameters:

figmatplotlib.figure.Figure, optional: Existing figure to draw into. If None, a new figure is created.
axmatplotlib.axes.Axes or numpy.ndarray of Axes, optional: Existing axes to draw into. If None, new axes are created.
**kwargs: Keyword arguments forwarded to prepareTTs.

Returns:

figmatplotlib.figure.Figure: The figure object.
axnumpy.ndarray of matplotlib.axes.Axes: The axes objects for the subplots.

plotRDO(t_list, rdo_list, **kwargs)[source]

Plot all elements of the reduced density matrix over time.

Parameters:

t_listnumpy.ndarray: 1-D array of time points (in internal units; converted to ns using freqQ from kwargs).
rdo_listlist of numpy.ndarray: List of density matrices, one per time step.
**kwargs: Must contain "freqQ" (list of qubit frequencies in GHz). All other keys are ignored.

Returns:

figmatplotlib.figure.Figure: The figure object.
axesnumpy.ndarray of matplotlib.axes.Axes: 2-D array of axes with shape (dim, dim).

plotQC(**kwargs)[source]

Plot the Qiskit quantum circuit stored in kwargs.

Parameters:

**kwargs: Must contain "qc" (a qiskit.QuantumCircuit).

Returns:

figmatplotlib.figure.Figure: The figure object.
axmatplotlib.axes.Axes: The axes containing the circuit diagram.

Raises:

ValueError: If "qc" is not present in kwargs.