From 550ad535fcca77b646b61e8b820cb6daf9f77360 Mon Sep 17 00:00:00 2001
From: Dmitry Vasilevsky <dmitryv@microsoft.com>
Date: Thu, 9 Sep 2021 18:48:55 -0700
Subject: [PATCH 1/2] Made unit tests work. Added comments

---
 .../SparseSimulator/Native/SparseSimulator.h    | 17 ++++++++++++++---
 .../SparseSimulatorTests.cpp                    |  9 ++++-----
 2 files changed, 18 insertions(+), 8 deletions(-)

diff --git a/src/Simulation/Simulators/SparseSimulator/Native/SparseSimulator.h b/src/Simulation/Simulators/SparseSimulator/Native/SparseSimulator.h
index aff67c6b7fd..5cce6e6b859 100644
--- a/src/Simulation/Simulators/SparseSimulator/Native/SparseSimulator.h
+++ b/src/Simulation/Simulators/SparseSimulator/Native/SparseSimulator.h
@@ -47,9 +47,17 @@ 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.
+// Zero coefficients are simply not stored.
+// It has good performance only when the number of non-zero coefficients is low.
+// It employs hashtable structure (by Malte Skarupke) to store non-zero coefficients.
+// Keys are basis vectors represented by std::bitset<>.
+// Values are amplitudes represented by std::complex<RealType>.
+// 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 +592,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);
 	}
diff --git a/src/Simulation/Simulators/SparseSimulator/SparseSimulatorTests/SparseSimulatorTests.cpp b/src/Simulation/Simulators/SparseSimulator/SparseSimulatorTests/SparseSimulatorTests.cpp
index c43956686e5..d3674644420 100644
--- a/src/Simulation/Simulators/SparseSimulator/SparseSimulatorTests/SparseSimulatorTests.cpp
+++ b/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,7 +67,7 @@ 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;
@@ -78,7 +75,9 @@ namespace SparseSimulatorTests
 				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);
 				}
 			}
 		}

From 5667211d0836ec14e55c29a73248368ca9bffeea Mon Sep 17 00:00:00 2001
From: Dmitry Vasilevsky <dmitryv@microsoft.com>
Date: Thu, 9 Sep 2021 21:30:27 -0700
Subject: [PATCH 2/2] Updated SparseSimulator comment

---
 .../Simulators/SparseSimulator/Native/SparseSimulator.h    | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/src/Simulation/Simulators/SparseSimulator/Native/SparseSimulator.h b/src/Simulation/Simulators/SparseSimulator/Native/SparseSimulator.h
index 5cce6e6b859..ecdde7c5fe2 100644
--- a/src/Simulation/Simulators/SparseSimulator/Native/SparseSimulator.h
+++ b/src/Simulation/Simulators/SparseSimulator/Native/SparseSimulator.h
@@ -48,11 +48,12 @@ std::shared_ptr<BasicQuantumState> expand_wfn_helper(std::shared_ptr<BasicQuantu
 }
 
 // Sparse simulator only stores non-zero coefficients of the quantum state.
-// Zero coefficients are simply not stored.
 // It has good performance only when the number of non-zero coefficients is low.
-// It employs hashtable structure (by Malte Skarupke) to store non-zero coefficients.
+// 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 amplitudes represented by std::complex<RealType>.
+// 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