Convenience Tools and Functions

Calling Script Function Support

class tools.ForkablePdb(completekey='tab', stdin=None, stdout=None, skip=None, nosigint=False, readrc=True)

A Pdb subclass that may be used from a forked multiprocessing child

Usage:

from libensemble.tools import ForkablePdb
ForkablePdb().set_trace()
tools.add_unique_random_streams(persis_info, nstreams, seed='')

Creates nstreams random number streams for the libE manager and workers when nstreams is num_workers + 1. Stream i is initialized with seed i by default. Otherwise the streams can be initialized with a provided seed.

The entries are appended to the provided persis_info dictionary.

persis_info = add_unique_random_streams(old_persis_info, nworkers + 1)
Parameters

  • persis_info (dict) – Persistent information dictionary (example)

  • nstreams (int) – Number of independent random number streams to produce

  • seed (int) – (Optional) Seed for identical random number streams for each worker. If explicitly set to None, random number streams are unique and seed via other pseudorandom mechanisms.

tools.check_inputs(libE_specs=None, alloc_specs=None, sim_specs=None, gen_specs=None, exit_criteria=None, H0=None, serial_check=False)

Checks whether the libEnsemble arguments are of the correct data type and contain sufficient information to perform a run. There is no return value. An exception is raised if any of the checks fail.

from libensemble.tools import check_inputs
check_inputs(sim_specs=my_sim_specs, gen_specs=my_gen_specs, exit_criteria=ec)
Parameters

  • libE_specs (dict, optional) – libEnsemble data structures

  • alloc_specs (dict, optional) – libEnsemble data structures

  • sim_specs (dict, optional) – libEnsemble data structures

  • gen_specs (dict, optional) – libEnsemble data structures

  • exit_criteria (dict, optional) – libEnsemble data structures

  • H0 (numpy structured array, optional) – A previous libEnsemble history to be prepended to the history in the current libEnsemble run (example)

  • serial_check (boolean) – If true, assumes running a serial check. This means, for example, the details of current MPI communicator are not checked (can be run with libE_specs{‘mpi_comm’: ‘mpi’} without running through mpiexec.

tools.eprint(*args, **kwargs)

Prints a user message to standard error

tools.parse_args()

Parses command-line arguments.

from libensemble.tools import parse_args
nworkers, is_manager, libE_specs, misc_args = parse_args()

From the shell:

$ python calling_script --comms local --nworkers 4

Usage:

usage: test_... [-h] [--comms [{local,tcp,ssh,client,mpi}]]
                [--nworkers [NWORKERS]] [--workers WORKERS [WORKERS ...]]
                [--workerID [WORKERID]] [--server SERVER SERVER SERVER]
                [--pwd [PWD]] [--worker_pwd [WORKER_PWD]]
                [--worker_python [WORKER_PYTHON]]
                [--tester_args [TESTER_ARGS [TESTER_ARGS ...]]]
Returns

  • nworkers (int) – Number of workers libEnsemble will inititate

  • is_manager (boolean) – Indicates whether the current process is the manager process

  • libE_specs (dict) – Settings and specifications for libEnsemble (example)

tools.save_libE_output(H, persis_info, calling_file, nworkers, mess='Run completed')

Writes out history array and persis_info to files.

Format: <calling_script>_results_History_length=<length>_evals=<Completed evals>_ranks=<nworkers>

save_libE_output(H, persis_info, __file__, nworkers)
Parameters

  • H (NumPy structured array) – History array storing rows for each point. (example)

  • persis_info (dict) – Persistent information dictionary (example)

  • calling_file (string) – Name of user-calling script (or user chosen name) to prefix output files. The convention is to send __file__ from user calling script.

  • nworkers (int) – The number of workers in this ensemble. Added to output file names.

  • mess (String) – A message to print/log when saving the file.

Generator Function Support

These routines are commonly used within persistent generator functions like persistent_aposmm in libensemble/gen_funcs/ for intermediate communication with the manager.

gen_support.get_mgr_worker_msg(comm)

Get message to worker from manager.

Parameters

comm – libEnsemble communicator object

Returns

message tag, Work dictionary, calc_in array

gen_support.send_mgr_worker_msg(comm, output)

Send message from worker to manager.

Parameters

  • comm – libEnsemble communicator object

  • output – Output array to be sent to manager

Returns

None

gen_support.sendrecv_mgr_worker_msg(comm, output)

Send message from worker to manager and receive response.

Parameters

  • comm – libEnsemble communicator object

  • output – Output array to be sent to manager

Returns

message tag, Work dictionary, calc_in array

Allocation Function Support

These routines are used within custom allocation functions to help prepare Work structures for workers. See the routines within libensemble/alloc_funcs/ for examples.

alloc_support.all_returned(H, pt_filter=True)

Check if all expected points have returned from sim

Parameters

  • H – A history array

  • pt_filter – Optional boolean array filtering expected returned points: Default: All True

Returns

Boolean. True if all expected points have been returned

alloc_support.avail_worker_ids(W, persistent=None, active_recv=False)

Returns available workers (active == 0), as an array, filtered by persis_state.

Parameters

  • W – Worker array

  • persistent – Optional Boolean. If specified, also return workers with given persis_state.

alloc_support.count_gens(W)

Return the number of active generators in a set of workers.

Parameters

W – Worker array

alloc_support.count_persis_gens(W)

Return the number of active persistent generators in a set of workers.

Parameters

W – Worker array

alloc_support.gen_work(Work, i, H_fields, H_rows, persis_info, **libE_info)

Add gen work record to given Work array.

Parameters

  • W – Worker array

  • i – Worker ID.

  • H_fields – Which fields from H to send

  • persis_info – current persis_info dictionary

Returns

None

alloc_support.sim_work(Work, i, H_fields, H_rows, persis_info, **libE_info)

Add sim work record to given Work array.

Parameters

  • W – Worker array

  • i – Worker ID.

  • H_fields – Which fields from H to send

  • persis_info – current persis_info dictionary

Returns

None

alloc_support.test_any_gen(W)

Return True if a generator worker is active.

Parameters

W – Worker array