Developer documentation

Libsubmit

Uniform interface to diverse and multi-lingual set of computational resources.

libsubmit.set_stream_logger(name='libsubmit', level=10, format_string=None)

Add a stream log handler

Parameters:

• name (-) – Set the logger name.
• level (-) – Set to logging.DEBUG by default.
• format_string (-) – Set to None by default.

Returns:

• None

libsubmit.set_file_logger(filename, name='libsubmit', level=10, format_string=None)

Add a stream log handler

Parameters:

• filename (-) – Name of the file to write logs to
• name (-) – Logger name
• level (-) – Set the logging level.
• format_string (-) – Set the format string

Returns:

• None

ExecutionProviders

An execution provider is basically an adapter to various types of execution resources. The providers abstract away the interfaces provided by various systems to request, monitor, and cancel computate resources.

Slurm

Cobalt

Condor

Torque

Local

AWS

Channels

For certain resources such as campus clusters or supercomputers at research laboratories, resource requirements may require authentication. For instance some resources may allow access to their job schedulers from only their login-nodes which require you to authenticate on through SSH, GSI-SSH and sometimes even require two factor authentication. Channels are simple abstractions that enable the ExecutionProvider component to talk to the resource managers of compute facilities. The simplest Channel, LocalChannel simply executes commands locally on a shell, while the SshChannel authenticates you to remote systems.

class libsubmit.channels.channel_base.Channel

Define the interface to all channels. Channels are usually called via the execute_wait function. For channels that execute remotely, a push_file function allows you to copy over files.

                      +------------------
                      |
cmd, wtime    ------->|  execute_wait
(ec, stdout, stderr)<-|---+
                      |
cmd, wtime    ------->|  execute_no_wait
(ec, stdout, stderr)<-|---+
                      |
src, dst_dir  ------->|  push_file
   dst_path  <--------|----+
                      |
dst_script_dir <------|  script_dir
                      |
                      +-------------------

close()

Closes the channel. Clean out any auth credentials.

Parameters:None – Returns:Bool

execute_no_wait(cmd, walltime, envs={}, *args, **kwargs)

Optional. THis is infrequently used.

Parameters:

• cmd (-) – Command string to execute over the channel
• walltime (-) – Timeout in seconds

KWargs:

• envs (dict) : Environment variables to push to the remote side

Returns:

• (exit_code(None), stdout, stderr) (int, io_thing, io_thing)

execute_wait(cmd, walltime, envs={}, *args, **kwargs)

Executes the cmd, with a defined walltime.

Parameters:

• cmd (-) – Command string to execute over the channel
• walltime (-) – Timeout in seconds

KWargs:

• envs (dict) : Environment variables to push to the remote side

Returns:

• (exit_code, stdout, stderr) (int, string, string)

push_file(source, dest_dir)

Channel will take care of moving the file from source to the destination directory

Parameters:

• source (string) – Full filepath of the file to be moved
• dest_dir (string) – Absolute path of the directory to move to

Returns:

destination_path (string)

script_dir

This is a property. Returns the directory assigned for storing all internal scripts such as scheduler submit scripts. This is usually where error logs from the scheduler would reside on the channel destination side.

Parameters:None (-) – Returns:

• Channel script dir

LocalChannel

class libsubmit.channels.local.local.LocalChannel(userhome='.', envs={}, script_dir='./.scripts', **kwargs)

This is not even really a channel, since opening a local shell is not heavy and done so infrequently that they do not need a persistent channel

__init__(userhome='.', envs={}, script_dir='./.scripts', **kwargs)

Initialize the local channel. script_dir is required by set to a default.

KwArgs:

• userhome (string): (default=’.’) This is provided as a way to override and set a specific userhome
• envs (dict) : A dictionary of env variables to be set when launching the shell
• script_dir (string): (default=”./.scripts”) Directory to place scripts

close()

There’s nothing to close here, and this really doesn’t do anything

Returns:

• False, because it really did not “close” this channel.

execute_no_wait(cmd, walltime, envs={})

Synchronously execute a commandline string on the shell.

Parameters:

• cmd (-) – Commandline string to execute
• walltime (-) – walltime in seconds, this is not really used now.

Returns:

Return code from the execution, -1 on fail - stdout : stdout string - stderr : stderr string

Return type:

• retcode

Raises:

None.

execute_wait(cmd, walltime, envs={})

Synchronously execute a commandline string on the shell.

Parameters:

• cmd (-) – Commandline string to execute
• walltime (-) – walltime in seconds, this is not really used now.

Kwargs:

• envs (dict) : Dictionary of env variables. This will be used to override the envs set at channel initialization.

Returns:Return code from the execution, -1 on fail - stdout : stdout string - stderr : stderr string Return type:

• retcode

Raises: None.

push_file(source, dest_dir)

If the source files dirpath is the same as dest_dir, a copy is not necessary, and nothing is done. Else a copy is made.

Parameters:

• source (-) – Path to the source file
• dest_dir (-) – Path to the directory to which the files is to be copied

Returns:

Absolute path of the destination file

Return type:

• destination_path (String)

Raises:

- FileCopyException – If file copy failed.

script_dir

This is a property. Returns the directory assigned for storing all internal scripts such as scheduler submit scripts. This is usually where error logs from the scheduler would reside on the channel destination side.

Parameters:None (-) – Returns:

• Channel script dir

SshChannel

SshILChannel

Launchers

Launchers are basically wrappers for user submitted scripts as they are submitted to a specific execution resource.