update Parallel Magics notebook

docs/examples/parallel/Parallel Magics.ipynb

@@ -1,323 +1,334 b''
 {
  "metadata": {
   "name": "Parallel Magics"
  },
  "nbformat": 3,
  "worksheets": [
   {
    "cells": [
     {
      "cell_type": "heading",
      "level": 1,
      "source": [
       "Using Parallel Magics"
      ]
     },
     {
      "cell_type": "markdown",
      "source": [
-      "IPython has a few magics for working with your engines.",
-      "",
-      "This assumes you have started an IPython cluster, either with the notebook interface,",
+      "IPython has a few magics for working with your engines.\n",
+      "\n",
+      "This assumes you have started an IPython cluster, either with the notebook interface,\n",
       "or the `ipcluster/controller/engine` commands."
      ]
     },
     {
      "cell_type": "code",
-     "collapsed": false,
      "input": [
-      "from IPython import parallel",
-      "rc = parallel.Client()",
-      "dv = rc[:]",
-      "dv.block = True",
-      "dv"
+      "from IPython import parallel\n",
+      "rc = parallel.Client()\n",
+      "dv = rc[:]\n",
+      "rc.ids"
      ],
      "language": "python",
      "outputs": []
     },
     {
      "cell_type": "markdown",
      "source": [
-      "The parallel magics come from the `parallelmagics` IPython extension.",
-      "The magics are set to work with a particular View object,",
-      "so to activate them, you call the `activate()` method on a particular view:"
+      "Creating a Client registers the parallel magics `%px`, `%%px`, `%pxresult`, and `%autopx`.  \n",
+      "These magics are initially associated with a DirectView always associated with all currently registered engines."
      ]
     },
     {
-     "cell_type": "code",
-     "collapsed": true,
-     "input": [
-      "dv.activate()"
-     ],
-     "language": "python",
-     "outputs": []
-    },
-    {
      "cell_type": "markdown",
      "source": [
       "Now we can execute code remotely with `%px`:"
      ]
     },
     {
      "cell_type": "code",
-     "collapsed": false,
      "input": [
       "%px a=5"
      ],
      "language": "python",
      "outputs": []
     },
     {
      "cell_type": "code",
-     "collapsed": false,
      "input": [
       "%px print a"
      ],
      "language": "python",
      "outputs": []
     },
     {
      "cell_type": "code",
-     "collapsed": false,
      "input": [
       "%px a"
      ],
      "language": "python",
      "outputs": []
     },
     {
      "cell_type": "code",
-     "collapsed": false,
      "input": [
-      "with dv.sync_imports():",
+      "with dv.sync_imports():\n",
       "    import sys"
      ],
      "language": "python",
      "outputs": []
     },
     {
      "cell_type": "code",
-     "collapsed": false,
      "input": [
       "%px print >> sys.stderr, \"ERROR\""
      ],
      "language": "python",
      "outputs": []
     },
     {
      "cell_type": "markdown",
      "source": [
-      "You don't have to wait for results:"
+      "You don't have to wait for results.  The `%pxconfig` magic lets you change the default blocking/targets for the `%px` magics:"
      ]
     },
     {
      "cell_type": "code",
-     "collapsed": true,
      "input": [
-      "dv.block = False"
+      "%pxconfig --noblock"
      ],
      "language": "python",
      "outputs": []
     },
     {
      "cell_type": "code",
-     "collapsed": false,
      "input": [
-      "%px import time",
-      "%px time.sleep(5)",
+      "%px import time\n",
+      "%px time.sleep(5)\n",
       "%px time.time()"
      ],
      "language": "python",
      "outputs": []
     },
     {
      "cell_type": "markdown",
      "source": [
-      "But you will notice that this didn't output the result of the last command.",
+      "But you will notice that this didn't output the result of the last command.\n",
       "For this, we have `%result`, which displays the output of the latest request:"
      ]
     },
     {
      "cell_type": "code",
-     "collapsed": false,
      "input": [
       "%result"
      ],
      "language": "python",
      "outputs": []
     },
     {
      "cell_type": "markdown",
      "source": [
       "Remember, an IPython engine is IPython, so you can do magics remotely as well!"
      ]
     },
     {
      "cell_type": "code",
-     "collapsed": false,
      "input": [
-      "dv.block = True",
+      "%pxconfig --block\n",
       "%px %pylab inline"
      ],
      "language": "python",
      "outputs": []
     },
     {
      "cell_type": "markdown",
      "source": [
-      "`%%px` can also be used as a cell magic, for submitting whole blocks.",
-      "This one acceps `--block` and `--noblock` flags to specify",
-      "the blocking behavior, though the default is unchanged.",
-      ""
+      "`%%px` can also be used as a cell magic, for submitting whole blocks.\n",
+      "This one acceps `--block` and `--noblock` flags to specify\n",
+      "the blocking behavior, though the default is unchanged.\n"
      ]
     },
     {
      "cell_type": "code",
-     "collapsed": true,
      "input": [
-      "dv.scatter('id', dv.targets, flatten=True)",
+      "dv.scatter('id', dv.targets, flatten=True)\n",
       "dv['stride'] = len(dv)"
      ],
      "language": "python",
      "outputs": []
     },
     {
      "cell_type": "code",
-     "collapsed": false,
      "input": [
-      "%%px --noblock",
-      "x = linspace(0,pi,1000)",
-      "for n in range(id,12, stride):",
-      "    print n",
-      "    plt.plot(x,sin(n*x))",
+      "%%px --noblock\n",
+      "x = linspace(0,pi,1000)\n",
+      "for n in range(id,12, stride):\n",
+      "    print n\n",
+      "    plt.plot(x,sin(n*x))\n",
       "plt.title(\"Plot %i\" % id)"
      ],
      "language": "python",
      "outputs": []
     },
     {
      "cell_type": "code",
-     "collapsed": false,
      "input": [
       "%result"
      ],
      "language": "python",
      "outputs": []
     },
     {
      "cell_type": "markdown",
      "source": [
-      "It also lets you choose some amount of the grouping of the outputs with `--group-outputs`:",
-      "",
-      "The choices are:",
-      "",
-      "* `engine` - all of an engine's output is collected together",
-      "* `type` - where stdout of each engine is grouped, etc. (the default)",
-      "* `order` - same as `type`, but individual displaypub outputs are interleaved.",
-      "  That is, it will output the first plot from each engine, then the second from each,",
+      "It also lets you choose some amount of the grouping of the outputs with `--group-outputs`:\n",
+      "\n",
+      "The choices are:\n",
+      "\n",
+      "* `engine` - all of an engine's output is collected together\n",
+      "* `type` - where stdout of each engine is grouped, etc. (the default)\n",
+      "* `order` - same as `type`, but individual displaypub outputs are interleaved.\n",
+      "  That is, it will output the first plot from each engine, then the second from each,\n",
       "  etc."
      ]
     },
     {
      "cell_type": "code",
-     "collapsed": false,
      "input": [
-      "%%px --group-outputs=engine",
-      "x = linspace(0,pi,1000)",
-      "for n in range(id,12, stride):",
-      "    print n",
-      "    plt.figure()",
-      "    plt.plot(x,sin(n*x))",
-      "plt.title(\"Plot %i\" % id)"
+      "%%px --group-outputs=engine\n",
+      "x = linspace(0,pi,1000)\n",
+      "for n in range(id+1,12, stride):\n",
+      "    print n\n",
+      "    plt.figure()\n",
+      "    plt.plot(x,sin(n*x))\n",
+      "    plt.title(\"Plot %i\" % n)"
      ],
      "language": "python",
      "outputs": []
     },
     {
      "cell_type": "markdown",
      "source": [
-      "When you specify 'order', then individual display outputs (e.g. plots) will be interleaved:"
+      "When you specify 'order', then individual display outputs (e.g. plots) will be interleaved.\n",
+      "\n",
+      "`%result` takes the same output-ordering arguments as `%%px`, \n",
+      "so you can view the previous result in a variety of different ways with a few sequential calls to `%result`:"
      ]
     },
     {
      "cell_type": "code",
-     "collapsed": false,
      "input": [
-      "%%px --group-outputs=order",
-      "x = linspace(0,pi,1000)",
-      "for n in range(id,12, stride):",
-      "    print n",
-      "    plt.figure()",
-      "    plt.plot(x,sin(n*x))",
-      "plt.title(\"Plot %i\" % id)"
+      "%result --group-outputs=order"
      ],
      "language": "python",
      "outputs": []
     },
     {
      "cell_type": "heading",
      "level": 2,
      "source": [
       "Single-engine views"
      ]
     },
     {
      "cell_type": "markdown",
      "source": [
       "When a DirectView has a single target, the output is a bit simpler (no prefixes on stdout/err, etc.):"
      ]
     },
     {
      "cell_type": "code",
-     "collapsed": true,
      "input": [
-      "def generate_output():",
-      "    \"\"\"function for testing output",
-      "    ",
-      "    publishes two outputs of each type, and returns something",
-      "    \"\"\"",
-      "    ",
-      "    import sys,os",
-      "    from IPython.core.display import display, HTML, Math",
-      "    ",
-      "    print \"stdout\"",
-      "    print >> sys.stderr, \"stderr\"",
-      "    ",
-      "    display(HTML(\"<b>HTML</b>\"))",
-      "    ",
-      "    print \"stdout2\"",
-      "    print >> sys.stderr, \"stderr2\"",
-      "    ",
-      "    display(Math(r\"\\alpha=\\beta\"))",
-      "    ",
-      "    return os.getpid()",
-      "",
+      "def generate_output():\n",
+      "    \"\"\"function for testing output\n",
+      "    \n",
+      "    publishes two outputs of each type, and returns something\n",
+      "    \"\"\"\n",
+      "    \n",
+      "    import sys,os\n",
+      "    from IPython.core.display import display, HTML, Math\n",
+      "    \n",
+      "    print \"stdout\"\n",
+      "    print >> sys.stderr, \"stderr\"\n",
+      "    \n",
+      "    display(HTML(\"<b>HTML</b>\"))\n",
+      "    \n",
+      "    print \"stdout2\"\n",
+      "    print >> sys.stderr, \"stderr2\"\n",
+      "    \n",
+      "    display(Math(r\"\\alpha=\\beta\"))\n",
+      "    \n",
+      "    return os.getpid()\n",
+      "\n",
       "dv['generate_output'] = generate_output"
      ],
      "language": "python",
      "outputs": []
     },
     {
+     "cell_type": "markdown",
+     "source": [
+      "You can also have more than one set of parallel magics registered at a time.\n",
+      "\n",
+      "The `View.activate()` method takes a suffix argument, which is added to `'px'`."
+     ]
+    },
+    {
      "cell_type": "code",
-     "collapsed": true,
      "input": [
-      "e0 = rc[-1]",
-      "e0.block = True",
-      "e0.activate()"
+      "e0 = rc[-1]\n",
+      "e0.block = True\n",
+      "e0.activate('0')"
+     ],
+     "language": "python",
+     "outputs": []
+    },
+    {
+     "cell_type": "code",
+     "input": [
+      "%px0 generate_output()"
      ],
      "language": "python",
      "outputs": []
     },
     {
      "cell_type": "code",
-     "collapsed": false,
      "input": [
       "%px generate_output()"
      ],
      "language": "python",
      "outputs": []
+    },
+    {
+     "cell_type": "markdown",
+     "source": [
+      "As mentioned above, we can redisplay those same results with various grouping:"
+     ]
+    },
+    {
+     "cell_type": "code",
+     "input": [
+      "%pxresult --group-outputs order"
+     ],
+     "language": "python",
+     "outputs": []
+    },
+    {
+     "cell_type": "code",
+     "input": [
+      "%pxresult --group-outputs engine"
+     ],
+     "language": "python",
+     "outputs": []
+    },
+    {
+     "cell_type": "code",
+     "input": [],
+     "language": "python",
+     "outputs": []
     }
    ]
   }
  ]
 }
  No newline at end of file