Validation

Functions to control QuEST's user-input validation. More...

Functions
qreal	getQuESTValidationEpsilon ()
void	setQuESTInputErrorHandler (void(*callback)(const char *func, const char *msg))
void	setQuESTValidationEpsilon (qreal eps)
void	setQuESTValidationEpsilonToDefault ()
void	setQuESTValidationOff ()
void	setQuESTValidationOn ()

Detailed Description

Functions to control QuEST's user-input validation.

These can be used to adjust the precision with which properties like unitarity are checked/enforced, or otherwise disable all input validation (e.g. is the given qubit index valid?). Note passing erroneous input while validation is disabled can result in runtime errors like segmentation faults.

Function Documentation

getQuESTValidationEpsilon()

qreal getQuESTValidationEpsilon

(

)

Returns the threshold used by QuEST's numerical validation.

This is the value last passed to setQuESTValidationEpsilon(), unless overridden by setQuESTValidationEpsilonToDefault(), or similarly if never called. It indicates the precision and correctness demanded of input numerical quantities to the QuEST API. A larger epsilon corresponds to more permissive validation, while a smaller epsilon means validation is harder to pass and input quantities must be more carefully prepared.

Note

A validation epsilon of 0 indicates numerical validation is disabled.

The exact usage of the validation epsilon is function specific. For an example, see applyCompMatr1(). The validation has no effect when validation has been disabled entirely via setQuESTValidationOff().

Returns

The validation epsilon.

See also

• setQuESTValidationEpsilon()
• setQuESTValidationEpsilonToDefault()
• setQuESTValidationOff()

Author

Tyson Jones

Definition at line 115 of file debug.cpp.

                                  {
    validate_envIsInit(__func__);
 
    return validateconfig_getEpsilon();
}

setQuESTInputErrorHandler()

void setQuESTInputErrorHandler

(

void(*

callback )(const char *func, const char *msg)

)

Sets the function which QuEST will call when encountering an invalid input.

By default, when a user passes an invalid input to QuEST (such as a negative qubit index), an internal function default_inputErrorHandler() is called which prints a message to stdout, attempts to gracefully clean up communication in distributed settings, then exits execution with exit(EXIT_FAILURE). If this is undesired, setQuESTInputErrorHandler() allows the user to substitute callback for the default handler, which will receive the throwing API function name func, and the error message string msg.

QuEST endeavours to perform input validation upfront before proceeding to any mutation of passed objects (like a Qureg). This permits gracefully catching validation errors through custom handling without corrupting QuEST's state. For example, C++ users may wish to throw an exception within callback, or MPI superusers may wish to perform custom communicator cleanup before exiting.

Important

It is crucial that callback does not return execution back to the throwing QuEST function, which is likely to cause a segmentation fault or other internal error. Instead, callback should exit or throw an exception, caught by the user's control flow.

Note validation can be changed or disabled with setQuESTValidationEpsilon() and setQuESTValidationOff(), which affects when callback will be called. This function can be called at any time to update the error handler.

Example

void myErrorHandler(const char* errFunc, const char* errMsg) {
    printf("Ruh-roh, Raggy! Function '%s' has reported '%s'.\n", errFunc, errMsg);
    printf("We will now be very good children and exit immediately!\n");
    exit(0);
}
 
int main() {
    initQuESTEnv();
    setQuESTInputErrorHandler(myErrorHandler);
    createQureg(9999); // invokes myErrorHandler
    ...
}

Parameters

[in]

callback

a pointer to a function which accepts two const char* arguments.

Exceptions

error	if the QuEST environment has not been initialised via initQuESTEnv().
seg-fault	if callback is a null-ptr and an invalid input is later encountered.

See also

• C and C++ examples
• setQuESTValidationOff()

Author

Tyson Jones

Definition at line 74 of file debug.cpp.

                                                                           {
    validate_envIsInit(__func__);
 
    validateconfig_setErrorHandler(callback);
}

setQuESTValidationEpsilon()

void setQuESTValidationEpsilon

(

qreal

eps

)

Modifies QuEST's validation threshold for testing numerical or approximate quantities, to eps.

Many of QuEST's API functions validate that expected numerical properties of the input are satisfied. For example, that the matrix passed to applyCompMatr1() is unitary, and ergo that the product of the matrix with its own adjoint produces the identity matrix. Due to floating-point error, such properties cannot be evaluated exactly, and small disagreement between the expected and given property is tolerated. This difference is the validation epsilon, as overridden by this function. Precisely how the validation epsilon is used by numerical validation is function specific, and individually documented.

Remarks

Passing eps=0 effectively encodes eps=infinity, and disables all numerical validation.

The validation epsilon has no effect on non-numerical validation, such as whether qubit incices are valid. In general, it is therefore safe to modify and disable numerical validation via this function.

The default validation epsilon, which can itself be controlled by the QUEST_DEFAULT_VALIDATION_EPSILON environment variable, is restored via setQuESTValidationEpsilonToDefault().

Note that many data structures (e.g. CompMatr, DiagMatr, KrausMap) will assess epsilon-dependent validation properties such as unitarity once, recording the result in a persistent heap field (like KrausMap.isApproxCPTP) to avoid superfluous re-calculation. Updating the global validation epsilon via this function will update all persistent heap fields, marking epsilon-dependent properties as "unknown", which will be lazily re-evaluated when validation is next performed. Ergo, calling this function can cause later additional function overheads.

Example

// | max [matr . adj(matr) - identity] |^2 = 576
CompMatr1 matr = getInlineCompMatr1({{1,2},{3,4}}); // non-unitary
setQuESTValidationEpsilon(576.0);
applyCompMatr1(qureg, 0, matr); // no error
 
matr.elems[0][0] = 999;
setQuESTValidationEpsilon(0); // disable all numerical validation
applyCompMatr1(qureg, 0, matr); // no error
 
// target=-1 would still trigger an error
// applyCompMatr1(qureg, -1, matr);

Parameters

[in]

eps

the new validation epsilon.

Exceptions

error

if the QuEST environment has not been initialised via initQuESTEnv(). if eps is negative.

See also

• setQuESTValidationEpsilonToDefault()
• getQuESTValidationEpsilon()
• setQuESTValidationOff()

Author

Tyson Jones

Definition at line 100 of file debug.cpp.

                                          {
    validate_envIsInit(__func__);
    validate_newEpsilonValue(eps, __func__);
 
    validateconfig_setEpsilon(eps);
    util_setEpsilonSensitiveHeapFlagsToUnknown();
}

Referenced by TEST_CASE(), and TEST_CASE().

setQuESTValidationEpsilonToDefault()

void setQuESTValidationEpsilonToDefault

(

)

Restores QuEST's validation threshold for testing numerical or approximate quantities, to its default value.

The default value is informed by the environment variable QUEST_DEFAULT_VALIDATION_EPSILON. If the environment variable was not specified during the launch of the QuEST executable, then the default validation epsilon is specific to the precision of qreal, as controlled by QUEST_FLOAT_PRECISION. These are:

QUEST_FLOAT_PRECISION	qreal	default epsilon
1	float	1E-5
2	double	1E-12
4	long double	1E-15

See also

• setQuESTValidationEpsilon()

Author

Tyson Jones

Definition at line 108 of file debug.cpp.

                                          {
    validate_envIsInit(__func__);
 
    validateconfig_setEpsilonToDefault();
    util_setEpsilonSensitiveHeapFlagsToUnknown();
}

Referenced by TEST_CASE(), and TEST_CASE().

setQuESTValidationOff()

void setQuESTValidationOff

(

)

Disables all of QuEST's input validation.

When a QuEST API function encounters an invalid input, the error will be ignored and execution of the function will proceed. This is useful in order to call a QuEST function in a manner which is ordinarily forbidden to avoid user mistakes.

Important

This function disables all of QuEST's runtime input validation, meaning invalid inputs such as negative qubit indices will be accepted and trusted, likely causing internal errors and segmentation faults.

Users wishing only to adjust numerical validation tolerances, or disable numerical validations such as matrix unitarity checks, should instead use the safer setQuESTValidationEpsilon(). If it is essential to disable all validation, it should be later restored with setQuESTValidationOn().

Example

Qureg qureg = createDensityQureg(3); // ~ 6-qubit statevector
CompMatr1 matr = getInlineCompMatr1({{1,2},{3,4}});
 
int target = 4; // 0-2 valid, 3-5 hacky, 6+ seg-fault
 
setQuESTValidationOff();
leftapplyCompMatr1(qureg, target, matr);
setQuESTValidationOn();

See also

• setQuESTValidationOn()
• setQuESTValidationEpsilon()
• setQuESTInputErrorHandler()

Author

Tyson Jones

Definition at line 86 of file debug.cpp.

                             {
    validate_envIsInit(__func__);
 
    // disables all validation and computation
    // of matrix properties like isUnitary. Also
    // means pre-computed matrix properties are
    // ignored. It does not however erase pre-
    // computed properties; subsequently restoring 
    // validation will not necessitate re-eval.
 
    validateconfig_disable();
}

Referenced by TEST_CASE().

setQuESTValidationOn()

void setQuESTValidationOn

(

)

Restores QuEST's input validation.

This means that invalid inputs to other QuEST API functions will call the error handler (the default, or one passed to setQuESTInputErrorHandler()), rather than be silently ignored.

This function only has an affect if setQuESTValidationOff() was prior called. This function does not affect the validation epsilon controlled with setQuESTValidationEpsilon(), which when zero, will still see the skipping of numerically-approximated validations (such as unitarity checks).

See also

• setQuESTValidationOff()

Author

Tyson Jones

Definition at line 80 of file debug.cpp.

                            {
    validate_envIsInit(__func__);
    
    validateconfig_enable();
}

Referenced by TEST_CASE().