Merge pull request #3 from sam-jaques/dmitryv/sparse-simulator-feedback-3

Unit tests, comments and feedback from review

Author: sam-jaques

src/Simulation/Simulators/SparseSimulator/Native/SparseSimulator.h

@@ -47,9 +47,18 @@ std::shared_ptr<BasicQuantumState> expand_wfn_helper(std::shared_ptr<BasicQuantu
 	return (nqubits > max_num_bits / 2) ? std::shared_ptr<BasicQuantumState>(new QuantumState<max_num_bits>(old_sim)): expand_wfn_helper<max_num_bits / 2>(old_sim, nqubits);
 }
 
+// Sparse simulator only stores non-zero coefficients of the quantum state.
+// It has good performance only when the number of non-zero coefficients is low.
+// If the number of non-zero coefficients is low, the number of qubits may be fairly large.
+// Sparse simulator employs hashtable structure (by Malte Skarupke) to store non-zero coefficients.
+// Keys are basis vectors represented by std::bitset<>.
+// Values are non-zero amplitudes represented by std::complex<RealType>.
+// Zero amplitudes are simply not stored.
+// Hashtable is reallocated and reconstructed on almost every gate.
+// Reallocation is saved for some gates that can be performed in one round.
 class SparseSimulator
 {
-public:
+public: 
 
 	std::set<std::string> operations_done;
 
@@ -584,13 +593,16 @@ class SparseSimulator
 		// as a phase/permutation gate
 		// This means if an assert fails, it will fail
 		// at some future point, not at the point of failure
-		#if NDEBUG
+		#if defined(NDEBUG)
 			if (isAllZ) {
 				_queued_operations.push_back(operation(OP::Assert, qubits, result));
+				// In release mode we queue Z assertion and return.
 				return;
 			}
 		#endif
-		// X or Y assertions require execution
+		// X or Y assertions require immediate execution.
+		// We also execute Z assertion immediately in debug mode
+		// to provide feedback at the point of failure.
 		_execute_queued_ops(qubits, OP::PermuteLarge);
 		_quantum_state->Assert(axes, qubits, result);
 	}

src/Simulation/Simulators/SparseSimulator/SparseSimulatorTests/SparseSimulatorTests.cpp

@@ -7,9 +7,6 @@
 #include "TestHelpers.hpp"
 #include <cmath>
 #include <iostream>
-#include <locale> // necessary for string conversions for logging
-#include <codecvt> // necessary for string conversions for logging
-#include <string> // necessary for string conversions for logging
 
 using namespace Microsoft::VisualStudio::CppUnitTestFramework;
 using namespace Microsoft::Quantum::SPARSESIMULATOR;
@@ -70,15 +67,17 @@ namespace SparseSimulatorTests
 			uint64_t k = 0;
 			qubit_label_type<num_qubits> label1(0);
 			qubit_label_type<num_qubits> label2(1);
-			std::wstring_convert<std::codecvt_utf8_utf16<wchar_t>> converter;
+
 			for (i = 0; i < 500; i++){
 				k += i * i * i * i;
 				uint64_t m = 0;
 				label1 = qubit_label_type<num_qubits>(k);
 				for (j = 0; j < 500; j++){
 					m += j * j * j * j;
 					label2 = qubit_label_type<num_qubits>(m);
-					Assert::AreEqual<bool>(k < m, label1 < label2, converter.from_bytes("Comparing " + std::to_string(k) + " to " + std::to_string(m) + "\n").c_str());
+					wchar_t message[100];
+					swprintf(message, sizeof(message)/sizeof(*message), L"Comparing %llu to %llu\n", k, m);
+					Assert::AreEqual<bool>(k < m, label1 < label2, message);
 				}
 			}
 		}