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 abort_on_exception: Optional[bool] = True: In MPI mode, whether to call MPI_ABORT on an exception. If False, an exception will be raised by the manager.

field authkey: Optional[str] = 'libE_auth_33770': TCP Only: Authkey for Manager’s system.

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

field comms: Optional[str] = 'mpi': Manager/Worker communications mode. 'mpi', 'local', or 'tcp'

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

field disable_log_files: Optional[bool] = False: Disable ensemble.log and libE_stats.txt log files.

field disable_resource_manager: Optional[bool] = 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: Optional[bool] = False: Whether libEnsemble should immediately exit after validating all inputs.

field enforce_worker_core_bounds: Optional[bool] = 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: Optional[bool] = 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: Optional[Union[str, Path]] = PosixPath('ensemble'): Path to main ensemble directory. Can serve as a single working directory for workers, or contain calculation directories

field final_gen_send: Optional[bool] = 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: Optional[List[Union[str, Path]]] = []: Paths to copy into the working directory upon calling the generator function. List of strings or pathlib.Path objects

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

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

field gen_input_dir: Optional[Union[str, Path]] = None: Copy this directory’s contents into the working directory upon calling the generator function.

field gen_num_gpus: Optional[int] = None: 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: Optional[int] = None: 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 ip: Optional[str] = None: TCP Only: IP address for Manager’s system.

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

field mpi_comm: Optional[Any] = None: libEnsemble MPI communicator. Default: MPI.COMM_WORLD

field num_resource_sets: Optional[int] = None: 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: Optional[int] = None: Number of worker processes in "local" or "tcp".

field platform: Optional[str] = ''

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.