Insert QUEST into environment variables

.github/workflows/test_paid.yml

@@ -144,17 +144,17 @@ jobs:
           -DENABLE_CUDA=${{ matrix.cuda }}
           -DENABLE_CUQUANTUM=${{ matrix.cuquantum }}
           -DCMAKE_CUDA_ARCHITECTURES=${{ env.cuda_arch }}
-          -DTEST_ALL_DEPLOYMENTS=${{ env.test_all_deploys }}
-          -DTEST_MAX_NUM_QUBIT_PERMUTATIONS=${{ env.num_qubit_perms }}
+          -DQUEST_TEST_TRY_ALL_DEPLOYMENTS=${{ env.test_all_deploys }}
+          -DQUEST_TEST_MAX_NUM_QUBIT_PERMUTATIONS=${{ env.num_qubit_perms }}
 
       - name: Compile
         run: cmake --build ${{ env.build_dir }} --parallel
 
       # specifying only env-vars with non-default values
       - name: Configure tests with environment variables
         run: | 
-          echo "TEST_MAX_NUM_QUBIT_PERMUTATIONS=${{ env.num_qubit_perms }}" >> $GITHUB_ENV
-          echo "TEST_ALL_DEPLOYMENTS=${{ env.test_all_deploys }}" >> $GITHUB_ENV
+          echo "QUEST_TEST_MAX_NUM_QUBIT_PERMUTATIONS=${{ env.num_qubit_perms }}" >> $GITHUB_ENV
+          echo "QUEST_TEST_TRY_ALL_DEPLOYMENTS=${{ env.test_all_deploys }}" >> $GITHUB_ENV
 
       # cannot use ctests when distributed, grr!
       - name: Run multithreaded + distributed v4 tests (16 nodes, 4 threads eeach)
@@ -280,9 +280,9 @@ jobs:
       # specify only env-vars with non-default values
       - name: Configure tests with environment variables
         run: | 
-          echo "TEST_ALL_DEPLOYMENTS=${{ env.test_all_deploys }}" >> $GITHUB_ENV
-          echo "TEST_NUM_MIXED_DEPLOYMENT_REPETITIONS=${{ env.test_repetitions }}" >> $GITHUB_ENV
-          echo "PERMIT_NODES_TO_SHARE_GPU=${{ env.mpi_share_gpu }}" >> $GITHUB_ENV
+          echo "QUEST_TEST_TRY_ALL_DEPLOYMENTS=${{ env.test_all_deploys }}" >> $GITHUB_ENV
+          echo "QUEST_TEST_NUM_MIXED_DEPLOYMENT_REPETITIONS=${{ env.test_repetitions }}" >> $GITHUB_ENV
+          echo "QUEST_PERMIT_NODES_TO_SHARE_GPU=${{ env.mpi_share_gpu }}" >> $GITHUB_ENV
 
       # cannot use ctests when distributed, grr!
       - name: Run GPU + distributed v4 mixed tests (4 nodes sharing 1 GPU)

docs/cmake.md

@@ -60,7 +60,7 @@ make
 | `ENABLE_DEPRECATED_API` | (`OFF`), `ON` | As described above. When enabled alongside testing, the `v3 deprecated` unit tests will additionally be compiled and can be run from within `build` via `cd tests/deprecated; ctest`, or manually launched with `./tests/deprecated/dep_tests` (enabling distribution, as above).
 | `DOWNLOAD_CATCH2` | (`ON`), `OFF` | QuEST's tests require Catch2. By default, if you don't have Catch2 installed (or CMake doesn't find it) it will be downloaded from Github and built for you. If you don't want that to happen, for example because you _do_ have Catch2 installed, set this to `OFF`. |
 
-> As of `v4.2`, macros which configure the unit tests such as `TEST_MAX_NUM_QUBIT_PERMUTATIONS` have become environment variables specified before launch. See [`launch.md`](launch.md)
+> As of `v4.2`, macros which configure the unit tests such as `QUEST_TEST_MAX_NUM_QUBIT_PERMUTATIONS` have become environment variables specified before launch. See [`launch.md`](launch.md)
 
 ---------------------------
 

docs/launch.md

@@ -223,11 +223,11 @@ The `v4` unit tests make use of the below, optional environment variables to con
 
 | Environment variable  | Default | Description |
 | -------- | ------- | ------- |
-| `TEST_NUM_QUBITS_IN_QUREG` | `6` | The number of qubits in the Qureg(s) undergoing unit testing. In addition to operation upon larger Quregs being exponentially slower, beware that more qubits permit more variations and permutations of input parameters like target qubits, factorially increasing the number of tests per operation. |
-| `TEST_MAX_NUM_QUBIT_PERMUTATIONS`  | `0` | The maximum number of control and target qubit permutations under which to unit test each function. Set to `0` (default) to test all permutations, or to a positive integer (e.g. `50`) to accelerate the unit tests. See more info [here](https://quest-kit.github.io/QuEST/group__testutilsconfig.html#gac5adcc10bd26c56f20344f5ae3d9ba41). |
-| `TEST_MAX_NUM_SUPEROP_TARGETS` | `4` | The maximum number of superoperator targets for which to unit test functions `mixKrausMap()` and `mixSuperOp()`. These are computationally equivalent to simulating unitaries with double the number of targets upon a density matrix. Set to `0` to test all sizes which is likely prohibitively slow, or to a positive integer (e.g. the default of `4`) to accelerate the unit tests. |
-| `NUM_MIXED_DEPLOYMENT_REPETITIONS` | `10` | The number of times (minimum of `1`) to repeat each random mixed-deployment unit test for each deployment combination. |
-| `TEST_ALL_DEPLOYMENTS` | `1` | Whether unit tests will be run using all possible deployment combinations (i.e. OpenMP, CUDA, MPI) in-turn (`=1`), or only once using all available deployments simultaneously (`=0`). |
+| `QUEST_TEST_NUM_QUBITS_IN_QUREG` | `6` | The number of qubits in the Qureg(s) undergoing unit testing. In addition to operation upon larger Quregs being exponentially slower, beware that more qubits permit more variations and permutations of input parameters like target qubits, factorially increasing the number of tests per operation. |
+| `QUEST_TEST_MAX_NUM_QUBIT_PERMUTATIONS`  | `0` | The maximum number of control and target qubit permutations under which to unit test each function. Set to `0` (default) to test all permutations, or to a positive integer (e.g. `50`) to accelerate the unit tests. See more info [here](https://quest-kit.github.io/QuEST/group__testutilsconfig.html#gac5adcc10bd26c56f20344f5ae3d9ba41). |
+| `QUEST_TEST_MAX_NUM_SUPEROP_TARGETS` | `4` | The maximum number of superoperator targets for which to unit test functions `mixKrausMap()` and `mixSuperOp()`. These are computationally equivalent to simulating unitaries with double the number of targets upon a density matrix. Set to `0` to test all sizes which is likely prohibitively slow, or to a positive integer (e.g. the default of `4`) to accelerate the unit tests. |
+| `QUEST_TEST_NUM_MIXED_DEPLOYMENT_REPETITIONS` | `10` | The number of times (minimum of `1`) to repeat each random mixed-deployment unit test for each deployment combination. |
+| `QUEST_TEST_TRY_ALL_DEPLOYMENTS` | `1` | Whether unit tests will be run using all possible deployment combinations (i.e. OpenMP, CUDA, MPI) in-turn (`=1`), or only once using all available deployments simultaneously (`=0`). |
 
 
 
@@ -268,8 +268,8 @@ ctest
 
 QuEST execution can be configured prior to runtime using the below [environment variables](https://en.wikipedia.org/wiki/Environment_variable).
 
-- [`PERMIT_NODES_TO_SHARE_GPU`](https://quest-kit.github.io/QuEST/group__modes.html#ga7e12922138caa68ddaa6221e40f62dda)
-- [`DEFAULT_VALIDATION_EPSILON`](https://quest-kit.github.io/QuEST/group__modes.html#ga55810d6f3d23de810cd9b12a2bbb8cc2)
+- [`QUEST_PERMIT_NODES_TO_SHARE_GPU`](https://quest-kit.github.io/QuEST/group__modes.html#ga7e12922138caa68ddaa6221e40f62dda)
+- [`QUEST_DEFAULT_VALIDATION_EPSILON`](https://quest-kit.github.io/QuEST/group__modes.html#ga55810d6f3d23de810cd9b12a2bbb8cc2)
 
 Note the unit tests in the preceding section accept additional environment variables.
 

quest/include/modes.h

@@ -45,25 +45,25 @@
      * 
      * @author Tyson Jones
      */
-    const int PERMIT_NODES_TO_SHARE_GPU = 0;
+    const int QUEST_PERMIT_NODES_TO_SHARE_GPU = 0;
 
 
     /** @envvardoc
      * 
      * Specifies the default validation epsilon. 
      * 
-     * Specifying `DEFAULT_VALIDATION_EPSILON` to a positive, real number overrides the 
+     * Specifying `QUEST_DEFAULT_VALIDATION_EPSILON` to a positive, real number overrides the 
      * precision-specific default (`1E-5`, `1E-12`, `1E-13` for single, double and quadruple 
      * precision respectively). The specified epsilon is used by QuEST for numerical validation
      * unless overriden at runtime via setValidationEpsilon(), in which case it can be
      * restored to that specified by this environment variable using setValidationEpsilonToDefault().
      * 
      * @envvarvalues
-     *  - setting @p DEFAULT_VALIDATION_EPSILON=0 disables numerical validation, as if the value
+     *  - setting @p QUEST_DEFAULT_VALIDATION_EPSILON=0 disables numerical validation, as if the value
      *    were instead infinity.
-     *  - setting @p DEFAULT_VALIDATION_EPSILON='' is equivalent to _not_ specifying the variable,
+     *  - setting @p QUEST_DEFAULT_VALIDATION_EPSILON='' is equivalent to _not_ specifying the variable,
      *    adopting instead the precision-specific default above.
-     *  - setting @p DEFAULT_VALIDATION_EPSILON=x where `x` is a positive, valid `qreal` in any
+     *  - setting @p QUEST_DEFAULT_VALIDATION_EPSILON=x where `x` is a positive, valid `qreal` in any
      *    format accepted by `C` or `C++` (e.g. `0.01`, `1E-2`, `+1e-2`) will use `x` as the
      *    default validation epsilon.
      * 
@@ -75,7 +75,7 @@
      * 
      * @author Tyson Jones
      */
-    const qreal DEFAULT_VALIDATION_EPSILON = 0;
+    const qreal QUEST_DEFAULT_VALIDATION_EPSILON = 0;
 
 
 #endif

quest/src/core/envvars.cpp

@@ -26,8 +26,8 @@ using std::string;
 
 
 namespace envvar_names {
-    string PERMIT_NODES_TO_SHARE_GPU = "PERMIT_NODES_TO_SHARE_GPU";
-    string DEFAULT_VALIDATION_EPSILON = "DEFAULT_VALIDATION_EPSILON";
+    string QUEST_PERMIT_NODES_TO_SHARE_GPU = "QUEST_PERMIT_NODES_TO_SHARE_GPU";
+    string QUEST_DEFAULT_VALIDATION_EPSILON = "QUEST_DEFAULT_VALIDATION_EPSILON";
 }
 
 
@@ -41,11 +41,11 @@ namespace envvar_values {
 
     // by default, do not permit GPU sharing since it sabotages performance
     // and should only ever be carefully, deliberately enabled
-    bool PERMIT_NODES_TO_SHARE_GPU = false;
+    bool QUEST_PERMIT_NODES_TO_SHARE_GPU = false;
 
     // by default, the initial validation epsilon (before being overriden
     // by users at runtime) should depend on qreal (i.e. FLOAT_PRECISION)
-    qreal DEFAULT_VALIDATION_EPSILON = UNSPECIFIED_DEFAULT_VALIDATION_EPSILON;
+    qreal QUEST_DEFAULT_VALIDATION_EPSILON = UNSPECIFIED_DEFAULT_VALIDATION_EPSILON;
 }
 
 
@@ -94,7 +94,7 @@ void assertEnvVarsAreLoaded() {
 void validateAndSetWhetherGpuSharingIsPermitted(const char* caller) {
 
     // permit unspecified, falling back to default value
-    string name = envvar_names::PERMIT_NODES_TO_SHARE_GPU;
+    string name = envvar_names::QUEST_PERMIT_NODES_TO_SHARE_GPU;
     if (!isEnvVarSpecified(name))
         return;
 
@@ -103,14 +103,14 @@ void validateAndSetWhetherGpuSharingIsPermitted(const char* caller) {
     validate_envVarPermitNodesToShareGpu(value, caller);
 
     // overwrite default env-var value
-    envvar_values::PERMIT_NODES_TO_SHARE_GPU = (value[0] == '1');
+    envvar_values::QUEST_PERMIT_NODES_TO_SHARE_GPU = (value[0] == '1');
 }
 
 
 void validateAndSetDefaultValidationEpsilon(const char* caller) {
 
     // permit unspecified, falling back to the hardcoded precision-specific default
-    string name = envvar_names::DEFAULT_VALIDATION_EPSILON;
+    string name = envvar_names::QUEST_DEFAULT_VALIDATION_EPSILON;
     if (!isEnvVarSpecified(name))
         return;
 
@@ -119,7 +119,7 @@ void validateAndSetDefaultValidationEpsilon(const char* caller) {
     validate_envVarDefaultValidationEpsilon(value, caller);
 
     // overwrite default env-var value
-    envvar_values::DEFAULT_VALIDATION_EPSILON = parser_parseReal(value);    
+    envvar_values::QUEST_DEFAULT_VALIDATION_EPSILON = parser_parseReal(value);    
 }
 
 
@@ -147,12 +147,12 @@ void envvars_validateAndLoadEnvVars(const char* caller) {
 bool envvars_getWhetherGpuSharingIsPermitted() {
     assertEnvVarsAreLoaded();
 
-    return envvar_values::PERMIT_NODES_TO_SHARE_GPU;
+    return envvar_values::QUEST_PERMIT_NODES_TO_SHARE_GPU;
 }
 
 
 qreal envvars_getDefaultValidationEpsilon() {
     assertEnvVarsAreLoaded();
 
-    return envvar_values::DEFAULT_VALIDATION_EPSILON;
+    return envvar_values::QUEST_DEFAULT_VALIDATION_EPSILON;
 }

quest/src/core/envvars.hpp

@@ -13,8 +13,8 @@
 
 
 namespace envvar_names { 
-    extern std::string PERMIT_NODES_TO_SHARE_GPU;
-    extern std::string DEFAULT_VALIDATION_EPSILON;
+    extern std::string QUEST_PERMIT_NODES_TO_SHARE_GPU;
+    extern std::string QUEST_DEFAULT_VALIDATION_EPSILON;
 }
 
 

quest/src/core/validation.cpp

@@ -99,7 +99,7 @@ namespace report {
         "Cannot distribute QuEST between ${NUM_NODES} nodes; must use a power-of-2 number of nodes.";
 
     string MULTIPLE_NODES_BOUND_TO_SAME_GPU =
-        "Multiple MPI processes (nodes) were bound to the same GPU which is detrimental to performance and almost never intended. Please re-deploy QuEST with no more MPI processes than there are total GPUs. Alternatively, recompile QuEST with macro PERMIT_NODES_TO_SHARE_GPU=1.";
+        "Multiple MPI processes (nodes) were bound to the same GPU which is detrimental to performance and almost never intended. Please re-deploy QuEST with no more MPI processes than there are total GPUs. Alternatively, recompile QuEST with macro QUEST_PERMIT_NODES_TO_SHARE_GPU=1.";
 
     string CUQUANTUM_DEPLOYED_ON_BELOW_CC_GPU =
         "Cannot use cuQuantum on a GPU with compute-capability ${OUR_CC}; a compute-capability of ${MIN_CC} or above is required. Recompile with cuQuantum disabled to fall-back to using Thrust and custom kernels.";
@@ -1121,17 +1121,17 @@ namespace report {
      * ENVIRONMENT VARIABLES
      */
 
-    string INVALID_PERMIT_NODES_TO_SHARE_GPU_ENV_VAR =
-        "The optional, boolean '" + envvar_names::PERMIT_NODES_TO_SHARE_GPU + "' environment variable was specified to an invalid value. The variable can be unspecified, or set to '', '0' or '1'.";
+    string INVALID_QUEST_PERMIT_NODES_TO_SHARE_GPU_ENV_VAR =
+        "The optional, boolean '" + envvar_names::QUEST_PERMIT_NODES_TO_SHARE_GPU + "' environment variable was specified to an invalid value. The variable can be unspecified, or set to '', '0' or '1'.";
 
     string DEFAULT_EPSILON_ENV_VAR_NOT_A_REAL =
-        "The optional '" + envvar_names::DEFAULT_VALIDATION_EPSILON + "' environment variable was not a recognisable real number.";
+        "The optional '" + envvar_names::QUEST_DEFAULT_VALIDATION_EPSILON + "' environment variable was not a recognisable real number.";
 
     string DEFAULT_EPSILON_ENV_VAR_EXCEEDS_QREAL_RANGE = 
-        "The optional '" + envvar_names::DEFAULT_VALIDATION_EPSILON + "' environment variable was larger (in magnitude) than the maximum value which can be stored in a qreal.";
+        "The optional '" + envvar_names::QUEST_DEFAULT_VALIDATION_EPSILON + "' environment variable was larger (in magnitude) than the maximum value which can be stored in a qreal.";
 
     string DEFAULT_EPSILON_ENV_VAR_IS_NEGATIVE =
-        "The optional '" + envvar_names::DEFAULT_VALIDATION_EPSILON + "' environment variable was negative. The value must be zero or positive.";
+        "The optional '" + envvar_names::QUEST_DEFAULT_VALIDATION_EPSILON + "' environment variable was negative. The value must be zero or positive.";
 }
 
 
@@ -1220,8 +1220,8 @@ qreal REDUCTION_EPSILON_FACTOR = 100;
  */
 
 // the default epsilon is not known until runtime since the macro
-// UNSPECIFIED_DEFAULT_VALIDATION_EPSILON may be overriden by the
-// DEFAULT_VALIDATION_EPSILON environment variable. We do not read
+// UNSPECIFIED_QUEST_DEFAULT_VALIDATION_EPSILON may be overriden by the
+// QUEST_DEFAULT_VALIDATION_EPSILON environment variable. We do not read
 // the env-var immediately since it may malformed; we must wait for
 // initQuESTEnv() to validate and potentially throw an error
 static qreal global_validationEpsilon = -1; // must be overriden
@@ -4386,7 +4386,7 @@ void validate_envVarPermitNodesToShareGpu(string varValue, const char* caller) {
     // though caller should gaurantee varValue contains at least one character, 
     // we'll still check to avoid a segfault if this gaurantee is broken
     bool isValid = (varValue.size() == 1) && (varValue[0] == '0' || varValue[0] == '1');
-    assertThat(isValid, report::INVALID_PERMIT_NODES_TO_SHARE_GPU_ENV_VAR, caller);
+    assertThat(isValid, report::INVALID_QUEST_PERMIT_NODES_TO_SHARE_GPU_ENV_VAR, caller);
 }
 
 void validate_envVarDefaultValidationEpsilon(string varValue, const char* caller) {

tests/utils/config.cpp

@@ -47,30 +47,30 @@ int getIntEnvVarValueOrDefault(string name, int defaultValue) {
 
 int getNumQubitsInUnitTestedQuregs() {
 
-    static int value = getIntEnvVarValueOrDefault("TEST_NUM_QUBITS_IN_QUREG", 6);
+    static int value = getIntEnvVarValueOrDefault("QUEST_TEST_NUM_QUBITS_IN_QUREG", 6);
     return value;
 }
 
 int getMaxNumTestedQubitPermutations() {
 
-    static int value = getIntEnvVarValueOrDefault("TEST_MAX_NUM_QUBIT_PERMUTATIONS", 0);
+    static int value = getIntEnvVarValueOrDefault("QUEST_TEST_MAX_NUM_QUBIT_PERMUTATIONS", 0);
     return value;
 }
 
 int getMaxNumTestedSuperoperatorTargets() {
 
-    static int value = getIntEnvVarValueOrDefault("TEST_MAX_NUM_SUPEROP_TARGETS", 4);
+    static int value = getIntEnvVarValueOrDefault("QUEST_TEST_MAX_NUM_SUPEROP_TARGETS", 4);
     return value;
 }
 
 int getNumTestedMixedDeploymentRepetitions() {
 
-    static int value = getIntEnvVarValueOrDefault("TEST_NUM_MIXED_DEPLOYMENT_REPETITIONS", 10);
+    static int value = getIntEnvVarValueOrDefault("QUEST_TEST_NUM_MIXED_DEPLOYMENT_REPETITIONS", 10);
     return value;
 }
 
 bool getWhetherToTestAllDeployments() {
 
-    static bool value = getIntEnvVarValueOrDefault("TEST_ALL_DEPLOYMENTS", 1);
+    static bool value = getIntEnvVarValueOrDefault("QUEST_TEST_TRY_ALL_DEPLOYMENTS", 1);
     return value;
 }

tests/utils/config.hpp

@@ -33,7 +33,7 @@
 #if 0
 
     /// @envvardoc
-    const int TEST_NUM_QUBITS_IN_QUREG = 6;
+    const int QUEST_TEST_NUM_QUBITS_IN_QUREG = 6;
 
     /** @envvardoc
      * 
@@ -64,16 +64,16 @@
      * 
      * @author Tyson Jones
      */
-    const int TEST_MAX_NUM_QUBIT_PERMUTATIONS = 0;
+    const int QUEST_TEST_MAX_NUM_QUBIT_PERMUTATIONS = 0;
 
     /// @envvardoc
-    const int TEST_MAX_NUM_SUPEROP_TARGETS = 4;
+    const int QUEST_TEST_MAX_NUM_SUPEROP_TARGETS = 4;
 
     /// @envvardoc
-    const int TEST_ALL_DEPLOYMENTS = 1;
+    const int QUEST_TEST_TRY_ALL_DEPLOYMENTS = 1;
 
     /// @envvardoc
-    const int TEST_NUM_MIXED_DEPLOYMENT_REPETITIONS = 10;
+    const int QUEST_TEST_NUM_MIXED_DEPLOYMENT_REPETITIONS = 10;
 
 #endif