Release/v 1.0.0

.wci.yml

@@ -2,8 +2,8 @@ name: libEnsemble
 icon: https://raw.githubusercontent.com/Libensemble/libensemble/main/docs/images/libE_logo.png
 headline: Tool for running dynamic ensembles.
 description: |
-  libEnsemble is a Python toolkit for coordinating workflows of asynchronous
-  and dynamic ensembles of calculations.
+  libEnsemble is a Python toolkit for running workflows dynamic ensembles
+  of calculations.
 
   Users write generator and simulator functions to express their ensembles.
   A library of example functions is available which can be modified as needed.
@@ -17,8 +17,8 @@ description: |
 language: Python
 
 release:
-  version: 0.10.2
-  date: 2023-07-24
+  version: 1.0.0
+  date: 2023-09-22
 
 documentation:
   general: https://libensemble.readthedocs.io

CHANGELOG.rst

@@ -8,6 +8,71 @@ GitHub issues are referenced, and can be viewed with hyperlinks on the `github r
 
 .. _`github releases page`: https://github.com/Libensemble/libensemble/releases
 
+Release 1.0.0
+--------------
+
+:Date: September 22, 2023
+
+New capabilities:
+
+* *libE_specs* option `final_gen_send` returns last results to the generator (replaces `final_fields`). #1086
+* *libE_specs* option `reuse_output_dir` * allows reuse of workflow and ensemble directories. #1028 #1041
+* *libE_specs* option `calc_dir_id_width` no. of digits for calc ID in output sim/gen dirs. #1052 / #1066
+* Added `gen_num_procs` and `gen_num_gpus` *libE_specs* (and *persis_info*) options for resourcing a generator. #1068
+* Added `gpu_env_fallback` option to platform fields - specifies a GPU environment variable (for non-MPI usage). #1050
+* New MPIExecutor `submit()` argument `mpi_runner_type` specifies an MPI runner for current call only. #1054
+* Allow oversubscription when using the `num_procs` *gen_specs["out"]* option. #1058
+* sim/gen_specs can use `outputs` in place of `out` to be consistent with `inputs`. #1075
+* Executor can be obtained from `libE_info` (4th parameter) in user-functions #1078
+
+Breaking changes:
+
+* *libE_specs* option `final_fields` is removed in favor of `final_gen_send`. #1086
+* *libE_specs* option *kill_canceled_sims* nows defaults to **False**. #1062
+* *parse_args* is not run automatically by `Ensemble` constructor.
+
+Updates to **Object Oriented** ensemble interface:
+
+* Add `parse_args` as option to `Ensemble` constructor. #1065
+* The *executor* can be passed as an option to the `Ensemble` constructor. #1078
+* Better handling of `Ensemble.add_random_streams` and `ensemble.persis_info`. #1074
+
+* Output changes:
+  * The worker ID suffix is removed from sim/gen output directories #1041
+  * Separate *ensemble.log* and *libE_stats.txt* for diff workflows directories. #1027 #1041
+  * Defaults to four digits for sim/gen ID in output dirs (adds digits on overflow). #1052 / #1066
+
+Bug fixes:
+* Resolved PETSc/OpenMPI issue (when using the Executor). #1064
+* Prevent `mpi4py` validation running during local comms (when using OO interface) #1065
+
+Performance changes:
+* Optimize `kill_cancelled_sims` function.  #1043 / #1063
+* *safe_mode* defaults to False (for performance). #1053
+
+Updates to example functions:
+
+* Multiple regression tests and examples ported to use OO ensemble interface. #1014
+
+* Update forces examples
+  * Make persistent generator the default for both simple and GPU examples (inc. updated tutorials).
+  * Update to object oriented interface.
+  * Added separate variable resources example for forces GPU.
+  * Rename `multi_task` example to `multi_app`.
+
+Documentation:
+
+* General overhaul and simplification of documentation. #992
+
+:Note:
+
+* Tested platforms include Linux, MacOS, Windows and major systems including Frontier (OLCF), Polaris, and Perlmutter (NERSC). The major system tests ran heterogeneous workflows.
+* Tested Python versions: (Cpython) 3.7, 3.8, 3.9, 3.10, 3.11.
+
+:Known issues:
+
+* See known issues section in the documentation.
+
 Release 0.10.2
 --------------
 

docs/FAQ.rst

@@ -4,7 +4,17 @@ Frequently Asked Questions
 
 If you have any additional questions, feel free to contact us through Support_.
 
-.. _Support: https://github.com/Libensemble/libensemble#resources
+.. _Support: https://libensemble.readthedocs.io/en/main/introduction.html#resources
+
+
+Debugging
+---------
+
+We recommend using the following options to help debug workflows::
+
+    from libensemble import logger
+    logger.set_level("DEBUG")
+    libE_specs["safe_mode"] = True
 
 Common Errors
 -------------

docs/introduction.rst

@@ -20,29 +20,30 @@ and an exit condition. Run the following via ``python this_file.py --comms local
   from libensemble.specs import ExitCriteria, GenSpecs, SimSpecs
   from libensemble.tools import add_unique_random_streams
 
-  sampling = Ensemble(parse_args=True)
-  sampling.sim_specs = SimSpecs(
-      sim_f=six_hump_camel,
-      inputs=["x"],
-      outputs=[("f", float)],
-  )
-  sampling.gen_specs = GenSpecs(
-      gen_f=uniform_random_sample,
-      outputs=[("x", float, (2,))],
-      user={
-          "gen_batch_size": 500,
-          "lb": np.array([-3, -2]),
-          "ub": np.array([3, 2]),
-      },
-  )
-
-  sampling.persis_info = add_unique_random_streams({}, sampling.nworkers + 1)
-  sampling.exit_criteria = ExitCriteria(sim_max=101)
-
   if __name__ == "__main__":
+      sampling = Ensemble(parse_args=True)
+      sampling.sim_specs = SimSpecs(
+          sim_f=six_hump_camel,
+          inputs=["x"],
+          outputs=[("f", float)],
+      )
+      sampling.gen_specs = GenSpecs(
+          gen_f=uniform_random_sample,
+          outputs=[("x", float, (2,))],
+          user={
+              "gen_batch_size": 500,
+              "lb": np.array([-3, -2]),
+              "ub": np.array([3, 2]),
+          },
+      )
+
+      sampling.persis_info = add_unique_random_streams({}, sampling.nworkers + 1)
+      sampling.exit_criteria = ExitCriteria(sim_max=101)
       sampling.run()
       sampling.save_output(__file__)
-  print("Some output data:\n", sampling.H[["x", "f"]][:10])
+
+      if sampling.is_manager:
+          print("Some output data:\n", sampling.H[["x", "f"]][:10])
 
 See the :doc:`tutorial<tutorials/local_sine_tutorial>` for a step-by-step beginners guide.
 

docs/resource_manager/overview.rst

@@ -68,7 +68,7 @@ along with the work request (simulation).
 In the calling script, use a ``gen_specs["out"]`` field called ``resource_sets``:
 
 .. code-block:: python
-    :emphasize-lines: 4
+    :emphasize-lines: 6
 
     gen_specs = {
         "gen_f": gen_f,
@@ -133,7 +133,7 @@ For example, in *CUDA_variable_resources*, the environment variable
 ``CUDA_VISIBLE_DEVICES`` is set to slots:
 
 .. code-block:: python
-    :emphasize-lines: 3
+    :emphasize-lines: 2
 
     resources = Resources.resources.worker_resources
     resources.set_env_to_slots("CUDA_VISIBLE_DEVICES")  # Use convenience function.

libensemble/specs.py

@@ -531,7 +531,7 @@ def set_workflow_dir(cls, values):
 
 
 class _EnsembleSpecs(BaseModel):
-    """An all-encompasing model for a libEnsemble workflow."""
+    """An all-encompassing model for a libEnsemble workflow."""
 
     H0: Optional[Any] = None  # np.ndarray - avoids sphinx issue
     """ A previous or preformatted libEnsemble History array to prepend. """

libensemble/tests/regression_tests/test_persistent_surmise_killsims.py

@@ -76,7 +76,7 @@
     libE_specs["sim_dirs_make"] = True  # To keep all - make sim dirs
     # libE_specs["use_worker_dirs"] = True  # To overwrite - make worker dirs only
 
-    # Rename ensemble dir for non-inteference with other regression tests
+    # Rename ensemble dir for non-interference with other regression tests
     libE_specs["ensemble_dir_path"] = "ensemble_calib_kills"
 
     sim_specs = {

libensemble/version.py

@@ -1 +1 @@
-__version__ = "0.10.2+dev"
+__version__ = "1.0.0"

setup.py

@@ -96,7 +96,7 @@ def run_tests(self):
         "scripts/libesubmit",
     ],
     classifiers=[
-        "Development Status :: 4 - Beta",
+        "Development Status :: 5 - Production/Stable",
         "Intended Audience :: Developers",
         "Intended Audience :: Science/Research",
         "License :: OSI Approved :: BSD License",