Commit 1b12739f authored by Mccaskey, Alex's avatar Mccaskey, Alex
Browse files

Adding documentation throughout

parent 2cbbd456
/***********************************************************************************
* Copyright (c) 2016, UT-Battelle
* Copyright (c) 2017, UT-Battelle
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
......
/***********************************************************************************
* Copyright (c) 2016, UT-Battelle
* Copyright (c) 2017, UT-Battelle
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
......@@ -34,6 +34,7 @@ const std::string src("__qpu__ qft (qbit qreg) {\n"
" // Testing out new Kernel\n"
" // Replacement Preprocessor!\n"
" xacc::QFT(qreg);\n"
" xacc::InverseQFT(qreg);\n"
"}\n");
int main (int argc, char** argv) {
......
/***********************************************************************************
* Copyright (c) 2017, 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
*
**********************************************************************************/
#include "KernelReplacementPreprocessor.hpp"
#include <boost/algorithm/string.hpp>
#include "AlgorithmGenerator.hpp"
......@@ -58,7 +88,8 @@ const std::string KernelReplacementPreprocessor::process(const std::string& sour
auto translation = compiler->translate(bufName, algoKernel);
boost::replace_all(translation, "\n", "\n ");
boost::replace_all(translation, "\n", "\n "
"");
boost::replace_all(newSource, funcString, translation);
}
......
/***********************************************************************************
* Copyright (c) 2017, 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
*
**********************************************************************************/
#ifndef XACC_COMPILER_KERNELREPLACEMENTPREPROCESSOR_HPP_
#define XACC_COMPILER_KERNELREPLACEMENTPREPROCESSOR_HPP_
......@@ -8,6 +38,20 @@ namespace xacc {
namespace quantum {
/**
* The KernelReplacementPreprocessor is a preprocessor
* for gate model quantum computing that analyzing
* quantum kernel source code and looks for occurrences
* of 'xacc::FUNCTION' strings (for example, xacc::QFT(qreg)).
*
* Once one of these occurrences is found, this preprocessor
* queries the AlgorithmGenerator Registry for any available
* AlgorithmGenerators with that name. If such an AlgorithmGenerator
* exists, it generates the XACC IR instance for that algorithm,
* translates the IR to the Compiler's source code representation,
* and replaces the 'xacc::FUNCTION' occurrence with the
* new source code.
*/
class KernelReplacementPreprocessor : public xacc::Preprocessor {
public:
......@@ -15,9 +59,8 @@ public:
KernelReplacementPreprocessor();
/**
* This method is to be implemented by subclasses to take in a
* kernel source string and process it in an isomorphic manner, and
* returns the processed source code.
* This method replaces xacc::FUNCTION references with actual
* Compiler-specific source code.
*
* @param src The unprocessed kernel source code
* @param compiler The compiler being used to compile the code
......@@ -37,8 +80,6 @@ public:
return "kernel-replacement";
}
virtual ~KernelReplacementPreprocessor() {}
};
}
......
/***********************************************************************************
* Copyright (c) 2016, UT-Battelle
* Copyright (c) 2017, UT-Battelle
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
......
......@@ -5,11 +5,27 @@
namespace xacc{
namespace quantum {
/**
* InverseQFT is a realization of the AlgorithmGenerator
* interface that produces an XACC IR representation
* of the Inverse Quantum Fourier Transform.
*/
class InverseQFT : public AlgorithmGenerator {
public:
/**
* This implementation returns a Function IR representation
* of the inverse quantum fourier transform.
*
* @param bits The bits this algorithm operates on
* @return function The algorithm represented as an IR Function
*/
virtual std::shared_ptr<Function> generateAlgorithm(std::vector<int> qubits);
/**
* The destructor
*/
virtual ~InverseQFT() {}
};
}
......
/*
* QFT.hpp
/***********************************************************************************
* Copyright (c) 2017, UT-Battelle
* All rights reserved.
*
* Created on: Jul 1, 2017
* Author: aqw
*/
* 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
*
**********************************************************************************/
#ifndef QUANTUM_GATE_IR_ALGORITHMS_QFT_HPP_
#define QUANTUM_GATE_IR_ALGORITHMS_QFT_HPP_
......@@ -12,11 +35,29 @@
namespace xacc{
namespace quantum {
/**
* QFT is a realization of the AlgorithmGenerator
* interface that produces an XACC IR representation
* of the Quantum Fourier Transform.
*
* @author Alex McCaskey
*/
class QFT : public AlgorithmGenerator {
public:
/**
* This implementation returns a Function IR representation
* of the quantum fourier transform.
*
* @param bits The bits this algorithm operates on
* @return function The algorithm represented as an IR Function
*/
virtual std::shared_ptr<Function> generateAlgorithm(std::vector<int> qubits);
/**
* The destructor
*/
virtual ~QFT() {}
};
}
......
......@@ -72,6 +72,7 @@ enum AcceleratorType {
* call the protected storeBuffer method to store the AcceleratorBuffer
* for future reference by Compilers and clients of Accelerator.
*
* @author Alex McCaskey
*/
class Accelerator : public OptionsProvider {
......@@ -87,15 +88,16 @@ public:
/**
* Return any IR Transformations that must be applied to ensure
* the compiled IR is amenable to execution on this Accelerator.
* @return
*
* @return transformations The IR transformations this Accelerator exposes
*/
virtual std::vector<IRTransformation> getIRTransformations() = 0;
/**
* Execute the provided XACC IR Function on the provided AcceleratorBuffer.
*
* @param buffer
* @param ir
* @param buffer The buffer of bits this Accelerator should operate on.
* @param function The kernel to execute.
*/
virtual void execute(std::shared_ptr<AcceleratorBuffer> buffer,
const std::shared_ptr<Function> function) = 0;
......@@ -106,9 +108,9 @@ public:
* The string id serves as a unique identifier
* for future lookups and reuse of the AcceleratorBuffer.
*
* @param varId
* @param size
* @return
* @param varId The variable name of the created buffer
* @param size The number of bits in the created buffer
* @return buffer The buffer instance created.
*/
virtual std::shared_ptr<AcceleratorBuffer> createBuffer(
const std::string& varId, const int size) = 0;
......@@ -117,8 +119,8 @@ public:
* Return the stored AcceleratorBuffer with the provided
* string id.
*
* @param varid
* @return
* @param varid The variable name of the created buffer
* @return buffer The buffer with given varid.
*/
virtual std::shared_ptr<AcceleratorBuffer> getBuffer(
const std::string& varid) {
......@@ -142,13 +144,6 @@ public:
return names;
}
/**
* Return true if this Accelerator can allocated
* NBits number of bits.
* @param NBits
* @return
*/
virtual bool isValidBufferSize(const int NBits) = 0;
/**
* Return an empty options_description, this is for
......@@ -166,12 +161,22 @@ public:
protected:
/**
* Return true if this Accelerator can allocated
* NBits number of bits. This is meant to be implemented
* and used by subclasses.
*
* @param NBits The number of bits to allocate
* @return valid True if size is valid.
*/
virtual bool isValidBufferSize(const int NBits) = 0;
/**
* This protected method is to be used by derived
* Accelerators to store any created AcceleratorBuffer.
*
* @param id
* @param b
* @param id The variable name of the buffer to store
* @param b The buffer to store
*/
void storeBuffer(const std::string& id,
std::shared_ptr<AcceleratorBuffer> b) {
......
......@@ -86,6 +86,10 @@ protected:
};
/**
* The AcceleratorBuffer models an allocated buffer of
* bits that are operated on by a kernel. As such,
* the AcceleratorBuffer's primary role is to store
* Accelerator execution results.
*
* @author Alex McCaskey
*/
......@@ -93,6 +97,9 @@ class AcceleratorBuffer {
public:
/**
* The Constructor
*/
AcceleratorBuffer(const std::string& str, const int N) :
bufferId(str), bits(std::vector<AcceleratorBit>(N)) {
}
......
/***********************************************************************************
* Copyright (c) 2017, 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
*
**********************************************************************************/
#ifndef XACC_COMPILER_PREPROCESSOR_HPP_
#define XACC_COMPILER_PREPROCESSOR_HPP_
......@@ -6,13 +36,17 @@
namespace xacc {
/**
* The Preprocessor interface provides a mechanism for
* processing quantum kernel source code before
* compilation takes place. Realizations of this interface
* implement the process method which takes as input the
* source code to process, and the compiler and accelerator
* this code is targeted at.
*
*/
class Preprocessor : public OptionsProvider {
public:
Preprocessor() {}
/**
* This method is to be implemented by subclasses to take in a
* kernel source string and process it in an isomorphic manner, and
......
/***********************************************************************************
* Copyright (c) 2017, 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
*
**********************************************************************************/
#ifndef IR_ALGORITHMS_ALGORITHMGENERATOR_HPP_
#define IR_ALGORITHMS_ALGORITHMGENERATOR_HPP_
......@@ -6,16 +36,33 @@
namespace xacc {
/**
* The AlgorithmGenerator interface provides a mechanism for
* generating algorithms modeled as an XACC Function instance.
*
* @author Alex McCaskey
*/
class AlgorithmGenerator {
public:
virtual std::shared_ptr<Function> generateAlgorithm(std::vector<int> qubits) = 0;
/**
* Implementations of this method generate a Function IR
* instance corresponding to the implementation's modeled
* algorithm. The algorithm is specified to operate over the
* provided bits.
*
* @param bits The bits this algorithm operates on
* @return function The algorithm represented as an IR Function
*/
virtual std::shared_ptr<Function> generateAlgorithm(std::vector<int> bits) = 0;
/**
* The destructor
*/
virtual ~AlgorithmGenerator() {}
};
using AlgorithmGeneratorRegistry = Registry<AlgorithmGenerator>;
/**
......
......@@ -41,6 +41,8 @@ using InstPtr = std::shared_ptr<Instruction>;
/**
* The Function is an Instruction that contains further
* child Instructions.
*
* @author Alex McCaskey
*/
class Function : public virtual Instruction {
public:
......@@ -108,12 +110,14 @@ public:
virtual bool isComposite() { return true; }
/**
* This method is used to evaluate this Function's parameterized
* Instructions that have string variable InstructionParameters.
* These parameters are updated with the given runtime parameters.
*
* @param parameters The runtime parameters
*/
virtual void evaluateVariableParameters(std::vector<InstructionParameter> parameters) = 0;
// virtual void persist(std::ostream& stream) = 0;
/**
* The destructor
*/
......
......@@ -101,6 +101,11 @@ public:
*/
virtual std::shared_ptr<Function> getKernel(const std::string& name) = 0;
/**
* Return all of this IR instance's kernels.
*
* @return kernels The kernels this IR contains.
*/
virtual std::vector<std::shared_ptr<Function>> getKernels() = 0;
/**
......
......@@ -40,6 +40,9 @@
namespace xacc {
/**
* InstructionParameters can be ints, doubles, floats, or strings (for variables)
*/
using InstructionParameter = boost::variant<int, double, float, std::string>;
/**
......@@ -93,6 +96,11 @@ public:
*/
virtual InstructionParameter getParameter(const int idx) = 0;
/**
* Return all of this Instruction's parameters.
*
* @return params This instructions parameters.
*/
virtual std::vector<InstructionParameter> getParameters() = 0;
/**
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment