adding ro error decorator docs

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

docs/source/extensions.rst

@@ -642,9 +642,55 @@ Accelerator Decorators
 ----------------------
 ROErrorDecorator
 ++++++++++++++++
+The ``ROErrorDecorator`` provides an ``AcceleratorDecorator`` implementation for affecting
+readout error mitigation as in the `deuteron paper <https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.120.210501>`_.
+It takes as input readout error probabilities ``p(0|1)`` and ``p(1|0)`` for all qubits and shifts expecation values
+accordingly (see paper).
+
+By default it will request the backend properties from the decorated ``Accelerator`` (``Accelerator::getProperties()``). This method
+returns a ``HeterogeneousMap``. If this map contains a vector of doubles at keys ``p01s`` and ``p10s``, then these
+values will be used in the readout error correction. Alternatively, if the backend does not provide this data,
+users can provide a custom JSON file containing the probabilities. This file should be structured as such
+
+.. code:: bash
+
+   {
+       "shots": 1024,
+       "backend": "qcs:Aspen-2Q-A",
+       "0": {
+           "0|1": 0.0565185546875,
+           "1|0": 0.0089111328125,
+           "+": 0.0654296875,
+           "-": 0.047607421875
+       },
+       "1": {
+           "0|1": 0.095458984375,
+           "1|0": 0.0115966796875,
+           "+": 0.1070556640625,
+           "-": 0.0838623046875
+       }
+   }
+
+Automating readout error mitigation with this decorator can be done in the following way:
+
+.. code:: python
+
+   qpu = xacc.getAccelerator('ibm:ibmq_johannesburg', {'shots':1024})
+
+   # Turn on readout error correction by decorating qpu
+   qpu = xacc.getAcceleratorDecorator('ro-error', qpu)
+
+   # Now use qpu as your Accelerator...
+   # execution will be automatically readout
+   # error corrected
+
+Similarly, with a provided configuration file
+
+.. code:: cpp
+
+   auto qpu = xacc::getAccelerator("qcs:Aspen-2Q-A");
+   qpu = xacc::getAcceleratorDecorator("ro-error", qpu, {std::make_pair("file", "probs.json")});
 
-RichExtrapDecorator
-+++++++++++++++++++
 
 RDMPurificationDecorator
 ++++++++++++++++++++++++

quantum/plugins/decorators/ROErrorDecorator.cpp

@@ -12,6 +12,7 @@
  *******************************************************************************/
 #include "ROErrorDecorator.hpp"
 #include "InstructionIterator.hpp"
+#include "Utils.hpp"
 #include "xacc.hpp"
 #include <fstream>
 #include <set>
@@ -47,22 +48,21 @@ void ROErrorDecorator::execute(
       piminus.insert({i, p01s[i] - p10s[i]});
     }
   } else {
-    if (!xacc::optionExists("ro-error-file")) {
-      xacc::info("Cannot find ro-error-file. Skipping ReadoutError "
+    if (!xacc::fileExists(roErrorFile)) {
+      xacc::info("Cannot find readout erro file (key 'file'). Skipping ReadoutError "
                  "correction.");
       return;
     }
 
     // Get RO error probs
-    auto roeStr = xacc::getOption("ro-error-file");
-    buffer->addExtraInfo("ro-error-file", ExtraInfo(roeStr));
+    buffer->addExtraInfo("ro-error-file", ExtraInfo(roErrorFile));
 
-    std::ifstream t(roeStr);
+    std::ifstream t(roErrorFile);
     std::string json((std::istreambuf_iterator<char>(t)),
                      std::istreambuf_iterator<char>());
 
     if (json.empty()) {
-      xacc::error("Invalid ROError JSON file: " + roeStr);
+      xacc::error("Invalid ROError JSON file: " + roErrorFile);
     }
 
     Document d;
@@ -172,20 +172,19 @@ void ROErrorDecorator::execute(
     }
   } else {
 
-    if (!xacc::optionExists("ro-error-file")) {
-      xacc::info("Cannot find ro-error-file. Skipping ReadoutError "
+    if (!xacc::fileExists(roErrorFile)) {
+      xacc::info("Cannot find readout error file (key 'file'). Skipping ReadoutError "
                  "correction.");
       return;
     }
     // Get RO error probs
-    auto roeStr = xacc::getOption("ro-error-file");
-    buffer->addExtraInfo("ro-error-file", ExtraInfo(roeStr));
+    buffer->addExtraInfo("ro-error-file", ExtraInfo(roErrorFile));
 
-    std::ifstream t(roeStr);
+    std::ifstream t(roErrorFile);
     std::string json((std::istreambuf_iterator<char>(t)),
                      std::istreambuf_iterator<char>());
     if (json.empty()) {
-      xacc::error("Invalid ROError JSON file: " + roeStr);
+      xacc::error("Invalid ROError JSON file: " + roErrorFile);
     }
 
     Document d;

quantum/plugins/decorators/ROErrorDecorator.hpp

@@ -20,10 +20,27 @@ namespace xacc {
 namespace quantum {
 
 class ROErrorDecorator : public AcceleratorDecorator {
+protected:
+
+   std::string roErrorFile = "";
+
 public:
 
+  void initialize(const HeterogeneousMap &params = {}) override {
+    decoratedAccelerator->initialize(params);
+    if (params.stringExists("file")) {
+        roErrorFile = params.getString("file");
+    }
+  }
+
+  void updateConfiguration(const HeterogeneousMap &config) override {
+    decoratedAccelerator->updateConfiguration(config);
+    if (config.stringExists("file")) {
+        roErrorFile = config.getString("file");
+    }
+  }
   const std::vector<std::string> configurationKeys() override {
-      return {};
+      return {"file"};
   }
 
   void execute(std::shared_ptr<AcceleratorBuffer> buffer,

xacc/service/ServiceRegistry.hpp

@@ -24,6 +24,7 @@
 #include "Observable.hpp"
 #include "Optimizer.hpp"
 #include "IRTransformation.hpp"
+#include "AcceleratorDecorator.hpp"
 
 #include <cppmicroservices/FrameworkFactory.h>
 #include <cppmicroservices/Framework.h>
@@ -41,7 +42,8 @@ namespace xacc {
 using ContributableService =
     Variant<std::shared_ptr<Instruction>, std::shared_ptr<Accelerator>,
             std::shared_ptr<Compiler>, std::shared_ptr<Optimizer>,
-            std::shared_ptr<IRTransformation>, std::shared_ptr<Observable>>;
+            std::shared_ptr<IRTransformation>, std::shared_ptr<Observable>,
+            std::shared_ptr<AcceleratorDecorator>>;
 
 class ServiceRegistry {
 

xacc/xacc.cpp

@@ -19,6 +19,7 @@
 #include <fstream>
 #include "xacc_config.hpp"
 #include "cxxopts.hpp"
+#include "AcceleratorDecorator.hpp"
 
 #include "xacc_service.hpp"
 
@@ -186,6 +187,23 @@ void setAccelerator(const std::string &acceleratorName) {
   setOption("accelerator", acceleratorName);
 }
 
+std::shared_ptr<Accelerator> getAcceleratorDecorator(const std::string& decorator, std::shared_ptr<Accelerator> acc, const HeterogeneousMap& params) {
+ std::shared_ptr<AcceleratorDecorator> accd;
+  if (xacc::hasService<AcceleratorDecorator>(decorator)) {
+    accd = xacc::getService<AcceleratorDecorator>(decorator, false);
+  } else if (xacc::hasContributedService<AcceleratorDecorator>(decorator)) {
+    accd = xacc::getContributedService<AcceleratorDecorator>(decorator, false);
+  }
+
+  if (!accd) {
+      xacc::error("Cannot find AcceleratorDecorator with name " + decorator);
+  }
+
+  accd->setDecorated(acc);
+  accd->initialize(params);
+  return accd;
+}
+
 std::shared_ptr<Accelerator> getAccelerator() {
   if (!xacc::xaccFrameworkInitialized) {
     error("XACC not initialized before use.\nPlease execute "

xacc/xacc.hpp

@@ -127,6 +127,7 @@ std::shared_ptr<Accelerator> getAccelerator(const std::string &name,
                                             std::shared_ptr<Client> client,
                                             const HeterogeneousMap& params = {});
 std::shared_ptr<Accelerator> getAccelerator();
+std::shared_ptr<Accelerator> getAcceleratorDecorator(const std::string& decorator, std::shared_ptr<Accelerator> acc, const HeterogeneousMap& params = {});
 
 bool hasAccelerator(const std::string &name);