Legacy Balsam MPI Executor

This module launches and controls the running of tasks with Balsam versions up to 0.5.0. Balsam is especially useful when running libEnsemble on three-tier systems with intermediate launch nodes. Typically on such systems, MPI processes are themselves unable to submit further MPI tasks to the batch scheduler. Therefore when libEnsemble’s workers have been launched in a distributed fashion via MPI, they must communicate with an intermediate service like Balsam running on the launch nodes. The Balsam service then reserves compute resources and launches tasks from libEnsemble’s workers that are using the Balsam MPI Executor.

In order to create a Balsam executor, the calling script should contain

exctr = LegacyBalsamMPIExecutor()

The Balsam executor inherits from the MPI executor. See the MPIExecutor for shared API. Any differences are shown below.

class legacy_balsam_executor.LegacyBalsamMPIExecutor(custom_info={})

Bases: MPIExecutor

Inherits from MPIExecutor and wraps the Balsam task management service


Task kills are not configurable in the Balsam executor.


Balsam serial setup includes empyting database and adding applications

static del_apps()

Deletes all Balsam apps in the libe_app namespace

static del_tasks()

Deletes all Balsam tasks

static add_app(name, exepath, desc)

Add application to Balsam database

submit(calc_type=None, app_name=None, num_procs=None, num_nodes=None, procs_per_node=None, machinefile=None, app_args=None, stdout=None, stderr=None, stage_inout=None, hyperthreads=False, dry_run=False, wait_on_start=False, extra_args='')

Creates a new task, and either executes or schedules to execute in the executor

The created task object is returned.


Gets the default app for a given calc type

property gen_default_app

Returns the default generator app


Gets the app for a given app_name or raise exception


Returns the task object for the supplied task ID


Kills a task


Polls for a manager signal

The executor manager_signal attribute will be updated.


Polls a task

polling_loop(task, timeout=None, delay=0.1, poll_manager=False)

Optional, blocking, generic task status polling loop. Operates until the task finishes, times out, or is optionally killed via a manager signal. On completion, returns a presumptive calc_status integer. Potentially useful for running an application via the Executor until it stops without monitoring its intermediate output.

  • task (object) – a Task object returned by the executor on submission

  • timeout (int, optional) – Maximum number of seconds for the polling loop to run. Tasks that run longer than this limit are killed. Default: No timeout

  • delay (int, optional) – Sleep duration between polling loop iterations. Default: 0.1 seconds

  • poll_manager (bool, optional) – Whether to also poll the manager for ‘finish’ or ‘kill’ signals. If detected, the task is killed. Default: False.


calc_status – presumptive integer attribute describing the final status of a launched task

Return type


register_app(full_path, app_name=None, calc_type=None, desc=None)

Registers a user application to libEnsemble.

The full_path of the application must be supplied. Either app_name or calc_type can be used to identify the application in user scripts (in the submit function). app_name is recommended.

  • full_path (String) – The full path of the user application to be registered

  • app_name (String, optional) – Name to identify this application.

  • calc_type (String, optional) – Calculation type: Set this application as the default ‘sim’ or ‘gen’ function.

  • desc (String, optional) – Description of this application


Sets the worker ID for this executor

set_worker_info(comm, workerid=None)

Sets info for this executor

property sim_default_app

Returns the default simulation app

class legacy_balsam_executor.LegacyBalsamTask(app=None, app_args=None, workdir=None, stdout=None, stderr=None, workerid=None)

Bases: Task

Wraps a Balsam Task from the Balsam service

The same attributes and query routines are implemented.


Opens and reads the named file in the task’s workdir


Opens and reads the task’s stdout file in the task’s workdir


Opens and reads the task’s stderr file in the task’s workdir


Calculate timing information for this task


Polls and updates the status attributes of the supplied task


Waits on completion of the task or raises TimeoutExpired exception

Status attributes of task are updated on completion.


timeout – Time in seconds after which a TimeoutExpired exception is raised


Kills or cancels the supplied task


Wrapper for task.kill() without waiting


Return `True if task successfully cancelled.


Return `True if task is finished.


Wrapper for task.wait() that instead returns the task’s error code on completion.


timeout – Time in seconds after which a TimeoutExpired exception is raised


Returns true if the named file exists in the task’s workdir


Wrapper for task.wait() that also returns the task’s status on completion.


timeout – Time in seconds after which a TimeoutExpired exception is raised


Return `True if task is currently running.


Returns true if the task’s stderr file exists in the workdir


Returns true if the task’s stdout file exists in the workdir


Returns true if the task’s workdir exists