03-hybrid-computing-components.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Quantum-Classical Hybrid Computing: Components\n",
    "\n",
    "These notebooks expand the content presented in the D-Wave webinar [Hybrid Quantum Programming](https://www.youtube.com/watch?v=EW44reo8Bn0), demonstrating how you can apply [Leap's](https://cloud.dwavesys.com/leap) cloud-based hybrid solvers and Ocean software's [*dwave-hybrid*](https://docs.ocean.dwavesys.com/en/stable/docs_hybrid/sdk_index.html) solvers to your problem, create hybrid workflows, and develop custom hybrid components.\n",
    "\n",
    "This **third** notebook examines and develops *dwave-hybrid* components:\n",
    "\n",
    "1. [A Sample Problem](#A-Sample-Problem) section reproduces the  [Quantum-Classical Hybrid Computing: Getting Started](01-hybrid-computing-getting-started.ipynb) example problem for use in this notebook.\n",
    "2. [Working with Components](#Working-with-Components) section is a close look at hybrid components and their main methods.\n",
    "3. [Developing and Modifying Components](#Developing-and-Modifying-Components) section demonstrates developing your own components to optimize performance.\n",
    "\n",
    "More-basic content is provided in the previous notebooks:\n",
    "\n",
    "* [Quantum-Classical Hybrid Computing: Getting Started](01-hybrid-computing-getting-started.ipynb) notebook starts you off with Leap hybrid solvers and *dwave-hybrid* solvers and workflows.\n",
    "* [Quantum-Classical Hybrid Computing: Workflows](02-hybrid-computing-workflows.ipynb) notebook shows how you create your own workflows using *dwave-hybrid* components. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# A Sample Problem\n",
    "This section recreates the [Quantum-Classical Hybrid Computing: Getting Started](01-hybrid-computing-getting-started.ipynb) problem for use in the following sections. \n",
    "\n",
    "<div class=\"alert alert-warning\" role=\"alert\" style=\"margin: 10px\">Note: Problem size (nodes and density of edges) selected below ensures that runtimes on compute resources (virtual CPUs) provided by the Leap environment do not exceed a few minutes.</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "from helpers.draw import plot \n",
    "%matplotlib inline\n",
    "import networkx as nx\n",
    "import dwave_networkx as dnx\n",
    "import dimod\n",
    "import numpy as np\n",
    "\n",
    "problem_node_count = 300\n",
    "\n",
    "G = nx.random_geometric_graph(problem_node_count, radius=0.0005*problem_node_count)\n",
    "\n",
    "qubo = dnx.algorithms.independent_set.maximum_weighted_independent_set_qubo(G)\n",
    "bqm = dimod.BQM.from_qubo(qubo)\n",
    "\n",
    "plot(G)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Working with Components\n",
    "\n",
    "*dwave-hybrid* provides a variety of components that enable you to build workflows optimized for your problem. For many problems, using just these components is sufficient. This section examines these components and their methods to help you best exploit them and to provide a foundation for section [Developing and Modifying Components](#Developing-and-Modifying-Components)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## States\n",
    "[State](https://docs.ocean.dwavesys.com/en/stable/docs_hybrid/reference/core.html) is a subclass of a *dwave-hybrid* class, *PliableDict*, which extends the [dict](https://docs.python.org/3/library/stdtypes.html#dict) class with attribute accessors acting as item accessors. It is used to pass computation states to and from components and typically contains at least *samples* and *problem* fields. As you saw in the [Quantum-Classical Hybrid Computing: Workflows](02-hybrid-computing-workflows.ipynb) notebook, standard *dwave-hybrid* Runnables add fields such as *subproblem* and *subsamples* when decomposing problems, and you can add custom fields of your own. \n",
    "\n",
    "A closely related class, [States](https://docs.ocean.dwavesys.com/en/stable/docs_hybrid/reference/core.html), is a list of state objects. It is used, for example, to hold the multiple states produced by a workflow's parallel branches.   "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Creating States\n",
    "*dwave-hybrid* provides several utility methods for creating states. Because Runnable components require an input state, you typically need to provide some initial state to your workflows. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Create a state from the example problem. The *problem* field is a [dimod](https://docs.ocean.dwavesys.com/en/stable/docs_dimod/sdk_index.html) binary quadratic model ([BQM](https://docs.ocean.dwavesys.com/en/stable/concepts/bqm.html)) and the *samples* field is a subclass of the *dimod* [SampleSet](https://docs.ocean.dwavesys.com/en/stable/docs_dimod/reference/sampleset.html). "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hybrid\n",
    "\n",
    "state = hybrid.State.from_problem(bqm)\n",
    "print(\"Field problem is of type: {}\\nField samples is of type: {}\".format(\n",
    "       type(state.problem), type(state.samples)))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can set samples' values&mdash;for some initial samples you may be in a position to provide values you know are better than zeros or random for your problem; for example, if you are intermittently running a very large problem, possibly on more than one solver, and saving intermediate results. \n",
    "\n",
    "Here, for simplicity, `max_sample` is used to set values."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "state = hybrid.State.from_sample(hybrid.max_sample(bqm), bqm)\n",
    "print(\"Initial state's sampleset has energy {}.\".format(state.samples.first.energy))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Updating States\n",
    "The *updated()* method, which you saw demonstrated in the [Quantum-Classical Hybrid Computing: Workflows](02-hybrid-computing-workflows.ipynb) notebook through Runnable [Lambda](https://docs.ocean.dwavesys.com/en/stable/docs_hybrid/reference/flow.html), returns a deep copy of the state updated by specified arguments.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "state_info = state.updated(info=\"Some information\")\n",
    "print(\"Content of info field: {}.\".format(state_info.info))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The method can also update the States class. Runnable `Dup` duplicates `n` times an input state to an output States class.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "states_info = hybrid.Dup(2).run(state_info).result()\n",
    "\n",
    "states_info2 = states_info.updated(info2=\"Some more information\")\n",
    "\n",
    "for s in states_info2:\n",
    "    print(\"Content of info2 field: {}.\".format(s.info2))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Resolving States\n",
    "States created by Runnables are held in [Future](https://docs.python.org/3/library/concurrent.futures.html#concurrent.futures.Future)-like objects. By default, hybrid components use *hybrid.concurrency.thread_executor* to create an asynchronous call. The *result()* method implements `concurrent.Future`-compatible result resolution. \n",
    "\n",
    "While the loop below iterates `max_iter` times on Runnable `Identity`, which copies its input state to its output state, the output state is a Future with status \"running\". Once execution terminates, the status changes to \"finished\".  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from time import sleep\n",
    "\n",
    "output_state = hybrid.Loop(hybrid.Identity(), max_iter=50).run(state)\n",
    "\n",
    "print(\"State during execution: {}.\".format(output_state))\n",
    "sleep(3)\n",
    "print(\"State after execution: {}.\".format(output_state))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Trying to access the output state directly raises an error. Use the *result()* method to retrieve the encapsulated output state from the Future."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "try:\n",
    "    print(output_state.samples.first.energy)\n",
    "except AttributeError as err:\n",
    "    print(\"Accessing state before resolution: {}.\".format(err))\n",
    "\n",
    "output_state = output_state.result()\n",
    "print(\"Accessing state after resolution: {}.\".format(output_state.samples.first.energy))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Runnables are by default asynchronous, but you can specify a blocking call. For a blocking call, the state is returned in a [Present](https://docs.ocean.dwavesys.com/en/stable/docs_hybrid/reference/core.html) class, which is a `Future` resolved at construction time. \n",
    "\n",
    "Run `Identity` in a loop again, but as a blocking call. The `print` command cannot execute until execution terminates, with the status of the Present containing the output state set to \"finished\".  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "output_state = hybrid.Loop(hybrid.Identity(), max_iter=300).run(state, \n",
    "                                    executor=hybrid.immediate_executor)\n",
    "\n",
    "output_state = output_state.result()\n",
    "print(\"After termination and resolution: {}.\".format(output_state.samples.first.energy))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Runnables\n",
    "[Runnable](https://docs.ocean.dwavesys.com/en/stable/docs_hybrid/reference/core.html) is the key superclass in *dwave-hybrid*: all basic components&mdash;samplers, decomposers, composers&mdash;and flow-structuring components such as branches inherit from this class. \n",
    "\n",
    "A Runnable executes for an iteration in which it updates the state it receives. Its main methods are `run` or `next` to execute an iteration and `stop` to terminate the Runnable."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Executing Runnables\n",
    "By this point you have run a number of components using the *run()* method. Runnable class's *run()* handles some housekeeping work and passes the Future-encapsulated input state to the *dispatch()* method for resolution. This dispatcher does some verification and passes the state to either *error()* method to handle resolution errors or to *next()* method.\n",
    "\n",
    "By default, *error()* method just raises the exception. In the [Developing and Modifying Components](#Developing-and-Modifying-Components) section you will overwrite the base Runnable *error()* method to customize error handling."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "invalid_state_in_future = hybrid.Identity().run(1)\n",
    "\n",
    "try:\n",
    "    hybrid.Dup(2).dispatch(invalid_state_in_future)\n",
    "except Exception as exc:\n",
    "    print(\"Default error handling raises message: {}.\".format(exc))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The *next()* method executes one blocking iteration of an instantiated Runnable with a valid state as input. In the [Developing and Modifying Components](#Developing-and-Modifying-Components) section you will overwrite the base Runnable *next()* method to customize your own components."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "output_state = hybrid.Identity().next(state)\n",
    "\n",
    "print(\"Energy: {}.\".format(state.samples.first.energy))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that in contrast to *run()*, which inputs a Future, the input to *next()* is a state resolved and validated by *dispatch()*."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Terminating Runnables\n",
    "Runnable components might not terminate on their own; for example, your workflow might run a non-terminating sampler or a loop without terminating conditions. In such cases, your workflow will use the *stop()* method to terminate execution. (Note that not all components are interruptible.)   "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "workflow = hybrid.Loop(hybrid.Identity())\n",
    "\n",
    "output_state = workflow.run(state)\n",
    "\n",
    "sleep(0.2)\n",
    "print(\"Workflow after run(): {}.\".format(output_state))\n",
    "workflow.stop()\n",
    "sleep(0.2)\n",
    "print(\"Workflow after stop(): {}.\".format(output_state))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The base Runnable *stop()* method calls the *halt()* method, which is not implemented by the base Runnable itself. As you will do in the [Developing and Modifying Components](#Developing-and-Modifying-Components) section, Runnable components overwrite the *halt()* method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "workflow = hybrid.Loop(hybrid.Identity())\n",
    "\n",
    "output_state = workflow.run(state)\n",
    "\n",
    "workflow.halt()\n",
    "sleep(0.2)\n",
    "print(\"Workflow after halt(): {}.\".format(output_state))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Developing and Modifying Components\n",
    "Although *dwave-hybrid* provides a variety of components, some problems can benefit from non-standard processing or you might have fresh ideas on ways to solve a problem. This section demonstrates how to write new hybrid components and modify existing components. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## A Simple Runnable\n",
    "You can create a simple hybrid component of your own by overwriting the Runnable base class's *next()* method, which executes one blocking iteration of an instantiated Runnable with a valid state as input.  \n",
    "\n",
    "`IncrementCount` is a very simple example: it updates a counter in its input state, similar to such updates that the [Quantum-Classical Hybrid Computing: Workflows](02-hybrid-computing-workflows.ipynb) notebook demonstrated using Runnable `Lambda`. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class IncrementCount(hybrid.Runnable):\n",
    "    \"\"\"An example Runnable that increments a counter in the input state.\"\"\"\n",
    "    \n",
    "    def next(self, state, **kwargs):\n",
    "        return state.updated(counter=state.counter+1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Set an initial value for the `counter` field and instantiate and execute your simple component. In the [Adding Custom Traits](#Adding-Custom-Traits) subsection below, you will see how to ensure the input state contains any such required field."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "state_count_0 = state.updated(counter=0)\n",
    "\n",
    "output_state = IncrementCount().run(state_count_0).result()\n",
    "print(\"Counter field value after one execution: {}.\".format(output_state.counter))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-success\" role=\"alert\" style=\"margin: 10px\"> \n",
    "    <b>Exercise:</b> In the placeholder code cell below, modify <code>IncrementCount</code> to also print the state's best energy. Test your code in the EXERCISE TEST CELL below. Open the hidden code cell above it for a solution.\n",
    "    <p>Note: a <code>samples</code> field is present in the tested input state, <code>state_count_0</code>, and for simplicity, assume this is always the case. In the <i>Adding Custom Traits</i> subsection below, you will see how to ensure this is always the case.</p></div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "solution2": "hidden",
    "solution2_first": true
   },
   "outputs": [],
   "source": [
    "# Placeholder cell for exercise code. Modify the code lines below:\n",
    "\n",
    "class IncrementCountPrintEnergy(hybrid.Runnable):\n",
    "    \"\"\"An example Runnable that increments a counter in the input state.\"\"\"\n",
    "    \n",
    "    def next(self, state, **kwargs):\n",
    "        return state.updated(counter=state.counter+1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "jupyter": {
     "source_hidden": true
    },
    "solution2": "hidden"
   },
   "outputs": [],
   "source": [
    "# Click here to see solution:\n",
    "class IncrementCountIncrementCountPrintEnergy(hybrid.Runnable):\n",
    "    \"\"\"An example Runnable that increments a counter in the input state.\"\"\"\n",
    "    \n",
    "    def next(self, state, **kwargs):\n",
    "        print(\"Best energy in current state is {}.\".format(state.samples.first.energy))\n",
    "        return state.updated(counter=state.counter+1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# EXERCISE TEST CELL\n",
    "\n",
    "output_state = IncrementCountIncrementCountPrintEnergy().run(state_count_0).result()\n",
    "print(\"Counter field value after one execution: {}.\".format(output_state.counter))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Customizing Termination\n",
    "The `@stoppable` [decorator](https://www.python.org/dev/peps/pep-0318/) extends Runnable subclasses with a `stop_signal` [semaphore/event](https://docs.python.org/2/library/threading.html). \n",
    "\n",
    "The `IncrementCountSeconds` example Runnable increments a counter in its input state every second for up to 10 seconds, unless terminated by *stop()*. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import time\n",
    "\n",
    "@hybrid.stoppable\n",
    "class IncrementCountSeconds(hybrid.Runnable):\n",
    "    \"\"\"An example Runnable that increments a counter every second.\"\"\"\n",
    "\n",
    "    def next(self, state, **kwargs):\n",
    "        cnt = state.counter\n",
    "        t0 = time.time()\n",
    "        self.stop_signal.wait(timeout=10)\n",
    "        cnt += time.time() - t0\n",
    "        return state.updated(counter=int(cnt))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Your Runnable inherits the base *stop()* and *halt()* methods for termination. Run `IncrementCountSeconds` but terminate in less than 10 seconds. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "workflow = IncrementCountSeconds()\n",
    "\n",
    "output_state = workflow.run(state_count_0)\n",
    "\n",
    "sleep(2)\n",
    "workflow.stop()\n",
    "\n",
    "print(\"Counter is now {}.\".format(output_state.result().counter))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Runnable `Loop` implements the `@stoppable` decorator and can be terminated. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "workflow = hybrid.Loop(IncrementCount())\n",
    "\n",
    "output_state = workflow.run(state_count_0)\n",
    "\n",
    "sleep(0.5)\n",
    "workflow.stop()\n",
    "print(\"Counter is now {}.\".format(output_state.result().counter))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you need to implement a custom termination of your Runnable, overwrite the base *halt()* method, which is called by *stop()* for that purpose, rather than the *stop()* method. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class IncrementCount(hybrid.Runnable):\n",
    "    \"\"\"An example Runnable that increments a counter in the input state.\"\"\"\n",
    "    \n",
    "    def next(self, state, **kwargs):\n",
    "        return state.updated(counter=state.counter+1)\n",
    "    \n",
    "    def halt(self):\n",
    "        print(\"\\nTerminated.\\n\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "workflow = hybrid.Loop(IncrementCount())\n",
    "\n",
    "output_state = workflow.run(state_count_0)\n",
    "\n",
    "sleep(0.5)\n",
    "workflow.stop()\n",
    "print(\"Counter is now {}.\".format(output_state.result().counter))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-success\" role=\"alert\" style=\"margin: 10px\"> \n",
    "    <b>Exercise:</b> Modify <code>IncrementCount</code> below to automatically print the counter value when terminated. Test your code in the EXERCISE TEST CELL below. Open the hidden code cell above it for a solution.\n",
    "<p>Note: Although your component does not accept parameters, the placeholder code's Runnable base initialization includes the <code>runopts</code> parameter.</p></div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "solution2": "hidden",
    "solution2_first": true
   },
   "outputs": [],
   "source": [
    "# Write your exercise code here:\n",
    "\n",
    "class IncrementCount(hybrid.Runnable):\n",
    "    \"\"\"An example Runnable that increments a counter in the input state.\"\"\"\n",
    "\n",
    "    def __init__(self, **runopts):\n",
    "        super(IncrementCount, self).__init__(**runopts)\n",
    "        self.count = 0\n",
    "\n",
    "    def next(self, state, **kwargs):\n",
    "        return state.updated(counter=state.counter+1)\n",
    "    \n",
    "    def halt(self):\n",
    "        print(\"\\nTerminated.\\n\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "jupyter": {
     "source_hidden": true
    },
    "solution2": "hidden"
   },
   "outputs": [],
   "source": [
    "# Click here to see solution:\n",
    "class IncrementCount(hybrid.Runnable):\n",
    "    \"\"\"An example Runnable that increments a counter in the input state.\"\"\"\n",
    "\n",
    "    def __init__(self, **runopts):\n",
    "        super(IncrementCount, self).__init__(**runopts)\n",
    "        self.count = 0\n",
    "\n",
    "    def next(self, state, **kwargs):\n",
    "        self.count = state.counter+1\n",
    "        return state.updated(counter=self.count)\n",
    "    \n",
    "    def halt(self):\n",
    "        print(\"\\nTerminated with counter = {}.\\n\".format(self.count))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# EXERCISE TEST CELL\n",
    "workflow = hybrid.Loop(IncrementCount())\n",
    "\n",
    "output_state = workflow.run(state_count_0)\n",
    "\n",
    "sleep(0.2)\n",
    "workflow.stop()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Specifying Traits"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "State [traits](https://docs.ocean.dwavesys.com/en/stable/docs_hybrid/reference/traits.html) are verified for all Runnable objects that inherit from *StateTraits* or its subclasses. Traits of a new Runnable must be expressed and modified at construction time by its parent. When developing new Runnable classes, constructing composite traits can be nontrivial for some advanced flow-control Runnables."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example Trait: SISO\n",
    "Your simple Runnable can only process a single-state input. A complex workflow might incorrectly provide it with a `States` input, in which case the error message to the user might be confusing. \n",
    "\n",
    "Try running `IncrementCount` on a *States*-class object:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "states_count_0 = hybrid.States(state_count_0, state_count_0)\n",
    "\n",
    "try:\n",
    "    output_states = IncrementCount().run(states_count_0).result()\n",
    "except Exception as exc:\n",
    "    print(\"Low-level error message: {}.\".format(exc))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Add the trait `SISO` (single input, single output) to the Runnable to validate the input."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class IncrementCount(hybrid.traits.SISO, hybrid.Runnable):\n",
    "    \"\"\"An example Runnable that increments a counter in the input state.\"\"\"\n",
    "    \n",
    "    def next(self, state, **kwargs):\n",
    "        return state.updated(counter=state.counter+1)\n",
    "    \n",
    "    def halt(self):\n",
    "        print(\"\\nTerminated.\\n\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Try running `IncrementCount` with the SISO trait on a *States*-class object:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "try:\n",
    "    output_states = IncrementCount().run(states_count_0).result()\n",
    "except hybrid.exceptions.StateDimensionalityError as exc:\n",
    "    print(\"High-level error message: {}.\".format(exc))\n",
    "except Exception as exc:\n",
    "    print(\"Low-level error message: {}.\".format(exc))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example Trait: MIMO"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-success\" role=\"alert\" style=\"margin: 10px\"> \n",
    "    <b>Exercise:</b> Modify <code>IncrementCount</code> from inheriting the SISO trait to inheriting the MIMO (multiple input, multiple output) trait and test it in the EXERCISE TEST CELL below. Open the hidden code cell above it for a solution.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "solution2": "hidden",
    "solution2_first": true
   },
   "outputs": [],
   "source": [
    "# Write your exercise code here:\n",
    "\n",
    "class IncrementCountMIMO(hybrid.traits.MIMO, hybrid.Runnable):\n",
    "    \"\"\"An example Runnable that increments a counter in the input state.\"\"\"\n",
    "    \n",
    "    def next(self, state, **kwargs):\n",
    "        return state.updated(counter=state.counter+1)\n",
    "    \n",
    "    def halt(self):\n",
    "        print(\"\\nTerminated.\\n\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "jupyter": {
     "source_hidden": true
    },
    "solution2": "hidden"
   },
   "outputs": [],
   "source": [
    "# Click here to see solution:\n",
    "class IncrementCountMIMO(hybrid.traits.MIMO, hybrid.Runnable):\n",
    "    \"\"\"An example Runnable that increments a counter in the input state.\"\"\"\n",
    "    \n",
    "    def next(self, states, **kwargs):\n",
    "        for i in range(len(states)):\n",
    "            states[i] = states[i].updated(counter=states[i].counter+1)\n",
    "        return states\n",
    "    \n",
    "    def halt(self):\n",
    "        print(\"\\nTerminated\\n\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Test your exercise solution by running the next cell, which uses `IncrementCount` on a *States*-class object:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#EXERCISE TEST CELL\n",
    "from random import randint\n",
    "\n",
    "# test case: input MIMO (should work)\n",
    "print(\"Test MIMO:\")\n",
    "\n",
    "states_count_initial = hybrid.States(state_count_0.updated(counter=randint(0, 10)), \n",
    "                                     state_count_0.updated(counter=randint(0, 10)))\n",
    "\n",
    "try:\n",
    "    output_states = IncrementCountMIMO().run(states_count_initial).result()\n",
    "    for ind, s in enumerate(output_states):\n",
    "        print(\"Counter value of state {} is {}.\".format(ind, s.counter))\n",
    "except hybrid.exceptions.StateDimensionalityError as exc:\n",
    "    print(\"High-level error message: {}.\".format(exc))\n",
    "except Exception as exc:\n",
    "    print(\"Low-level error message: {}.\".format(exc))\n",
    "    \n",
    "# test case: input SISO (should give error)\n",
    "print(\"\\nTest SISO:\")\n",
    "\n",
    "try:\n",
    "    output_states = IncrementCountMIMO().run(state_count_0).result()\n",
    "    print(\"Counter value is {}.\".format(output_states.counter))\n",
    "except hybrid.exceptions.StateDimensionalityError as exc:\n",
    "    print(\"High-level error message: {}.\".format(exc))\n",
    "except Exception as exc:\n",
    "    print(\"Low-level error message: {}.\".format(exc))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Adding Custom Traits\n",
    "\n",
    "The hybrid framework makes it easy to add your own traits. \n",
    "\n",
    "### Example: Existing Trait SamplesProcessor\n",
    "\n",
    "The `SamplesProcessor` trait requires that the Runnable input samples and output samples. It does so by simply specifying two existing traits: \n",
    "\n",
    "`class SamplesProcessor(SamplesIntaking, SamplesProducing):\n",
    "     pass`\n",
    "\n",
    "The `SamplesIntaking` trait, for example, simply adds \"samples\" to the list of validated traits by the `InputValidated` trait:\n",
    "\n",
    "`class SamplesIntaking(InputValidated, StateTraits):\n",
    "    def __init__(self):\n",
    "        super(SamplesIntaking, self).__init__()\n",
    "        self.inputs.add('samples')`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can see how it works by adding it to a tabu search:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class TabuProblemSamplerInitialized(hybrid.traits.SamplesProcessor, \n",
    "                                    hybrid.traits.ProblemSampler, \n",
    "                                    hybrid.traits.SISO, \n",
    "                                    hybrid.Runnable):\n",
    "    \"\"\"A tabu search with the SamplesProcessor state trait.\"\"\"\n",
    "    \n",
    "    def next(self, state, **kwargs):\n",
    "        samples = hybrid.TabuProblemSampler().run(state).result().samples\n",
    "        return state.updated(samples=samples)   "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following test artificially removes the `samples` field from the input state. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# test case: input state has samples should work\n",
    "print(\"Test with samples:\")\n",
    "\n",
    "state = hybrid.State.from_problem(bqm)\n",
    "\n",
    "try:\n",
    "    output_states = TabuProblemSamplerInitialized().run(state).result()\n",
    "    print(\"works.\")\n",
    "except Exception as exc:\n",
    "    print(\"Low-level error message: {}.\".format(exc))\n",
    "    \n",
    "# test case: input state has no samples should give error\n",
    "print(\"Test without samples:\")\n",
    "\n",
    "del state['samples']\n",
    "\n",
    "try:\n",
    "    output_states = TabuProblemSamplerInitialized().run(state).result()\n",
    "    print(\"Works.\")\n",
    "except hybrid.exceptions.StateTraitMissingError as exc:\n",
    "    print(\"High-level error message: {}.\".format(exc))\n",
    "except Exception as exc:\n",
    "    print(\"Low-level error message: {}.\".format(exc))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example: New Trait TraitCounterIntaking\n",
    "In previous subsections, you used fields in the input state such as `info` or `counter`, relying on the user to initialize the state with the required field. Now you know how to ensure any fields you require are there: define a subclass of `InputValidated` that adds the required field and inherit your new trait in your component. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class TraitCounterIntaking(hybrid.traits.InputValidated, hybrid.traits.StateTraits):\n",
    "    def __init__(self):\n",
    "        super(TraitCounterIntaking, self).__init__()\n",
    "        self.inputs.add('counter')\n",
    "\n",
    "class IncrementCount(TraitCounterIntaking, \n",
    "                     hybrid.traits.SISO, \n",
    "                     hybrid.Runnable):\n",
    "    \"\"\"An example Runnable that increments a counter in the input state.\"\"\"\n",
    "    \n",
    "    def next(self, state, **kwargs):\n",
    "        return state.updated(counter=state.counter+1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "try:\n",
    "    output_states = IncrementCount().run(state).result()\n",
    "except hybrid.exceptions.StateTraitMissingError as exc:\n",
    "    print(\"High-level error message: {}.\".format(exc))\n",
    "except Exception as exc:\n",
    "    print(\"Low-level error message: {}.\".format(exc))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## A Custom Sampler\n",
    "\n",
    "Consider again an example where G represents a sprinkler system and you build a hybrid workflow that finds which sprinklers to use to water a lawn evenly with the lowest number of sprinklers. Say that at some mid-point in your workflow some sprinklers are marked as defective in the input state to a branch that runs tabu search.\n",
    "\n",
    "<div class=\"alert alert-success\" role=\"alert\" style=\"margin: 10px\"> \n",
    "    <b>Summary Exercise:</b> Customize a sampler that uses TabuProblemSampler but checks its best solution against a list of specified sprinklers in the state's <code>info</code> field, as shown in the EXERCISE TEST CELL below. It updates that field if those sprinklers are selected. Open the hidden code cell above it for a solution.\n",
    "</div>    "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "solution2": "hidden",
    "solution2_first": true
   },
   "outputs": [],
   "source": [
    "# Write your exercise code here:\n",
    "\n",
    "class TabuProblemSamplerFilteredNodes(hybrid.traits.ProblemSampler, \n",
    "                                      hybrid.traits.SISO, \n",
    "                                      hybrid.Runnable):\n",
    "    \"\"\"A tabu search that marks samples that select specified nodes.\"\"\"\n",
    "    \n",
    "    def next(self, state, **kwargs):\n",
    "        samples = hybrid.TabuProblemSampler().run(state).result().samples\n",
    "        pass   "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "jupyter": {
     "source_hidden": true
    },
    "solution2": "hidden"
   },
   "outputs": [],
   "source": [
    "# Click here to see solution:\n",
    "class TraitInfoIntaking(hybrid.traits.InputValidated, hybrid.traits.StateTraits):\n",
    "    def __init__(self):\n",
    "        super(TraitInfoIntaking, self).__init__()\n",
    "        self.inputs.add('info')\n",
    "\n",
    "\n",
    "class TabuProblemSamplerFilteredNodes(TraitInfoIntaking, \n",
    "                                      hybrid.traits.ProblemSampler, \n",
    "                                      hybrid.traits.SISO, \n",
    "                                      hybrid.Runnable):\n",
    "    \"\"\"A tabu search that marks samples that select specified nodes.\"\"\"\n",
    "\n",
    "    def next(self, state, **kwargs):\n",
    "        info = state.info\n",
    "        info[\"filtered nodes selected\"] = False\n",
    "        \n",
    "        samples = hybrid.TabuProblemSampler().run(state).result().samples\n",
    "        best_sample = samples.first.sample\n",
    "        \n",
    "        for node, val in best_sample.items(): \n",
    "            if node in state.info[\"filter nodes\"] and val==1:\n",
    "                info[\"filtered nodes selected\"] = True\n",
    "                break       \n",
    "                \n",
    "        return state.updated(samples=samples, info=info)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here, the input state to `TabuProblemSamplerFilteredNodes` is set to specify two random sprinklers:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#EXERCISE TEST CELL\n",
    "state_filtered_nodes = state.updated(info={\"filter nodes\": list(np.random.randint(0, problem_node_count, 2))})\n",
    "\n",
    "output_state = TabuProblemSamplerFilteredNodes().run(state_filtered_nodes).result()\n",
    "\n",
    "print(output_state.info)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You now have enough familiarity with *dwave-hybrid* to start experimenting on your own. When building new components, reference the source code directly for up-to-date information and helpful inline comments written for developers. \n",
    "\n",
    "Satisfied with your new component? Share it with the community by making a pull request to https://github.com/dwavesystems/dwave-hybrid. \n",
    "\n",
    "Have a great idea and need some implementation advice or assistance? Post it to the [Leap community](https://support.dwavesys.com/hc/en-us/community/topics)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Dimod Conversion\n",
    "*dwave-hybrid* provides classes that convert between hybrid and [dimod](https://docs.ocean.dwavesys.com/en/stable/docs_dimod/sdk_index.html) samplers. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the [Quantum-Classical Hybrid Computing: Workflows](02-hybrid-computing-workflows.ipynb) notebook you built a hybrid workflow that runs tabu and simulated annealing in parallel. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "workflow = (hybrid.Parallel(hybrid.TabuProblemSampler(num_reads=2, timeout=10),\n",
    "            hybrid.SimulatedAnnealingProblemSampler(num_reads=1)) |\n",
    "            hybrid.ArgMin() )\n",
    "\n",
    "state_updated = workflow.run(state).result()\n",
    "print(\"Updated state has {} sample sets with lowest energy {}.\".format(\n",
    "       len(state_updated.samples), state_updated.samples.first.energy))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `HybridSampler` class enables you to convert a Runnable, in this case a workflow, into a dimod sampler: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "dimod_sampler = hybrid.HybridSampler(workflow)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Run the converted workflow. Remember that *dimod* samplers input a BQM, not a state. Here, the original problem BQM is provided:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "solution = dimod_sampler.sample(bqm)\n",
    "print(\"Best energy found is {}.\".format(solution.first.energy))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also convert your custom components. The `TabuProblemSamplerFilteredNodes` below recodes the previous example&mdash;it checks its best solution against a list of specified sprinklers and notifies the user if those sprinklers are selected&mdash;but this time accepts a list of nodes as a runtime parameter. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class TabuProblemSamplerFilteredNodes(hybrid.traits.ProblemSampler, \n",
    "                                      hybrid.traits.SISO, \n",
    "                                      hybrid.Runnable):\n",
    "    \"\"\"A tabu search that marks samples that select specified nodes.\"\"\"\n",
    "    \n",
    "    def next(self, state, filter_nodes=[], **runopts):\n",
    "        state = state.updated(info={\"filter nodes\":filter_nodes})\n",
    "        state.info[\"filtered nodes selected\"] = False\n",
    "        \n",
    "        samples = hybrid.TabuProblemSampler().run(state).result().samples\n",
    "        best_sample = samples.first.sample\n",
    "        \n",
    "        for node, val in best_sample.items(): \n",
    "            if node in state.info[\"filter nodes\"] and val==1:\n",
    "                state.info[\"filtered nodes selected\"] = True\n",
    "                break \n",
    "                \n",
    "        return state.updated(samples=samples, info=state.info)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can execute this hybrid Runnable subclass on a given state, specifying the selected nodes in the `filter_nodes` argument:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "selected_nodes = list(np.random.randint(0, problem_node_count, 2))\n",
    "\n",
    "output_state = TabuProblemSamplerFilteredNodes().run(state, filter_nodes=selected_nodes).result()\n",
    "print(output_state.info)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or use the `HybridSampler` class to convert your Runnable into a dimod sampler: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "dimod_sampler = hybrid.HybridSampler(TabuProblemSamplerFilteredNodes())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Run the converted `TabuProblemSamplerFilteredNodes`. Setting the `return_state` parameter to True copies the final state, with its updated `info` field, into the `info` field of the returned *SampleSet*. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "solution = dimod_sampler.sample(bqm, filter_nodes=[2, 9, 6], return_state=True)\n",
    "print(solution.info[\"state\"][\"info\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Copyright &copy; 2020 D-Wave Systems, Inc\n",
    "\n",
    "The software is licensed under the Apache License, Version 2.0 (the \"License\");\n",
    "you may not use this file except in compliance with the License.\n",
    "You may obtain a copy of the License at\n",
    "\n",
    "    http://www.apache.org/licenses/LICENSE-2.0\n",
    "\n",
    "Unless required by applicable law or agreed to in writing, software\n",
    "distributed under the License is distributed on an \"AS IS\" BASIS,\n",
    "WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n",
    "See the License for the specific language governing permissions and\n",
    "limitations under the License.\n",
    "\n",
    "<a rel=\"license\" href=\"http://creativecommons.org/licenses/by-nc-sa/4.0/\"><img alt=\"Creative Commons License\" style=\"border-width:0\" src=\"https://i.creativecommons.org/l/by-nc-sa/4.0/88x31.png\" /></a><br />This Jupyter Notebook is licensed under a <a rel=\"license\" href=\"http://creativecommons.org/licenses/by-nc-sa/4.0/\">Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License</a>"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.0"
  },
  "latex_envs": {
   "LaTeX_envs_menu_present": true,
   "autoclose": false,
   "autocomplete": true,
   "bibliofile": "biblio.bib",
   "cite_by": "apalike",
   "current_citInitial": 1,
   "eqLabelWithNumbers": true,
   "eqNumInitial": 1,
   "hotkeys": {
    "equation": "Ctrl-E",
    "itemize": "Ctrl-I"
   },
   "labels_anchors": false,
   "latex_user_defs": false,
   "report_style_numbering": false,
   "user_envs_cfg": false
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": false,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {
    "height": "calc(100% - 180px)",
    "left": "10px",
    "top": "150px",
    "width": "165px"
   },
   "toc_section_display": true,
   "toc_window_display": true
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}