Add Submission example to docs

Author: Daraan

docs/source/index.rst

@@ -34,18 +34,71 @@ Quick Start
 
 .. code-block:: python
 
-   from ray_utilities.setup import PPOSetup
+   from ray_utilities.config import DefaultArgumentParser
    from ray_utilities.runfiles import run_tune
+   from ray_utilities.setup import PPOSetup
 
-   with PPOSetup() as setup:
+   with (
+      DefaultArgumentParser.patch_args(
+         # Override default CLI arguments. Passed CLI arguments still have a higher priority.
+         "--batch-size", 1024,
+      ),
+      PPOSetup() as setup
+   ):
       # Inside the with block modify your configuration
-      setup.config.env = "CartPole-v1"
+      # setup.config can be any AlgorithmConfig
+      setup.config.environment(env="CartPole-v1")
       setup.config.lr = 0.001
-   # Now the config is frozen and the setup.trainable is build
+   # After the with block the config is frozen and the setup.trainable is ready to use with Ray Tune
 
    # Run hyperparameter optimization
    results = run_tune(setup)
 
+
+Ray Job Submission CLI
+----------------------
+
+The script ``ray_submit.py`` provides a command-line interface for submitting and monitoring Ray jobs in bulk using a YAML configuration file.
+It leverages the Ray Job Submission API to automate experiment runs and track their status.
+See one of the submission scripts in ``experiments/`` for example usage how to define an entrypoint template and replacement variables.
+
+**Basic Usage:**
+
+.. code-block:: bash
+
+   # Basic use
+   python ray_submit.py <group|"all"|"monitor"|"restore"> <submissions_file.yaml> [--address <RAY_DASHBOARD_URL>] [--max-jobs <N>] [--test]
+
+   # View the help message for detailed options
+   python ray_submit.py --help
+
+**Arguments:**
+
+- ``group``: The group key in the YAML file to run, ``all`` for all groups, or ``monitor`` to only monitor jobs.
+  ``restore`` can be used to restore failed jobs. These must be labled with ``status: RESTORE`` in the YAML file.
+- ``submissions_file``: Path to the YAML file containing job definitions.
+- ``monitor_group``: (Optional) Additional group(s) to monitor.
+
+**Options:**
+
+- ``--address``: Address of the Ray cluster (default: uses ``DASHBOARD_ADDRESS`` env or ``localhost:8265``).
+- ``--test``: Run in test mode without submitting jobs.
+- ``--failed-only``: Only submit jobs that have previously failed.
+- ``--max-jobs``: Maximum number of jobs to submit concurrently.
+- ``--excludes ...``: Space-separated key words in the job name to exclude from submission.
+- ``--includes ...``: Space-separated key words in the job name to include for submission, excludes all non-matching jobs.
+
+**Example:**
+
+.. code-block:: bash
+
+   python ray_submit.py all submissions.yaml --failed-only
+
+This will submit all jobs defined in ``submissions.yaml`` that have previously failed, using the specified Ray cluster address.
+
+For more details, see the script's docstring or run ``python ray_submit.py --help``.
+
+
 Installation
 ------------
 

experiments/create_tune_parameters.py

@@ -79,6 +79,7 @@
     "vf_clip_param": {"grid_search": [0.05, 0.125, 0.33, 1.0, 2.0, 10.0, 100.0]},
     # kl_coeff if use_kl_loss; default is 0.2, target is 0.1
     "kl_coeff": {"grid_search": [0.025, 0.05, 0.1, 0.15, 0.2, 0.25, 0.3]},
+    # num_epochs: {"grid_search": [1, 4, 8, 16, 32, 64, 128]},
     # endregion PPO
     # Dummy value --tune test
     "test": {"grid_search": [1, 2, 3]},