expand engine/controller_launcher_class helpstring and docs

also fix foo_launcher -> foo_launcher_class in parallel docs

The names for these have been changed in 0.12

IPython/parallel/apps/ipclusterapp.py

@@ -1,535 +1,557 b''
 #!/usr/bin/env python
 # encoding: utf-8
 """
 The ipcluster application.
 
 Authors:
 
 * Brian Granger
 * MinRK
 
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2011  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 import errno
 import logging
 import os
 import re
 import signal
 
 from subprocess import check_call, CalledProcessError, PIPE
 import zmq
 from zmq.eventloop import ioloop
 
 from IPython.config.application import Application, boolean_flag
 from IPython.config.loader import Config
 from IPython.core.application import BaseIPythonApplication
 from IPython.core.profiledir import ProfileDir
 from IPython.utils.daemonize import daemonize
 from IPython.utils.importstring import import_item
 from IPython.utils.sysinfo import num_cpus
 from IPython.utils.traitlets import (Int, Unicode, Bool, CFloat, Dict, List, Any,
                                         DottedObjectName)
 
 from IPython.parallel.apps.baseapp import (
     BaseParallelApplication,
     PIDFileError,
     base_flags, base_aliases
 )
 
 
 #-----------------------------------------------------------------------------
 # Module level variables
 #-----------------------------------------------------------------------------
 
 
 default_config_file_name = u'ipcluster_config.py'
 
 
 _description = """Start an IPython cluster for parallel computing.
 
 An IPython cluster consists of 1 controller and 1 or more engines.
 This command automates the startup of these processes using a wide
 range of startup methods (SSH, local processes, PBS, mpiexec,
 Windows HPC Server 2008). To start a cluster with 4 engines on your
 local host simply do 'ipcluster start --n=4'. For more complex usage
 you will typically do 'ipython profile create mycluster --parallel', then edit
 configuration files, followed by 'ipcluster start --profile=mycluster --n=4'.
 """
 
 _main_examples = """
 ipcluster start --n=4 # start a 4 node cluster on localhost
 ipcluster start -h    # show the help string for the start subcmd
 
 ipcluster stop -h     # show the help string for the stop subcmd
 ipcluster engines -h  # show the help string for the engines subcmd
 """
 
 _start_examples = """
 ipython profile create mycluster --parallel # create mycluster profile
 ipcluster start --profile=mycluster --n=4   # start mycluster with 4 nodes
 """
 
 _stop_examples = """
 ipcluster stop --profile=mycluster  # stop a running cluster by profile name
 """
 
 _engines_examples = """
 ipcluster engines --profile=mycluster --n=4  # start 4 engines only
 """
 
 
 # Exit codes for ipcluster
 
 # This will be the exit code if the ipcluster appears to be running because
 # a .pid file exists
 ALREADY_STARTED = 10
 
 
 # This will be the exit code if ipcluster stop is run, but there is not .pid
 # file to be found.
 ALREADY_STOPPED = 11
 
 # This will be the exit code if ipcluster engines is run, but there is not .pid
 # file to be found.
 NO_CLUSTER = 12
 
 
 #-----------------------------------------------------------------------------
 # Main application
 #-----------------------------------------------------------------------------
 start_help = """Start an IPython cluster for parallel computing
 
 Start an ipython cluster by its profile name or cluster
 directory. Cluster directories contain configuration, log and
 security related files and are named using the convention
 'profile_<name>' and should be creating using the 'start'
 subcommand of 'ipcluster'. If your cluster directory is in
 the cwd or the ipython directory, you can simply refer to it
 using its profile name, 'ipcluster start --n=4 --profile=<profile>`,
 otherwise use the 'profile-dir' option.
 """
 stop_help = """Stop a running IPython cluster
 
 Stop a running ipython cluster by its profile name or cluster
 directory. Cluster directories are named using the convention
 'profile_<name>'. If your cluster directory is in
 the cwd or the ipython directory, you can simply refer to it
 using its profile name, 'ipcluster stop --profile=<profile>`, otherwise
 use the '--profile-dir' option.
 """
 engines_help = """Start engines connected to an existing IPython cluster
 
 Start one or more engines to connect to an existing Cluster
 by profile name or cluster directory.
 Cluster directories contain configuration, log and
 security related files and are named using the convention
 'profile_<name>' and should be creating using the 'start'
 subcommand of 'ipcluster'. If your cluster directory is in
 the cwd or the ipython directory, you can simply refer to it
 using its profile name, 'ipcluster engines --n=4 --profile=<profile>`,
 otherwise use the 'profile-dir' option.
 """
 stop_aliases = dict(
     signal='IPClusterStop.signal',
 )
 stop_aliases.update(base_aliases)
 
 class IPClusterStop(BaseParallelApplication):
     name = u'ipcluster'
     description = stop_help
     examples = _stop_examples
     config_file_name = Unicode(default_config_file_name)
 
     signal = Int(signal.SIGINT, config=True,
         help="signal to use for stopping processes.")
 
     aliases = Dict(stop_aliases)
 
     def start(self):
         """Start the app for the stop subcommand."""
         try:
             pid = self.get_pid_from_file()
         except PIDFileError:
             self.log.critical(
                 'Could not read pid file, cluster is probably not running.'
             )
             # Here I exit with a unusual exit status that other processes
             # can watch for to learn how I existed.
             self.remove_pid_file()
             self.exit(ALREADY_STOPPED)
 
         if not self.check_pid(pid):
             self.log.critical(
                 'Cluster [pid=%r] is not running.' % pid
             )
             self.remove_pid_file()
             # Here I exit with a unusual exit status that other processes
             # can watch for to learn how I existed.
             self.exit(ALREADY_STOPPED)
 
         elif os.name=='posix':
             sig = self.signal
             self.log.info(
                 "Stopping cluster [pid=%r] with [signal=%r]" % (pid, sig)
             )
             try:
                 os.kill(pid, sig)
             except OSError:
                 self.log.error("Stopping cluster failed, assuming already dead.",
                     exc_info=True)
                 self.remove_pid_file()
         elif os.name=='nt':
             try:
                 # kill the whole tree
                 p = check_call(['taskkill', '-pid', str(pid), '-t', '-f'], stdout=PIPE,stderr=PIPE)
             except (CalledProcessError, OSError):
                 self.log.error("Stopping cluster failed, assuming already dead.",
                     exc_info=True)
             self.remove_pid_file()
 
 engine_aliases = {}
 engine_aliases.update(base_aliases)
 engine_aliases.update(dict(
     n='IPClusterEngines.n',
     engines = 'IPClusterEngines.engine_launcher_class',
     daemonize = 'IPClusterEngines.daemonize',
 ))
 engine_flags = {}
 engine_flags.update(base_flags)
 
 engine_flags.update(dict(
     daemonize=(
         {'IPClusterEngines' : {'daemonize' : True}},
         """run the cluster into the background (not available on Windows)""",
     )
 ))
 class IPClusterEngines(BaseParallelApplication):
 
     name = u'ipcluster'
     description = engines_help
     examples = _engines_examples
     usage = None
     config_file_name = Unicode(default_config_file_name)
     default_log_level = logging.INFO
     classes = List()
     def _classes_default(self):
         from IPython.parallel.apps import launcher
         launchers = launcher.all_launchers
         eslaunchers = [ l for l in launchers if 'EngineSet' in l.__name__]
         return [ProfileDir]+eslaunchers
 
     n = Int(num_cpus(), config=True,
         help="""The number of engines to start. The default is to use one for each
         CPU on your machine""")
 
     engine_launcher = Any(config=True, help="Deprecated, use engine_launcher_class")
     def _engine_launcher_changed(self, name, old, new):
         if isinstance(new, basestring):
             self.log.warn("WARNING: %s.engine_launcher is deprecated as of 0.12,"
                     " use engine_launcher_class" % self.__class__.__name__)
             self.engine_launcher_class = new
     engine_launcher_class = DottedObjectName('LocalEngineSetLauncher',
         config=True,
         help="""The class for launching a set of Engines. Change this value
         to use various batch systems to launch your engines, such as PBS,SGE,MPIExec,etc.
         Each launcher class has its own set of configuration options, for making sure
         it will work in your environment.
 
         You can also write your own launcher, and specify it's absolute import path,
         as in 'mymodule.launcher.FTLEnginesLauncher`.
 
         Examples include:
 
             LocalEngineSetLauncher : start engines locally as subprocesses [default]
             MPIExecEngineSetLauncher : use mpiexec to launch in an MPI environment
             PBSEngineSetLauncher : use PBS (qsub) to submit engines to a batch queue
             SGEEngineSetLauncher : use SGE (qsub) to submit engines to a batch queue
+            LSFEngineSetLauncher : use LSF (bsub) to submit engines to a batch queue
             SSHEngineSetLauncher : use SSH to start the controller
                                 Note that SSH does *not* move the connection files
                                 around, so you will likely have to do this manually
                                 unless the machines are on a shared file system.
             WindowsHPCEngineSetLauncher : use Windows HPC
+
+        If you are using one of IPython's builtin launchers, you can specify just the
+        prefix, e.g:
+
+            c.IPClusterEngines.engine_launcher_class = 'SSH'
+
+        or:
+
+            ipcluster start --engines 'MPIExec'
+
         """
         )
     daemonize = Bool(False, config=True,
         help="""Daemonize the ipcluster program. This implies --log-to-file.
         Not available on Windows.
         """)
 
     def _daemonize_changed(self, name, old, new):
         if new:
             self.log_to_file = True
 
     aliases = Dict(engine_aliases)
     flags = Dict(engine_flags)
     _stopping = False
 
     def initialize(self, argv=None):
         super(IPClusterEngines, self).initialize(argv)
         self.init_signal()
         self.init_launchers()
 
     def init_launchers(self):
         self.engine_launcher = self.build_launcher(self.engine_launcher_class, 'EngineSet')
         self.engine_launcher.on_stop(lambda r: self.loop.stop())
 
     def init_signal(self):
         # Setup signals
         signal.signal(signal.SIGINT, self.sigint_handler)
 
     def build_launcher(self, clsname, kind=None):
         """import and instantiate a Launcher based on importstring"""
         if '.' not in clsname:
             # not a module, presume it's the raw name in apps.launcher
             if kind and kind not in clsname:
                 # doesn't match necessary full class name, assume it's
                 # just 'PBS' or 'MPIExec' prefix:
                 clsname = clsname + kind + 'Launcher'
             clsname = 'IPython.parallel.apps.launcher.'+clsname
         try:
             klass = import_item(clsname)
         except (ImportError, KeyError):
             self.log.fatal("Could not import launcher class: %r"%clsname)
             self.exit(1)
 
         launcher = klass(
             work_dir=u'.', config=self.config, log=self.log,
             profile_dir=self.profile_dir.location, cluster_id=self.cluster_id,
         )
         return launcher
 
     def start_engines(self):
         self.log.info("Starting %i engines"%self.n)
         self.engine_launcher.start(self.n)
 
     def stop_engines(self):
         self.log.info("Stopping Engines...")
         if self.engine_launcher.running:
             d = self.engine_launcher.stop()
             return d
         else:
             return None
 
     def stop_launchers(self, r=None):
         if not self._stopping:
             self._stopping = True
             self.log.error("IPython cluster: stopping")
             self.stop_engines()
             # Wait a few seconds to let things shut down.
             dc = ioloop.DelayedCallback(self.loop.stop, 4000, self.loop)
             dc.start()
 
     def sigint_handler(self, signum, frame):
         self.log.debug("SIGINT received, stopping launchers...")
         self.stop_launchers()
 
     def start_logging(self):
         # Remove old log files of the controller and engine
         if self.clean_logs:
             log_dir = self.profile_dir.log_dir
             for f in os.listdir(log_dir):
                 if re.match(r'ip(engine|controller)z-\d+\.(log|err|out)',f):
                     os.remove(os.path.join(log_dir, f))
         # This will remove old log files for ipcluster itself
         # super(IPBaseParallelApplication, self).start_logging()
 
     def start(self):
         """Start the app for the engines subcommand."""
         self.log.info("IPython cluster: started")
         # First see if the cluster is already running
 
         # Now log and daemonize
         self.log.info(
             'Starting engines with [daemon=%r]' % self.daemonize
         )
         # TODO: Get daemonize working on Windows or as a Windows Server.
         if self.daemonize:
             if os.name=='posix':
                 daemonize()
 
         dc = ioloop.DelayedCallback(self.start_engines, 0, self.loop)
         dc.start()
         # Now write the new pid file AFTER our new forked pid is active.
         # self.write_pid_file()
         try:
             self.loop.start()
         except KeyboardInterrupt:
             pass
         except zmq.ZMQError as e:
             if e.errno == errno.EINTR:
                 pass
             else:
                 raise
 
 start_aliases = {}
 start_aliases.update(engine_aliases)
 start_aliases.update(dict(
     delay='IPClusterStart.delay',
     controller = 'IPClusterStart.controller_launcher_class',
 ))
 start_aliases['clean-logs'] = 'IPClusterStart.clean_logs'
 
 class IPClusterStart(IPClusterEngines):
 
     name = u'ipcluster'
     description = start_help
     examples = _start_examples
     default_log_level = logging.INFO
     auto_create = Bool(True, config=True,
         help="whether to create the profile_dir if it doesn't exist")
     classes = List()
     def _classes_default(self,):
         from IPython.parallel.apps import launcher
         return [ProfileDir] + [IPClusterEngines] + launcher.all_launchers
 
     clean_logs = Bool(True, config=True,
         help="whether to cleanup old logs before starting")
 
     delay = CFloat(1., config=True,
         help="delay (in s) between starting the controller and the engines")
 
     controller_launcher = Any(config=True, help="Deprecated, use controller_launcher_class")
     def _controller_launcher_changed(self, name, old, new):
         if isinstance(new, basestring):
             # old 0.11-style config
             self.log.warn("WARNING: %s.controller_launcher is deprecated as of 0.12,"
                     " use controller_launcher_class" % self.__class__.__name__)
             self.controller_launcher_class = new
     controller_launcher_class = DottedObjectName('LocalControllerLauncher',
         config=True,
         help="""The class for launching a Controller. Change this value if you want
         your controller to also be launched by a batch system, such as PBS,SGE,MPIExec,etc.
 
         Each launcher class has its own set of configuration options, for making sure
         it will work in your environment.
 
         Examples include:
 
             LocalControllerLauncher : start engines locally as subprocesses
             MPIExecControllerLauncher : use mpiexec to launch engines in an MPI universe
             PBSControllerLauncher : use PBS (qsub) to submit engines to a batch queue
             SGEControllerLauncher : use SGE (qsub) to submit engines to a batch queue
+            LSFControllerLauncher : use LSF (bsub) to submit engines to a batch queue
             SSHControllerLauncher : use SSH to start the controller
             WindowsHPCControllerLauncher : use Windows HPC
+
+        If you are using one of IPython's builtin launchers, you can specify just the
+        prefix, e.g:
+
+            c.IPClusterStart.controller_launcher_class = 'SSH'
+
+        or:
+
+            ipcluster start --controller 'MPIExec'
+
         """
         )
     reset = Bool(False, config=True,
         help="Whether to reset config files as part of '--create'."
         )
 
     # flags = Dict(flags)
     aliases = Dict(start_aliases)
 
     def init_launchers(self):
         self.controller_launcher = self.build_launcher(self.controller_launcher_class, 'Controller')
         self.engine_launcher = self.build_launcher(self.engine_launcher_class, 'EngineSet')
         self.controller_launcher.on_stop(self.stop_launchers)
 
     def start_controller(self):
         self.controller_launcher.start()
 
     def stop_controller(self):
         # self.log.info("In stop_controller")
         if self.controller_launcher and self.controller_launcher.running:
             return self.controller_launcher.stop()
 
     def stop_launchers(self, r=None):
         if not self._stopping:
             self.stop_controller()
             super(IPClusterStart, self).stop_launchers()
 
     def start(self):
         """Start the app for the start subcommand."""
         # First see if the cluster is already running
         try:
             pid = self.get_pid_from_file()
         except PIDFileError:
             pass
         else:
             if self.check_pid(pid):
                 self.log.critical(
                     'Cluster is already running with [pid=%s]. '
                     'use "ipcluster stop" to stop the cluster.' % pid
                 )
                 # Here I exit with a unusual exit status that other processes
                 # can watch for to learn how I existed.
                 self.exit(ALREADY_STARTED)
             else:
                 self.remove_pid_file()
 
 
         # Now log and daemonize
         self.log.info(
             'Starting ipcluster with [daemon=%r]' % self.daemonize
         )
         # TODO: Get daemonize working on Windows or as a Windows Server.
         if self.daemonize:
             if os.name=='posix':
                 daemonize()
 
         dc = ioloop.DelayedCallback(self.start_controller, 0, self.loop)
         dc.start()
         dc = ioloop.DelayedCallback(self.start_engines, 1000*self.delay, self.loop)
         dc.start()
         # Now write the new pid file AFTER our new forked pid is active.
         self.write_pid_file()
         try:
             self.loop.start()
         except KeyboardInterrupt:
             pass
         except zmq.ZMQError as e:
             if e.errno == errno.EINTR:
                 pass
             else:
                 raise
         finally:
             self.remove_pid_file()
 
 base='IPython.parallel.apps.ipclusterapp.IPCluster'
 
 class IPClusterApp(Application):
     name = u'ipcluster'
     description = _description
     examples = _main_examples
 
     subcommands = {
                 'start' : (base+'Start', start_help),
                 'stop' : (base+'Stop', stop_help),
                 'engines' : (base+'Engines', engines_help),
     }
 
     # no aliases or flags for parent App
     aliases = Dict()
     flags = Dict()
 
     def start(self):
         if self.subapp is None:
             print "No subcommand specified. Must specify one of: %s"%(self.subcommands.keys())
             print
             self.print_description()
             self.print_subcommands()
             self.exit(1)
         else:
             return self.subapp.start()
 
 def launch_new_instance():
     """Create and run the IPython cluster."""
     app = IPClusterApp.instance()
     app.initialize()
     app.start()
 
 
 if __name__ == '__main__':
     launch_new_instance()
 

docs/source/parallel/parallel_process.txt

@@ -1,734 +1,761 b''
 .. _parallel_process:
 
 ===========================================
 Starting the IPython controller and engines
 ===========================================
 
 To use IPython for parallel computing, you need to start one instance of
 the controller and one or more instances of the engine. The controller
 and each engine can run on different machines or on the same machine.
 Because of this, there are many different possibilities.
 
 Broadly speaking, there are two ways of going about starting a controller and engines:
 
 * In an automated manner using the :command:`ipcluster` command.
 * In a more manual way using the :command:`ipcontroller` and 
   :command:`ipengine` commands.
 
 This document describes both of these methods. We recommend that new users
 start with the :command:`ipcluster` command as it simplifies many common usage
 cases.
 
 General considerations
 ======================
 
 Before delving into the details about how you can start a controller and
 engines using the various methods, we outline some of the general issues that
 come up when starting the controller and engines. These things come up no
 matter which method you use to start your IPython cluster.
 
 If you are running engines on multiple machines, you will likely need to instruct the
 controller to listen for connections on an external interface. This can be done by specifying
 the ``ip`` argument on the command-line, or the ``HubFactory.ip`` configurable in
 :file:`ipcontroller_config.py`.
 
 If your machines are on a trusted network, you can safely instruct the controller to listen
 on all public interfaces with::
 
     $> ipcontroller --ip=*
 
 Or you can set the same behavior as the default by adding the following line to your :file:`ipcontroller_config.py`:
 
 .. sourcecode:: python
 
     c.HubFactory.ip = '*'
 
 .. note::
 
     Due to the lack of security in ZeroMQ, the controller will only listen for connections on
     localhost by default. If you see Timeout errors on engines or clients, then the first
     thing you should check is the ip address the controller is listening on, and make sure
     that it is visible from the timing out machine.
     
 .. seealso::
 
     Our `notes <parallel_security>`_ on security in the new parallel computing code.
 
 Let's say that you want to start the controller on ``host0`` and engines on
 hosts ``host1``-``hostn``. The following steps are then required:
 
 1. Start the controller on ``host0`` by running :command:`ipcontroller` on
    ``host0``.  The controller must be instructed to listen on an interface visible
    to the engine machines, via the ``ip`` command-line argument or ``HubFactory.ip``
    in :file:`ipcontroller_config.py`.
 2. Move the JSON file (:file:`ipcontroller-engine.json`) created by the 
    controller from ``host0`` to hosts ``host1``-``hostn``.
 3. Start the engines on hosts ``host1``-``hostn`` by running 
    :command:`ipengine`.  This command has to be told where the JSON file 
    (:file:`ipcontroller-engine.json`) is located.
 
 At this point, the controller and engines will be connected. By default, the JSON files
 created by the controller are put into the :file:`~/.ipython/profile_default/security`
 directory. If the engines share a filesystem with the controller, step 2 can be skipped as
 the engines will automatically look at that location.
 
 The final step required to actually use the running controller from a client is to move
 the JSON file :file:`ipcontroller-client.json` from ``host0`` to any host where clients
 will be run. If these file are put into the :file:`~/.ipython/profile_default/security`
 directory of the client's host, they will be found automatically. Otherwise, the full path
 to them has to be passed to the client's constructor.
 
 Using :command:`ipcluster`
 ===========================
 
 The :command:`ipcluster` command provides a simple way of starting a
 controller and engines in the following situations:
 
 1. When the controller and engines are all run on localhost. This is useful
    for testing or running on a multicore computer.
 2. When engines are started using the :command:`mpiexec` command that comes 
    with most MPI [MPI]_ implementations
 3. When engines are started using the PBS [PBS]_ batch system 
    (or other `qsub` systems, such as SGE).
 4. When the controller is started on localhost and the engines are started on 
    remote nodes using :command:`ssh`.
 5. When engines are started using the Windows HPC Server batch system.
 
 .. note::
 
     Currently :command:`ipcluster` requires that the
     :file:`~/.ipython/profile_<name>/security` directory live on a shared filesystem that is
     seen by both the controller and engines. If you don't have a shared file
     system you will need to use :command:`ipcontroller` and
     :command:`ipengine` directly.
 
 Under the hood, :command:`ipcluster` just uses :command:`ipcontroller`
 and :command:`ipengine` to perform the steps described above.
 
 The simplest way to use ipcluster requires no configuration, and will
 launch a controller and a number of engines on the local machine. For instance, 
 to start one controller and 4 engines on localhost, just do::
 
     $ ipcluster start -n 4
 
 To see other command line options, do::
 
     $ ipcluster -h
 
 
 Configuring an IPython cluster
 ==============================
 
 Cluster configurations are stored as `profiles`.  You can create a new profile with::
 
     $ ipython profile create --parallel --profile=myprofile
 
 This will create the directory :file:`IPYTHONDIR/profile_myprofile`, and populate it
 with the default configuration files for the three IPython cluster commands. Once
 you edit those files, you can continue to call ipcluster/ipcontroller/ipengine
 with no arguments beyond ``profile=myprofile``, and any configuration will be maintained.
 
 There is no limit to the number of profiles you can have, so you can maintain a profile for each
 of your common use cases. The default profile will be used whenever the
 profile argument is not specified, so edit :file:`IPYTHONDIR/profile_default/*_config.py` to
 represent your most common use case.
 
 The configuration files are loaded with commented-out settings and explanations,
 which should cover most of the available possibilities.
 
 Using various batch systems with :command:`ipcluster`
 -----------------------------------------------------
 
 :command:`ipcluster` has a notion of Launchers that can start controllers
 and engines with various remote execution schemes.  Currently supported
-models include :command:`ssh`, :command:`mpiexec`, PBS-style (Torque, SGE),
+models include :command:`ssh`, :command:`mpiexec`, PBS-style (Torque, SGE, LSF),
 and Windows HPC Server.
 
+In general, these are configured by the :attr:`IPClusterEngines.engine_set_launcher_class`,
+and :attr:`IPClusterStart.controller_launcher_class` configurables, which can be the
+fully specified object name (e.g. ``'IPython.parallel.apps.launcher.LocalControllerLauncher'``),
+but if you are using IPython's builtin launchers, you can specify just the class name,
+or even just the prefix e.g:
+
+.. sourcecode:: python
+
+    c.IPClusterEngines.engine_launcher_class = 'SSH'
+    # equivalent to
+    c.IPClusterEngines.engine_launcher_class = 'SSHEngineSetLauncher'
+    # both of which expand to
+    c.IPClusterEngines.engine_launcher_class = 'IPython.parallel.apps.launcher.SSHEngineSetLauncher'
+
+The shortest form being of particular use on the command line, where all you need to do to
+get an IPython cluster running with engines started with MPI is:
+
+.. sourcecode:: bash
+
+    $> ipcluster start --engines=MPIExec
+
+Assuming that the default MPI config is sufficient.
+
+.. note::
+
+    shortcuts for builtin launcher names were added in 0.12, as was the ``_class`` suffix
+    on the configurable names.  If you use the old 0.11 names (e.g. ``engine_set_launcher``),
+    they will still work, but you will get a deprecation warning that the name has changed.
+
+
 .. note::
 
     The Launchers and configuration are designed in such a way that advanced
     users can subclass and configure them to fit their own system that we
     have not yet supported (such as Condor)
 
 Using :command:`ipcluster` in mpiexec/mpirun mode
 --------------------------------------------------
 
 
 The mpiexec/mpirun mode is useful if you:
 
 1. Have MPI installed.
 2. Your systems are configured to use the :command:`mpiexec` or
    :command:`mpirun` commands to start MPI processes.
 
 If these are satisfied, you can create a new profile::
 
     $ ipython profile create --parallel --profile=mpi
 
 and edit the file :file:`IPYTHONDIR/profile_mpi/ipcluster_config.py`.
 
 There, instruct ipcluster to use the MPIExec launchers by adding the lines:
 
 .. sourcecode:: python
 
-    c.IPClusterEngines.engine_launcher = 'IPython.parallel.apps.launcher.MPIExecEngineSetLauncher'
+    c.IPClusterEngines.engine_launcher_class = 'MPIExecEngineSetLauncher'
 
 If the default MPI configuration is correct, then you can now start your cluster, with::
 
     $ ipcluster start -n 4 --profile=mpi
 
 This does the following:
 
 1. Starts the IPython controller on current host.
 2. Uses :command:`mpiexec` to start 4 engines.
 
 If you have a reason to also start the Controller with mpi, you can specify:
 
 .. sourcecode:: python
 
-    c.IPClusterStart.controller_launcher = 'IPython.parallel.apps.launcher.MPIExecControllerLauncher'
+    c.IPClusterStart.controller_launcher_class = 'MPIExecControllerLauncher'
 
 .. note::
 
     The Controller *will not* be in the same MPI universe as the engines, so there is not
     much reason to do this unless sysadmins demand it.
 
 On newer MPI implementations (such as OpenMPI), this will work even if you
 don't make any calls to MPI or call :func:`MPI_Init`. However, older MPI
 implementations actually require each process to call :func:`MPI_Init` upon
 starting. The easiest way of having this done is to install the mpi4py
 [mpi4py]_ package and then specify the ``c.MPI.use`` option in :file:`ipengine_config.py`:
 
 .. sourcecode:: python
 
     c.MPI.use = 'mpi4py'
 
 Unfortunately, even this won't work for some MPI implementations. If you are
 having problems with this, you will likely have to use a custom Python
 executable that itself calls :func:`MPI_Init` at the appropriate time.
 Fortunately, mpi4py comes with such a custom Python executable that is easy to
 install and use. However, this custom Python executable approach will not work
 with :command:`ipcluster` currently.
 
 More details on using MPI with IPython can be found :ref:`here <parallelmpi>`.
 
 
 Using :command:`ipcluster` in PBS mode
 ---------------------------------------
 
 The PBS mode uses the Portable Batch System (PBS) to start the engines. 
 
 As usual, we will start by creating a fresh profile::
 
     $ ipython profile create --parallel --profile=pbs
 
 And in :file:`ipcluster_config.py`, we will select the PBS launchers for the controller
 and engines:
 
 .. sourcecode:: python
 
-    c.IPClusterStart.controller_launcher = \
-        'IPython.parallel.apps.launcher.PBSControllerLauncher'
-    c.IPClusterEngines.engine_launcher = \
-        'IPython.parallel.apps.launcher.PBSEngineSetLauncher'
+    c.IPClusterStart.controller_launcher_class = 'PBSControllerLauncher'
+    c.IPClusterEngines.engine_launcher_class = 'PBSEngineSetLauncher'
 
 .. note::
 
     Note that the configurable is IPClusterEngines for the engine launcher, and
     IPClusterStart for the controller launcher. This is because the start command is a
     subclass of the engine command, adding a controller launcher. Since it is a subclass,
     any configuration made in IPClusterEngines is inherited by IPClusterStart unless it is
     overridden.
 
 IPython does provide simple default batch templates for PBS and SGE, but you may need
 to specify your own. Here is a sample PBS script template:
 
 .. sourcecode:: bash
 
     #PBS -N ipython
     #PBS -j oe
     #PBS -l walltime=00:10:00
     #PBS -l nodes={n/4}:ppn=4
     #PBS -q {queue}
 
     cd $PBS_O_WORKDIR
     export PATH=$HOME/usr/local/bin
     export PYTHONPATH=$HOME/usr/local/lib/python2.7/site-packages
     /usr/local/bin/mpiexec -n {n} ipengine --profile-dir={profile_dir}
 
 There are a few important points about this template:
 
 1. This template will be rendered at runtime using IPython's :class:`EvalFormatter`.
    This is simply a subclass of :class:`string.Formatter` that allows simple expressions
    on keys.
 
 2. Instead of putting in the actual number of engines, use the notation
    ``{n}`` to indicate the number of engines to be started. You can also use
    expressions like ``{n/4}`` in the template to indicate the number of nodes.
    There will always be ``{n}`` and ``{profile_dir}`` variables passed to the formatter.
    These allow the batch system to know how many engines, and where the configuration
    files reside. The same is true for the batch queue, with the template variable
    ``{queue}``.
 
 3. Any options to :command:`ipengine` can be given in the batch script
    template, or in :file:`ipengine_config.py`.
 
 4. Depending on the configuration of you system, you may have to set
    environment variables in the script template.
 
 The controller template should be similar, but simpler:
 
 .. sourcecode:: bash
 
     #PBS -N ipython
     #PBS -j oe
     #PBS -l walltime=00:10:00
     #PBS -l nodes=1:ppn=4
     #PBS -q {queue}
 
     cd $PBS_O_WORKDIR
     export PATH=$HOME/usr/local/bin
     export PYTHONPATH=$HOME/usr/local/lib/python2.7/site-packages
     ipcontroller --profile-dir={profile_dir}
 
 
 Once you have created these scripts, save them with names like
 :file:`pbs.engine.template`. Now you can load them into the :file:`ipcluster_config` with:
 
 .. sourcecode:: python
 
     c.PBSEngineSetLauncher.batch_template_file = "pbs.engine.template"
     
     c.PBSControllerLauncher.batch_template_file = "pbs.controller.template"
         
 
 Alternately, you can just define the templates as strings inside :file:`ipcluster_config`.
 
 Whether you are using your own templates or our defaults, the extra configurables available are
 the number of engines to launch (``{n}``, and the batch system queue to which the jobs are to be
 submitted (``{queue}``)). These are configurables, and can be specified in
 :file:`ipcluster_config`:
 
 .. sourcecode:: python
 
     c.PBSLauncher.queue = 'veryshort.q'
     c.IPClusterEngines.n = 64
 
 Note that assuming you are running PBS on a multi-node cluster, the Controller's default behavior
 of listening only on localhost is likely too restrictive.  In this case, also assuming the
 nodes are safely behind a firewall, you can simply instruct the Controller to listen for
 connections on all its interfaces, by adding in :file:`ipcontroller_config`:
 
 .. sourcecode:: python
 
     c.HubFactory.ip = '*'
 
 You can now run the cluster with::
 
     $ ipcluster start --profile=pbs -n 128
 
 Additional configuration options can be found in the PBS section of :file:`ipcluster_config`.
 
 .. note::
 
     Due to the flexibility of configuration, the PBS launchers work with simple changes
     to the template for other :command:`qsub`-using systems, such as Sun Grid Engine,
     and with further configuration in similar batch systems like Condor.
 
 
 Using :command:`ipcluster` in SSH mode
 ---------------------------------------
 
 
 The SSH mode uses :command:`ssh` to execute :command:`ipengine` on remote
 nodes and :command:`ipcontroller` can be run remotely as well, or on localhost.
 
 .. note::
 
     When using this mode it highly recommended that you have set up SSH keys
     and are using ssh-agent [SSH]_ for password-less logins.
 
 As usual, we start by creating a clean profile::
 
     $ ipython profile create --parallel --profile=ssh
 
 To use this mode, select the SSH launchers in :file:`ipcluster_config.py`:
 
 .. sourcecode:: python
 
-    c.IPClusterEngines.engine_launcher = \
-        'IPython.parallel.apps.launcher.SSHEngineSetLauncher'
+    c.IPClusterEngines.engine_launcher_class = 'SSHEngineSetLauncher'
     # and if the Controller is also to be remote:
-    c.IPClusterStart.controller_launcher = \
-        'IPython.parallel.apps.launcher.SSHControllerLauncher'
-    
+    c.IPClusterStart.controller_launcher_class = 'SSHControllerLauncher'
+
+
 
 The controller's remote location and configuration can be specified:
 
 .. sourcecode:: python
 
     # Set the user and hostname for the controller
     # c.SSHControllerLauncher.hostname = 'controller.example.com'
     # c.SSHControllerLauncher.user = os.environ.get('USER','username')
 
     # Set the arguments to be passed to ipcontroller
     # note that remotely launched ipcontroller will not get the contents of 
     # the local ipcontroller_config.py unless it resides on the *remote host*
     # in the location specified by the `profile-dir` argument.
     # c.SSHControllerLauncher.program_args = ['--reuse', '--ip=*', '--profile-dir=/path/to/cd']
 
 .. note::
 
     SSH mode does not do any file movement, so you will need to distribute configuration
     files manually.  To aid in this, the `reuse_files` flag defaults to True for ssh-launched
     Controllers, so you will only need to do this once, unless you override this flag back
     to False.
 
 Engines are specified in a dictionary, by hostname and the number of engines to be run
 on that host.
 
 .. sourcecode:: python
 
     c.SSHEngineSetLauncher.engines = { 'host1.example.com' : 2,
                 'host2.example.com' : 5,
                 'host3.example.com' : (1, ['--profile-dir=/home/different/location']),
                 'host4.example.com' : 8 }
 
 * The `engines` dict, where the keys are the host we want to run engines on and
   the value is the number of engines to run on that host.
 * on host3, the value is a tuple, where the number of engines is first, and the arguments
   to be passed to :command:`ipengine` are the second element.
 
 For engines without explicitly specified arguments, the default arguments are set in
 a single location:
 
 .. sourcecode:: python
 
     c.SSHEngineSetLauncher.engine_args = ['--profile-dir=/path/to/profile_ssh']
 
 Current limitations of the SSH mode of :command:`ipcluster` are:
 
 * Untested on Windows. Would require a working :command:`ssh` on Windows.
   Also, we are using shell scripts to setup and execute commands on remote
   hosts.
 * No file movement - This is a regression from 0.10, which moved connection files
   around with scp. This will be improved, but not before 0.11 release.
 
 Using the :command:`ipcontroller` and :command:`ipengine` commands
 ====================================================================
 
 It is also possible to use the :command:`ipcontroller` and :command:`ipengine`
 commands to start your controller and engines. This approach gives you full
 control over all aspects of the startup process.
 
 Starting the controller and engine on your local machine
 --------------------------------------------------------
 
 To use :command:`ipcontroller` and :command:`ipengine` to start things on your
 local machine, do the following.
 
 First start the controller::
 
     $ ipcontroller
     
 Next, start however many instances of the engine you want using (repeatedly)
 the command::
 
     $ ipengine
 
 The engines should start and automatically connect to the controller using the
 JSON files in :file:`~/.ipython/profile_default/security`. You are now ready to use the
 controller and engines from IPython.
 
 .. warning:: 
     
     The order of the above operations may be important.  You *must*
     start the controller before the engines, unless you are reusing connection
     information (via ``--reuse``), in which case ordering is not important.
 
 .. note::
 
     On some platforms (OS X), to put the controller and engine into the
     background you may need to give these commands in the form ``(ipcontroller
     &)`` and ``(ipengine &)`` (with the parentheses) for them to work
     properly.
 
 Starting the controller and engines on different hosts
 ------------------------------------------------------
 
 When the controller and engines are running on different hosts, things are
 slightly more complicated, but the underlying ideas are the same:
 
 1. Start the controller on a host using :command:`ipcontroller`. The controller must be
    instructed to listen on an interface visible to the engine machines, via the ``ip``
    command-line argument or ``HubFactory.ip`` in :file:`ipcontroller_config.py`.
 2. Copy :file:`ipcontroller-engine.json` from :file:`~/.ipython/profile_<name>/security` on
    the controller's host to the host where the engines will run.
 3. Use :command:`ipengine` on the engine's hosts to start the engines.
 
 The only thing you have to be careful of is to tell :command:`ipengine` where
 the :file:`ipcontroller-engine.json` file is located. There are two ways you
 can do this:
 
 * Put :file:`ipcontroller-engine.json` in the :file:`~/.ipython/profile_<name>/security`
   directory on the engine's host, where it will be found automatically.
 * Call :command:`ipengine` with the ``--file=full_path_to_the_file``
   flag.
 
 The ``file`` flag works like this::
 
     $ ipengine --file=/path/to/my/ipcontroller-engine.json
 
 .. note::
     
     If the controller's and engine's hosts all have a shared file system  
     (:file:`~/.ipython/profile_<name>/security` is the same on all of them), then things
     will just work!
 
 SSH Tunnels
 ***********
 
 If your engines are not on the same LAN as the controller, or you are on a highly
 restricted network where your nodes cannot see each others ports, then you can
 use SSH tunnels to connect engines to the controller.
 
 .. note::
 
     This does not work in all cases.  Manual tunnels may be an option, but are
     highly inconvenient. Support for manual tunnels will be improved.
 
 You can instruct all engines to use ssh, by specifying the ssh server in 
 :file:`ipcontroller-engine.json`:
 
 .. I know this is really JSON, but the example is a subset of Python:
 .. sourcecode:: python
 
     {
       "url":"tcp://192.168.1.123:56951",
       "exec_key":"26f4c040-587d-4a4e-b58b-030b96399584",
       "ssh":"[e-mail]",
       "location":"192.168.1.123"
     }
 
 This will be specified if you give the ``--enginessh=[e-mail]`` argument when
 starting :command:`ipcontroller`.
 
 Or you can specify an ssh server on the command-line when starting an engine::
 
     $> ipengine --profile=foo --ssh=my.login.node
 
 For example, if your system is totally restricted, then all connections will actually be
 loopback, and ssh tunnels will be used to connect engines to the controller::
 
     [node1] $> ipcontroller --enginessh=node1
     [node2] $> ipengine
     [node3] $> ipcluster engines --n=4
 
 Or if you want to start many engines on each node, the command `ipcluster engines --n=4`
 without any configuration is equivalent to running ipengine 4 times.
 
 
 Make JSON files persistent
 --------------------------
 
 At fist glance it may seem that that managing the JSON files is a bit
 annoying. Going back to the house and key analogy, copying the JSON around
 each time you start the controller is like having to make a new key every time
 you want to unlock the door and enter your house. As with your house, you want
 to be able to create the key (or JSON file) once, and then simply use it at
 any point in the future.
 
 To do this, the only thing you have to do is specify the `--reuse` flag, so that
 the connection information in the JSON files remains accurate::
 
     $ ipcontroller --reuse
 
 Then, just copy the JSON files over the first time and you are set. You can
 start and stop the controller and engines any many times as you want in the
 future, just make sure to tell the controller to reuse the file.
 
 .. note::
 
     You may ask the question: what ports does the controller listen on if you
     don't tell is to use specific ones? The default is to use high random port
     numbers. We do this for two reasons: i) to increase security through
     obscurity and ii) to multiple controllers on a given host to start and
     automatically use different ports.
 
 Log files
 ---------
 
 All of the components of IPython have log files associated with them.
 These log files can be extremely useful in debugging problems with
 IPython and can be found in the directory :file:`~/.ipython/profile_<name>/log`.
 Sending the log files to us will often help us to debug any problems.
 
 
 Configuring `ipcontroller`
 ---------------------------
 
 The IPython Controller takes its configuration from the file :file:`ipcontroller_config.py`
 in the active profile directory.
 
 Ports and addresses
 *******************
 
 In many cases, you will want to configure the Controller's network identity.  By default,
 the Controller listens only on loopback, which is the most secure but often impractical.
 To instruct the controller to listen on a specific interface, you can set the 
 :attr:`HubFactory.ip` trait.  To listen on all interfaces, simply specify:
 
 .. sourcecode:: python
 
     c.HubFactory.ip = '*'
 
 When connecting to a Controller that is listening on loopback or behind a firewall, it may
 be necessary to specify an SSH server to use for tunnels, and the external IP of the
 Controller. If you specified that the HubFactory listen on loopback, or all interfaces,
 then IPython will try to guess the external IP. If you are on a system with VM network
 devices, or many interfaces, this guess may be incorrect. In these cases, you will want
 to specify the 'location' of the Controller. This is the IP of the machine the Controller
 is on, as seen by the clients, engines, or the SSH server used to tunnel connections.
 
 For example, to set up a cluster with a Controller on a work node, using ssh tunnels
 through the login node, an example :file:`ipcontroller_config.py` might contain:
 
 .. sourcecode:: python
 
     # allow connections on all interfaces from engines
     # engines on the same node will use loopback, while engines
     # from other nodes will use an external IP
     c.HubFactory.ip = '*'
     
     # you typically only need to specify the location when there are extra
     # interfaces that may not be visible to peer nodes (e.g. VM interfaces)
     c.HubFactory.location = '10.0.1.5'
     # or to get an automatic value, try this:
     import socket
     ex_ip = socket.gethostbyname_ex(socket.gethostname())[-1][0]
     c.HubFactory.location = ex_ip
     
     # now instruct clients to use the login node for SSH tunnels:
     c.HubFactory.ssh_server = 'login.mycluster.net'
 
 After doing this, your :file:`ipcontroller-client.json` file will look something like this:
 
 .. this can be Python, despite the fact that it's actually JSON, because it's
 .. still valid Python
 
 .. sourcecode:: python
 
     {
       "url":"tcp:\/\/*:43447",
       "exec_key":"9c7779e4-d08a-4c3b-ba8e-db1f80b562c1",
       "ssh":"login.mycluster.net",
       "location":"10.0.1.5"
     }
 
 Then this file will be all you need for a client to connect to the controller, tunneling
 SSH connections through login.mycluster.net.
 
 Database Backend
 ****************
 
 The Hub stores all messages and results passed between Clients and Engines.
 For large and/or long-running clusters, it would be unreasonable to keep all
 of this information in memory. For this reason, we have two database backends:
 [MongoDB]_ via PyMongo_, and SQLite with the stdlib :py:mod:`sqlite`.
 
 MongoDB is our design target, and the dict-like model it uses has driven our design. As far
 as we are concerned, BSON can be considered essentially the same as JSON, adding support
 for binary data and datetime objects, and any new database backend must support the same
 data types.
 
 .. seealso::
 
     MongoDB `BSON doc <http://www.mongodb.org/display/DOCS/BSON>`_
 
 To use one of these backends, you must set the :attr:`HubFactory.db_class` trait:
 
 .. sourcecode:: python
 
     # for a simple dict-based in-memory implementation, use dictdb
     # This is the default and the fastest, since it doesn't involve the filesystem
     c.HubFactory.db_class = 'IPython.parallel.controller.dictdb.DictDB'
     
     # To use MongoDB:
     c.HubFactory.db_class = 'IPython.parallel.controller.mongodb.MongoDB'
     
     # and SQLite:
     c.HubFactory.db_class = 'IPython.parallel.controller.sqlitedb.SQLiteDB'
 
 When using the proper databases, you can actually allow for tasks to persist from
 one session to the next by specifying the MongoDB database or SQLite table in
 which tasks are to be stored.  The default is to use a table named for the Hub's Session,
 which is a UUID, and thus different every time.
 
 .. sourcecode:: python
 
     # To keep persistant task history in MongoDB:
     c.MongoDB.database = 'tasks'
     
     # and in SQLite:
     c.SQLiteDB.table = 'tasks'
 
 
 Since MongoDB servers can be running remotely or configured to listen on a particular port,
 you can specify any arguments you may need to the PyMongo `Connection 
 <http://api.mongodb.org/python/1.9/api/pymongo/connection.html#pymongo.connection.Connection>`_:
 
 .. sourcecode:: python
 
     # positional args to pymongo.Connection
     c.MongoDB.connection_args = []
     
     # keyword args to pymongo.Connection
     c.MongoDB.connection_kwargs = {}
 
 .. _MongoDB: http://www.mongodb.org
 .. _PyMongo: http://api.mongodb.org/python/1.9/
 
 Configuring `ipengine`
 -----------------------
 
 The IPython Engine takes its configuration from the file :file:`ipengine_config.py`
 
 The Engine itself also has some amount of configuration. Most of this
 has to do with initializing MPI or connecting to the controller.
 
 To instruct the Engine to initialize with an MPI environment set up by
 mpi4py, add:
 
 .. sourcecode:: python
 
     c.MPI.use = 'mpi4py'
 
 In this case, the Engine will use our default mpi4py init script to set up
 the MPI environment prior to exection.  We have default init scripts for
 mpi4py and pytrilinos.  If you want to specify your own code to be run
 at the beginning, specify `c.MPI.init_script`.
 
 You can also specify a file or python command to be run at startup of the
 Engine:
 
 .. sourcecode:: python
 
     c.IPEngineApp.startup_script = u'/path/to/my/startup.py'
     
     c.IPEngineApp.startup_command = 'import numpy, scipy, mpi4py'
 
 These commands/files will be run again, after each
 
 It's also useful on systems with shared filesystems to run the engines
 in some scratch directory.  This can be set with:
 
 .. sourcecode:: python
 
     c.IPEngineApp.work_dir = u'/path/to/scratch/'
 
 
 
 .. [MongoDB] MongoDB database http://www.mongodb.org
 
 .. [PBS] Portable Batch System http://www.openpbs.org
 
 .. [SSH] SSH-Agent http://en.wikipedia.org/wiki/ssh-agent

docs/source/parallel/parallel_winhpc.txt

@@ -1,334 +1,332 b''
 ============================================
 Getting started with Windows HPC Server 2008
 ============================================
 
 .. note::
 
     Not adapted to zmq yet
 
 Introduction
 ============
 
 The Python programming language is an increasingly popular language for
 numerical computing. This is due to a unique combination of factors. First,
 Python is a high-level and *interactive* language that is well matched to
 interactive numerical work. Second, it is easy (often times trivial) to
 integrate legacy C/C++/Fortran code into Python. Third, a large number of
 high-quality open source projects provide all the needed building blocks for
 numerical computing: numerical arrays (NumPy), algorithms (SciPy), 2D/3D
 Visualization (Matplotlib, Mayavi, Chaco), Symbolic Mathematics (Sage, Sympy)
 and others.
 
 The IPython project is a core part of this open-source toolchain and is
 focused on creating a comprehensive environment for interactive and
 exploratory computing in the Python programming language. It enables all of
 the above tools to be used interactively and consists of two main components:
 
 * An enhanced interactive Python shell with support for interactive plotting
   and visualization.
 * An architecture for interactive parallel computing.
 
 With these components, it is possible to perform all aspects of a parallel
 computation interactively. This type of workflow is particularly relevant in
 scientific and numerical computing where algorithms, code and data are
 continually evolving as the user/developer explores a problem. The broad
 treads in computing (commodity clusters, multicore, cloud computing, etc.)
 make these capabilities of IPython particularly relevant.
 
 While IPython is a cross platform tool, it has particularly strong support for
 Windows based compute clusters running Windows HPC Server 2008. This document
 describes how to get started with IPython on Windows HPC Server 2008. The
 content and emphasis here is practical: installing IPython, configuring
 IPython to use the Windows job scheduler and running example parallel programs
 interactively. A more complete description of IPython's parallel computing
 capabilities can be found in IPython's online documentation
 (http://ipython.org/documentation.html).
 
 Setting up your Windows cluster
 ===============================
 
 This document assumes that you already have a cluster running Windows
 HPC Server 2008. Here is a broad overview of what is involved with setting up
 such a cluster:
 
 1. Install Windows Server 2008 on the head and compute nodes in the cluster.
 2. Setup the network configuration on each host. Each host should have a 
    static IP address.
 3. On the head node, activate the "Active Directory Domain Services" role 
    and make the head node the domain controller.
 4. Join the compute nodes to the newly created Active Directory (AD) domain.
 5. Setup user accounts in the domain with shared home directories.
 6. Install the HPC Pack 2008 on the head node to create a cluster.
 7. Install the HPC Pack 2008 on the compute nodes.
 
 More details about installing and configuring Windows HPC Server 2008 can be
 found on the Windows HPC Home Page (http://www.microsoft.com/hpc). Regardless
 of what steps you follow to set up your cluster, the remainder of this
 document will assume that:
 
 * There are domain users that can log on to the AD domain and submit jobs
   to the cluster scheduler.
 * These domain users have shared home directories. While shared home
   directories are not required to use IPython, they make it much easier to
   use IPython.
 
 Installation of IPython and its dependencies
 ============================================
 
 IPython and all of its dependencies are freely available and open source.
 These packages provide a powerful and cost-effective approach to numerical and
 scientific computing on Windows. The following dependencies are needed to run
 IPython on Windows:
 
 * Python 2.6 or 2.7 (http://www.python.org)
 * pywin32 (http://sourceforge.net/projects/pywin32/)
 * PyReadline (https://launchpad.net/pyreadline)
 * pyzmq (http://github.com/zeromq/pyzmq/downloads)
 * IPython (http://ipython.org)
 
 In addition, the following dependencies are needed to run the demos described
 in this document.
 
 * NumPy and SciPy (http://www.scipy.org)
 * Matplotlib (http://matplotlib.sourceforge.net/)
 
 The easiest way of obtaining these dependencies is through the Enthought
 Python Distribution (EPD) (http://www.enthought.com/products/epd.php). EPD is
 produced by Enthought, Inc. and contains all of these packages and others in a
 single installer and is available free for academic users. While it is also
 possible to download and install each package individually, this is a tedious
 process. Thus, we highly recommend using EPD to install these packages on
 Windows.
 
 Regardless of how you install the dependencies, here are the steps you will
 need to follow:
 
 1. Install all of the packages listed above, either individually or using EPD
    on the head node, compute nodes and user workstations.
 
 2. Make sure that :file:`C:\\Python27` and :file:`C:\\Python27\\Scripts` are
    in the system :envvar:`%PATH%` variable on each node.
 
 3. Install the latest development version of IPython. This can be done by
    downloading the the development version from the IPython website
    (http://ipython.org) and following the installation instructions.
 
 Further details about installing IPython or its dependencies can be found in
 the online IPython documentation (http://ipython.org/documentation.html)
 Once you are finished with the installation, you can try IPython out by
 opening a Windows Command Prompt and typing ``ipython``. This will
 start IPython's interactive shell and you should see something like the
 following screenshot:
 
 .. image:: figs/ipython_shell.*
 
 Starting an IPython cluster
 ===========================
 
 To use IPython's parallel computing capabilities, you will need to start an
 IPython cluster. An IPython cluster consists of one controller and multiple
 engines:
 
 IPython controller
     The IPython controller manages the engines and acts as a gateway between 
     the engines and the client, which runs in the user's interactive IPython
     session. The controller is started using the :command:`ipcontroller`
     command.
 
 IPython engine
     IPython engines run a user's Python code in parallel on the compute nodes. 
     Engines are starting using the :command:`ipengine` command.
 
 Once these processes are started, a user can run Python code interactively and
 in parallel on the engines from within the IPython shell using an appropriate
 client. This includes the ability to interact with, plot and visualize data
 from the engines.
 
 IPython has a command line program called :command:`ipcluster` that automates
 all aspects of starting the controller and engines on the compute nodes.
 :command:`ipcluster` has full support for the Windows HPC job scheduler,
 meaning that :command:`ipcluster` can use this job scheduler to start the
 controller and engines. In our experience, the Windows HPC job scheduler is
 particularly well suited for interactive applications, such as IPython. Once
 :command:`ipcluster` is configured properly, a user can start an IPython
 cluster from their local workstation almost instantly, without having to log
 on to the head node (as is typically required by Unix based job schedulers).
 This enables a user to move seamlessly between serial and parallel
 computations.
 
 In this section we show how to use :command:`ipcluster` to start an IPython
 cluster using the Windows HPC Server 2008 job scheduler. To make sure that
 :command:`ipcluster` is installed and working properly, you should first try
 to start an IPython cluster on your local host. To do this, open a Windows
 Command Prompt and type the following command::
 
     ipcluster start n=2
 
 You should see a number of messages printed to the screen, ending with 
 "IPython cluster: started". The result should look something like the following
 screenshot:
 
 .. image:: figs/ipcluster_start.*
 
 At this point, the controller and two engines are running on your local host.
 This configuration is useful for testing and for situations where you want to
 take advantage of multiple cores on your local computer. 
 
 Now that we have confirmed that :command:`ipcluster` is working properly, we
 describe how to configure and run an IPython cluster on an actual compute
 cluster running Windows HPC Server 2008. Here is an outline of the needed
 steps:
 
 1. Create a cluster profile using: ``ipython profile create --parallel profile=mycluster``
 
 2. Edit configuration files in the directory :file:`.ipython\\cluster_mycluster`
 
 3. Start the cluster using: ``ipcluser start profile=mycluster n=32``
 
 Creating a cluster profile
 --------------------------
 
 In most cases, you will have to create a cluster profile to use IPython on a
 cluster. A cluster profile is a name (like "mycluster") that is associated
 with a particular cluster configuration. The profile name is used by
 :command:`ipcluster` when working with the cluster.
 
 Associated with each cluster profile is a cluster directory. This cluster
 directory is a specially named directory (typically located in the
 :file:`.ipython` subdirectory of your home directory) that contains the
 configuration files for a particular cluster profile, as well as log files and
 security keys. The naming convention for cluster directories is:
 :file:`profile_<profile name>`. Thus, the cluster directory for a profile named
 "foo" would be :file:`.ipython\\cluster_foo`.
 
 To create a new cluster profile (named "mycluster") and the associated cluster
 directory, type the following command at the Windows Command Prompt::
 
     ipython profile create --parallel --profile=mycluster
 
 The output of this command is shown in the screenshot below. Notice how
 :command:`ipcluster` prints out the location of the newly created cluster
 directory.
 
 .. image:: figs/ipcluster_create.*
 
 Configuring a cluster profile
 -----------------------------
 
 Next, you will need to configure the newly created cluster profile by editing
 the following configuration files in the cluster directory:
 
 * :file:`ipcluster_config.py`
 * :file:`ipcontroller_config.py`
 * :file:`ipengine_config.py`
 
 When :command:`ipcluster` is run, these configuration files are used to 
 determine how the engines and controller will be started. In most cases,
 you will only have to set a few of the attributes in these files.
 
 To configure :command:`ipcluster` to use the Windows HPC job scheduler, you
 will need to edit the following attributes in the file
 :file:`ipcluster_config.py`::
 
     # Set these at the top of the file to tell ipcluster to use the
     # Windows HPC job scheduler.
-    c.IPClusterStart.controller_launcher = \
-        'IPython.parallel.apps.launcher.WindowsHPCControllerLauncher'
-    c.IPClusterEngines.engine_launcher = \
-        'IPython.parallel.apps.launcher.WindowsHPCEngineSetLauncher'
+    c.IPClusterStart.controller_launcher_class = 'WindowsHPCControllerLauncher'
+    c.IPClusterEngines.engine_launcher_class = 'WindowsHPCEngineSetLauncher'
 
     # Set these to the host name of the scheduler (head node) of your cluster.
     c.WindowsHPCControllerLauncher.scheduler = 'HEADNODE'
     c.WindowsHPCEngineSetLauncher.scheduler = 'HEADNODE'
 
 There are a number of other configuration attributes that can be set, but
 in most cases these will be sufficient to get you started.
 
 .. warning::
     If any of your configuration attributes involve specifying the location
     of shared directories or files, you must make sure that you use UNC paths
     like :file:`\\\\host\\share`. It is also important that you specify
     these paths using raw Python strings: ``r'\\host\share'`` to make sure
     that the backslashes are properly escaped.
 
 Starting the cluster profile
 ----------------------------
 
 Once a cluster profile has been configured, starting an IPython cluster using
 the profile is simple::
 
     ipcluster start --profile=mycluster -n 32
 
 The ``-n`` option tells :command:`ipcluster` how many engines to start (in
 this case 32). Stopping the cluster is as simple as typing Control-C.
 
 Using the HPC Job Manager
 -------------------------
 
 When ``ipcluster start`` is run the first time, :command:`ipcluster` creates
 two XML job description files in the cluster directory:
 
 * :file:`ipcontroller_job.xml`
 * :file:`ipengineset_job.xml`
 
 Once these files have been created, they can be imported into the HPC Job
 Manager application. Then, the controller and engines for that profile can be
 started using the HPC Job Manager directly, without using :command:`ipcluster`.
 However, anytime the cluster profile is re-configured, ``ipcluster start``
 must be run again to regenerate the XML job description files. The
 following screenshot shows what the HPC Job Manager interface looks like
 with a running IPython cluster.
 
 .. image:: figs/hpc_job_manager.*
 
 Performing a simple interactive parallel computation
 ====================================================
 
 Once you have started your IPython cluster, you can start to use it. To do
 this, open up a new Windows Command Prompt and start up IPython's interactive
 shell by typing::
 
     ipython
 
 Then you can create a :class:`MultiEngineClient` instance for your profile and
 use the resulting instance to do a simple interactive parallel computation. In
 the code and screenshot that follows, we take a simple Python function and
 apply it to each element of an array of integers in parallel using the
 :meth:`MultiEngineClient.map` method:
 
 .. sourcecode:: ipython
 
     In [1]: from IPython.parallel import *
 
     In [2]: c = MultiEngineClient(profile='mycluster')
 
     In [3]: mec.get_ids()
     Out[3]: [0, 1, 2, 3, 4, 5, 67, 8, 9, 10, 11, 12, 13, 14]
 
     In [4]: def f(x):
        ...:     return x**10
 
     In [5]: mec.map(f, range(15))  # f is applied in parallel
     Out[5]:
     [0,
      1,
      1024,
      59049,
      1048576,
      9765625,
      60466176,
      282475249,
      1073741824,
      3486784401L,
      10000000000L,
      25937424601L,
      61917364224L,
      137858491849L,
      289254654976L]
 
 The :meth:`map` method has the same signature as Python's builtin :func:`map`
 function, but runs the calculation in parallel. More involved examples of using
 :class:`MultiEngineClient` are provided in the examples that follow.
 
 .. image:: figs/mec_simple.*