This module contains the classes
Task. The class
Executor can be used to subprocess an application
locally. For MPI programs, or any program using non-local compute resources, one of the
inherited classes should be used. Inherited classes include MPI and Balsam variants.
executor can create and manage multiple
tasks. The user function
can issue and manage
tasks using the submit, poll, wait, and kill functions.
Task attributes are queried to determine status. Functions are
also provided to access and interrogate files in the
task’s working directory. A
manager_poll function can be used to poll for STOP signals from the manager.
See this example for usage.
See the Executor APIs for optional arguments.
Only create an object of this class for running local serial-launched applications. To run MPI applications and use detected resources, use an alternative Executor class, as shown above.
- class executor.Executor
The executor can create, poll and kill runnable tasks
Executor – executor: The executor object is stored here and can be retrieved in user functions.
list_of_tasks (list) – A list of tasks created in this executor
Instantiate a new Executor instance.
A new Executor object is created. This is typically created in the user calling script.
- register_app(full_path, app_name=None, calc_type=None, desc=None)
Registers a user application to libEnsemble.
full_pathof the application must be supplied. Either
calc_typecan be used to identify the application in user scripts (in the submit function).
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
- submit(calc_type=None, app_name=None, app_args=None, stdout=None, stderr=None, dry_run=False, wait_on_start=False)
Create a new task and run as a local serial subprocess.
The created task object is returned.
calc_type (String, optional) – The calculation type: ‘sim’ or ‘gen’ Only used if app_name is not supplied. Uses default sim or gen application.
app_name (String, optional) – The application name. Must be supplied if calc_type is not.
app_args (string, optional) – A string of the application arguments to be added to task submit command line
stdout (string, optional) – A standard output filename
stderr (string, optional) – A standard error filename
dry_run (boolean, optional) – Whether this is a dry_run - no task will be launched; instead runline is printed to logger (at INFO level)
wait_on_start (boolean, optional) – Whether to wait for task to be polled as RUNNING (or other active/end state) before continuing
task – The launched task object
- Return type
Tasks are created and returned through the Executor
submit() function. Tasks
can be polled and killed with the respective poll and kill functions. Task
information can be queried through the task attributes below and the query
functions. Note that the task attributes are updated only when they are
polled/killed (or through other task or Executor functions).
- class executor.Task(app=None, app_args=None, workdir=None, stdout=None, stderr=None, workerid=None, dry_run=False)
Manages the creation, configuration and status of a launchable task
Returns true if the named file exists in the task’s workdir
Kills or cancels the supplied task
Sends SIGTERM, waits for a period of <wait_time> for graceful termination, then sends a hard kill with SIGKILL. If <wait_time> is 0, we go immediately to SIGKILL; if <wait_time> is none, we never do a SIGKILL.
Polls and updates the status attributes of the task
Opens and reads the named file in the task’s workdir
Opens and reads the task’s stderr file in the task’s workdir
Opens and reads the task’s stdout file in the task’s workdir
Returns true if the task’s stderr file exists in the workdir
Returns true if the task’s stdout file exists in the workdir
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
Returns true if the task’s workdir exists
Following is a list of task status and configuration attributes that can be retrieved from a task.
These should not be set directly. Tasks are launched by the Executor, and task information can be queried through the task attributes below and the query functions.
Task status attributes include the following:
(string) The task status. One of (‘UNKNOWN’|’CREATED’|’WAITING’|’RUNNING’|’FINISHED’|’USER_KILLED’|’FAILED’)
(process obj) The process object used by the underlying process manager (e.g., return value of subprocess.Popen).
(int) The errorcode/return code used by the underlying process manager.
(Boolean) True means task has finished running - not whether it was successful.
(Boolean) Did task complete successfully (e.g., the returncode is zero)?
(int) Time in seconds that task has been running.
(int) Total time from task submission to completion (only available when task is finished).
Run configuration attributes - some will be autogenerated:
(string) Work directory for the task
(string) Name of task - autogenerated
(app obj) Use application/executable, registered using exctr.register_app
(string) Application arguments as a string
(string) Name of file where the standard output of the task is written (in task.workdir)
(string) Name of file where the standard error of the task is written (in task.workdir)