Adding documentation to Accelerator, removing ExecutionQueue and IROptimization

examples/quantum/gate/teleport_scaffold.cpp

@@ -79,7 +79,7 @@ int main (int argc, char** argv) {
 	// Create a reference to the IBM5Qubit Accelerator
 	auto ibm_qpu = std::make_shared<IBM5Qubit>();
 
-	// Allocate some qubits...
+	// Allocate some qubits, give them a unique identifier...
 	auto qreg = ibm_qpu->allocate<xacc::quantum::Qubits<3>>("qreg");
 
 	// Construct a new Program

quantum/gate/CMakeLists.txt

@@ -28,7 +28,10 @@
 #   Initial API and implementation - Alex McCaskey
 #
 #**********************************************************************************/
-add_subdirectory(scaffold)
+include_directories(${CMAKE_CURRENT_SOURCE_DIR}/utils)
+
+add_subdirectory(compilers)
+add_subdirectory(accelerators)
 add_subdirectory(utils)
 
 # Gather tests

quantum/gate/accelerators/CMakeLists.txt

+#***********************************************************************************
+# Copyright (c) 2016, UT-Battelle
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#   * Redistributions of source code must retain the above copyright
+#     notice, this list of conditions and the following disclaimer.
+#   * Redistributions in binary form must reproduce the above copyright
+#     notice, this list of conditions and the following disclaimer in the
+#     documentation and/or other materials provided with the distribution.
+#   * Neither the name of the xacc nor the
+#     names of its contributors may be used to endorse or promote products
+#     derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
+# DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+# Contributors:
+#   Initial API and implementation - Alex McCaskey
+#
+#**********************************************************************************/
+#add_subdirectory(compilers)
+#add_subdirectory(accelerators)
+#add_subdirectory(utils)
+
+# Gather tests
+#file (GLOB test_files tests/*.cpp)
+#add_tests("${test_files}" "${CMAKE_CURRENT_SOURCE_DIR}/utils;${CMAKE_CURRENT_SOURCE_DIR}" "${Boost_LIBRARIES}")
+

quantum/gate/compilers/CMakeLists.txt

+#***********************************************************************************
+# Copyright (c) 2016, UT-Battelle
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#   * Redistributions of source code must retain the above copyright
+#     notice, this list of conditions and the following disclaimer.
+#   * Redistributions in binary form must reproduce the above copyright
+#     notice, this list of conditions and the following disclaimer in the
+#     documentation and/or other materials provided with the distribution.
+#   * Neither the name of the xacc nor the
+#     names of its contributors may be used to endorse or promote products
+#     derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
+# DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+# Contributors:
+#   Initial API and implementation - Alex McCaskey
+#
+#**********************************************************************************/
+add_subdirectory(scaffold)
+
+# Gather tests
+#file (GLOB test_files tests/*.cpp)
+#add_tests("${test_files}" "${CMAKE_CURRENT_SOURCE_DIR}/utils;${CMAKE_CURRENT_SOURCE_DIR}" "${Boost_LIBRARIES}")
+

xacc/accelerator/Accelerator.hpp

@@ -38,11 +38,36 @@
 
 namespace xacc {
 
+/**
+ * The AcceleratorBits class provides a common
+ * base class for allocating accelerator-specific
+ * bit resources (for example, qubits). It takes an
+ * integer template parameter at construction that indicates
+ * the number of bits this AcceleratorBits models.
+ *
+ * Derived Accelerators should define a subclass of this
+ * class that models the hardware.
+ *
+ * @author Alex McCaskey
+ */
 template<const int Number>
 class AcceleratorBits {
 public:
+	/**
+	 * Reference to the number of bits
+	 */
 	static constexpr int N = Number;
+private:
+
+	/**
+	 *  The bits themselves
+	 */
 	std::bitset<(size_t)Number> bits;
+
+	/**
+	 * Return the current state of the bits
+	 * @return
+	 */
 	std::bitset<(size_t)Number> toBits() {
 		return bits;
 	}
@@ -50,22 +75,52 @@ public:
 };
 
 /**
+ * The Accelerator class provides a high-level abstraction
+ * for XACC's interaction with attached post-exascale
+ * accelerators (quantum and neuromorphic processing units).
+ *
+ * Derived Accelerators must provide a valid execute implementation
+ * that takes XACC IR and executes it on the attached hardware or
+ * simulator.
  *
+ * Derived Accelerators must provide a list of IRTransformation
+ * instances that transform XACC IR to be amenable to execution
+ * on the hardware.
  */
 class Accelerator {
 
 public:
+
+	/**
+	 * The types of Accelerators that XACC interacts with
+	 */
 	enum AcceleratorType { qpu_gate, qpu_aqc, npu };
 
+	/**
+	 * Return the type of this Accelerator.
+	 *
+	 * @return type The Accelerator type - Gate or AQC QPU, or NPU
+	 */
 	virtual AcceleratorType getType() = 0;
 
+	/**
+	 * Return any IR Transformations that must be applied to ensure
+	 * the compiled IR is amenable to execution on this Accelerator.
+	 * @return
+	 */
 	virtual std::vector<IRTransformation> getIRTransformations() = 0;
 
+	/**
+	 * Execute the provided XACC IR on this attached Accelerator.
+	 *
+	 * @param ir
+	 */
 	virtual void execute(const std::shared_ptr<IR> ir) = 0;
 
 	/**
+	 * Allocate bit resources (if needed).
 	 *
-	 * @return
+	 * @return bits The AcceleratorBits derived type
 	 */
 	template<typename BitsType>
 	BitsType allocate(const std::string& variableNameId) {
@@ -79,22 +134,50 @@ public:
 		return bits;
 	}
 
+	/**
+	 * Return the number of bits that the user most recently
+	 * requested.
+	 *
+	 * @return nBits The number of requested bits
+	 */
 	virtual int getAllocationSize() {
 		return NBitsAllocated;
 	}
 
+	/**
+	 * Return the variable name provided upon bit allocation
+	 * (for example - qreg for gate model quantum bits in (qbit qreg[2];))
+	 *
+	 * @return varName The name of the bits allocated.
+	 */
 	virtual const std::string getVariableName() {
 		return bitVarId;
 	}
 
+	/**
+	 * Destructor
+	 */
 	virtual ~Accelerator() {}
 
 protected:
 
+	/**
+	 * The number of bits allocated upon the most
+	 * recent user request for bit resources.
+	 */
 	int NBitsAllocated = 0;
 
+	/**
+	 * The variable name of the bits
+	 */
 	std::string bitVarId;
 
+	/**
+	 * Return true if this Accelerator can allocate
+	 * the provided number of bits.
+	 * @param NBits The number of bits to allocate
+	 * @return canAllocate True if can allocate, false if not.
+	 */
 	virtual bool canAllocate(const int NBits) = 0;
 };
 }

xacc/accelerator/ExecutionQueue.hpp

-#ifndef XACC_ACCELERATOR_EXECUTIONQUEUE_HPP_
-#define XACC_ACCELERATOR_EXECUTIONQUEUE_HPP_
-
-#include "Kernel.hpp"
-
-namespace xacc {
-/**
- *
- */
-class ExecutionQueue {
-
-protected:
-
-	std::queue<Kernel> execQueue;
-
-public:
-
-	enum execType {
-		ASYNC, SYNC
-	};
-
-	void enqueueKernel(Kernel k) {
-		execQueue.push(k);
-	}
-
-	template<typename T>
-	T execute(std::string, execType type, std::string accExecOpts) {
-
-	}
-};
-}
-
-#endif

xacc/compiler/IROptimization.hpp

-/***********************************************************************************
- * Copyright (c) 2016, UT-Battelle
- * All rights reserved.
- *
- * Redistribution and use in source and binary forms, with or without
- * modification, are permitted provided that the following conditions are met:
- *   * Redistributions of source code must retain the above copyright
- *     notice, this list of conditions and the following disclaimer.
- *   * Redistributions in binary form must reproduce the above copyright
- *     notice, this list of conditions and the following disclaimer in the
- *     documentation and/or other materials provided with the distribution.
- *   * Neither the name of the <organization> nor the
- *     names of its contributors may be used to endorse or promote products
- *     derived from this software without specific prior written permission.
- *
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
- * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
- * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
- * DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
- * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
- * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
- * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
- * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
- * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- *
- * Contributors:
- *   Initial API and implementation - Alex McCaskey
- *
- **********************************************************************************/
-#ifndef XACC_COMPILER_IROPTIMIZATION_HPP_
-#define XACC_COMPILER_IROPTIMIZATION_HPP_
-
-#include "IR.hpp"
-
-namespace xacc {
-
-class IROptimization {
-public:
-	virtual void optimize(IR& ir) = 0;
-	virtual ~IROptimization() {}
-};
-
-}
-#endif

xacc/program/Program.hpp

@@ -80,6 +80,9 @@ protected:
 	 */
 	std::shared_ptr<options_description> compilerOptions;
 
+	/**
+	 *
+	 */
 	std::shared_ptr<IR> xaccIR;
 
 public: