Smartsim Documentation Refactor

doc/api/smartsim_api.rst

@@ -34,6 +34,8 @@ Experiment
    :members:
 
 
+.. _settings-info:
+
 Settings
 ========
 
@@ -388,12 +390,14 @@ Orchestrator
 Orchestrator
 ------------
 
+.. _orchestrator_api:
 
 .. autoclass:: Orchestrator
    :members:
    :inherited-members:
    :undoc-members:
 
+.. _model_api:
 
 Model
 =====
@@ -417,17 +421,17 @@ Model
    Model.disable_key_prefixing
    Model.query_key_prefixing
 
+Model
+-----
+
 .. autoclass:: Model
    :members:
    :show-inheritance:
    :inherited-members:
 
-.. _ensemble_api:
-
 Ensemble
 ========
 
-
 .. currentmodule:: smartsim.entity.ensemble
 
 .. autosummary::
@@ -443,6 +447,11 @@ Ensemble
    Ensemble.query_key_prefixing
    Ensemble.register_incoming_entity
 
+Ensemble
+--------
+
+.. _ensemble_api:
+
 .. autoclass:: Ensemble
    :members:
    :show-inheritance:

doc/batch_settings.rst

@@ -0,0 +1,113 @@
+.. _batch_settings_doc:
+**************
+Batch Settings
+**************
+========
+Overview
+========
+SmartSim provides functionality to launch entities (``Model`` or ``Ensemble``)
+as batch jobs supported by the ``BatchSettings`` base class. While the ``BatchSettings`` base
+class is not intended for direct use by users, its derived child classes offer batch
+launching capabilities tailored for specific workload managers (WLMs). Each SmartSim
+`launcher` interfaces with a ``BatchSettings`` subclass specific to a system's WLM:
+
+- The Slurm `launcher` supports:
+   - :ref:`SbatchSettings<sbatch_api>`
+- The PBS Pro `launcher` supports:
+   - :ref:`QsubBatchSettings<qsub_api>`
+- The LSF `launcher` supports:
+   - :ref:`BsubBatchSettings<bsub_api>`
+
+.. note::
+      The local `launcher` does not support batch jobs.
+
+After creating a ``BatchSettings`` instance, users gain access to the attributes and methods
+of the associated child class, providing them with the ability to further configure the batch
+settings for jobs.
+
+In the following :ref:`Examples<batch_settings_ex>` subsection, we demonstrate the initialization
+and configuration of a batch settings object for each supported SmartSim `launcher`.
+
+.. _batch_settings_ex:
+========
+Examples
+========
+A ``BatchSettings`` child class is created using the ``Experiment.create_batch_settings()``
+factory method. When the user initializes the ``Experiment`` at the beginning of the Python driver script,
+they may specify a `launcher` argument. SmartSim will then register or detect the `launcher` and return the
+corresponding supported child class when ``Experiment.create_batch_settings()`` is called. This
+design allows SmartSim driver scripts utilizing ``BatchSettings`` to be portable between systems,
+requiring only a change in the specified `launcher` during ``Experiment`` initialization.
+
+Below are examples of how to initialize a ``BatchSettings`` object per `launcher`.
+
+.. tabs::
+
+    .. group-tab:: Slurm
+      To instantiate the ``SbatchSettings`` object, which interfaces with the Slurm job scheduler, specify
+      `launcher="slurm"` when initializing the ``Experiment``. Upon calling ``create_batch_settings()``,
+      SmartSim will detect the job scheduler and return the appropriate batch settings object.
+
+        .. code-block:: python
+
+            from smartsim import Experiment
+
+            # Initialize the experiment and provide launcher Slurm
+            exp = Experiment("name-of-experiment", launcher="slurm")
+
+            # Initialize a SbatchSettings object
+            sbatch_settings = exp.create_batch_settings(nodes=1, time="10:00:00", batch_args={"ntasks": 1})
+            # Set the account for the slurm batch job
+            sbatch_settings.set_account("12345-Cray")
+            # Set the partition for the slurm batch job
+            sbatch_settings.set_queue("default")
+
+      The initialized ``SbatchSettings`` instance can now be passed to a SmartSim entity
+      (``Model`` or ``Ensemble``) via the `batch_settings` argument in ``create_batch_settings()``.
+
+    .. group-tab:: PBS Pro
+      To instantiate the ``QsubBatchSettings`` object, which interfaces with the PBS Pro job scheduler, specify
+      `launcher="pbs"` when initializing the ``Experiment``. Upon calling ``create_batch_settings()``,
+      SmartSim will detect the job scheduler and return the appropriate batch settings object.
+
+        .. code-block:: python
+
+            from smartsim import Experiment
+
+            # Initialize the experiment and provide launcher PBS Pro
+            exp = Experiment("name-of-experiment", launcher="pbs")
+
+            # Initialize a QsubBatchSettings object
+            qsub_batch_settings = exp.create_batch_settings(nodes=1, time="10:00:00", batch_args={"ntasks": 1})
+            # Set the account for the PBS Pro batch job
+            qsub_batch_settings.set_account("12345-Cray")
+            # Set the partition for the PBS Pro batch job
+            qsub_batch_settings.set_queue("default")
+
+      The initialized ``QsubBatchSettings`` instance can now be passed to a SmartSim entity
+      (``Model`` or ``Ensemble``) via the `batch_settings` argument in ``create_batch_settings()``.
+
+    .. group-tab:: LSF
+      To instantiate the ``BsubBatchSettings`` object, which interfaces with the LSF job scheduler, specify
+      `launcher="lsf"` when initializing the ``Experiment``. Upon calling ``create_batch_settings()``,
+      SmartSim will detect the job scheduler and return the appropriate batch settings object.
+
+        .. code-block:: python
+
+            from smartsim import Experiment
+
+            # Initialize the experiment and provide launcher LSF
+            exp = Experiment("name-of-experiment", launcher="lsf")
+
+            # Initialize a BsubBatchSettings object
+            bsub_batch_settings = exp.create_batch_settings(nodes=1, time="10:00:00", batch_args={"ntasks": 1})
+            # Set the account for the lsf batch job
+            bsub_batch_settings.set_account("12345-Cray")
+            # Set the partition for the lsf batch job
+            bsub_batch_settings.set_queue("default")
+
+      The initialized ``BsubBatchSettings`` instance can now be passed to a SmartSim entity
+      (``Model`` or ``Ensemble``) via the `batch_settings` argument in ``create_batch_settings()``.
+
+.. warning::
+      Note that initialization values provided (e.g., `nodes`, `time`, etc) will overwrite the same arguments in `batch_args` if present.

doc/conf.py

@@ -52,7 +52,8 @@
     'breathe',
     'nbsphinx',
     'sphinx_copybutton',
-    'sphinx_tabs.tabs'
+    'sphinx_tabs.tabs',
+    'sphinx_panels'
 ]
 
 suppress_warnings = ['autosectionlabel']