Utilities for seeding and debugging, such as state-logging. More...
Functions | |
void | copyStateFromGPU (Qureg qureg) |
In GPU mode, this copies the state-vector (or density matrix) from GPU memory (qureg.deviceStateVec) to RAM (qureg.stateVec), where it can be accessed/modified by the user. More... | |
void | copyStateToGPU (Qureg qureg) |
In GPU mode, this copies the state-vector (or density matrix) from RAM (qureg.stateVec) to VRAM / GPU-memory (qureg.deviceStateVec), which is the version operated upon by other calls to the API. More... | |
void | getEnvironmentString (QuESTEnv env, Qureg qureg, char str[200]) |
Sets str to a string containing the number of qubits in qureg , and the hardware facilities used (e.g. More... | |
void | initDebugState (Qureg qureg) |
Initialises qureg to be in the un-normalised, non-physical state with with n-th complex amplitude (2n/10 + i(2n+1)/10). More... | |
void | invalidQuESTInputError (const char *errMsg, const char *errFunc) |
An internal function called when invalid arguments are passed to a QuEST API call, which the user can optionally override by redefining. More... | |
void | reportPauliHamil (PauliHamil hamil) |
Print the PauliHamil to screen. More... | |
void | reportQuESTEnv (QuESTEnv env) |
Report information about the QuEST environment. More... | |
void | reportQuregParams (Qureg qureg) |
Report metainformation about a set of qubits: number of qubits, number of probability amplitudes. More... | |
void | reportState (Qureg qureg) |
Print the current state vector of probability amplitudes for a set of qubits to file. More... | |
void | reportStateToScreen (Qureg qureg, QuESTEnv env, int reportRank) |
Print the current state vector of probability amplitudes for a set of qubits to standard out. More... | |
void | seedQuEST (unsigned long int *seedArray, int numSeeds) |
Seed the Mersenne Twister used for random number generation in the QuEST environment with a user defined seed. More... | |
void | seedQuESTDefault (void) |
Seed the Mersenne Twister used for random number generation in the QuEST environment with an example defualt seed. More... | |
void | syncQuESTEnv (QuESTEnv env) |
Guarantees that all code up to the given point has been executed on all nodes (if running in distributed mode) More... | |
int | syncQuESTSuccess (int successCode) |
Performs a logical AND on all successCodes held by all processes. More... | |
Detailed Description
Utilities for seeding and debugging, such as state-logging.
Function Documentation
◆ copyStateFromGPU()
void copyStateFromGPU | ( | Qureg | qureg | ) |
In GPU mode, this copies the state-vector (or density matrix) from GPU memory (qureg.deviceStateVec) to RAM (qureg.stateVec), where it can be accessed/modified by the user.
In CPU mode, this function has no effect. In conjunction with copyStateToGPU(), this allows a user to directly modify the state-vector in a harware agnostic way. Note though that users should instead use setAmps() if possible.
For example, to set the first real element to 1, one could do:
copyStateFromGPU(qureg); qureg.stateVec.real[0] = 1; copyStateToGPU(qureg);
Note users should never access qureg.deviceStateVec directly.
- Parameters
-
[in,out] qureg the qureg of which to copy .deviceStateVec to .stateVec in GPU mode
Definition at line 39 of file QuEST_cpu.c.
References DEBUG, Qureg::deviceStateVec, Qureg::numAmpsPerChunk, and Qureg::stateVec.
Referenced by areEqual(), densmatr_calcTotalProb(), statevec_calcTotalProb(), statevec_compareStates(), statevec_reportStateToScreen(), TEST_CASE(), toQMatrix(), and toQVector().
◆ copyStateToGPU()
void copyStateToGPU | ( | Qureg | qureg | ) |
In GPU mode, this copies the state-vector (or density matrix) from RAM (qureg.stateVec) to VRAM / GPU-memory (qureg.deviceStateVec), which is the version operated upon by other calls to the API.
In CPU mode, this function has no effect. In conjunction with copyStateFromGPU() (which should be called first), this allows a user to directly modify the state-vector in a harware agnostic way. Note though that users should instead use setAmps() if possible.
For example, to set the first real element to 1, one could do:
copyStateFromGPU(qureg); qureg.stateVec.real[0] = 1; copyStateToGPU(qureg);
Note users should never access qureg.deviceStateVec directly.
- Parameters
-
[in,out] qureg the qureg of which to copy .stateVec to .deviceStateVec in GPU mode
Definition at line 36 of file QuEST_cpu.c.
References DEBUG, Qureg::deviceStateVec, Qureg::numAmpsPerChunk, and Qureg::stateVec.
Referenced by statevec_initStateFromSingleFile(), TEST_CASE(), and toQureg().
◆ getEnvironmentString()
Sets str
to a string containing the number of qubits in qureg
, and the hardware facilities used (e.g.
GPU, MPI and/or OMP).
- Parameters
-
[in] env object representing the execution environment. A single instance is used for each program [in] qureg the qureg of which to query the simulating hardware [out] str to be populated with the output string
Definition at line 447 of file QuEST_gpu.cu.
References Qureg::numQubitsInStateVec.
◆ initDebugState()
void initDebugState | ( | Qureg | qureg | ) |
Initialises qureg
to be in the un-normalised, non-physical state with with n-th complex amplitude (2n/10 + i(2n+1)/10).
This is used internally for debugging and testing.
- Parameters
-
[in,out] qureg the register to have its amplitudes overwritten
Definition at line 1308 of file QuEST.c.
References statevec_initDebugState().
Referenced by TEST_CASE().
◆ invalidQuESTInputError()
void invalidQuESTInputError | ( | const char * | errMsg, |
const char * | errFunc | ||
) |
An internal function called when invalid arguments are passed to a QuEST API call, which the user can optionally override by redefining.
This function is a weak symbol, so that users can choose how input errors are handled, by redefining it in their own code. Users must ensure that the triggered API call does not continue (e.g. the user exits or throws an exception), else QuEST will continue with the valid input and likely trigger a seg-fault. This function is triggered before any internal state-change, hence it is safe to interrupt with exceptions.
E.g. in C
This function is compatible with C++ exceptions, though note the user of extern "C":
- Parameters
-
[in] errMsg a string describing the nature of the argument error [in] errFunc the name of the invalidly-called API function
- Exceptions
-
invalidQuESTInputError unless overriden by the user
An internal function called when invalid arguments are passed to a QuEST API call, which the user can optionally override by redefining.
an negative qubit index). This is redefined here to, in lieu of printing and exiting, throw a C++ exception which can be caught (and hence unit tested for) by Catch2
Definition at line 176 of file QuEST_validation.c.
References exitWithError().
Referenced by QuESTAssert(), validateFileOpened(), validateHamilFileCoeffParsed(), validateHamilFileParams(), validateHamilFilePauliCode(), and validateHamilFilePauliParsed().
◆ reportPauliHamil()
void reportPauliHamil | ( | PauliHamil | hamil | ) |
Print the PauliHamil
to screen.
The output features a new line for each term, each with format
c p1 p2 p3 ... pN
where c
is the real coefficient of the term, and p1
... pN
are numbers 0
, 1
, 2
, 3
to indicate identity, pauliX, pauliY and pauliZ operators respectively, acting on qubits 0
through N-1
(all qubits). A tab character separates c and p1, but single spaces separate the Pauli operators.
- Parameters
-
[in] hamil an instantiated PauliHamil
- Exceptions
-
invalidQuESTInputError if the parameters of hamil
are invalid, i.e. ifnumQubits
<= 0, or ifnumSumTerms
<= 0, or ifpauliCodes
contains an invalid Pauli code.
Definition at line 1328 of file QuEST.c.
References PauliHamil::numQubits, PauliHamil::numSumTerms, PauliHamil::pauliCodes, PauliHamil::termCoeffs, and validatePauliHamil().
◆ reportQuESTEnv()
void reportQuESTEnv | ( | QuESTEnv | env | ) |
Report information about the QuEST environment.
- Parameters
-
[in] env object representing the execution environment. A single instance is used for each program
Definition at line 179 of file QuEST_cpu_distributed.c.
References QuESTEnv::numRanks, qreal, and QuESTEnv::rank.
◆ reportQuregParams()
void reportQuregParams | ( | Qureg | qureg | ) |
Report metainformation about a set of qubits: number of qubits, number of probability amplitudes.
- Parameters
-
[in] qureg object representing the set of qubits
Definition at line 234 of file QuEST_common.c.
References Qureg::chunkId, Qureg::numChunks, and Qureg::numQubitsInStateVec.
◆ reportState()
void reportState | ( | Qureg | qureg | ) |
Print the current state vector of probability amplitudes for a set of qubits to file.
File format:
real, imag realComponent1, imagComponent1 realComponent2, imagComponent2 ... realComponentN, imagComponentN
File naming convention:
For each node that the program runs on, a file 'state_rank_[node_rank].csv' is generated. If there is more than one node, ranks after the first do not include the header
real, imag
so that files are easier to combine.
- Parameters
-
[in,out] qureg object representing the set of qubits
Definition at line 216 of file QuEST_common.c.
References Qureg::chunkId, Qureg::numAmpsPerChunk, and Qureg::stateVec.
◆ reportStateToScreen()
Print the current state vector of probability amplitudes for a set of qubits to standard out.
For debugging purposes. Each rank should print output serially. Only print output for systems <= 5 qubits
Definition at line 1324 of file QuEST.c.
References statevec_reportStateToScreen().
◆ seedQuEST()
void seedQuEST | ( | unsigned long int * | seedArray, |
int | numSeeds | ||
) |
Seed the Mersenne Twister used for random number generation in the QuEST environment with a user defined seed.
This function uses the mt19937 init_by_array function with numSeeds keys supplied by the user. Subsequent calls to mt19937 genrand functions will use this seeding. For a multi process code, the same seed is given to all process, therefore this seeding is only appropriate to use for functions such as measure where all processes require the same random value.
For more information about the MT, see http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/MT2002/emt19937ar.html
- Parameters
-
[in] seedArray Array of integers to use as seed. This allows the MT to be initialised with more than a 32-bit integer if required [in] numSeeds Length of seedArray
Seed the Mersenne Twister used for random number generation in the QuEST environment with a user defined seed.
Definition at line 209 of file QuEST_common.c.
References init_by_array().
◆ seedQuESTDefault()
void seedQuESTDefault | ( | void | ) |
Seed the Mersenne Twister used for random number generation in the QuEST environment with an example defualt seed.
This default seeding function uses the mt19937 init_by_array function with two keys – time and pid. Subsequent calls to mt19937 genrand functions will use this seeding. For a multi process code, the same seed is given to all process, therefore this seeding is only appropriate to use for functions such as measure where all processes require the same random value.
For more information about the MT, see http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/MT2002/emt19937ar.html
Definition at line 1318 of file QuEST_cpu_distributed.c.
References getQuESTDefaultSeedKey(), and init_by_array().
Referenced by createQuESTEnv().
◆ syncQuESTEnv()
void syncQuESTEnv | ( | QuESTEnv | env | ) |
Guarantees that all code up to the given point has been executed on all nodes (if running in distributed mode)
- Parameters
-
[in] env object representing the execution environment. A single instance is used for each program
Definition at line 162 of file QuEST_cpu_distributed.c.
Referenced by areEqual(), statevec_initStateFromSingleFile(), statevec_reportStateToScreen(), toQMatrix(), toQureg(), and toQVector().
◆ syncQuESTSuccess()
int syncQuESTSuccess | ( | int | successCode | ) |
Performs a logical AND on all successCodes held by all processes.
If any one process has a zero successCode all processes will return a zero success code.
- Parameters
-
[in] successCode 1 if process task succeeded, 0 if process task failed
- Returns
- 1 if all processes succeeded, 0 if any one process failed
Definition at line 166 of file QuEST_cpu_distributed.c.