improving documentation, improving error handling

Signed-off-by: Alex McCaskey <mccaskeyaj@ornl.gov>

python/xacc-py.cpp

@@ -113,7 +113,7 @@ PYBIND11_MODULE(pyxacc, m) {
     f.def("addInstruction", &xacc::Function::addInstruction, "Add an Instruction to this Function.");
     f.def("nInstructions", &xacc::Function::nInstructions, "Return the number of Instructions in this Function.");
     f.def("getInstruction", &xacc::Function::getInstruction, "Return the instruction at the provided index.");
-    f.def("insertInstruction", &xacc::Function::insertInstruction, "");
+    f.def("insertInstruction", &xacc::Function::insertInstruction, "Insert an Instruction at the given index");
     f.def("getParameter", (InstructionParameter (xacc::Function::*)(const int)) &xacc::Function::getParameter, "");
 
     // Expose the IR interface
@@ -167,15 +167,16 @@ PYBIND11_MODULE(pyxacc, m) {
 			//py::overload_cast<const std::string&, const int>(
 					&xacc::Accelerator::createBuffer,
 			"Return a newly created register of qubits.");
-	acc.def("execute", (void (xacc::Accelerator::*)(std::shared_ptr<AcceleratorBuffer>, std::shared_ptr<Function>)) &xacc::Accelerator::execute, "");
+	acc.def("execute", (void (xacc::Accelerator::*)(std::shared_ptr<AcceleratorBuffer>, std::shared_ptr<Function>)) &xacc::Accelerator::execute, "Execute the Function with the given AcceleratorBuffer.");
+
 	// Expose the AcceleratorBuffer
 	py::class_<xacc::AcceleratorBuffer, std::shared_ptr<xacc::AcceleratorBuffer>> accb(m,
 			"AcceleratorBuffer", "The AcceleratorBuffer models a register of qubits.");
 	accb.def("printBuffer", (void (xacc::AcceleratorBuffer::*)()) &xacc::AcceleratorBuffer::print, "Print the AcceleratorBuffer to standard out.");
 	accb.def("getExpectationValueZ", &xacc::AcceleratorBuffer::getExpectationValueZ, "Return the expectation value with respect to the Z operator.");
 	accb.def("resetBuffer", &xacc::AcceleratorBuffer::resetBuffer, "Reset this buffer for use in another computation.");
-	accb.def("getMeasurementStrings", &xacc::AcceleratorBuffer::getMeasurementStrings, "");
-	accb.def("computeMeasurementProbability", &xacc::AcceleratorBuffer::computeMeasurementProbability, "");
+	accb.def("getMeasurementStrings", &xacc::AcceleratorBuffer::getMeasurementStrings, "Return observed measurement bit strings");
+	accb.def("computeMeasurementProbability", &xacc::AcceleratorBuffer::computeMeasurementProbability, "Compute the probability of a given bit string");
 
 	// Expose the Compiler
 	py::class_<xacc::Compiler, std::shared_ptr<xacc::Compiler>> compiler(m,
@@ -213,8 +214,8 @@ PYBIND11_MODULE(pyxacc, m) {
 	m.def("setOption", &xacc::setOption, "Set an XACC framework option.");
 	m.def("getOption", &xacc::getOption, "Get an XACC framework option.");
 	m.def("optionExists", &xacc::optionExists, "Set an XACC framework option.");
-	m.def("translate", &xacc::translate, "Translate one language quantum kernel to another");
-	m.def("translateWithVisitor", &xacc::translateWithVisitor, "Translate one language quantum kernel to another");
+//	m.def("translate", &xacc::translate, "Translate one language quantum kernel to another");
+//	m.def("translateWithVisitor", &xacc::translateWithVisitor, "Translate one language quantum kernel to another");
 	m.def("Finalize", &xacc::Finalize, "Finalize the framework");
 
 	py::module gatesub = m.def_submodule("gate", "Gate model quantum computing data structures.");
@@ -230,10 +231,6 @@ PYBIND11_MODULE(pyxacc, m) {
 	gateinst.def("setParameter", &xacc::quantum::GateInstruction::setParameter, "Set the parameter value at the give index");
 	gateinst.def("toString", &xacc::quantum::GateInstruction::toString, "Return the instruction as a string representation.");
 
-//	py::class_<xacc::quantum::GateInstructionRegistry, std::shared_ptr<xacc::quantum::GateInstructionRegistry>> gatereg(gatesub,
-//				"GateInstructionRegistry", "Registry of available quantum gates.");
-//	gatereg.def_static("instance", &xacc::quantum::GateInstructionRegistry::instance, "Singleton instance method.");
-//	gatereg.def("create", &xacc::quantum::GateInstructionRegistry::create, "Create");
 
 	py::class_<xacc::quantum::GateFunction, xacc::Function, std::shared_ptr<xacc::quantum::GateFunction>> gatefunction(gatesub, 
 			"GateFunction",
@@ -250,7 +247,7 @@ PYBIND11_MODULE(pyxacc, m) {
 	gateqir.def(py::init<>(), "The constructor");
 	gateqir.def("addKernel", &xacc::quantum::GateQIR::addKernel, "Add an Kernel to this GateQIR.");
 
-	gatesub.def("create", &create, "", py::arg("name"), py::arg("qbits"),
+	gatesub.def("create", &create, "Convenience function for creating a new GateInstruction.", py::arg("name"), py::arg("qbits"),
 			py::arg("params") = std::vector<InstructionParameter> { });
 
 	m.def("setCredentials", &setCredentials,

xacc/XACC.cpp

@@ -28,7 +28,7 @@ char** getArgv() {
 	return argv;
 }
 void Initialize(std::vector<std::string> argv) {
-	XACCInfo("Initializing the XACC Framework");
+	XACCLogger::instance()->info("Initializing the XACC Framework");
 	std::vector<char*> cstrs;
 	argv.insert(argv.begin(),"appExec");
 	for (auto& s : argv) {
@@ -60,6 +60,8 @@ void Initialize(int arc, char** arv) {
 		} catch (std::exception& e) {
 			XACCLogger::instance()->error("Failure initializing XACC Plugin Registry - " +
 					std::string(e.what()));
+			Finalize();
+			exit(-1);
 		}
 
 		// Parse any user-supplied command line options
@@ -104,6 +106,9 @@ void debug(const std::string& msg, MessagePredicate predicate) {
 
 void error(const std::string& msg, MessagePredicate predicate) {
 	XACCLogger::instance()->error(msg, predicate);
+	XACCLogger::instance()->error("Framework Exiting", predicate);
+	xacc::Finalize();
+	exit(-1);
 }
 
 void addCommandLineOption(const std::string& optionName,
@@ -303,7 +308,6 @@ void Finalize() {
 	info("");
 	info("[xacc::plugins] Cleaning up Plugin Registry.");
 	xacc::ServiceRegistry::instance()->destroy();
-//	XACCLogger::instance()->destroy();
 	xacc::xaccFrameworkInitialized = false;
 	info("[xacc] Finalizing XACC Framework.");
 }

xacc/XACC.hpp

@@ -42,17 +42,44 @@ extern char** argv;
  */
 void Initialize(int argc, char** argv);
 
+/**
+ * Return command line argc integer.
+ *
+ * @return argc The number of arguments on the command line
+ */
 int getArgc();
+
+/**
+ * Return the command line arguments
+ *
+ * @return argv The command line arguments
+ */
 char** getArgv();
 
+/**
+ * Initialize the framework with a vector of strings as arguments.
+ *
+ * @param argv Vector of string arguments
+ */
 void Initialize(std::vector<std::string> argv);
 
+/**
+ * Initialize the framework with no arguments
+ */
 void Initialize();
 
+/**
+ * Return if the framework has been initialized.
+ *
+ * @return initialized Bool indicating true if initialized
+ */
 bool isInitialized();
 
 /**
  * Add a valid command line option
+ *
+ * @param optionName The name of the string option
+ * @param optionDescription The description of the option
  */
 void addCommandLineOption(const std::string& optionName,
 		const std::string& optionDescription = "");
@@ -65,13 +92,49 @@ void addCommandLineOption(const std::string& optionName,
  */
 void addCommandLineOptions(const std::string& category, const std::map<std::string, std::string>& options);
 
+/**
+ * Add a set of options as a boost options_description object. This method
+ * gives clients the most flexibility to provide custom options.
+ *
+ * @param options The command line options
+ */
 void addCommandLineOptions(std::shared_ptr<options_description> options);
 
+/**
+ * Provide a predicate function that determines
+ * whether the XACCLogger should print logs.
+ *
+ * @param predicate Function with no arguments that returns bool
+ */
 void setGlobalLoggerPredicate(MessagePredicate predicate);
+
+/**
+ * Print an info log to the XACC Logger.
+ *
+ * @param msg The log to print
+ * @param predicate Function with no arguments that returns bool
+ */
 void info(const std::string& msg, MessagePredicate predicate = std::function<bool(void)>([]() {return true;}));
+
+/**
+ * Print an debug log to the XACC Logger.
+ *
+ * @param msg The log to print
+ * @param predicate Function with no arguments that returns bool
+ */
 void debug(const std::string& msg, MessagePredicate predicate = std::function<bool(void)>([]() {return true;}));
+
+/**
+ * Print an error log to the XACC Logger.
+ *
+ * @param msg The log to print
+ * @param predicate Function with no arguments that returns bool
+ */
 void error(const std::string& msg, MessagePredicate predicate = std::function<bool(void)>([]() {return true;}));
 
+/**
+ * Clear the options database
+ */
 void clearOptions();
 
 /**
@@ -113,22 +176,51 @@ void setAccelerator(const std::string& acceleratorName);
 
 /**
  * Return the Accelerator with given name
+ *
+ * @param name The name of the Accelerator
+ * @return accelerator The Accelerator
  */
 std::shared_ptr<Accelerator> getAccelerator(const std::string& name);
+
+/**
+ * Get the Accelerator that is currently specified by the
+ * 'accelerator' option key.
+ *
+ * @return accelerator The Accelerator
+ */
 std::shared_ptr<Accelerator> getAccelerator();
 
+/**
+ * Return true if the framework has an Accelerator
+ * with the given name.
+ *
+ * @param name Accelerator name
+ * @return exists Bool that's true if framework has given Accelerator
+ */
 bool hasAccelerator(const std::string& name);
 
 /**
  * Return the Compiler with given name
  */
 std::shared_ptr<Compiler> getCompiler(const std::string& name);
+
+/**
+ * Get the Compiler that is currently specified by the
+ * 'compiler' option key.
+ *
+ * @return compiler The Compiler
+ */
 std::shared_ptr<Compiler> getCompiler();
-bool hasCompiler(const std::string& name);
 
-/*
- * Return the IRTransformation with given name
+/**
+ * Return true if the framework has a Compiler
+ * with the given name.
+ *
+ * @param name Compiler name
+ * @return exists Bool that's true if framework has given Compiler
  */
+bool hasCompiler(const std::string& name);
+
 std::shared_ptr<IRTransformation> getIRTransformation(const std::string& name);
 
 const std::string translate(const std::string& original, const std::string& originalLanguageName,

xacc/accelerator/Accelerator.hpp

@@ -24,6 +24,7 @@
 #include "OptionsProvider.hpp"
 #include "Graph.hpp"
 #include "Identifiable.hpp"
+#include "Utils.hpp"
 
 namespace xacc {
 
@@ -148,7 +149,7 @@ public:
 			return allocatedBuffers[varid];
 		} else {
 			auto tmpBuffer = createBuffer(varid, 100);
-			XACCInfo("Could not find AcceleratorBuffer with id " + varid + ", creating one with 100 bits.");
+			XACCLogger::instance()->info("Could not find AcceleratorBuffer with id " + varid + ", creating one with 100 bits.");
 			storeBuffer(varid, tmpBuffer);
 			return tmpBuffer;
 		}

xacc/utils/ServiceRegistry.cpp

@@ -55,7 +55,7 @@ void ServiceRegistry::initialize() {
 			}
 
 		} else {
-			XACCInfo(
+			XACCLogger::instance()->enqueueLog(
 					"There are no plugins. Install plugins to begin working with XACC.");
 		}
 

xacc/utils/Utils.cpp

@@ -102,7 +102,7 @@ void XACCLogger::debug(const std::string& msg, MessagePredicate predicate) {
 	if (useCout) {
 		if (predicate() && globalPredicate()) {
 			if (useColor) {
-				std::cout << "\033[1;33m[XACC Debug] " + msg + "\033[0m \n";
+				std::cout << "\033[1;32m[XACC Debug] " + msg + "\033[0m \n";
 			} else {
 				std::cout << "[XACC Debug] " + msg + "\n";
 			}
@@ -120,13 +120,12 @@ void XACCLogger::debug(const std::string& msg, MessagePredicate predicate) {
 void XACCLogger::error(const std::string& msg, MessagePredicate predicate) {
 	if (useCout) {
 		if (predicate() && globalPredicate())
-			XACCError(msg);
+			std::cerr << msg << "\n";
 	} else {
 		if (predicate() && globalPredicate()) {
-			logger->error(msg);
+			logger->error("\033[1;31m[XACC Error] " + msg + "\033[0m");
 		}
 	}
-	XACCError(msg);
 }
 
 }

xacc/utils/Utils.hpp

@@ -51,56 +51,48 @@ void tuple_for_each(TupleType&& t, FunctionType f) {
 			std::integral_constant<size_t, 0>());
 }
 
-class XACCException: public std::exception {
-protected:
-
-	std::string errorMessage;
-
-public:
-
-	XACCException(std::string error) :
-			errorMessage(error) {
-//		if (RuntimeOptions::instance()->exists("use-cout")) {
-//			std::cout << errorMessage << "\n";
-//		} else {
-//			auto c = spdlog::get("xacc-logger");
-//			if (c) {
-//				c->error("\033[1;31m" + errorMessage + "\033[0m");
-//			}
+//class XACCException: public std::exception {
+//protected:
+//
+//	std::string errorMessage;
+//
+//public:
+//
+//	XACCException(std::string error) :
+//			errorMessage(error) {
+//	}
+//
+//	virtual const char * what() const throw () {
+//		return errorMessage.c_str();
+//	}
+//
+//	~XACCException() throw () {
+//	}
+//};
+//
+//#define XACC_Abort do {std::abort();} while(0);
+//
+//class XACCInfoT {
+//public:
+//	static void printInfo(const std::string& msg) {
+//		auto c = spdlog::get("xacc-console");
+//		if (c) {
+//			c->info("\033[1;34m" + msg + "\033[0m");
 //		}
-	}
-
-	virtual const char * what() const throw () {
-		return errorMessage.c_str();
-	}
-
-	~XACCException() throw () {
-	}
-};
-
-#define XACC_Abort do {std::abort();} while(0);
-
-class XACCInfoT {
-public:
-	static void printInfo(const std::string& msg) {
-		auto c = spdlog::get("xacc-console");
-		if (c) {
-			c->info("\033[1;34m" + msg + "\033[0m");
-		}
-	}
-};
-
-#define XACCError(errorMsg)												\
-	do {																\
-		using namespace xacc; 											\
-    	throw XACCException("\n\n XACC Error caught! \n\n"	 		    \
-            	+ std::string(errorMsg) + "\n\n");						\
-	} while(0)
-
-#define XACCInfo(infoMsg)												\
-	do {																\
-		xacc::XACCInfoT::printInfo(std::string(infoMsg));						\
-	} while(0)
+//	}
+//};
+//
+//#define XACCError(errorMsg)												\
+//	do {																\
+//		using namespace xacc; 											\
+//    	throw XACCException("\n\n XACC Error thrown! \n\n"	 		    \
+//            	+ std::string(errorMsg) + "\n\n");						\
+//	} while(0)
+//
+//#define XACCInfo(infoMsg)												\
+//	do {																\
+//		xacc::XACCInfoT::printInfo(std::string(infoMsg));						\
+//	} while(0)
 
 using MessagePredicate = std::function<bool(void)>;