From f66c61ba5c9907bcbd83917c60479b88ebb75669 Mon Sep 17 00:00:00 2001 From: shudson Date: Wed, 13 Sep 2023 17:43:37 -0500 Subject: [PATCH 1/2] Add platform specs section --- docs/data_structures/data_structures.rst | 1 + docs/data_structures/libE_specs.rst | 43 +------- docs/data_structures/platform_specs.rst | 110 ++++++++++++++++++++ docs/tutorials/executor_forces_tutorial.rst | 2 +- docs/tutorials/forces_gpu_tutorial.rst | 4 +- 5 files changed, 118 insertions(+), 42 deletions(-) create mode 100644 docs/data_structures/platform_specs.rst diff --git a/docs/data_structures/data_structures.rst b/docs/data_structures/data_structures.rst index 21fad3de23..fee823a3a6 100644 --- a/docs/data_structures/data_structures.rst +++ b/docs/data_structures/data_structures.rst @@ -13,5 +13,6 @@ See :ref:`here` for more information on combining these into a comp gen_specs libE_specs alloc_specs + platform_specs persis_info exit_criteria diff --git a/docs/data_structures/libE_specs.rst b/docs/data_structures/libE_specs.rst index 09fbb83a19..e8955d03c1 100644 --- a/docs/data_structures/libE_specs.rst +++ b/docs/data_structures/libE_specs.rst @@ -233,7 +233,7 @@ the ``LibeSpecs`` class. When provided as a Python class, options are validated "resource_info" [dict]: Provide resource information that will override automatically detected resources. - The allowable fields are given below in "Overriding Auto-detection" + The allowable fields are given below in "Overriding Resource Auto-Detection" Ignored if ``"disable_resource_manager"`` is set. "scheduler_opts" [dict]: @@ -251,40 +251,6 @@ the ``LibeSpecs`` class. When provided as a Python class, options are validated :field-list-validators: False :model-show-field-summary: False -.. _known-platforms: - -Known Platforms List --------------------- - -.. dropdown:: ``Known_platforms`` - :open: - - .. autopydantic_model:: libensemble.resources.platforms.Known_platforms - :model-show-validator-members: False - :model-show-validator-summary: False - :model-show-field-summary: False - :field-list-validators: False - :field-show-required: False - :field-show-default: False - :field-show-alias: False - :member-order: - -.. _platform-fields: - -Platform Fields ----------------- - -.. dropdown:: ``Platform Fields`` - :open: - - .. autopydantic_model:: libensemble.resources.platforms.Platform - :model-show-validator-members: False - :model-show-validator-summary: False - :field-list-validators: False - :field-show-default: False - :member-order: - :model-show-field-summary: False - Scheduler Options ----------------- @@ -296,7 +262,8 @@ Overriding Resource Auto-Detection ---------------------------------- Note that ``"cores_on_node"`` and ``"gpus_on_node"`` are supported for backward -compatibility, but use of ``platform_specs`` is recommended for these settings. +compatibility, but use of :ref:`Platform specification` is +recommended for these settings. .. dropdown:: Resource Info Fields @@ -342,8 +309,8 @@ compatibility, but use of ``platform_specs`` is recommended for these settings. libE_specs["resource_info"] = customizer -Formatting libE_stats.txt -------------------------- +Formatting Options for libE_stats File +-------------------------------------- The allowable ``libE_specs["stats_fmt"]`` fields are:: diff --git a/docs/data_structures/platform_specs.rst b/docs/data_structures/platform_specs.rst new file mode 100644 index 0000000000..6eb031f6d4 --- /dev/null +++ b/docs/data_structures/platform_specs.rst @@ -0,0 +1,110 @@ +.. _datastruct-platform-specs: + +Platform Specs +============== + +libEnsemble detects platform specfications including MPI runners and resources. +Usually this will result in the correct settings. However, users can configure +platform specification via the `platform_specs`_ option or indicate a known +platform via the `platform`_ option. + +platform_specs +-------------- + +A Platform object or dictionary specifying settings for a platform. + +To define a platform (in calling script): + +.. tab-set:: + + .. tab-item:: Platform Object + + .. code-block:: python + + from libensemble.resources.platforms import Platform + + libE_specs["platform_specs"] = Platform( + mpi_runner="srun", + cores_per_node=64, + logical_cores_per_node=128, + gpus_per_node=8, + gpu_setting_type="runner_default", + gpu_env_fallback="ROCR_VISIBLE_DEVICES", + scheduler_match_slots=False + ) + + .. tab-item:: Dictionary + + .. code-block:: python + + libE_specs["platform_specs"] = { + "mpi_runner" : "srun", + "cores_per_node": 64, + "logical_cores_per_node": 128, + "gpus_per_node": 8, + "gpu_setting_type": "runner_default", + "gpu_env_fallback": "ROCR_VISIBLE_DEVICES", + "scheduler_match_slots": False + } + +The list of platform fields are given below. Any fields not given, will be +auto-detected by libEnsemble. + +.. _platform-fields: + +.. dropdown:: ``Platform Fields`` + :open: + + .. autopydantic_model:: libensemble.resources.platforms.Platform + :model-show-validator-members: False + :model-show-validator-summary: False + :field-list-validators: False + :field-show-default: False + :member-order: + :model-show-field-summary: False + +To use an existing platform: + +.. code-block:: python + + from libensemble.resources.platforms import PerlmutterGPU + + libE_specs["platform_specs"] = PerlmutterGPU() + +See :ref:`known platforms`. + +platform +-------- + +A string giving the name of a known platform defined in the platforms module. + +.. code-block:: python + + libE_specs["platform"] = "perlmutter_g" + +Note: the environment variable LIBE_PLATFORM is an alternative way of setting. + +E.g., on command line or batch submission script: + +.. code-block:: shell + + export LIBE_PLATFORM="perlmutter_g" + +.. _known-platforms: + +Known Platforms List +-------------------- + +.. dropdown:: ``Known_platforms`` + :open: + + .. autopydantic_model:: libensemble.resources.platforms.Known_platforms + :model-show-validator-members: False + :model-show-validator-summary: False + :model-show-field-summary: False + :field-list-validators: False + :field-show-required: False + :field-show-default: False + :field-show-alias: False + :member-order: + diff --git a/docs/tutorials/executor_forces_tutorial.rst b/docs/tutorials/executor_forces_tutorial.rst index a68da6ff0a..c77c010731 100644 --- a/docs/tutorials/executor_forces_tutorial.rst +++ b/docs/tutorials/executor_forces_tutorial.rst @@ -190,7 +190,7 @@ Write an alternative Calling Script similar to above, but with the following dif from libensemble import logger logger.set_level("DEBUG") - **Soln 2.** This can also be specified via :attr:`platform_specs` option. + **Soln 2.** This can also be specified via :ref:`platform_specs` option. .. code-block:: python :linenos: diff --git a/docs/tutorials/forces_gpu_tutorial.rst b/docs/tutorials/forces_gpu_tutorial.rst index 91429044b4..dfbba1b321 100644 --- a/docs/tutorials/forces_gpu_tutorial.rst +++ b/docs/tutorials/forces_gpu_tutorial.rst @@ -95,9 +95,7 @@ The user can also set ``num_procs`` and ``num_gpus`` in the generator as in the `forces_gpu_var_resources`_ example, and skip lines 31-32. Line 37 simply prints out how the GPUs were assigned. If this is not as expected, -a :attr:`platform_specs` *libE_specs* -option can be provided in the calling script. Alternatively, for known systems, -the LIBE_PLATFORM environment variable can be set. +:ref:`platform configuration` can be provided. While this is sufficient for many/most users, note that it is possible to query the resources assigned to *this* worker (nodes and partitions of nodes), From 71eaf16ef7118615a750d61a5f8aeb422928415b Mon Sep 17 00:00:00 2001 From: shudson Date: Wed, 13 Sep 2023 22:53:39 -0500 Subject: [PATCH 2/2] Add platform link --- docs/tutorials/executor_forces_tutorial.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/executor_forces_tutorial.rst b/docs/tutorials/executor_forces_tutorial.rst index c77c010731..cc437d7292 100644 --- a/docs/tutorials/executor_forces_tutorial.rst +++ b/docs/tutorials/executor_forces_tutorial.rst @@ -270,7 +270,7 @@ an argument string for our launched application. The particle count doubles up as a random number seed here. We then retrieve our previously instantiated Executor. libEnsemble will use -the MPI runner detected (or provided by platform options). +the MPI runner detected (or provided by :ref:`platform options`). As `num_procs` (or similar) is not specified, libEnsemble will assign the processors available to this worker.