{
 "metadata": {
  "name": ""
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "heading",
     "level": 2,
     "metadata": {},
     "source": [
      "Installation"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "To begin, we install [pIDLy](https://github.com/anthonyjsmith/pIDLy):\n",
      "    \n",
      "    pip install pidly\n",
      "    \n",
      "Then we install idlmagic:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%install_ext https://raw.github.com/ebellm/ipython-idlmagic/master/idlmagic.py"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "heading",
     "level": 2,
     "metadata": {},
     "source": [
      "Usage"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "When starting a new notebook, we load the magic:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%load_ext idlmagic"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "IDL not found, using GDL\n"
       ]
      }
     ],
     "prompt_number": 1
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "(I am using [GDL](http://gnudatalanguage.sourceforge.net/) rather than IDL on this computer.  `idlmagic` will first look for the `idl` interpreter on the search path and and fall back to `gdl` if needed.)"
     ]
    },
    {
     "cell_type": "heading",
     "level": 3,
     "metadata": {},
     "source": [
      "Line magics"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The `%idl` magic enables one-line execution of IDL commands in the IPython interpreter or notebook:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%idl print, findgen(5)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "display_data",
       "text": [
        "      0.00000      1.00000      2.00000      3.00000      4.00000"
       ]
      }
     ],
     "prompt_number": 2
    },
    {
     "cell_type": "heading",
     "level": 3,
     "metadata": {},
     "source": [
      "Cell magics"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Multi-line input can be entered with the `%%idl` cell magic:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%idl\n",
      "x = findgen(5)\n",
      "y = x^2.\n",
      "; comments are supported\n",
      "print, $ ; as are line continuations\n",
      "mean(y)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "display_data",
       "text": [
        "% Compiled module: MEAN.\n",
        "      6.00000"
       ]
      }
     ],
     "prompt_number": 3
    },
    {
     "cell_type": "heading",
     "level": 3,
     "metadata": {},
     "source": [
      "Passing variables between Python and IDL"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The mechanisms for passing variables to and from IDL are based on those in the built-in `%R` and `%octave` magics.\n",
      "\n",
      "Variables may be pushed from Python into IDL with `%idl_push`:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "msg = '  padded   string   '\n",
      "import numpy as np\n",
      "arr = np.arange(5)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 4
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%idl_push msg arr"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 5
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%idl\n",
      "print, strcompress(msg,/REMOVE_ALL)\n",
      "print, reverse(arr)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "display_data",
       "text": [
        "paddedstring\n",
        "                     4                     3                     2\n",
        "                     1                     0"
       ]
      }
     ],
     "prompt_number": 6
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Similarly, variables can be pulled from IDL back to Python with `%idl_pull`:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%idl arr += 1"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 7
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%idl_pull arr"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 8
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "arr"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 9,
       "text": [
        "array([1, 2, 3, 4, 5])"
       ]
      }
     ],
     "prompt_number": 9
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Variables can also be pushed and pulled from IDL inline using the `-i` (or ``--input``) and `-o` (or `--output`) flags:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "Z = np.array([1, 4, 5, 10])"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 10
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%idl -i Z -o W W = sqrt(Z)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 11
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "W"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 12,
       "text": [
        "array([ 0.99999994,  1.99999988,  2.23606801,  3.1622777 ], dtype=float32)"
       ]
      }
     ],
     "prompt_number": 12
    },
    {
     "cell_type": "heading",
     "level": 3,
     "metadata": {},
     "source": [
      "Plotting"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Inline plots are displayed automatically by the IPython notebook.  IDL Direct graphics are used.  The optional `-s width,height` argument (or `--size`; default: `600,375`) specifies the size of the resulting png image."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%idl -s 400,400\n",
      "plot,findgen(10),xtitle='X',ytitle='Y'"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "display_data",
       "text": [
        "% Compiled module: WRITE_PNG."
       ]
      },
      {
       "metadata": {},
       "output_type": "display_data",
       "png": "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\ngg==\n"
      }
     ],
     "prompt_number": 13
    },
    {
     "cell_type": "heading",
     "level": 2,
     "metadata": {},
     "source": [
      "Known issues and limitations"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "* Only one plot can be rendered per cell\n",
      "* Processing for possibly unused plot output slows execution\n",
      "* Scalar variables from IDL may be returned as single-element Numpy arrays\n",
      "* The `%idl` line magic fails with `TypeError: coercing to Unicode: need string or buffer, dict found` in  IPython 0.13.2 and below due to a [known bug](http://stackoverflow.com/questions/14574434/unicode-error-with-ipython-rmagic-r-seems-to-work-but-not-r-fully); IPython 1.0 and later should work as expected."
     ]
    }
   ],
   "metadata": {}
  }
 ]
}