General Specs

libEnsemble is primarily customized by setting options within a LibeSpecs class or dictionary.

from libensemble.specs import LibeSpecs

specs = LibeSpecs(
    comm=MPI.COMM_WORLD,
    comms="mpi",
    save_every_k_gens=1000,
    sim_dirs_make=True,
    ensemble_dir_path="/scratch/ensemble",
)

Complete Class API

pydantic model libensemble.specs.LibeSpecs

Specifications for configuring libEnsemble’s runtime behavior.

field H_file_prefix: str | None = 'libE_history': Prefix for H filename.

field abort_on_exception: bool | None = True: In MPI mode, whether to call MPI_ABORT on an exception. If False, an exception will be raised by the manager.

field authkey: str | None = 'libE_auth_38670': TCP Only: Authkey for Manager’s system.

field calc_dir_id_width: int | None = 4: The width of the numerical ID component of a calculation directory name. Leading zeros are padded to the sim/gen ID.

field comms: str | None = 'mpi': Manager/Worker communications mode. 'mpi', 'local', 'threads', or 'tcp' If nworkers is specified, then local comms will be used unless a parallel MPI environment is detected.

field dedicated_mode: bool | None = False: Instructs libEnsemble to not run applications on resources where libEnsemble processes (manager and workers) are running.

field disable_log_files: bool | None = False: Disable ensemble.log and libE_stats.txt log files.

field disable_resource_manager: bool | None = False: Disable the built-in resource manager, including automatic resource detection and/or assignment of resources to workers. "resource_info" will be ignored.

field dry_run: bool | None = False: Whether libEnsemble should immediately exit after validating all inputs.

field enforce_worker_core_bounds: bool | None = False: If False, the Executor will permit the submission of tasks with a higher processor count than the CPUs available to the worker as detected by the resource manager. Larger node counts are not allowed. When "disable_resource_manager" is True, this argument is ignored

field ensemble_copy_back: bool | None = False: Whether to copy back contents of ensemble_dir_path to launch location. Useful if ensemble_dir_path is located on node-local storage.

field ensemble_dir_path: str | Path | None = PosixPath('ensemble'): Path to main ensemble directory. Can serve as a single working directory for workers, or contain calculation directories

field final_gen_send: bool | None = False: Send final simulation results to persistent generators before shutdown. The results will be sent along with the PERSIS_STOP tag.

field gen_dir_copy_files: List[Path | str] | None = []: Paths to copy into the working directory upon calling the generator function. List of strings or pathlib.Path objects

field gen_dir_symlink_files: List[Path | str] | None = []: Paths to symlink into the working directory upon calling the generator function. List of strings or pathlib.Path objects.

field gen_dirs_make: bool | None = False: Whether to make generator-specific calculation directories for each generator function call.

field gen_input_dir: str | Path | None = None: Copy this directory’s contents into the working directory upon calling the generator function. Forms the base of a generator directory.

field gen_num_gpus: int | None = 0: The default number of GPUs required by generators. Unless overridden by the equivalent persis_info settings, generators will be allocated this many GPUs.

field gen_num_procs: int | None = 0: The default number of processors (MPI ranks) required by generators. Unless overridden by the equivalent persis_info settings, generators will be allocated this many processors for applications launched via the MPIExecutor.

field gen_on_manager: bool | None = False: Instructs Manager process to run generator functions. This generator function can access/modify user objects by reference.

field gen_workers: List[int] | None = []: List of workers that should only run generators. All other workers will only run simulator functions.

field gpus_per_group: int | None = None: Number of GPUs for each group in the scheduler. This can be used to deal with scenarios where nodes have different numbers of GPUs. In effect a block of this many GPUs will be treated as a virtual node. By default the GPUs on a node are treated as a group.

field ip: str | None = None: TCP Only: IP address for Manager’s system.

field kill_canceled_sims: bool | None = False: Try to kill sims with "cancel_requested" set True. If False, the manager avoids this moderate overhead.

field live_data: Any | None = None: Add a live data capture object (e.g., for plotting).

field mpi_comm: Any | None = None: libEnsemble MPI communicator. Default: MPI.COMM_WORLD

field num_resource_sets: int | None = 0: Total number of resource sets. Resources will be divided into this number. If not set, resources will be divided evenly (excluding zero_resource_workers).

field nworkers: int | None = 0: Number of worker processes in "local", "threads", or "tcp".

field platform: str | None = ''

Name of a known platform defined in the platforms module.

See Known Platforms List.

Example:

libE_specs["platform"] = "perlmutter_g"

Alternatively set the environment variable LIBE_PLATFORM:

export LIBE_PLATFORM="perlmutter_g"

Scheduler Options

See options for built-in scheduler.

Overriding Resource Auto-Detection

Note that "cores_on_node" and "gpus_on_node" are supported for backward compatibility, but use of Platform specification is recommended for these settings.

Formatting Options for libE_stats File

The allowable libE_specs["stats_fmt"] fields are:

"task_timing" [bool] = ``False``:
    Outputs elapsed time for each task launched by the executor.

"task_datetime" [bool] = ``False``:
    Outputs the elapsed time and start and end time for each task launched by the executor.
    Can be used with the ``"plot_libe_tasks_util_v_time.py"`` to give task utilization plots.

"show_resource_sets" [bool] = ``False``:
    Shows the resource set IDs assigned to each worker for each call of the user function.