Updating documentation throughout, starting on QIR update

quantum/QIR.hpp

+/*
+ * QIR.hpp
+ *
+ *  Created on: Apr 12, 2017
+ *      Author: aqw
+ */
+
+#ifndef QUANTUM_QIR_HPP_
+#define QUANTUM_QIR_HPP_
+
+#include "IR.hpp"
+
+template<typename VertexType>
+class QIR : public virtual xacc::Graph<VertexType> {
+public:
+	virtual void generateGraph() = 0;
+	virtual ~QIR() {}
+};
+
+#endif /* QUANTUM_QIR_HPP_ */

quantum/gate/GateQIR.hpp

+/*
+ * GateQIR.hpp
+ *
+ *  Created on: Apr 12, 2017
+ *      Author: aqw
+ */
+
+#ifndef QUANTUM_GATE_GATEQIR_HPP_
+#define QUANTUM_GATE_GATEQIR_HPP_
+
+
+#include "QIR.hpp"
+#include "QuantumCircuit.hpp"
+
+class GateQIR : public virtual QIR<xacc::quantum::CircuitNode> {
+
+protected:
+
+	std::vector<QInstruction> instructions;
+
+	virtual ~GateQIR() {}
+};
+
+
+#endif

quantum/gate/ir/QFunction.hpp

+/*
+ * QFunction.hpp
+ *
+ *  Created on: Apr 12, 2017
+ *      Author: aqw
+ */
+
+#ifndef QUANTUM_GATE_IR_QFUNCTION_HPP_
+#define QUANTUM_GATE_IR_QFUNCTION_HPP_
+
+#include "QInstruction.hpp"
+
+class QFunction : public virtual QInstruction {
+
+protected:
+
+protected:
+
+	std::string name;
+
+	int layer;
+
+	std::vector<int> qbits;
+
+	std::vector<std::shared_ptr<QInstruction>> instructions;
+
+public:
+
+	virtual std::string getName() {
+		return name;
+	}
+
+	virtual int layer() {
+		return 0;
+	}
+
+	virtual std::vector<int> qubits() {
+		return qbits;
+	}
+
+	virtual void addInstruction(std::shared_ptr<QInstruction> inst) {
+		instructions.push_back(inst);
+	}
+};
+
+#endif /* QUANTUM_GATE_IR_QFUNCTION_HPP_ */

quantum/gate/ir/QInstruction.hpp

+/*
+ * QInstruction.hpp
+ *
+ *  Created on: Apr 12, 2017
+ *      Author: aqw
+ */
+
+#ifndef QUANTUM_GATE_IR_QINSTRUCTION_HPP_
+#define QUANTUM_GATE_IR_QINSTRUCTION_HPP_
+
+#include <string>
+#include <vector>
+
+class QInstruction {
+public:
+	virtual std::string getName() = 0;
+	virtual int layer() = 0;
+	virtual std::vector<int> qubits() = 0;
+	virtual ~QInstruction() {}
+};
+
+#endif

quantum/gate/ir/QInstructionVisitor.hpp

+/*
+ * QInstructionVisitor.hpp
+ *
+ *  Created on: Apr 12, 2017
+ *      Author: aqw
+ */
+
+#ifndef QUANTUM_GATE_IR_QINSTRUCTIONVISITOR_HPP_
+#define QUANTUM_GATE_IR_QINSTRUCTIONVISITOR_HPP_
+
+#include "QInstruction.hpp"
+#include "Hadamard.hpp"
+#include "CNOT.hpp"
+#include "Rz.hpp"
+
+class QInstructionVisitor {
+public:
+	virtual void visit(QFunction* function) = 0;
+	virtual void visit(Hadamard* function) = 0;
+	virtual void visit(CNOT* function) = 0;
+	virtual void visit(Rz* function) = 0;
+	virtual ~QInstructionVisitor() {}
+};
+
+
+
+#endif /* QUANTUM_GATE_IR_QINSTRUCTIONVISITOR_HPP_ */

quantum/gate/ir/instructions/CNOT.hpp

+/*
+ * CNOT.hpp
+ *
+ *  Created on: Apr 12, 2017
+ *      Author: aqw
+ */
+
+#ifndef QUANTUM_GATE_IR_INSTRUCTIONS_CNOT_HPP_
+#define QUANTUM_GATE_IR_INSTRUCTIONS_CNOT_HPP_
+
+#include "QInstruction.hpp"
+
+class CNOT : public virtual QInstruction {
+
+};
+
+
+#endif /* QUANTUM_GATE_IR_INSTRUCTIONS_CNOT_HPP_ */

quantum/gate/ir/instructions/Hadamard.hpp

+/*
+ * Hadamard.hpp
+ *
+ *  Created on: Apr 12, 2017
+ *      Author: aqw
+ */
+
+#ifndef QUANTUM_GATE_IR_HADAMARD_HPP_
+#define QUANTUM_GATE_IR_HADAMARD_HPP_
+
+#include "QInstruction.hpp"
+
+class Hadamard : public virtual QInstruction {
+
+};
+
+
+
+#endif /* QUANTUM_GATE_IR_HADAMARD_HPP_ */

quantum/gate/ir/instructions/Rz.hpp

+/*
+ * Rz.hpp
+ *
+ *  Created on: Apr 12, 2017
+ *      Author: aqw
+ */
+
+#ifndef QUANTUM_GATE_IR_INSTRUCTIONS_RZ_HPP_
+#define QUANTUM_GATE_IR_INSTRUCTIONS_RZ_HPP_
+
+
+#include "QInstruction.hpp"
+
+class Rz : public virtual QInstruction {
+
+};
+
+
+
+#endif /* QUANTUM_GATE_IR_INSTRUCTIONS_RZ_HPP_ */

xacc/accelerator/Accelerator.hpp

@@ -63,7 +63,13 @@ enum AcceleratorType {
  * instances that transform XACC IR to be amenable to execution
  * on the hardware.
  *
- * STORE ALLOCATED BUFFERS
+ * Derived Accelerators must provide implementations of createBuffer
+ * that provide a valid AcceleratorBuffer instance modeling the
+ * hardware memory or bits being computed on. Upon creating an
+ * AcceleratorBuffer, derived Accelerator implementations must
+ * call the protected storeBuffer method to store the AcceleratorBuffer
+ * for future reference by Compilers and clients of Accelerator.
+ *
  */
 class Accelerator {
 
@@ -84,18 +90,47 @@ public:
 	virtual std::vector<IRTransformation> getIRTransformations() = 0;
 
 	/**
-	 * Execute the provided XACC IR on this attached Accelerator.
+	 * Execute the provided XACC IR on the provided AcceleratorBuffer.
 	 *
+	 * @param buffer
 	 * @param ir
 	 */
 	virtual void execute(std::shared_ptr<AcceleratorBuffer> buffer,
 			const std::shared_ptr<IR> ir) = 0;
 
-	virtual std::shared_ptr<AcceleratorBuffer> createBuffer(const std::string& varId) = 0;
+	/**
+	 * Create, store, and return an AcceleratorBuffer with the given
+	 * variable id string. This string serves as a unique identifier
+	 * for future lookups and reuse of the AcceleratorBuffer.
+	 *
+	 * @param varId
+	 * @return
+	 */
+	virtual std::shared_ptr<AcceleratorBuffer> createBuffer(
+			const std::string& varId) = 0;
 
-	virtual std::shared_ptr<AcceleratorBuffer> createBuffer(const std::string& varId, const int size) = 0;
+	/**
+	 * Create, store, and return an AcceleratorBuffer with the given
+	 * variable id string and of the given number of bits.
+	 * The string id serves as a unique identifier
+	 * for future lookups and reuse of the AcceleratorBuffer.
+	 *
+	 * @param varId
+	 * @param size
+	 * @return
+	 */
+	virtual std::shared_ptr<AcceleratorBuffer> createBuffer(
+			const std::string& varId, const int size) = 0;
 
-	virtual std::shared_ptr<AcceleratorBuffer> getBuffer(const std::string& varid) {
+	/**
+	 * Return the stored AcceleratorBuffer with the provided
+	 * string id.
+	 *
+	 * @param varid
+	 * @return
+	 */
+	virtual std::shared_ptr<AcceleratorBuffer> getBuffer(
+			const std::string& varid) {
 		if (isValidBuffer(varid)) {
 			return allocatedBuffers[varid];
 		} else {
@@ -103,6 +138,12 @@ public:
 		}
 	}
 
+	/**
+	 * Return true if this Accelerator can allocated
+	 * NBits number of bits.
+	 * @param NBits
+	 * @return
+	 */
 	virtual bool isValidBufferSize(const int NBits) = 0;
 
 	/**
@@ -113,21 +154,52 @@ public:
 
 protected:
 
-	void storeBuffer(const std::string& id, std::shared_ptr<AcceleratorBuffer> b) {
+	/**
+	 * This protected method is to be used by derived
+	 * Accelerators to store any created AcceleratorBuffer.
+	 *
+	 * @param id
+	 * @param b
+	 */
+	void storeBuffer(const std::string& id,
+			std::shared_ptr<AcceleratorBuffer> b) {
 		allocatedBuffers.insert(std::make_pair(id, b));
 	}
 
 private:
 
+	/**
+	 * The mapping of string ids to created AcceleratorBuffers.
+	 */
 	std::map<std::string, std::shared_ptr<AcceleratorBuffer>> allocatedBuffers;
 
+	/**
+	 * Private utility method to indicate whether there exists
+	 * an AcceleratorBuffer with the provided string id.
+	 * @param str
+	 * @return
+	 */
 	bool isValidBuffer(const std::string& str) {
 		return allocatedBuffers.find(str) != allocatedBuffers.end();
 	}
 
 };
 
+/**
+ * Create an alias for a Registry of Accelerators.
+ */
 using AcceleratorRegistry = Registry<Accelerator>;
+
+/**
+ * RegisterAccelerator is a convenience class for
+ * registering custom derived Accelerator classes.
+ *
+ * Creators of Accelerator subclasses create an instance
+ * of this class with their Accelerator subclass as the template
+ * parameter to register their Accelerator with XACC. This instance
+ * must be created in the CPP implementation file for the Accelerator
+ * and at global scope.
+ */
 template<typename T>
 class RegisterAccelerator {
 public:

xacc/compiler/Compiler.hpp

@@ -40,36 +40,55 @@
 namespace xacc {
 
 /**
- *
+ * The Compiler class provides an extensible interface
+ * for injecting custom compilation mechanisms into the
+ * XACC framework. Implementations provide a compile method
+ * that takes the kernel source code string, performs
+ * compiler-specific compilation mechanism, and returns a valid
+ * XACC IR instance modeling the result of the compilation.
  */
 class Compiler {
 
 public:
 
 	/**
-	 * The Compiler.compile method is in charge of modifying
-	 * the source code to be amenable to compilation by derived
-	 * types.
+	 * This method is to be implemented by derived Compilers
+	 * and is in charge of executing the compilation mechanism
+	 * on the provided source string. Implementations also are
+	 * given access to the Accelerator that this source code is
+	 * intended for.
 	 *
 	 * @param src The kernel source string.
+	 * @param acc The Accelerator this code will be executed on
 	 * @return ir Intermediate representation for provided source kernel code.
 	 */
 	virtual std::shared_ptr<IR> compile(const std::string& src,
 			std::shared_ptr<Accelerator> acc) = 0;
 
+	/**
+	 * This method is to be implemented by derived Compilers
+	 * and is in charge of executing the compilation mechanism
+	 * on the provided source string.
+	 * @param src
+	 * @return
+	 */
 	virtual std::shared_ptr<IR> compile(const std::string& src) = 0;
 
+	/**
+	 * The destructor
+	 */
 	virtual ~Compiler() {}
 
 protected:
 
 	/**
-	 *
+	 * Reference to the provided kernel source code string
 	 */
 	std::string kernelSource;
 
 	/**
-	 *
+	 * Reference to the Accelerator that this compiler is
+	 * targeting.
 	 */
 	std::shared_ptr<Accelerator> accelerator;
 };
@@ -81,9 +100,14 @@ protected:
 using CompilerRegistry = Registry<Compiler>;
 
 /**
- * The RegisterCompiler class simply provides
- * a convenience constructor that adds the provided template
- * parameter type to the CompilerRegistry.
+ * RegisterCompiler is a convenience class for
+ * registering custom derived Compiler classes.
+ *
+ * Creators of Compiler subclasses create an instance
+ * of this class with their Compiler subclass as the template
+ * parameter to register their Compiler with XACC. This instance
+ * must be created in the CPP implementation file for the Compiler
+ * and at global scope.
  */
 template<typename T>
 class RegisterCompiler {

xacc/program/Program.hpp

@@ -48,15 +48,19 @@ using namespace boost::program_options;
 
 namespace xacc {
 
+/**
+ * Placeholder, soon we will have Acc Independent transformations...
+ * @param accType
+ * @return
+ */
 std::vector<IRTransformation> getAcceleratorIndependentTransformations(
 		AcceleratorType& accType) {
 	std::vector<IRTransformation> transformations;
-
 	return transformations;
 }
 
 /**
- * The Program is  the main entrypoint for the XACC
+ * The Program is the main entrypoint for the XACC
  * API. Users with accelerator kernels must construct a
  * valid Program to be compiled and executed on the
  * attached accelerator. Programs must be given the
@@ -86,13 +90,16 @@ protected:
 	std::shared_ptr<options_description> compilerOptions;
 
 	/**
-	 *
+	 * Reference to the XACC IR instance that is
+	 * created by the Compiler
 	 */
 	std::shared_ptr<IR> xaccIR;
 
+	/**
+	 * Reference to the compiler
+	 */
 	std::shared_ptr<Compiler> compiler;
 
-
 	/**
 	 * Execute the compilation mechanism on the provided program
 	 * source kernel code to produce XACC IR that can be executed
@@ -129,7 +136,8 @@ protected:
 
 		// Execute IR Translations
 		auto acceleratorType = accelerator->getType();
-		auto defaultTransforms = getAcceleratorIndependentTransformations(acceleratorType);
+		auto defaultTransforms = getAcceleratorIndependentTransformations(
+				acceleratorType);
 		auto accDepTransforms = accelerator->getIRTransformations();
 		for (IRTransformation& t : defaultTransforms) {
 			t.transform(*xaccIR.get());
@@ -164,18 +172,22 @@ public:
 				"XACC Compiler Options");
 		compilerOptions->add_options()("help", "Help Message")("compiler",
 				value<std::string>()->default_value("scaffold"),
-				"Indicate the compiler to be used.")
-				("writeIR", value<std::string>(), "Persist generated IR to provided file name.");
+				"Indicate the compiler to be used.")("writeIR",
+				value<std::string>(),
+				"Persist generated IR to provided file name.");
 	}
 
 	/**
+	 * Return an executable version of the quantum kernel
+	 * referenced by the kernelName string.
 	 *
 	 * @param name
 	 * @param args
 	 * @return
 	 */
 	template<typename ... RuntimeArgs>
-	std::function<void(std::shared_ptr<AcceleratorBuffer>, RuntimeArgs...)> getKernel(const std::string& kernelName) {
+	std::function<void(std::shared_ptr<AcceleratorBuffer>, RuntimeArgs...)> getKernel(
+			const std::string& kernelName) {
 		return [&](std::shared_ptr<AcceleratorBuffer> buffer, RuntimeArgs... args) {
 			build("--compiler scaffold", args...);
 			accelerator->execute(buffer, xaccIR);