Commit 078b04b0 authored by Mccaskey, Alex's avatar Mccaskey, Alex
Browse files

Updating documentation throughout, starting on QIR update

parent 182968d8
/*
* 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_ */
/*
* 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
/*
* 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_ */
/*
* 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
/*
* 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_ */
/*
* 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_ */
/*
* 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_ */
/*
* 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_ */
......@@ -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:
......
......@@ -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 {
......
......@@ -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);
......
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