From 47409a3549ba55c87c2c13ed66901998fbd89cd6 Mon Sep 17 00:00:00 2001 From: shudson Date: Thu, 20 Mar 2025 16:54:53 -0500 Subject: [PATCH 01/18] Rename image --- ...d_new_detailed.png => centralized_dedicated.png} | Bin 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/images/{centralized_new_detailed.png => centralized_dedicated.png} (100%) diff --git a/docs/images/centralized_new_detailed.png b/docs/images/centralized_dedicated.png similarity index 100% rename from docs/images/centralized_new_detailed.png rename to docs/images/centralized_dedicated.png From bc6425636f71e63e2815b52bf61e7c63d7958f0e Mon Sep 17 00:00:00 2001 From: shudson Date: Thu, 20 Mar 2025 16:56:59 -0500 Subject: [PATCH 02/18] Update HPC running instructions --- docs/data_structures/libE_specs.rst | 4 +- docs/images/centralized_gen_on_manager.png | Bin 0 -> 102982 bytes docs/platforms/platforms_index.rst | 74 +++++++++++++-------- libensemble/specs.py | 4 +- 4 files changed, 51 insertions(+), 31 deletions(-) create mode 100644 docs/images/centralized_gen_on_manager.png diff --git a/docs/data_structures/libE_specs.rst b/docs/data_structures/libE_specs.rst index 2a9195cea5..fb092dce9d 100644 --- a/docs/data_structures/libE_specs.rst +++ b/docs/data_structures/libE_specs.rst @@ -272,8 +272,8 @@ libEnsemble is primarily customized by setting options within a ``LibeSpecs`` cl ``disable_resource_manager`` is set. **dedicated_mode** [bool] = ``False``: - Disallow any resources running libEnsemble processes (manager and workers) - from being valid targets for app submissions. + Instructs libEnsemble’s MPI executor not to run applications on nodes where + libEnsemble processes (manager and workers) are running. **zero_resource_workers** [list of ints]: List of workers (by IDs) that require no resources. For when a fixed mapping of workers diff --git a/docs/images/centralized_gen_on_manager.png b/docs/images/centralized_gen_on_manager.png new file mode 100644 index 0000000000000000000000000000000000000000..949f8e3968653c80503c58acd26b4bb4bf25de24 GIT binary patch literal 102982 zcmX`SbzGC*`#+9=(p{3HLrO)Z87V0s-60LqU85zWq>&Usq#Gm$qd{6a=4g-@Aq?2q zZ@%8Y@8|K@Kiq8heeUaA=Q`IjPQ13JG6^9AAr=-EiK>dC4i*+R5)11=CjKMLl}L52 za4alVELBB0y#R|N^M?U?%8N3d{@1_R9KZZfH+`aAR+gdT$oJCOa=qdXPp=}Iu%!;g zZ)D1Q;>H$19!KThhL%p(2x?k>{2p>*?^YP<=WTcLQ?e--Dt=MuEui8`_#h@+UY4zx zTpOPkmm2%upUdo4)~$lNB)b21<^R5*LIHY-|G#hj-!*D%`$Sm>PGmvDguPU>{@lNR zQz;h@4g9IAto!e_i7XGAIKfePWUcg1t-?cz_Ha@csV-c|cL$*jPDq>iROFdh>d0OzkY$@ZnXafuUjcrgueIncZjv4xU;H zi?m5R$_u-g8~f1_k$whdVAJgsPl+Hv5HjEn4)^dU_a~E-loa);AY$Pp_2sneTI_zG zv#k!PW4lj)`=6XfICua1kqkaQgseY-_4b^(jWQa5&i?J+nFu}0n3VNH-!^C;<-J@o#Yh#Re&5^akyNp1wcD@zQVTN!PwjBwRHitTDMd@S zNjz9xb%gx&I{{|~q~l>+pyAw~7o4ngMc#;*IWIV4K~g{cc($-`ucw8eHb2%kDPFyG z%t#_GBE$J8%s=M2_bgKY?`34i0H^l>ZiwHo-|^Wv_+XOiJHM+X*^^_>wJb|kq{ih< z6Uih6B@6fM4_dT|*WDm`?_sE~?tdv^HH81P-67IKdH3P6gF5h4-_03iX%X}$rlz{t zkH25Mi%>i9!W&LikZj{5_EM0Kk1zDkLd~G>faRw!5f)&j)4yDTkv|P8A!<+dm6Z*r z3kV?xU7}=XbNBDCu^r&Srbqr(g(=xMKe_|@N~YGJl&A9n`Y?UtYm1mafyV8xd!AB| z7iDHbJ)+byOaIFxPVD+g)AQ4+tC&y&*3*T6y=xo=2NGDg3%@qM81%0DWGApdo6XGyihY!9j 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≪88YJcR+9fMv}r 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 gives an +example with a simple MPI application. -The first mode we refer to as **central** mode, where the libEnsemble manager and worker processes -are grouped onto one or more dedicated nodes. Workers launch applications onto -the remaining allocated nodes: +Central Mode +------------ - .. image:: ../images/centralized_new_detailed.png +The default communications scheme places the manager and workers on the first node. +The :doc:`MPI Executor<../executor/mpi_executor>` can then be used on each +simulation worker to distribute user applications across the current node allocation. + +The generator will run on a worker by default, but if running a single generator, +the :ref:`libE_specs` option **gen_on_manager** is recommended, +which runs the generator on the manager (using a thread) as below. + + .. image:: ../images/centralized_gen_on_manager.png + :alt: centralized + :scale: 55 + :align: center + + +If the :ref:`libE_specs` option **dedicated_mode** is set to +True, the MPI executor will not launch applications on nodes where libEnsemble Python +processes (manager and workers) are running. Worker’s launch applications onto the +remaining nodes in the allocation. + + .. image:: ../images/centralized_dedicated.png :alt: centralized :scale: 30 :align: center -Alternatively, in **distributed** mode, the libEnsemble (manager/worker) processes -will share nodes with submitted tasks. This enables libEnsemble, using the *mpi4py* -communicator, to be run with the workers spread across nodes so as to be co-located +.. note:: + Note that **gen_on_manager** is not set in the above example. + +Note that while these diagrams show one application being run per node, configurations +with multiple nodes per worker or multiple workers per node are both common use cases. + +Distributed Mode +---------------- + +In the **distributed** approach, libEnsemble, using the *mpi4py* communicator, +can be run with the workers spread across nodes so as to be co-located with their tasks. .. image:: ../images/distributed_new_detailed.png @@ -30,10 +56,10 @@ with their tasks. :scale: 30 :align: center -Configurations with multiple nodes per worker or multiple workers per node are both -common use cases. The distributed approach allows the libEnsemble worker to read files -produced by the application on local node storage. HPC systems that allow only one -application to be launched to a node at any one time prevent distributed configuration. +The distributed approach allows the libEnsemble worker to read files +produced by the application on local node storage. + +Distributed mode is also useful when workers are running simulations directly through Configuring the Run ------------------- @@ -63,22 +89,16 @@ or:: Either of these will run libEnsemble (inc. manager and 4 workers) on the first node. The remaining 4 nodes will be divided among the workers for submitted applications. If the same run was -performed without ``libE_specs["dedicated_mode"]=True``, runs could be submitted to all 5 nodes. The number of workers -can be modified to allow either multiple workers to map to each node or multiple nodes per worker. +performed without ``libE_specs["dedicated_mode"]=True``, runs could be submitted to all 5 nodes. +The number of workers can be modified to allow either multiple workers to map to each node or +multiple nodes per worker. To launch libEnsemble distributed requires a less trivial libEnsemble run script. For example:: mpirun -np 5 -ppn 1 python myscript.py -would launch libEnsemble with 5 processes across 5 nodes. However, the manager would have its -own node, which is likely wasteful. More often, a ``machinefile`` is used to add the manager to -the first node. In the :doc:`examples` directory, you can find an example submission -script, configured to run libensemble distributed, with multiple workers per node or multiple nodes -per worker, and adding the manager onto the first node. - -HPC systems that only allow one application to be launched to a node at any one time, -will not allow a distributed configuration. +would launch libEnsemble with 5 processes across 5 nodes. Systems with Launch/MOM Nodes ----------------------------- diff --git a/libensemble/specs.py b/libensemble/specs.py index 3b72482fc2..aa70018362 100644 --- a/libensemble/specs.py +++ b/libensemble/specs.py @@ -469,8 +469,8 @@ class LibeSpecs(BaseModel): dedicated_mode: Optional[bool] = False """ - Instructs libEnsemble to not run applications on resources where libEnsemble - processes (manager and workers) are running. + Instructs libEnsemble’s MPI executor not to run applications on nodes where + libEnsemble processes (manager and workers) are running. """ zero_resource_workers: Optional[List[int]] = [] From 2984dffdee89fe52e42a3c97b8991056dd89d104 Mon Sep 17 00:00:00 2001 From: shudson Date: Fri, 21 Mar 2025 15:51:02 -0500 Subject: [PATCH 03/18] Show code alongside diagram --- docs/platforms/platforms_index.rst | 39 +++++++++++++++++++++++------- 1 file changed, 30 insertions(+), 9 deletions(-) diff --git a/docs/platforms/platforms_index.rst b/docs/platforms/platforms_index.rst index b61693adfb..afed527d7d 100644 --- a/docs/platforms/platforms_index.rst +++ b/docs/platforms/platforms_index.rst @@ -17,6 +17,7 @@ Central Mode The default communications scheme places the manager and workers on the first node. The :doc:`MPI Executor<../executor/mpi_executor>` can then be used on each simulation worker to distribute user applications across the current node allocation. +This is the most common approach, when each simulation is running an MPI application. The generator will run on a worker by default, but if running a single generator, the :ref:`libE_specs` option **gen_on_manager** is recommended, @@ -27,6 +28,20 @@ which runs the generator on the manager (using a thread) as below. :scale: 55 :align: center + .. code-block:: python + + ensemble.libE_specs = LibeSpecs( + gen_on_manager=True, + ) + +When using **gen_on_manager**, set ``nworkers`` to the number of workers desired for running +simulations. A batch script may include: + + .. code-block:: bash + + #SBATCH --nodes 3 + + python run_libe_forces.py --nworkers 3 If the :ref:`libE_specs` option **dedicated_mode** is set to True, the MPI executor will not launch applications on nodes where libEnsemble Python @@ -38,28 +53,34 @@ remaining nodes in the allocation. :scale: 30 :align: center -.. note:: - Note that **gen_on_manager** is not set in the above example. +Note that **gen_on_manager** is not set in the above example. + + .. code-block:: python + + ensemble.libE_specs = LibeSpecs( + dedicated_mode=True, + ) + Note that while these diagrams show one application being run per node, configurations -with multiple nodes per worker or multiple workers per node are both common use cases. +with **multiple nodes per worker** or **multiple workers per node** are both common use cases. Distributed Mode ---------------- -In the **distributed** approach, libEnsemble, using the *mpi4py* communicator, -can be run with the workers spread across nodes so as to be co-located -with their tasks. +In the **distributed** approach, libEnsemble can be run using the **mpi4py** +communicator, with workers distributed across nodes to be co-located with their tasks. .. image:: ../images/distributed_new_detailed.png :alt: distributed :scale: 30 :align: center -The distributed approach allows the libEnsemble worker to read files -produced by the application on local node storage. +The distributed approach allows the libEnsemble worker to read files produced by the +application on local node storage. -Distributed mode is also useful when workers are running simulations directly through +Distributed mode is also useful when workers are running simulations directly, via a +Python interface. Configuring the Run ------------------- From c1734275d0d74e9e25780173ff37cba5797d61d8 Mon Sep 17 00:00:00 2001 From: shudson Date: Fri, 21 Mar 2025 15:54:50 -0500 Subject: [PATCH 04/18] Clarifying wording --- docs/platforms/platforms_index.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/platforms/platforms_index.rst b/docs/platforms/platforms_index.rst index afed527d7d..7451145181 100644 --- a/docs/platforms/platforms_index.rst +++ b/docs/platforms/platforms_index.rst @@ -15,9 +15,10 @@ Central Mode ------------ The default communications scheme places the manager and workers on the first node. -The :doc:`MPI Executor<../executor/mpi_executor>` can then be used on each -simulation worker to distribute user applications across the current node allocation. -This is the most common approach, when each simulation is running an MPI application. +The :doc:`MPI Executor<../executor/mpi_executor>` can then be invoked on each +simulation worker, and libEnsemble will distribute user applications across the +current node allocation. This is the most common approach, when each simulation +is running an MPI application. The generator will run on a worker by default, but if running a single generator, the :ref:`libE_specs` option **gen_on_manager** is recommended, From bd0c9426cba848a744fb405caf627973d1850775 Mon Sep 17 00:00:00 2001 From: shudson Date: Fri, 21 Mar 2025 18:26:49 -0500 Subject: [PATCH 05/18] Restructure HPC docs --- docs/platforms/platforms_index.rst | 85 +++++++++++++------------- docs/tutorials/forces_gpu_tutorial.rst | 2 + 2 files changed, 44 insertions(+), 43 deletions(-) diff --git a/docs/platforms/platforms_index.rst b/docs/platforms/platforms_index.rst index 7451145181..fd4836b9b8 100644 --- a/docs/platforms/platforms_index.rst +++ b/docs/platforms/platforms_index.rst @@ -77,6 +77,12 @@ communicator, with workers distributed across nodes to be co-located with their :scale: 30 :align: center + +To run using a 3-node allocation with 3 workers using an `mpich` based MPI. From the +head node of the allocation run the following (inc. manager and 3 workers):: + + mpirun -np 4 -ppn 1 python myscript.py + The distributed approach allows the libEnsemble worker to read files produced by the application on local node storage. @@ -92,35 +98,53 @@ the nodes within that allocation. *How does libEnsemble know where to run tasks (user applications)?* -The libEnsemble :doc:`Executor<../executor/ex_index>` can be initialized from the user calling +The libEnsemble :doc:`MPI Executor<../executor/mpi_executor>` can be initialized from the user calling script, and then used by workers to run tasks. The Executor will automatically detect the nodes available on most systems. Alternatively, the user can provide a file called **node_list** in the run directory. By default, the Executor will divide up the nodes evenly to each worker. -If the argument ``libE_specs["dedicated_mode"]=True`` is used when initializing libEnsemble, then any node -that is running a libEnsemble manager or worker will be removed from the node-list available -to the workers, ensuring libEnsemble has dedicated nodes. -To run in central mode using a 5-node allocation with 4 workers: From the head node -of the allocation:: +Mapping Tasks to Resources +-------------------------- - mpirun -np 5 python myscript.py +The :ref:`resource manager` detects node lists from +:ref:`common batch schedulers`, +and partition these to workers. The :doc:`MPI Executor<../executor/mpi_executor>` +accesses the resources available to the current worker when launching tasks. + +Zero-resource workers +~~~~~~~~~~~~~~~~~~~~~ + +Users with persistent ``gen_f`` functions may notice that the persistent workers +are still automatically assigned system resources. This can be resolved by using +the ``gen_on_manager`` option or by +:ref:`fixing the number of resource sets`. -or:: +Assigning GPUs +-------------- - python myscript.py --nworkers 4 +libEnsemble automatically detects and assigns Nvidia, AMD, and Intel GPUs without modifying the user scripts. This automatically works on many systems, but if the assignment is incorrect or needs to be modified the user can specify :ref:`platform information`. +The :doc:`forces_gpu tutorial<../tutorials/forces_gpu_tutorial>` shows an example of this. -Either of these will run libEnsemble (inc. manager and 4 workers) on the first node. The remaining -4 nodes will be divided among the workers for submitted applications. If the same run was -performed without ``libE_specs["dedicated_mode"]=True``, runs could be submitted to all 5 nodes. -The number of workers can be modified to allow either multiple workers to map to each node or -multiple nodes per worker. +Varying resources +----------------- -To launch libEnsemble distributed requires a less trivial libEnsemble run script. -For example:: +libEnsemble also features :ref:`dynamic resource assignment`, whereby the +number of processes and/or the number of GPUs can be a set for each simulation by the generator. + + +Overriding Auto-Detection +------------------------- + +libEnsemble can automatically detect system information. This includes resource information, such as +available nodes and the number of cores on the node, and information about available MPI runners. + +System detection for resources can be overridden using the :ref:`resource_info` +libE_specs option. + +When using the MPI Executor, it is possible to override the detected information using the +`custom_info` argument. See the :doc:`MPI Executor<../executor/mpi_executor>` for more. - mpirun -np 5 -ppn 1 python myscript.py -would launch libEnsemble with 5 processes across 5 nodes. Systems with Launch/MOM Nodes ----------------------------- @@ -160,31 +184,6 @@ or *to entirely different systems*. Submission scripts for running on launch/MOM nodes and for using Balsam, can be found in the :doc:`examples`. -Mapping Tasks to Resources --------------------------- - -The :ref:`resource manager` can :ref:`detect system resources`, -and partition these to workers. The :doc:`MPI Executor<../executor/mpi_executor>` -accesses the resources available to the current worker when launching tasks. - -Zero-resource workers -~~~~~~~~~~~~~~~~~~~~~ - -Users with persistent ``gen_f`` functions may notice that the persistent workers -are still automatically assigned system resources. This can be resolved by -:ref:`fixing the number of resource sets`. - -Overriding Auto-Detection -------------------------- - -libEnsemble can automatically detect system information. This includes resource information, such as -available nodes and the number of cores on the node, and information about available MPI runners. - -System detection for resources can be overridden using the :ref:`resource_info` -libE_specs option. - -When using the MPI Executor, it is possible to override the detected information using the -`custom_info` argument. See the :doc:`MPI Executor<../executor/mpi_executor>` for more. .. _globus_compute_ref: diff --git a/docs/tutorials/forces_gpu_tutorial.rst b/docs/tutorials/forces_gpu_tutorial.rst index e53687af4e..7e6423ac54 100644 --- a/docs/tutorials/forces_gpu_tutorial.rst +++ b/docs/tutorials/forces_gpu_tutorial.rst @@ -225,6 +225,8 @@ If you want to have two GPUs per worker on the same system (with four GPUs per n you could assign only four workers. You will see that two GPUs are used for each forces run. +.. _var_resources_gpu + Varying resources ----------------- From 0c8165c4286833cc576e37cae4be10f409df108c Mon Sep 17 00:00:00 2001 From: shudson Date: Fri, 21 Mar 2025 18:57:57 -0500 Subject: [PATCH 06/18] Fix broken link --- docs/platforms/platforms_index.rst | 2 +- docs/tutorials/forces_gpu_tutorial.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/platforms/platforms_index.rst b/docs/platforms/platforms_index.rst index fd4836b9b8..a46a4f23e8 100644 --- a/docs/platforms/platforms_index.rst +++ b/docs/platforms/platforms_index.rst @@ -128,7 +128,7 @@ The :doc:`forces_gpu tutorial<../tutorials/forces_gpu_tutorial>` shows an exampl Varying resources ----------------- -libEnsemble also features :ref:`dynamic resource assignment`, whereby the +libEnsemble also features :ref:`dynamic resource assignment`, whereby the number of processes and/or the number of GPUs can be a set for each simulation by the generator. diff --git a/docs/tutorials/forces_gpu_tutorial.rst b/docs/tutorials/forces_gpu_tutorial.rst index 7e6423ac54..ab1ee121fc 100644 --- a/docs/tutorials/forces_gpu_tutorial.rst +++ b/docs/tutorials/forces_gpu_tutorial.rst @@ -225,7 +225,7 @@ If you want to have two GPUs per worker on the same system (with four GPUs per n you could assign only four workers. You will see that two GPUs are used for each forces run. -.. _var_resources_gpu +.. _var-resources-gpu: Varying resources ----------------- From 2dea88ec9c1be08754a27942db8093add273f6a6 Mon Sep 17 00:00:00 2001 From: shudson Date: Sat, 22 Mar 2025 11:15:47 -0500 Subject: [PATCH 07/18] Put example code beside diagrams --- docs/platforms/platforms_index.rst | 78 ++++++++++++++++++++---------- 1 file changed, 52 insertions(+), 26 deletions(-) diff --git a/docs/platforms/platforms_index.rst b/docs/platforms/platforms_index.rst index a46a4f23e8..6f5c3e8f33 100644 --- a/docs/platforms/platforms_index.rst +++ b/docs/platforms/platforms_index.rst @@ -11,8 +11,8 @@ the available nodes. The :doc:`Forces tutorial <../../tutorials/executor_forces_tutorial>` gives an example with a simple MPI application. -Central Mode ------------- +Centralized Running +------------------- The default communications scheme places the manager and workers on the first node. The :doc:`MPI Executor<../executor/mpi_executor>` can then be invoked on each @@ -24,50 +24,76 @@ The generator will run on a worker by default, but if running a single generator the :ref:`libE_specs` option **gen_on_manager** is recommended, which runs the generator on the manager (using a thread) as below. - .. image:: ../images/centralized_gen_on_manager.png - :alt: centralized - :scale: 55 - :align: center +.. list-table:: + :widths: 60 40 - .. code-block:: python + * - .. image:: ../images/centralized_gen_on_manager.png + :alt: centralized + :scale: 55 - ensemble.libE_specs = LibeSpecs( - gen_on_manager=True, - ) + - In calling script: + + .. code-block:: python + :linenos: + + ensemble.libE_specs = LibeSpecs( + gen_on_manager=True, + ) + + A SLURM batch script may include: -When using **gen_on_manager**, set ``nworkers`` to the number of workers desired for running -simulations. A batch script may include: - .. code-block:: bash + .. code-block:: bash - #SBATCH --nodes 3 + #SBATCH --nodes 3 - python run_libe_forces.py --nworkers 3 + python run_libe_forces.py --nworkers 3 + + +When using **gen_on_manager**, set ``nworkers`` to the number of workers desired for running simulations. + +Dedicated Mode +^^^^^^^^^^^^^^ If the :ref:`libE_specs` option **dedicated_mode** is set to True, the MPI executor will not launch applications on nodes where libEnsemble Python processes (manager and workers) are running. Worker’s launch applications onto the remaining nodes in the allocation. - .. image:: ../images/centralized_dedicated.png - :alt: centralized - :scale: 30 - :align: center -Note that **gen_on_manager** is not set in the above example. +.. list-table:: + :widths: 60 40 - .. code-block:: python + * - .. image:: ../images/centralized_dedicated.png + :alt: centralized dedicated mode + :scale: 30 + + - In calling script: + + .. code-block:: python + :linenos: + + ensemble.libE_specs = LibeSpecs( + dedicated_mode=True, + ) + + A SLURM batch script may include: - ensemble.libE_specs = LibeSpecs( - dedicated_mode=True, - ) + .. code-block:: bash + + #SBATCH --nodes 3 + + python run_libe_forces.py --nworkers 3 + + +Note that **gen_on_manager** is not set in the above example. Note that while these diagrams show one application being run per node, configurations with **multiple nodes per worker** or **multiple workers per node** are both common use cases. -Distributed Mode ----------------- +Distributed Running +-------------------- In the **distributed** approach, libEnsemble can be run using the **mpi4py** communicator, with workers distributed across nodes to be co-located with their tasks. From 0d1e13b44a5152560312feed5475630c5b6823e8 Mon Sep 17 00:00:00 2001 From: shudson Date: Sat, 22 Mar 2025 11:23:23 -0500 Subject: [PATCH 08/18] Update example libE specs options and change order --- docs/data_structures/data_structures.rst | 4 ++-- docs/data_structures/libE_specs.rst | 11 +++++------ 2 files changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/data_structures/data_structures.rst b/docs/data_structures/data_structures.rst index 1d88d993dd..35a5ba0158 100644 --- a/docs/data_structures/data_structures.rst +++ b/docs/data_structures/data_structures.rst @@ -8,9 +8,9 @@ See :ref:`here` for instruction on constructing a complete workflow :maxdepth: 2 :caption: libEnsemble Specifications: - sim_specs - gen_specs libE_specs + gen_specs + sim_specs alloc_specs platform_specs persis_info diff --git a/docs/data_structures/libE_specs.rst b/docs/data_structures/libE_specs.rst index fb092dce9d..c0ca141403 100644 --- a/docs/data_structures/libE_specs.rst +++ b/docs/data_structures/libE_specs.rst @@ -1,7 +1,7 @@ .. _datastruct-libe-specs: -General Specs -============= +LibE Specs +========== libEnsemble is primarily customized by setting options within a ``LibeSpecs`` class or dictionary. @@ -10,11 +10,10 @@ libEnsemble is primarily customized by setting options within a ``LibeSpecs`` cl from libensemble.specs import LibeSpecs specs = LibeSpecs( - comm=MPI.COMM_WORLD, - comms="mpi", - save_every_k_gens=1000, + gen_on_manager=True, + save_every_k_gens=100, sim_dirs_make=True, - ensemble_dir_path="/scratch/ensemble", + nworkers=4 ) .. dropdown:: Settings by Category From 47cdd6618756754d0c9dc07f4710698ef0d52042 Mon Sep 17 00:00:00 2001 From: Jeffrey Larson Date: Mon, 24 Mar 2025 15:33:57 -0500 Subject: [PATCH 09/18] Update platforms_index.rst --- docs/platforms/platforms_index.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/platforms/platforms_index.rst b/docs/platforms/platforms_index.rst index 6f5c3e8f33..6af3725f8f 100644 --- a/docs/platforms/platforms_index.rst +++ b/docs/platforms/platforms_index.rst @@ -3,9 +3,9 @@ Running on HPC Systems ====================== -libEnsemble has been tested on systems of highly varying scales, from laptops to +libEnsemble has been tested on systems of highly varying scales, from laptops to thousands of compute nodes. On multi-node systems, there are a few alternative -ways of configuring libEnsemble to run and launch tasks (user applications) on +ways of configuring libEnsemble to run and launch tasks (i.e., user applications) on the available nodes. The :doc:`Forces tutorial <../../tutorials/executor_forces_tutorial>` gives an @@ -15,12 +15,12 @@ Centralized Running ------------------- The default communications scheme places the manager and workers on the first node. -The :doc:`MPI Executor<../executor/mpi_executor>` can then be invoked on each +The :doc:`MPI Executor<../executor/mpi_executor>` can then be invoked by each simulation worker, and libEnsemble will distribute user applications across the -current node allocation. This is the most common approach, when each simulation -is running an MPI application. +node allocation. This is the most common approach where each simulation +runs an MPI application. -The generator will run on a worker by default, but if running a single generator, +The generator will run on one worker by default, but if running a single generator, the :ref:`libE_specs` option **gen_on_manager** is recommended, which runs the generator on the manager (using a thread) as below. From 4113234a88446fe18b02844364d3453c6be8dd43 Mon Sep 17 00:00:00 2001 From: Jeffrey Larson Date: Mon, 24 Mar 2025 15:39:16 -0500 Subject: [PATCH 10/18] Update platforms_index.rst --- docs/platforms/platforms_index.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/platforms/platforms_index.rst b/docs/platforms/platforms_index.rst index 6af3725f8f..baf57b7ae9 100644 --- a/docs/platforms/platforms_index.rst +++ b/docs/platforms/platforms_index.rst @@ -57,7 +57,7 @@ Dedicated Mode If the :ref:`libE_specs` option **dedicated_mode** is set to True, the MPI executor will not launch applications on nodes where libEnsemble Python -processes (manager and workers) are running. Worker’s launch applications onto the +processes (manager and workers) are running. Workers launch applications onto the remaining nodes in the allocation. @@ -112,7 +112,7 @@ head node of the allocation run the following (inc. manager and 3 workers):: The distributed approach allows the libEnsemble worker to read files produced by the application on local node storage. -Distributed mode is also useful when workers are running simulations directly, via a +Distributed mode is also useful when workers run simulations directly, via a Python interface. Configuring the Run @@ -134,7 +134,7 @@ Mapping Tasks to Resources The :ref:`resource manager` detects node lists from :ref:`common batch schedulers`, -and partition these to workers. The :doc:`MPI Executor<../executor/mpi_executor>` +and partitions these to workers. The :doc:`MPI Executor<../executor/mpi_executor>` accesses the resources available to the current worker when launching tasks. Zero-resource workers @@ -207,7 +207,7 @@ or *to entirely different systems*. (New) Multi-System: libEnsemble + BalsamExecutor -Submission scripts for running on launch/MOM nodes and for using Balsam, can be found in +Submission scripts for running on launch/MOM nodes and for using Balsam can be found in the :doc:`examples`. From 5dd254a06b73b9a99546dd54f996cbeeaa6ac07c Mon Sep 17 00:00:00 2001 From: shudson Date: Mon, 7 Apr 2025 11:05:35 -0500 Subject: [PATCH 11/18] Modify distributed docs --- docs/platforms/platforms_index.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/platforms/platforms_index.rst b/docs/platforms/platforms_index.rst index baf57b7ae9..a70ad05ee5 100644 --- a/docs/platforms/platforms_index.rst +++ b/docs/platforms/platforms_index.rst @@ -96,24 +96,24 @@ Distributed Running -------------------- In the **distributed** approach, libEnsemble can be run using the **mpi4py** -communicator, with workers distributed across nodes to be co-located with their tasks. +communicator, with workers distributed across nodes. This is most often used +when workers run simulation code directly, via a Python interface, and may be +run an mpirunner, for example (using an `mpich` based MPI):: + + mpirun -np 4 -ppn 1 python myscript.py + +The distributed approach, can also be used with the executor, to co-locate workers +with the applications they submit. To ensure workers are placed as required in this +case, requires a careful MPI rank placement. .. image:: ../images/distributed_new_detailed.png :alt: distributed :scale: 30 :align: center +This allows the libEnsemble worker to read files produced by the application on +local node storage. -To run using a 3-node allocation with 3 workers using an `mpich` based MPI. From the -head node of the allocation run the following (inc. manager and 3 workers):: - - mpirun -np 4 -ppn 1 python myscript.py - -The distributed approach allows the libEnsemble worker to read files produced by the -application on local node storage. - -Distributed mode is also useful when workers run simulations directly, via a -Python interface. Configuring the Run ------------------- From f5be0c4b62b3793ab6d623e0d9ce69992718dbe3 Mon Sep 17 00:00:00 2001 From: shudson Date: Mon, 7 Apr 2025 11:41:50 -0500 Subject: [PATCH 12/18] Update submission scripts docs add note --- docs/platforms/example_scripts.rst | 43 +++++++++++-------- .../submit_perlmutter.sh | 3 +- 2 files changed, 26 insertions(+), 20 deletions(-) diff --git a/docs/platforms/example_scripts.rst b/docs/platforms/example_scripts.rst index 3f63524520..93ab2a5cfd 100644 --- a/docs/platforms/example_scripts.rst +++ b/docs/platforms/example_scripts.rst @@ -2,8 +2,22 @@ Example Scheduler Submission Scripts ==================================== Below are example submission scripts used to configure and launch libEnsemble -on a variety of high-powered systems. See :ref:`here` for more -information about the respective systems and configuration. +on a variety of high-powered systems. See :ref:`Running on HPC Systems` +for more information about the respective systems and configuration. + +.. note:: + It is **highly recommended** that the directive lines (e.g., #SBATCH) in batch + submission scripts do **NOT** specify processor, task, or GPU configuration info + --- these lines should only specify the number of nodes required. + + For example, do not specify ``#SBATCH --gpus-per-node=4`` in order to use four + GPUs on the node, when each worker may use less than this, as this may assign + all of the GPUs to a single MPI invocation. Instead, the configuration should + be supplied either + :doc:`in the simulation function<../examples/sim_funcs/forces_simf_gpu>` + or, if using dynamic resources, + :doc:`in the generator<../examples/sim_funcs/forces_simf_gpu_vary_resources>`. + General examples ---------------- @@ -55,22 +69,22 @@ System Examples :caption: /examples/libE_submission_scripts/submit_pbs_polaris.sh :language: bash -.. dropdown:: Bridges - Central Mode +.. dropdown:: Bebop - Central Mode - .. literalinclude:: ../../examples/libE_submission_scripts/bridges_submit_slurm_central.sh - :caption: /examples/libE_submission_scripts/bridges_submit_slurm_central.sh + .. literalinclude:: ../../examples/libE_submission_scripts/bebop_submit_pbs_central.sh + :caption: /examples/libE_submission_scripts/bebop_submit_pbs_central.sh :language: bash -.. dropdown:: Bebop - Central Mode +.. dropdown:: Bridges - MPI / Central Mode - .. literalinclude:: ../../examples/libE_submission_scripts/bebop_submit_slurm_central.sh - :caption: /examples/libE_submission_scripts/bebop_submit_slurm_central.sh + .. literalinclude:: ../../examples/libE_submission_scripts/bridges_submit_slurm_central.sh + :caption: /examples/libE_submission_scripts/bridges_submit_slurm_central.sh :language: bash -.. dropdown:: Bebop - Distributed Mode +.. dropdown:: SLURM - MPI / Distributed Mode (co-locate workers & MPI applications) - .. literalinclude:: ../../examples/libE_submission_scripts/bebop_submit_pbs_distrib.sh - :caption: /examples/libE_submission_scripts/bebop_submit_pbs_distrib.sh + .. literalinclude:: ../../examples/libE_submission_scripts/submit_distrib_mpi4py.sh + :caption: /examples/libE_submission_scripts/submit_distrib_mpi4py.sh :language: bash .. dropdown:: Summit (Decommissioned) - On Launch Nodes with Multiprocessing @@ -78,10 +92,3 @@ System Examples .. literalinclude:: ../../examples/libE_submission_scripts/summit_submit_mproc.sh :caption: /examples/libE_submission_scripts/summit_submit_mproc.sh :language: bash - -.. dropdown:: Cobalt - Intermediate node with Multiprocessing - - .. literalinclude:: ../../examples/libE_submission_scripts/cobalt_submit_mproc.sh - :caption: /examples/libE_submission_scripts/cobalt_submit_mproc.sh - :language: bash - diff --git a/examples/libE_submission_scripts/submit_perlmutter.sh b/examples/libE_submission_scripts/submit_perlmutter.sh index ae34d39e56..8a029761ab 100644 --- a/examples/libE_submission_scripts/submit_perlmutter.sh +++ b/examples/libE_submission_scripts/submit_perlmutter.sh @@ -7,10 +7,9 @@ # This script is using GPU partition export MPICH_GPU_SUPPORT_ENABLED=1 -export SLURM_EXACT=1 # One worker for generator and 4 for sims (one GPU each) python libe_calling_script.py -n 5 # Or if libE_specs option gen_on_manager=True -python libe_calling_script.py -n 4 +# python libe_calling_script.py -n 4 From df38474ad7ef52ee42324220b0057c1511cc677e Mon Sep 17 00:00:00 2001 From: shudson Date: Mon, 7 Apr 2025 11:56:35 -0500 Subject: [PATCH 13/18] Comment out fallback lines --- examples/libE_submission_scripts/submit_distrib_mpi4py.sh | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/examples/libE_submission_scripts/submit_distrib_mpi4py.sh b/examples/libE_submission_scripts/submit_distrib_mpi4py.sh index d696c1dfa6..2d15c07abb 100644 --- a/examples/libE_submission_scripts/submit_distrib_mpi4py.sh +++ b/examples/libE_submission_scripts/submit_distrib_mpi4py.sh @@ -20,10 +20,11 @@ export NUM_WORKERS=4 export MANAGER_NODE=false # true = Manager has a dedicated node (assign one extra) export USE_NODE_LIST=true # If false, allow libE to determine node_list from environment. +# Sometimes may be necessary # As libE shares nodes with user applications allow fallback if contexts overrun. -unset I_MPI_FABRICS -export I_MPI_FABRICS_LIST=tmi,tcp -export I_MPI_FALLBACK=1 +# unset I_MPI_FABRICS +# export I_MPI_FABRICS_LIST=tmi,tcp +# export I_MPI_FALLBACK=1 # If using in calling script (After N mins manager kills workers and exits cleanly) export LIBE_WALLCLOCK=55 From ac9bae32abcadb07a41dc2e2444b46406ff2218f Mon Sep 17 00:00:00 2001 From: shudson Date: Mon, 7 Apr 2025 11:57:06 -0500 Subject: [PATCH 14/18] Example scripts - replace dropdowns --- docs/platforms/example_scripts.rst | 100 ++++++++++++++++------------- 1 file changed, 56 insertions(+), 44 deletions(-) diff --git a/docs/platforms/example_scripts.rst b/docs/platforms/example_scripts.rst index 93ab2a5cfd..f26a310d0b 100644 --- a/docs/platforms/example_scripts.rst +++ b/docs/platforms/example_scripts.rst @@ -22,73 +22,85 @@ for more information about the respective systems and configuration. General examples ---------------- -.. dropdown:: Slurm - Basic +Slurm - Basic +^^^^^^^^^^^^^ - .. literalinclude:: ../../examples/libE_submission_scripts/submit_slurm_simple.sh - :caption: /examples/libE_submission_scripts/submit_slurm_simple.sh - :language: bash +.. literalinclude:: ../../examples/libE_submission_scripts/submit_slurm_simple.sh + :caption: /examples/libE_submission_scripts/submit_slurm_simple.sh + :language: bash -.. dropdown:: PBS - Basic +PBS - Basic +^^^^^^^^^^^ - .. literalinclude:: ../../examples/libE_submission_scripts/submit_pbs_simple.sh - :caption: /examples/libE_submission_scripts/submit_pbs_simple.sh - :language: bash +.. literalinclude:: ../../examples/libE_submission_scripts/submit_pbs_simple.sh + :caption: /examples/libE_submission_scripts/submit_pbs_simple.sh + :language: bash -.. dropdown:: LSF - Basic +LSF - Basic +^^^^^^^^^^^ - .. literalinclude:: ../../examples/libE_submission_scripts/submit_lsf_simple.sh - :caption: /examples/libE_submission_scripts/submit_lsf_simple.sh - :language: bash +.. literalinclude:: ../../examples/libE_submission_scripts/submit_lsf_simple.sh + :caption: /examples/libE_submission_scripts/submit_lsf_simple.sh + :language: bash System Examples --------------- -.. dropdown:: Aurora +Aurora +^^^^^^ - .. literalinclude:: ../../examples/libE_submission_scripts/submit_pbs_aurora.sh - :caption: /examples/libE_submission_scripts/submit_pbs_aurora.sh - :language: bash +.. literalinclude:: ../../examples/libE_submission_scripts/submit_pbs_aurora.sh + :caption: /examples/libE_submission_scripts/submit_pbs_aurora.sh + :language: bash -.. dropdown:: Frontier (Large WarpX Ensemble) +Frontier (Large WarpX Ensemble) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - .. literalinclude:: ../../examples/libE_submission_scripts/submit_frontier_large.sh - :caption: /examples/libE_submission_scripts/submit_frontier_large.sh - :language: bash +.. literalinclude:: ../../examples/libE_submission_scripts/submit_frontier_large.sh + :caption: /examples/libE_submission_scripts/submit_frontier_large.sh + :language: bash +Perlmutter +^^^^^^^^^^ -.. dropdown:: Perlmutter +.. literalinclude:: ../../examples/libE_submission_scripts/submit_perlmutter.sh + :caption: /examples/libE_submission_scripts/submit_perlmutter.sh + :language: bash - .. literalinclude:: ../../examples/libE_submission_scripts/submit_perlmutter.sh - :caption: /examples/libE_submission_scripts/submit_perlmutter.sh - :language: bash +Polaris +^^^^^^^ -.. dropdown:: Polaris +.. literalinclude:: ../../examples/libE_submission_scripts/submit_pbs_polaris.sh + :caption: /examples/libE_submission_scripts/submit_pbs_polaris.sh + :language: bash - .. literalinclude:: ../../examples/libE_submission_scripts/submit_pbs_polaris.sh - :caption: /examples/libE_submission_scripts/submit_pbs_polaris.sh - :language: bash +Bebop - Central Mode +^^^^^^^^^^^^^^^^^^^^ -.. dropdown:: Bebop - Central Mode +.. literalinclude:: ../../examples/libE_submission_scripts/bebop_submit_pbs_central.sh + :caption: /examples/libE_submission_scripts/bebop_submit_pbs_central.sh + :language: bash - .. literalinclude:: ../../examples/libE_submission_scripts/bebop_submit_pbs_central.sh - :caption: /examples/libE_submission_scripts/bebop_submit_pbs_central.sh - :language: bash +Bridges - MPI / Central Mode +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. dropdown:: Bridges - MPI / Central Mode +.. literalinclude:: ../../examples/libE_submission_scripts/bridges_submit_slurm_central.sh + :caption: /examples/libE_submission_scripts/bridges_submit_slurm_central.sh + :language: bash - .. literalinclude:: ../../examples/libE_submission_scripts/bridges_submit_slurm_central.sh - :caption: /examples/libE_submission_scripts/bridges_submit_slurm_central.sh - :language: bash +.. _slurm_mpi_distributed: -.. dropdown:: SLURM - MPI / Distributed Mode (co-locate workers & MPI applications) +SLURM - MPI / Distributed Mode (co-locate workers & MPI applications) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - .. literalinclude:: ../../examples/libE_submission_scripts/submit_distrib_mpi4py.sh - :caption: /examples/libE_submission_scripts/submit_distrib_mpi4py.sh - :language: bash +.. literalinclude:: ../../examples/libE_submission_scripts/submit_distrib_mpi4py.sh + :caption: /examples/libE_submission_scripts/submit_distrib_mpi4py.sh + :language: bash -.. dropdown:: Summit (Decommissioned) - On Launch Nodes with Multiprocessing +Summit (Decommissioned) - On Launch Nodes with Multiprocessing +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - .. literalinclude:: ../../examples/libE_submission_scripts/summit_submit_mproc.sh - :caption: /examples/libE_submission_scripts/summit_submit_mproc.sh - :language: bash +.. literalinclude:: ../../examples/libE_submission_scripts/summit_submit_mproc.sh + :caption: /examples/libE_submission_scripts/summit_submit_mproc.sh + :language: bash From e49626cbc85be75eec149db9ff77415df3e8afa8 Mon Sep 17 00:00:00 2001 From: shudson Date: Mon, 7 Apr 2025 11:57:43 -0500 Subject: [PATCH 15/18] Link to distrib config script --- docs/platforms/platforms_index.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/platforms/platforms_index.rst b/docs/platforms/platforms_index.rst index a70ad05ee5..8d0f01fc69 100644 --- a/docs/platforms/platforms_index.rst +++ b/docs/platforms/platforms_index.rst @@ -97,14 +97,14 @@ Distributed Running In the **distributed** approach, libEnsemble can be run using the **mpi4py** communicator, with workers distributed across nodes. This is most often used -when workers run simulation code directly, via a Python interface, and may be -run an mpirunner, for example (using an `mpich` based MPI):: +when workers run simulation code directly, via a Python interface. The user +script is invoked with an MPI runner, for example (using an `mpich` based MPI):: mpirun -np 4 -ppn 1 python myscript.py The distributed approach, can also be used with the executor, to co-locate workers with the applications they submit. To ensure workers are placed as required in this -case, requires a careful MPI rank placement. +case, requires :ref:`a careful MPI rank placement `. .. image:: ../images/distributed_new_detailed.png :alt: distributed From 2581de2cd7e5161b8b10f6b61635828289ed0113 Mon Sep 17 00:00:00 2001 From: shudson Date: Mon, 7 Apr 2025 11:59:04 -0500 Subject: [PATCH 16/18] Fix naming --- docs/platforms/example_scripts.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/platforms/example_scripts.rst b/docs/platforms/example_scripts.rst index f26a310d0b..072cc65f22 100644 --- a/docs/platforms/example_scripts.rst +++ b/docs/platforms/example_scripts.rst @@ -75,8 +75,8 @@ Polaris :caption: /examples/libE_submission_scripts/submit_pbs_polaris.sh :language: bash -Bebop - Central Mode -^^^^^^^^^^^^^^^^^^^^ +Bebop +^^^^^ .. literalinclude:: ../../examples/libE_submission_scripts/bebop_submit_pbs_central.sh :caption: /examples/libE_submission_scripts/bebop_submit_pbs_central.sh From 6691a9f7700a7de475c8f08e1d502a4266fabbe0 Mon Sep 17 00:00:00 2001 From: shudson Date: Mon, 7 Apr 2025 12:10:16 -0500 Subject: [PATCH 17/18] Minor reformatting --- docs/platforms/platforms_index.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/platforms/platforms_index.rst b/docs/platforms/platforms_index.rst index 8d0f01fc69..1b682480dd 100644 --- a/docs/platforms/platforms_index.rst +++ b/docs/platforms/platforms_index.rst @@ -5,22 +5,26 @@ Running on HPC Systems libEnsemble has been tested on systems of highly varying scales, from laptops to thousands of compute nodes. On multi-node systems, there are a few alternative -ways of configuring libEnsemble to run and launch tasks (i.e., user applications) on -the available nodes. +ways of configuring libEnsemble to run and launch tasks (i.e., user applications) +on the available nodes. The :doc:`Forces tutorial <../../tutorials/executor_forces_tutorial>` gives an example with a simple MPI application. +Note that while the diagrams below show one application being run per node, +configurations with **multiple nodes per worker** or **multiple workers per node** +are both common use cases. + Centralized Running ------------------- The default communications scheme places the manager and workers on the first node. The :doc:`MPI Executor<../executor/mpi_executor>` can then be invoked by each simulation worker, and libEnsemble will distribute user applications across the -node allocation. This is the most common approach where each simulation +node allocation. This is the **most common approach** where each simulation runs an MPI application. -The generator will run on one worker by default, but if running a single generator, +The generator will run on a worker by default, but if running a single generator, the :ref:`libE_specs` option **gen_on_manager** is recommended, which runs the generator on the manager (using a thread) as below. @@ -89,9 +93,6 @@ remaining nodes in the allocation. Note that **gen_on_manager** is not set in the above example. -Note that while these diagrams show one application being run per node, configurations -with **multiple nodes per worker** or **multiple workers per node** are both common use cases. - Distributed Running -------------------- From 97e6fdbc1d788f70f806938b9c42f33f9e00bbf8 Mon Sep 17 00:00:00 2001 From: shudson Date: Mon, 7 Apr 2025 13:46:34 -0500 Subject: [PATCH 18/18] Add num_resource_sets setting to example --- docs/platforms/platforms_index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/platforms/platforms_index.rst b/docs/platforms/platforms_index.rst index 1b682480dd..c56ab66aa9 100644 --- a/docs/platforms/platforms_index.rst +++ b/docs/platforms/platforms_index.rst @@ -78,6 +78,7 @@ remaining nodes in the allocation. :linenos: ensemble.libE_specs = LibeSpecs( + num_resource_sets=2, dedicated_mode=True, )