IPython Documentation

Table Of Contents

Previous topic

Module: parallel.apps.iploggerapp

Next topic

Module: parallel.apps.logwatcher

This Page

Note

This documentation is for a development version of IPython. There may be significant differences from the latest stable release.

Module: parallel.apps.launcher

Facilities for launching IPython processes asynchronously.

42 Classes

class IPython.parallel.apps.launcher.LauncherError

Bases: exceptions.Exception

class IPython.parallel.apps.launcher.ProcessStateError

Bases: IPython.parallel.apps.launcher.LauncherError

class IPython.parallel.apps.launcher.UnknownStatus

Bases: IPython.parallel.apps.launcher.LauncherError

class IPython.parallel.apps.launcher.BaseLauncher(work_dir=u'.', config=None, **kwargs)

Bases: IPython.config.configurable.LoggingConfigurable

An asbtraction for starting, stopping and signaling a process.

__init__(work_dir=u'.', config=None, **kwargs)
arg_str

The string form of the program arguments.

args

A list of cmd and args that will be used to start the process.

This is what is passed to spawnProcess() and the first element will be the process name.

find_args()

The .args property calls this to find the args list.

Subcommand should implement this to construct the cmd and args.

notify_start(data)

Call this to trigger startup actions.

This logs the process startup and sets the state to ‘running’. It is a pass-through so it can be used as a callback.

notify_stop(data)

Call this to trigger process stop actions.

This logs the process stopping and sets the state to ‘after’. Call this to trigger callbacks registered via on_stop().

on_stop(f)

Register a callback to be called with this Launcher’s stop_data when the process actually finishes.

running

Am I running.

signal(sig)

Signal the process.

Parameters:

sig : str or int

‘KILL’, ‘INT’, etc., or any signal number

start()

Start the process.

stop()

Stop the process and notify observers of stopping.

This method will return None immediately. To observe the actual process stopping, see on_stop().

class IPython.parallel.apps.launcher.ClusterAppMixin(*args, **kw)

Bases: IPython.utils.traitlets.HasTraits

MixIn for cluster args as traits

class IPython.parallel.apps.launcher.ControllerMixin(*args, **kw)

Bases: IPython.parallel.apps.launcher.ClusterAppMixin

class IPython.parallel.apps.launcher.EngineMixin(*args, **kw)

Bases: IPython.parallel.apps.launcher.ClusterAppMixin

class IPython.parallel.apps.launcher.LocalProcessLauncher(work_dir=u'.', config=None, **kwargs)

Bases: IPython.parallel.apps.launcher.BaseLauncher

Start and stop an external process in an asynchronous manner.

This will launch the external process with a working directory of self.work_dir.

__init__(work_dir=u'.', config=None, **kwargs)
interrupt_then_kill(delay=2.0)

Send INT, wait a delay and then send KILL.

class IPython.parallel.apps.launcher.LocalControllerLauncher(work_dir=u'.', config=None, **kwargs)

Bases: IPython.parallel.apps.launcher.LocalProcessLauncher, IPython.parallel.apps.launcher.ControllerMixin

Launch a controller as a regular external process.

start()

Start the controller by profile_dir.

class IPython.parallel.apps.launcher.LocalEngineLauncher(work_dir=u'.', config=None, **kwargs)

Bases: IPython.parallel.apps.launcher.LocalProcessLauncher, IPython.parallel.apps.launcher.EngineMixin

Launch a single engine as a regular externall process.

class IPython.parallel.apps.launcher.LocalEngineSetLauncher(work_dir=u'.', config=None, **kwargs)

Bases: IPython.parallel.apps.launcher.LocalEngineLauncher

Launch a set of engines as regular external processes.

__init__(work_dir=u'.', config=None, **kwargs)
launcher_class

alias of LocalEngineLauncher

start(n)

Start n engines by profile or profile_dir.

class IPython.parallel.apps.launcher.MPILauncher(*args, **kwargs)

Bases: IPython.parallel.apps.launcher.LocalProcessLauncher

Launch an external process using mpiexec.

__init__(*args, **kwargs)
find_args()

Build self.args using all the fields.

start(n)

Start n instances of the program using mpiexec.

class IPython.parallel.apps.launcher.MPIControllerLauncher(*args, **kwargs)

Bases: IPython.parallel.apps.launcher.MPILauncher, IPython.parallel.apps.launcher.ControllerMixin

Launch a controller using mpiexec.

start()

Start the controller by profile_dir.

class IPython.parallel.apps.launcher.MPIEngineSetLauncher(*args, **kwargs)

Bases: IPython.parallel.apps.launcher.MPILauncher, IPython.parallel.apps.launcher.EngineMixin

Launch engines using mpiexec

start(n)

Start n engines by profile or profile_dir.

class IPython.parallel.apps.launcher.DeprecatedMPILauncher

Bases: object

class IPython.parallel.apps.launcher.MPIExecLauncher(*args, **kwargs)

Bases: IPython.parallel.apps.launcher.MPILauncher, IPython.parallel.apps.launcher.DeprecatedMPILauncher

Deprecated, use MPILauncher

__init__(*args, **kwargs)
class IPython.parallel.apps.launcher.MPIExecControllerLauncher(*args, **kwargs)

Bases: IPython.parallel.apps.launcher.MPIControllerLauncher, IPython.parallel.apps.launcher.DeprecatedMPILauncher

Deprecated, use MPIControllerLauncher

__init__(*args, **kwargs)
class IPython.parallel.apps.launcher.MPIExecEngineSetLauncher(*args, **kwargs)

Bases: IPython.parallel.apps.launcher.MPIEngineSetLauncher, IPython.parallel.apps.launcher.DeprecatedMPILauncher

Deprecated, use MPIEngineSetLauncher

__init__(*args, **kwargs)
class IPython.parallel.apps.launcher.SSHLauncher(work_dir=u'.', config=None, **kwargs)

Bases: IPython.parallel.apps.launcher.LocalProcessLauncher

A minimal launcher for ssh.

To be useful this will probably have to be extended to use the sshx idea for environment variables. There could be other things this needs as well.

fetch_files()

fetch remote files (called after start)

send_files()

send our files (called before start)

class IPython.parallel.apps.launcher.SSHClusterLauncher(work_dir=u'.', config=None, **kwargs)

Bases: IPython.parallel.apps.launcher.SSHLauncher, IPython.parallel.apps.launcher.ClusterAppMixin

class IPython.parallel.apps.launcher.SSHControllerLauncher(work_dir=u'.', config=None, **kwargs)

Bases: IPython.parallel.apps.launcher.SSHClusterLauncher, IPython.parallel.apps.launcher.ControllerMixin

class IPython.parallel.apps.launcher.SSHEngineLauncher(work_dir=u'.', config=None, **kwargs)

Bases: IPython.parallel.apps.launcher.SSHClusterLauncher, IPython.parallel.apps.launcher.EngineMixin

class IPython.parallel.apps.launcher.SSHEngineSetLauncher(work_dir=u'.', config=None, **kwargs)

Bases: IPython.parallel.apps.launcher.LocalEngineSetLauncher

engine_count

determine engine count from engines dict

start(n)

Start engines by profile or profile_dir. n is ignored, and the engines config property is used instead.

class IPython.parallel.apps.launcher.SSHProxyEngineSetLauncher(work_dir=u'.', config=None, **kwargs)

Bases: IPython.parallel.apps.launcher.SSHClusterLauncher

Launcher for calling ipcluster engines on a remote machine.

Requires that remote profile is already configured.

class IPython.parallel.apps.launcher.WindowsHPCLauncher(work_dir=u'.', config=None, **kwargs)

Bases: IPython.parallel.apps.launcher.BaseLauncher

__init__(work_dir=u'.', config=None, **kwargs)
parse_job_id(output)

Take the output of the submit command and return the job id.

start(n)

Start n copies of the process using the Win HPC job scheduler.

class IPython.parallel.apps.launcher.WindowsHPCControllerLauncher(work_dir=u'.', config=None, **kwargs)

Bases: IPython.parallel.apps.launcher.WindowsHPCLauncher, IPython.parallel.apps.launcher.ClusterAppMixin

start()

Start the controller by profile_dir.

class IPython.parallel.apps.launcher.WindowsHPCEngineSetLauncher(work_dir=u'.', config=None, **kwargs)

Bases: IPython.parallel.apps.launcher.WindowsHPCLauncher, IPython.parallel.apps.launcher.ClusterAppMixin

start(n)

Start the controller by profile_dir.

class IPython.parallel.apps.launcher.BatchClusterAppMixin(*args, **kw)

Bases: IPython.parallel.apps.launcher.ClusterAppMixin

ClusterApp mixin that updates the self.context dict, rather than cl-args.

class IPython.parallel.apps.launcher.BatchSystemLauncher(work_dir=u'.', config=None, **kwargs)

Bases: IPython.parallel.apps.launcher.BaseLauncher

Launch an external process using a batch system.

This class is designed to work with UNIX batch systems like PBS, LSF, GridEngine, etc. The overall model is that there are different commands like qsub, qdel, etc. that handle the starting and stopping of the process.

This class also has the notion of a batch script. The batch_template attribute can be set to a string that is a template for the batch script. This template is instantiated using string formatting. Thus the template can use {n} fot the number of instances. Subclasses can add additional variables to the template dict.

__init__(work_dir=u'.', config=None, **kwargs)
parse_job_id(output)

Take the output of the submit command and return the job id.

start(n)

Start n copies of the process using a batch system.

write_batch_script(n)

Instantiate and write the batch script to the work_dir.

class IPython.parallel.apps.launcher.PBSLauncher(work_dir=u'.', config=None, **kwargs)

Bases: IPython.parallel.apps.launcher.BatchSystemLauncher

A BatchSystemLauncher subclass for PBS.

class IPython.parallel.apps.launcher.PBSControllerLauncher(work_dir=u'.', config=None, **kwargs)

Bases: IPython.parallel.apps.launcher.PBSLauncher, IPython.parallel.apps.launcher.BatchClusterAppMixin

Launch a controller using PBS.

start()

Start the controller by profile or profile_dir.

class IPython.parallel.apps.launcher.PBSEngineSetLauncher(work_dir=u'.', config=None, **kwargs)

Bases: IPython.parallel.apps.launcher.PBSLauncher, IPython.parallel.apps.launcher.BatchClusterAppMixin

Launch Engines using PBS

class IPython.parallel.apps.launcher.SGELauncher(work_dir=u'.', config=None, **kwargs)

Bases: IPython.parallel.apps.launcher.PBSLauncher

Sun GridEngine is a PBS clone with slightly different syntax

class IPython.parallel.apps.launcher.SGEControllerLauncher(work_dir=u'.', config=None, **kwargs)

Bases: IPython.parallel.apps.launcher.SGELauncher, IPython.parallel.apps.launcher.BatchClusterAppMixin

Launch a controller using SGE.

start()

Start the controller by profile or profile_dir.

class IPython.parallel.apps.launcher.SGEEngineSetLauncher(work_dir=u'.', config=None, **kwargs)

Bases: IPython.parallel.apps.launcher.SGELauncher, IPython.parallel.apps.launcher.BatchClusterAppMixin

Launch Engines with SGE

class IPython.parallel.apps.launcher.LSFLauncher(work_dir=u'.', config=None, **kwargs)

Bases: IPython.parallel.apps.launcher.BatchSystemLauncher

A BatchSystemLauncher subclass for LSF.

start(n)

Start n copies of the process using LSF batch system. This cant inherit from the base class because bsub expects to be piped a shell script in order to honor the #BSUB directives : bsub < script

class IPython.parallel.apps.launcher.LSFControllerLauncher(work_dir=u'.', config=None, **kwargs)

Bases: IPython.parallel.apps.launcher.LSFLauncher, IPython.parallel.apps.launcher.BatchClusterAppMixin

Launch a controller using LSF.

start()

Start the controller by profile or profile_dir.

class IPython.parallel.apps.launcher.LSFEngineSetLauncher(work_dir=u'.', config=None, **kwargs)

Bases: IPython.parallel.apps.launcher.LSFLauncher, IPython.parallel.apps.launcher.BatchClusterAppMixin

Launch Engines using LSF

class IPython.parallel.apps.launcher.HTCondorLauncher(work_dir=u'.', config=None, **kwargs)

Bases: IPython.parallel.apps.launcher.BatchSystemLauncher

A BatchSystemLauncher subclass for HTCondor.

HTCondor requires that we launch the ipengine/ipcontroller scripts rather that the python instance but otherwise is very similar to PBS. This is because HTCondor destroys sys.executable when launching remote processes - a launched python process depends on sys.executable to effectively evaluate its module search paths. Without it, regardless of which python interpreter you launch you will get the to built in module search paths.

We use the ip{cluster, engine, controller} scripts as our executable to circumvent this - the mechanism of shebanged scripts means that the python binary will be launched with argv[0] set to the location of the ip{cluster, engine, controller} scripts on the remote node. This means you need to take care that:

  1. Your remote nodes have their paths configured correctly, with the ipengine and ipcontroller of the python environment you wish to execute code in having top precedence.
  2. This functionality is untested on Windows.

If you need different behavior, consider making you own template.

class IPython.parallel.apps.launcher.HTCondorControllerLauncher(work_dir=u'.', config=None, **kwargs)

Bases: IPython.parallel.apps.launcher.HTCondorLauncher, IPython.parallel.apps.launcher.BatchClusterAppMixin

Launch a controller using HTCondor.

start()

Start the controller by profile or profile_dir.

class IPython.parallel.apps.launcher.HTCondorEngineSetLauncher(work_dir=u'.', config=None, **kwargs)

Bases: IPython.parallel.apps.launcher.HTCondorLauncher, IPython.parallel.apps.launcher.BatchClusterAppMixin

Launch Engines using HTCondor

class IPython.parallel.apps.launcher.IPClusterLauncher(work_dir=u'.', config=None, **kwargs)

Bases: IPython.parallel.apps.launcher.LocalProcessLauncher

Launch the ipcluster program in an external process.

2 Functions

IPython.parallel.apps.launcher.check_output(*popenargs, **kwargs)

Run command with arguments and return its output as a byte string.

If the exit code was non-zero it raises a CalledProcessError. The CalledProcessError object will have the return code in the returncode attribute and output in the output attribute.

The arguments are the same as for the Popen constructor. Example:

>>> check_output(["ls", "-l", "/dev/null"])
'crw-rw-rw- 1 root root 1, 3 Oct 18  2007 /dev/null\n'

The stdout argument is not allowed as it is used internally. To capture standard error in the result, use stderr=STDOUT.

>>> check_output(["/bin/sh", "-c",
...               "ls -l non_existent_file ; exit 0"],
...              stderr=STDOUT)
'ls: non_existent_file: No such file or directory\n'
IPython.parallel.apps.launcher.find_job_cmd()