Add platform specs section

docs/data_structures/data_structures.rst

@@ -13,5 +13,6 @@ See :ref:`here<libe-module>` for more information on combining these into a comp
    gen_specs
    libE_specs
    alloc_specs
+   platform_specs
    persis_info
    exit_criteria

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<datastruct-platform-specs>` 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::
 

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<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:
+

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<libensemble.specs.LibeSpecs.platform_specs>` option.
+   **Soln 2.** This can also be specified via :ref:`platform_specs<datastruct-platform-specs>` option.
 
    .. code-block:: python
        :linenos:
@@ -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<datastruct-platform-specs>`).
 As `num_procs` (or similar) is not specified, libEnsemble will assign the processors
 available to this worker.
 

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<libensemble.specs.LibeSpecs.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<datastruct-platform-specs>` 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),