Output Management

Each of the following output files can be placed in a run-specific directory by setting libE_specs["use_workflow_dir"] = True.

Default Log Files

The history array H and persis_info dictionary are returned to the user by libEnsemble. If libEnsemble aborts on an exception, these structures are dumped automatically to these files:

  • libE_history_at_abort_<sim_count>.npy

  • libE_history_at_abort_<sim_count>.pickle

To suppress libEnsemble from producing these two files, set libE_specs["save_H_and_persis_on_abort"] = False.

Two other libEnsemble files produced by default:

  • libE_stats.txt: One-line summaries for each user calculation.

  • ensemble.log: Logging output. Multiple runs will append output if this file isn’t removed. See below for config info.

To suppress libEnsemble from producing these two files, set libE_specs["disable_log_files"] = True.

Logger Configuration

The libEnsemble logger uses the standard Python logging levels (DEBUG, INFO, WARNING, ERROR, CRITICAL) plus one additional custom level (MANAGER_WARNING) between WARNING and ERROR.

The default level is INFO, which includes information about how tasks are submitted and when tasks are killed. To gain additional diagnostics, set the logging level to DEBUG. libEnsemble writes to ensemble.log by default. A log file name can also be supplied.

To change the logging level to DEBUG:

from libensemble import logger
logger.set_level("DEBUG")

Logger messages of MANAGER_WARNING level or higher are also displayed through stderr by default. This boundary can be adjusted:

from libensemble import logger

# Only display messages with level >= ERROR
logger.set_stderr_level("ERROR")

stderr displaying can be effectively disabled by setting the stderr level to CRITICAL.

logger.set_level(level)

Sets libEnsemble logging level

Parameters:

level (int) –

Return type:

None

logger.get_level()

Returns libEnsemble logging level

Return type:

int

logger.set_filename(filename)

Sets logger filename if loggers not yet created, else None

Parameters:

filename (str) –

Return type:

None

logger.set_directory(dirname)

Sets target directory to contain logfiles if loggers not yet created

Parameters:

dirname (str) –

Return type:

None

logger.set_stderr_level(level)

Sets logger to mirror certain messages to stderr

Parameters:

level (int) –

Return type:

None

logger.get_stderr_level()

Returns libEnsemble stderr logging level

Return type:

int

Note

The scripts directory, in the libEnsemble project root directory, contains scripts to compare outputs and create plots based on the ensemble output.

Timing analysis scripts

Note that all plotting scripts produce a file rather than opening a plot interactively.

The following scripts must be run in the directory with the libE_stats.txt file. They extract and plot information from that file.

  • plot_libe_calcs_util_v_time.py: Extracts worker utilization vs. time plot (with one-second sampling). Shows number of workers running user sim or gen functions over time.

  • plot_libe_tasks_util_v_time.py: Extracts launched task utilization v time plot (with one second sampling). Shows number of workers with active tasks, launched via the executor, over time.

  • plot_libe_histogram.py: Creates histogram showing the number of completed/killed/failed user calculations binned by run time.

Results analysis scripts

  • print_npy.py: Prints to screen from a given *.npy file containing a NumPy structured array. Use done to print only the lines containing "sim_ended" points. Example:

    ./print_npy.py run_libe_forces_results_History_length=1000_evals=8.npy done

  • print_fields.py: Prints to screen from a given *.npy file containing a NumPy structured array. This is a more versatile version of print_npy.py that allows the user to select fields to print and boolean conditions determining which rows are printed (see ./print_fields.py -h for usage).

  • compare_npy.py: Compares either two provided *.npy files or one provided *.npy file with an expected results file (by default located at ../expected.npy). A tolerance is given on floating-point results, and NANs are compared as equal. Variable fields (such as those containing a time) are ignored. These fields may need to be modified depending on the user’s history array.

  • plot_pareto_2d.py: Loop through objective points in f and extract the Pareto front. Arguments are an *.npy file and a budget.

  • plot_pareto_3d.py: Loop through objective points in f and extract the Pareto front. Arguments are an *.npy file and a budget.

  • print_pickle.py: Prints to screen from a given *.pickle file. Example:

    ./print_pickle.py persis_info_length=1000_evals=1000_workers=2.pickle