Classes & Module Functions

This section documents internal classes and module-level functions, grouped by subsystem.

Pulse types and gate specifications

setGates(gateList)

Create pulse instances for all qubit gates in the gate list.

Parameters:

gateListlist

Input list of gate specifications. Each element is a 3-item list:

gateList[i][0]list of int

Qubit indices the gate acts on.

gateList[i][1]str

Gate name (e.g. 'rxyStep', 'directCplStepVarJ').

gateList[i][2]dict

Keyword arguments passed to the pulse constructor.

Returns:

pulselist

List of [qubit_indices, pulse_instance] pairs.

pulseMapdict

Mapping from sorted qubit-index tuples to pulse list indices.

Parameters:

gateList (list)

Return type:

tuple[list, dict]

getGate(pulseName, kwargs)

Instantiate a pulse object by name.

Parameters:

pulseNamestr

Name of the pulse class (e.g. 'rxyStep').

kwargsdict

Keyword arguments forwarded to the pulse constructor.

Returns:

abstractPulse

Instantiated pulse object.

Raises:

ValueError

If pulseName is not a supported gate type.

Parameters:

• pulseName (str)

• kwargs (dict)

class rxyStep(**kwargs)

Bases: U3Pulse

Single-qubit pulse with abrupt (step-function) amplitude changes.

Implements the abstractPulse interface using a U3-gate decomposition.

Attributes:

ampfloat

Pulse amplitude (rad per time unit).

omegafloat

Drive frequency (rad per time unit).

gateTimefloat

Gate time for an \(R_x(\pi)\) rotation.

ampSeqnumpy.ndarray

Time sequence of pulse amplitudes.

phaseSeqnumpy.ndarray

Time sequence of pulse phases.

getGateTime(dt, params)

Return the gate duration in units of dt.

Note

Call this method only after vzTransform has been applied.

Parameters:

dtfloat

Time step for HEOM integration.

paramslist

Gate parameters; params[0] is the rotation angle theta.

Returns:

int

Gate duration (number of time steps).

Parameters:

• dt (float)

• params (list)

Return type:

int

getPrefactor(dt, time, stepNum)

Compute the \(\sigma_x\) and \(\sigma_y\) prefactors.

Parameters:

dtfloat

Integration time step.

timefloat

Current time.

stepNumint

Current step number.

Returns:

preSXfloat

Prefactor for the \(\sigma_x\) term.

preSYfloat

Prefactor for the \(\sigma_y\) term.

Parameters:

• dt (float)

• time (float)

• stepNum (int)

Return type:

tuple[float, float]

initSeq(totalSize)

Allocate and zero-initialize the amplitude and phase sequences.

Parameters:

totalSizeint

Total number of time steps.

Parameters:

totalSize (int)

Return type:

None

setSeq(st, dur, params)

Set pulse values in the interval [st, st+dur).

The corresponding gate is assumed to be \(U_3(\theta, \phi, -\phi)\) after virtual-Z transformation.

Parameters:

stint

Starting time step.

durint

Duration in time steps.

paramslist

Gate parameters; params[0] is theta and params[1] is phi of the U3 gate.

Parameters:

• st (int)

• dur (int)

• params (list)

Return type:

None

class U3Pulse(**kwargs)

Bases: abstractPulse

Single-qubit pulse implemented as a U3 gate with virtual-Z transformation.

Applies a rotation in the x-y plane combined with a virtual Z gate.

cropPulse(en)

Trim the pulse sequences to length en.

Parameters:

enint

New end index (exclusive).

Return type:

None

elementalGates()

Return the elemental gate(s) used for circuit transpilation.

Returns:

list of qiskit.circuit.Instruction

A single-element list containing a parametric U3 gate.

Return type:

list[<MagicMock name=’mock.Instruction’ id=’139441689442960’>]

getEnPtr()

Return the index of the last non-zero element in the amplitude sequence.

Returns:

int

End pointer of the active pulse region.

Return type:

int

isDelayed(name)

Return whether an idling period should follow this gate.

Parameters:

namestr

Gate name ('u3').

Returns:

bool

Always True for U3 gates.

Parameters:

name (str)

Return type:

bool

vzTransform(params, globalPhase, localPhase, qubitIdx)

Apply the virtual-Z transformation to a U3 gate.

The transformation absorbs Z rotations into the gate phases:

\[U_3(\theta, \phi, \lambda)\, R_Z(a) = R_Z(c)\, U_3(\theta, -b, b)\, e^{i\varphi}\]

where \(b = \lambda + a\) and \(c = a + \phi + \lambda\).

Parameters:

paramslist of float

Gate parameters: [theta, phi, lam, gate_name].

globalPhasefloat

Accumulated global phase.

localPhaselist of float

Per-qubit accumulated local phases (rotation angles of RZ gates).

qubitIdxlist of int

Qubit indices to which the gate is applied.

Returns:

gateOutqiskit.circuit.Instruction

Transformed gate \(U_3(\theta, -b, b)\).

globalPhasefloat

Updated global phase.

localPhaselist of float

Updated per-qubit local phases.

Parameters:

• params (list[float])

• globalPhase (float)

• localPhase (list[float])

• qubitIdx (list[int])

Return type:

tuple[<MagicMock name=’mock.Instruction’ id=’139441689442960’>, float, float]

class iSwapDPulse(**kwargs)

Bases: abstractPulse

Pulse implementation for the iSWAP-dagger (complex conjugate of iSWAP) gate.

Attributes:

iSwapDqiskit.circuit.Gate

The iSWAP-dagger gate (with idling).

iSwapDSkipqiskit.circuit.Gate

The iSWAP-dagger gate (without idling).

elementalGates()

Return the list of elemental gate instructions.

Returns:

list of qiskit.circuit.Instruction

[iSwapD, iSwapDSkip].

Return type:

list[<MagicMock name=’mock.Instruction’ id=’139441689442960’>]

isDelayed(name)

Return whether an idling period should follow this gate.

Parameters:

namestr

Gate name ('iswapd' or 'iswapdskip').

Returns:

bool

True for 'iswapd', False for 'iswapdskip'.

Parameters:

name (str)

Return type:

bool

vzTransform(params, globalPhase, localPhase, qubitIdx)

Apply the virtual-Z transformation to an iSWAP-dagger gate.

The iSWAP-dagger gate swaps the local Z phases of the two qubits.

Parameters:

paramslist

Gate parameters; params[0] is the gate name ('iswapd' or 'iswapdskip').

globalPhasefloat

Accumulated global phase (unchanged by this gate).

localPhaselist of float

Per-qubit accumulated local phases; the phases of the two involved qubits are swapped.

qubitIdxlist of int

Qubit indices to which the gate is applied.

Returns:

gateOutqiskit.circuit.Instruction

The iSWAP-dagger gate instruction.

globalPhasefloat

Unchanged global phase.

localPhaselist of float

Updated per-qubit local phases (two entries swapped).

Parameters:

• params (list)

• globalPhase (float)

• localPhase (list[float])

• qubitIdx (list[int])

Return type:

tuple[<MagicMock name=’mock.Instruction’ id=’139441689442960’>, float, list[float]]

class directCplStepVarJ(**kwargs)

Bases: iSwapDPulse

Two-qubit pulse with abrupt (step-function) coupling strength changes.

Implements direct qubit-qubit coupling with a variable coupling strength, using the iSWAP-dagger gate as the elemental two-qubit operation.

Attributes:

ampfloat

Pulse amplitude (rad per time unit).

gateTimefloat

Gate time of the \(XX+YY(\pi)\) (= iSWAP-dagger) operation.

JSeqnumpy.ndarray

Time sequence of coupling strengths between qubits.

cropPulse(en)

Trim the coupling sequence to length en.

Parameters:

enint

New end index (exclusive).

Return type:

None

getEnPtr()

Return the index of the last non-zero element in the coupling sequence.

Returns:

int

End pointer of the active pulse region.

Return type:

int

getGateTime(dt, params)

Return the gate duration in units of dt.

Parameters:

dtfloat

Time step for HEOM integration.

paramslist

Gate parameters (unused for this gate type).

Returns:

int

Gate duration (number of time steps).

Parameters:

• dt (float)

• params (list)

Return type:

int

getPrefactor(dt, time, stepNum)

Compute the coupling prefactor for the Runge-Kutta update.

Parameters:

dtfloat

Integration time step.

timefloat

Current time.

stepNumint

Current step number.

Returns:

float

Prefactor for the qubit-qubit coupling term.

Parameters:

dt (float)

Return type:

float

initSeq(totalSize)

Allocate and zero-initialize the coupling-strength sequence.

Parameters:

totalSizeint

Total number of time steps.

Parameters:

totalSize (int)

Return type:

None

setOmegaQ(seqSize, omegaQ)

Return the qubit-frequency profiles during the two-qubit gate.

Both qubits are tuned to the lower of the two qubit frequencies.

Parameters:

seqSizeint

Number of time steps.

omegaQlist of float

Qubit frequencies of the two involved qubits.

Returns:

omegaQSeq0numpy.ndarray

Frequency profile of the first qubit.

omegaQSeq1numpy.ndarray

Frequency profile of the second qubit.

Parameters:

• seqSize (int)

• omegaQ (list[float])

Return type:

tuple[ndarray, ndarray]

setSeq(st, dur, params)

Set the coupling-strength sequence in the interval [st, st+dur).

Parameters:

stint

Starting time step.

durint

Duration in time steps.

paramslist

Gate parameters (unused for this gate type).

Parameters:

• st (int)

• dur (int)

• params (list)

Return type:

None

Tensor-train representation

class TTs(depth)

Bases: ABC

Abstract base class for the MPS/MPO tensor-train representation.

Attributes:

numQint

Number of qubits.

numCoreint

Number of tensor-train cores.

numHint

Number of partial Hamiltonian terms.

dimlist

Dimensions of the reservoir modes.

ptrKetlist

Pointers to the ket (row) indices of each spin.

ptrBralist

Pointers to the bra (column) indices of each spin.

rhonumpy.ndarray

1-D array of zTT cores representing the MPS.

Hnumpy.ndarray

2-D array of zTT cores representing the MPO.

omegaQSeqnumpy.ndarray

Time sequence of qubit frequencies.

pulselist

List of [qubit_indices, abstractPulse] pairs.

mapdict

Mapping from qubit-index tuples to pulse indices in self.pulse.

matVZnumpy.ndarray

Matrix representation of the virtual Z gates.

permMatnumpy.ndarray

Permutation matrix for qubit reordering.

shapeBathEye1list of tuple

Shapes of bond-dimension-1 identity MPO cores for the bath modes.

coreBathEye1list of numpy.ndarray

Bond-dimension-1 identity MPO cores for the bath modes.

shapeBathEye2list of tuple

Shapes of bond-dimension-2 identity MPO cores for the bath modes.

coreBathEye2list of numpy.ndarray

Bond-dimension-2 identity MPO cores for the bath modes.

shapeBathEye3list of tuple

Shapes of bond-dimension-3 identity MPO cores for the bath modes.

coreBathEye3list of numpy.ndarray

Bond-dimension-3 identity MPO cores for the bath modes.

abstractmethod getPrefactors(dt, time, stepNum)

Parameters:

• dt (float)

• time (float)

• stepNum (int)

abstractmethod getRDO()

getRhoBondDims(levels, bondDim)

Compute the bond dimensions for each MPS core.

Parameters:

levelsnumpy.ndarray

1-D array of local Hilbert-space dimensions for each core.

bondDimint

Maximum allowed bond dimension.

Returns:

rhoBondDimsnumpy.ndarray

2-D array of shape (numCore, 2) with left and right bond dimensions for each core.

setBathMPO(depth, nu, coeff, sysIdx, HIdx)

Build and store MPO cores for the system-bath interaction.

Parameters:

depthint

Maximum FP-HEOM hierarchy depth for this bath.

nunumpy.ndarray

Poles of the bath correlation function decomposition.

coeffnumpy.ndarray

Residues of the bath correlation function decomposition.

sysIdxint

Index used to look up ptrKet and ptrBra for the system site.

HIdxint

Row index in self.H where the MPO cores will be stored.

setH(coreIn, TTOut)

Copy an MPO core array into a zTT object.

Parameters:

coreInnumpy.ndarray

4-D MPO core array of shape (bondDimL, level, level, bondDimR).

TTOuttt.zTT

Target MPO core object; overwritten in place.

setRefH(coreShape, coreFlattenIn, TTOut)

Set an MPO core by reference (no copy) from a flattened array.

Parameters:

coreShapetuple

Shape of the core before flattening, (bondDimL, level, level, bondDimR).

coreFlattenInnumpy.ndarray

Flattened MPO core data; assigned by reference.

TTOuttt.zTT

Target MPO core object; overwritten in place.

class TTsTwoLevelId(depth)

Bases: TTs

class for two-level systems (independent reservoir)

sysEye

identity operator for the system

Type:

numpy.ndarray

shape1QKet

shape of MPO core for single-qubit operator acting on ket vector

Type:

tuple

shape1QBra

shape of MPO core for single-qubit operator acting on bra vector

Type:

tuple

coreKetSX/Y/Z

MPO core for sigma_X/Y/Z acting on ket vector

Type:

numpy.ndarray

coreBraSX/Y/Z

MPO core for sigma_X/Y/Z acting on bra vector

Type:

numpy.ndarray

shapeJKet1

shape of MPO core for two-qubit operator acting on ket vector for one of the coupled qubit

Type:

tuple

shapeJKet2

shape of MPO core for two-qubit operator acting on ket vector for the other copuled qubit

Type:

tuple

shapeJBra1

shape of MPO core for two-qubit operator acting on bra vector for one of the coupled qubit

Type:

tuple

shapeJBra2

shape of MPO core for two-qubit operator acting on bra vector for the other copuled qubit

Type:

tuple

coreJKet1

MPO core for direct coupling acting on ket vector for one of the coupled qubit

Type:

numpy.ndarray

coreJKet2

MPO core for direct coupling acting on ket vector for the other coupled qubit

Type:

numpy.ndarray

coreJBra1

MPO core for direct coupling acting on bra vector for one of the coupled qubit

Type:

numpy.ndarray

coreJBra2

MPO core for direct coupling acting on bra vector for the other coupled qubit

Type:

numpy.ndarray

shapeSysEye1

shape of MPO core for identity operator acting on ket/bra vectors of system bond dimension = 1

Type:

tuple

coreSysEye1

MPO core for identity operator acting on ket/bra vectors of system bond dimension = 1

Type:

numpy.ndarray

getRDO()

compute reduced density matrix

Returns:

reduced density matrix,

1D array in row-major order

Return type:

rhoOut (numpy.ndarray)

class TTs1Q(rhoIni, bondDim, V, depth, nu, coeff, pulse, pulseMap)

Bases: TTsTwoLevelId

MPS and MPO for 1qubit systems

getPrefactors(dt, time, stepNum)

compute prefactor terms for Runge-Kutta update

Parameters:

• dt (float) – step size for Runge-Kutta integration

• time (float) – current time

• stepNum (int) – current step number of the integration

Returns:

prefactors corresponding to MPO

Return type:

numpy.ndarray

zGetMPO(V, depth, nu, coeff)

create MPO

Parameters:

• V (numpy.ndarray) – matrices for qubit-reservoir coupling (3d array)

• pol (list) – list of poles for FP-HEOM

• res (list) – list of residues for FP-HEOM

• depth (list) – 1d list of depth of hierarchy of FP-HEOM (from 0 to depth)

zGetMPS(rhoIni, bondDim, depth)

create MPS

Parameters:

• rhoIni (numpy.ndarray) – initial reduced density operator

• bondDim (int) – bondDimension of MPS

• depth (list) – 1d list of depth of hierarchy of FP-HEOM (from 0 to depth)

class TTs2QId(rhoIni, bondDim, V, depth, nu, coeff, pulse, pulseMap)

Bases: TTsTwoLevelId

MPS and MPO for 2qubit systems (independent reservoir)

getPrefactors(dt, time, stepNum)

compute prefactor terms for Runge-Kutta update

Parameters:

• dt (float) – step size for Runge-Kutta integration

• time (float) – current time

• stepNum (int) – current step number of the integration

Returns:

prefactors corresponding to MPO

Return type:

numpy.ndarray

zGetMPO(V, depth, nu, coeff)

create MPO

Parameters:

• omegaQ (numpy.ndarray) – 1d array of qubit frequency

• J (list) – list of coupling strength between two qubits

• V (numpy.ndarray) – matrices for qubit-reservoir coupling (3d array)

• pol (list) – list of poles for FP-HEOM

• res (list) – list of residues for FP-HEOM

• depth (list) – 1d list of depth of hierarchy of FP-HEOM (from 0 to depth)

zGetMPS(rhoIni, bondDim, depth)

create MPS

Parameters:

• rhoIni (numpy.ndarray) – initial reduced density operator

• bondDim (int) – bondDimension of MPS

• depth (list) – 1d list of depth of hierarchy of FP-HEOM (from 0 to depth)

class TTsMQChainId(numQ, rhoIni, bondDim, V, depth, nu, coeff, pulse, pulseMap)

Bases: TTsTwoLevelId

MPS and MPO for multi-qubit systems (independent reservoir) in the chain configuration

getPrefactors(dt, time, stepNum)

compute prefactor terms for Runge-Kutta update

Parameters:

• dt (float) – step size for Runge-Kutta integration

• time (float) – current time

• stepNum (int) – current step number of the integration

Returns:

prefactors corresponding to MPO

Return type:

numpy.ndarray

zGetMPO(V, depth, nu, coeff)

create MPO

Parameters:

• omegaQ (numpy.ndarray) – 1d array of qubit frequency

• J (list) – list of coupling strength between two qubits

• V (numpy.ndarray) – matrices for qubit-reservoir coupling (3d array)

• pol (list) – list of poles for FP-HEOM

• res (list) – list of residues for FP-HEOM

• depth (list) – 1d list of depth of hierarchy of FP-HEOM (from 0 to depth)

zGetMPS(rhoIni, bondDim, depth)

create MPS

Parameters:

• rhoIni (numpy.ndarray) – initial reduced density operator

• bondDim (int) – bondDimension of MPS

• depth (numpy.ndarray) – 1d array of depth of hierarchy of FP-HEOM (from 0 to depth)

Circuit compilation

setPulseSeq(qc, TTs, omegaQ, dtFB, idlingTime)

Compile a quantum circuit into pulse sequences and store them in TTs.

Parameters:

qcqiskit.QuantumCircuit

Quantum circuit to be simulated.

TTsTTs.TTs

MPS/MPO object; pulse sequences are written to its attributes.

omegaQlist of float

Qubit frequencies in units of the maximum qubit frequency.

dtFBfloat

Time step for HEOM integration in units of 1/omegaQ[0].

idlingTimefloat

Idling time inserted after delayed gates, in units of omegaQ[0].

Parameters:

• qc (<MagicMock name='mock.QuantumCircuit' id='139441689370768'>)

• TTs (TTs)

• omegaQ (list[float])

• dtFB (float)

• idlingTime (float)

Return type:

None

transform(qc, TTs)

transform a quantum circuit into a circuit consisting of ‘rx’, ‘ry’, and ‘xx_plus_yy’

Parameters:

• qc (qiskit.QuantumCircuit) – quantum circuit to be transformed

• TTs (TTs) – class for MPS and MPO

Returns:

quantum circuit consisting of

elemental gates defined in TTs

Return type:

qiskit.QuantumCircuit

scheduling(qc)

padding delay for synchronization scheduling method: ALAP

Parameters:

qc (qiskit.QuantumCircuit) – quantum circuit to be transformed

Returns:

quantum circuit with delay

Return type:

qcNew (qiskit.QuantumCircuit)

Time evolution

class timeEvolution(TTsIni, dt, isRK13)

Bases: object

Time evolution of the tensor-train density operator via TDVP.

Attributes:

dtfloat

Step width.

numCoreint

Number of cores.

segArraylist

Segment tensors used for updating each core.

ZNRKint

Number of stages in the Runge-Kutta scheme.

zAnumpy.ndarray

Runge-Kutta coefficient array A.

zBnumpy.ndarray

Runge-Kutta coefficient array B.

zCnumpy.ndarray

Runge-Kutta coefficient array C.

Parameters:

• TTsIni (TTs)

• dt (float)

• isRK13 (bool)

zInitSegment(TTsIni)

Initialize the segment tensors from the rightmost core.

Parameters:

TTsIniTTs.TTs

Initialized MPS and MPO.

Returns:

segArraylist

List of segment tensors used for updating each core.

Parameters:

TTsIni (TTs)

zKRK4(rho, H, coreIdx, time)

Apply the Runge-Kutta update to an intermediate core.

Parameters:

rhott.zTT

MPS core; overwritten in place.

Hnumpy.ndarray

Array of MPO cores.

coreIdxint

Index of the current core.

timefloat

Current time.

zKRK4En(rho, H, coreIdx, time)

Apply the Runge-Kutta update to the last (ending) core.

Parameters:

rhott.zTT

MPS core; overwritten in place.

Hnumpy.ndarray

Array of MPO cores.

coreIdxint

Index of the current core.

timefloat

Current time.

zKRK4St(rho, H, coreIdx, time)

Apply the Runge-Kutta update to the first (starting) core.

Parameters:

rhott.zTT

MPS core; overwritten in place.

Hnumpy.ndarray

Array of MPO cores.

coreIdxint

Index of the current core.

timefloat

Current time.

zSRK4(S, coreIdx, rhoR, HRs, time)

Apply the Runge-Kutta update to the bond matrix S.

Parameters:

Snumpy.ndarray

Bond matrix; overwritten in place.

coreIdxint

Core index to the left of the bond.

rhoRint

Right bond dimension of rho.

HRslist of int

Right bond dimensions of each Hamiltonian term.

timefloat

Current time.

zTTTimeEvo(rho, H, time, stepNum)

Perform one forward-backward TDVP sweep to advance rho by dt.

Parameters:

rhonumpy.ndarray

1-D array of zTT (MPS); overwritten in place.

Hnumpy.ndarray

2-D array of zTT (MPO) representing the Hamiltonian.

timefloat

Current time.

stepNumint

Current step number.

zRightOrth(rho)

Right-orthogonalize all MPS cores (initialization sweep).

Parameters:

rhonumpy.ndarray

1-D array of zTT MPS cores; modified in place.

calcDynamics(dtFB, stride, TTs, timeEvo, file)

Run the time evolution and write the reduced density operator to a file.

Parameters:

dtFBfloat

Step width for forward + backward time integration.

strideint

Number of integration steps between successive outputs.

TTsTTs.TTs

MPS and MPO; the MPS must already be right-orthogonalized.

timeEvotdevott.timeEvolution

Time evolution object.

filefile object

Open file for writing results.

Parameters:

• dtFB (float)

• stride (int)

• TTs (TTs)

• timeEvo (timeEvolution)

outputCurrentStates(dt, stepNum, TTs, file)

Write the current reduced density operator to a file.

Mainly used for recording the initial state.

Parameters:

dtfloat

Time step of TTs.omegaQSeq.

stepNumint

Current step number.

TTsTTs.TTs

MPS and MPO.

filefile object

Open file for writing results.

Parameters:

• dt (float)

• stepNum (int)

• TTs (TTs)

getRotatingRDO(dt, stepNum, TTs)

Transform the reduced density operator from the lab frame to the rotating frame.

Parameters:

dtfloat

Time step of TTs.omegaQSeq.

stepNumint

Current step number.

TTsTTs.TTs

MPS and MPO.

Returns:

numpy.ndarray

Reduced density operator in the rotating frame.

Parameters:

• dt (float)

• stepNum (int)

• TTs (TTs)

HPC cluster support

submitJob(submissionParams, qcFilePath)

Submit a simulation job to an HPC cluster.

Parameters:

submissionParamsdict

HPC connection and scheduler parameters with the following keys:

'hostname'str

Server hostname to connect to.

'username'str

SSH username.

'password'str

SSH password.

'otp'str

One-time password for two-factor authentication.

'schedulerName'str

Job scheduler name (e.g. 'slurm').

'numNodes'int

Number of compute nodes.

'cpusPerTask'int

Number of CPU cores per task.

'maxTime'str

Wall-clock time limit in the form 'D-H:MM:SS'.

'emailAddress'str

Email address for job notifications.

'others'str

Additional scheduler directives.

'venvPath'str

Path to the Python virtual environment on the cluster.

qcFilePathstr

Local file path where the quantum-circuit QPY data will be saved.

Returns:

job_idstr or None

The cluster job ID assigned by the scheduler, or None if it could not be parsed from the submission output.

downloadResult(downloadParams, jobID, fileName)

Download a simulation result CSV file from an HPC cluster.

Parameters:

downloadParamsdict

Connection parameters with the following keys:

'hostname'str

Server hostname.

'username'str

SSH username.

'password'str

SSH password.

'otp'str

One-time password for two-factor authentication.

'schedulerName'str

Job scheduler name (e.g. 'slurm').

jobIDint or str

Job ID of the completed simulation; the remote file is named {jobID}.csv.

fileNamestr

Local file path where the result will be saved.

getClient(hostname, username, password, otp)

Open an authenticated SSH connection and return the client.

Parameters:

hostnamestr

Server hostname or IP address.

usernamestr

SSH username.

passwordstr

SSH password.

otpstr

One-time password for two-factor authentication.

Returns:

paramiko.client.SSHClient

Authenticated SSH client connected to hostname.

commandsForSubmission(submissionParams, qpyName, path)

Build the shell commands needed to submit a job to an HPC cluster.

Parameters:

submissionParamsdict

Submission parameters with the following keys:

'schedulerName'str

Job scheduler name (e.g. 'slurm').

'numNodes'int

Number of compute nodes.

'cpusPerTask'int

Number of CPU cores per task.

'maxTime'str

Wall-clock time limit in the form 'D-H:MM:SS'.

'others'str

Additional scheduler directives.

'venvPath'str

Path to the Python virtual environment.

qpyNamestr

Name of the input QPY file.

pathstr

Remote directory where the files will be placed.

Returns:

commandsstr

Shell command string to be executed on the remote host.

getStatus(schedulerName, jobID, client)

Check whether an HPC job has completed.

Parameters:

schedulerNamestr

Job scheduler name (e.g. 'slurm').

jobIDint or str

Job ID of the simulation.

clientparamiko.client.SSHClient

Active SSH client connected to the HPC cluster.

Returns:

bool

True if the job has completed, False if it is still running.

slurmShell(submissionParams, qpyName, scriptName)

Generate a Slurm batch script for job submission.

Parameters:

submissionParamsdict

Slurm submission parameters with the following keys:

'schedulerName'str

Job scheduler name.

'numNodes'int

Number of compute nodes.

'tasksPerNode'int

Number of MPI tasks per node.

'cpusPerTask'int

Number of CPU cores per task.

'maxTime'str

Wall-clock time limit in the form 'D-H:MM:SS'.

'emailAddress'str

Email address for Slurm job notifications.

'others'str

Additional user-defined #SBATCH directives.

'venvPath'str

Path to the Python virtual environment.

qpyNamestr

Name of the input file in QPY format.

scriptNamestr

Name of the Python runner script.

Returns:

shellstr

Slurm batch script content.

submissionCommandstr

Command used to submit the script ('sbatch').

slurmStatus(jobID, client)

Check whether a Slurm job has completed.

Parameters:

jobIDint or str

Job ID of the simulation.

clientparamiko.client.SSHClient

Active SSH client connected to the HPC cluster.

Returns:

bool

True if the job has completed, False if it is still running.