You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-``/regression_tests`` - Tests libEnsemble code with external code. Often more closely resembles actual use-cases.
25
25
-``/unit_tests`` - Tests for individual modules.
26
-
-``/tools`` - Tools. Misc functions and classes to ease development.
27
-
-``/utils`` - Utilities. Misc functions and classes used internally by multiple modules.
28
-
-``ensemble.py`` - The primary interface for parameterizing and running libEnsemble.
26
+
-``ensemble.py`` - The primary interface for parameterizing and running libEnsemble. The ``Ensemble`` class in this module wraps the lower-level ``libE`` function and automates argument parsing and state management.
29
27
-``generators.py`` - Base classes for generators that adhere to the `gest-api` standard.
30
-
-``history.py`` - Module for recording points that have been generated and simulation results. NumPy array.
31
-
-``libE.py`` - libE main file. Previous primary interface for parameterizing and running libEnsemble.
32
-
-``logger.py`` - Logging configuration.
28
+
-``history.py`` - Module for recording points that have been generated and simulation results. NumPy structured array.
29
+
-``libE.py`` - libE main file. Previous primary interface for parameterizing and running libEnsemble. The primary interface in ``ensemble.py`` wraps this function.
33
30
-``manager.py`` - Module for maintaining the history array and passing points between the workers.
34
31
-``message_numbers.py`` - Constants that represent states of the ensemble.
35
32
-``specs.py`` - Dataclasses for parameterizing the ensemble. Most importantly, contains ``LibeSpecs, SimSpecs, GenSpecs``.
36
33
-``worker.py`` - Module for running generators and simulators. Communicates with the manager.
37
-
-``version.py`` - Version file.
38
-
39
-
-``.github/`` - GitHub actions. See ``.github/workflows/`` for the CI.
40
-
-``docs/`` - Documentation. Check here first for information before reading the source code.
41
34
-``examples/`` - The ``*_funcs`` and ``calling_scripts`` directories contain symlinks to examples further in the source code.
42
35
-``/libE_submission_scripts`` - Example scripts for submitting libEnsemble jobs to HPC systems.
43
36
-``/tutorials`` - Tutorials on how to use libEnsemble.
44
-
-``pyproject.toml`` - Project configuration file. Contains information about the project and its dependencies.
45
-
46
-
Other files in the root directory should be self-documenting.
47
37
48
38
Information about Generators
49
39
----------------------------
@@ -55,8 +45,10 @@ Its fields match ``sim_specs/gen_specs["out"]`` or ``vocs`` attributes, plus add
55
45
long-running loop, sending and receiving points to and from the manager until the ensemble was complete.
56
46
- A ``gest-api`` or "standardized" generator is a class that at a minimum implements ``suggest`` and ``ingest`` methods, and is parameterized by a ``vocs``.
57
47
- See ``libensemble/generators.py`` for more information about the ``gest-api`` standard.
58
-
- If using a generator that adheres to the ``gest-api`` standard, or a classic persistent generator, use the ``start_only_persistent`` allocation function.
59
48
- Generators are often used for simple sampling, optimization, calibration, uncertainty quantification, and other simulation-based tasks.
49
+
-**Automatic Variable Mapping**: Subclasses of ``LibensembleGenerator`` (like ``UniformSample``) automatically map all ``VOCS`` variables to a single multi-dimensional ``"x"`` field in the History array if no explicit ``variables_mapping`` is provided.
50
+
-**Mandatory Input Fields**: Even for simple generators that don't ingest data, ``gen_specs["in"]`` or ``gen_specs["persis_in"]`` must be defined if using an allocation function like ``only_persistent_gens`` that attempts to send rows. If these are empty, the manager will raise an ``AssertionError`` stating that no fields were requested to be sent.
51
+
-**Default Allocator**: ``only_persistent_gens`` is the default allocator for standardized ``gest-api`` generators. It treats these generators as persistent entities that communicate throughout the run.
60
52
61
53
General Guidelines
62
54
------------------
@@ -77,7 +69,7 @@ Development Environment
77
69
-----------------------
78
70
79
71
-``pixi`` is the recommended environment manager for libEnsemble development. See ``pyproject.toml`` for the list
80
-
of dependencies and the available testing environments.
72
+
of dependencies and the available testing environments. (Note: If ``pixi`` is not in your system path, it can often be found in ``/opt/homebrew/bin/pixi`` or ``/usr/local/bin/pixi``).
81
73
- Enter the development environment with ``pixi shell -e dev``. This environment contains the most common dependencies for development and testing.
82
74
- For one-off commands, use ``pixi run -e dev``. This will run a single command in the development environment.
83
75
- If ``pixi`` is not available or not preferred by the user, ``pip install -e .`` can be used instead. Other dependencies may need to be installed manually.
@@ -87,9 +79,21 @@ the configuration and ``pyproject.toml`` for other configuration.
87
79
Testing
88
80
-------
89
81
90
-
- Run tests with the ``run-tests.py`` script: ``python libensemble/tests/run-tests.py``. See ``libensemble/tests/run-tests.py`` for usage information.
82
+
- Run tests with the ``run_tests.py`` script: ``python libensemble/tests/run_tests.py``. See ``libensemble/tests/run_tests.py`` for usage information.
91
83
- Some tests require third party software to be installed. When developing a feature or fixing a bug, since the entire test suite will be run on Github Actions,
92
84
for local development running individual tests is sufficient.
93
85
- Individual unit tests can be run with ``pixi run -e dev pytest path/to/test_file``.
94
86
- A libEnsemble run typically outputs an ``ensemble.log`` and ``libE_stats.txt`` file in the working directory. Check these files for tracebacks or run statistics.
95
87
- An "ensemble" or "workflow" directory may also be created, often containing per-simulation output directories
88
+
89
+
Modernizing Scripts for libEnsemble 2.0
90
+
---------------------------------------
91
+
92
+
When modernizing existing libEnsemble scripts (functionality tests, regression tests, or user examples) for version 2.0, follow these steps:
93
+
94
+
-**Switch to `gest-api` Generators**: Replace legacy generator functions (from `libensemble.gen_funcs`) with standardized generator classes (from `libensemble.gen_classes` or other `gest-api` compatible sources).
95
+
-**Use `VOCS` for Parameterization**: Standardized generators are parameterized by a `VOCS` object (from `gest_api.vocs`). Define variables and objectives within this object.
96
+
-**Set `gen_specs["generator"]`**: Instead of `gen_f`, use the `generator` field in `GenSpecs` to pass the initialized generator class.
97
+
-**Remove Explicit `AllocSpecs`**: In libEnsemble 2.0, `only_persistent_gens` is the default allocator. Scripts that previously used `give_sim_work_first` or other simple allocators can often remove `alloc_specs` entirely when switching to standardized generators.
98
+
-**Generator Placement**: By default, generators run on the manager thread (Worker 0). This means all allocated workers are available for simulation tasks unless `gen_on_worker` is explicitly set to `True` in `libE_specs`.
99
+
-**Mandatory Fields**: Ensure `gen_specs["in"]` or `gen_specs["persis_in"]` includes at least one field (e.g., `["sim_id"]`) if feedback is sent back to the generator, to satisfy the allocator's requirements.
0 commit comments