Merge pull request #79 from mnlevy1981/add_argparse

Use click to allow command line arguments

README.md

@@ -65,4 +65,33 @@ $ cupid-build config.yml # Will build HTML from Jupyter Book
 ```
 
 After the last step is finished, you can use Jupyter to view generated notebooks in `${CUPID_ROOT}/examples/coupled-model/computed_notebooks/quick-run`
-or you can view `${CUPID_ROOT}/examples/coupled-model/computed_notebooks/quick-run/_build/html/index.html` in a web browser.
+or you can view `${CUPID_ROOT}/examples/coupled-model/computed_notebooks/quick-run/_build/html/index.html` in a web browser.
+
+### CUPiD Options
+
+Most of CUPiD's configuration is done via the `config.yml` file, but there are a few command line options as well:
+
+```bash
+(cupid-dev) $ cupid-run -h
+Usage: cupid-run [OPTIONS] CONFIG_PATH
+
+  Main engine to set up running all the notebooks.
+
+Options:
+  -s, --serial        Do not use LocalCluster objects
+  -ts, --time-series  Run time series generation scripts prior to diagnostics
+  -h, --help          Show this message and exit.
+```
+
+By default, several of the example notebooks provided use a dask `LocalCluster` object to run in parallel.
+However, the `--serial` option will pass a logical flag to each notebook that can be used to skip starting the cluster.
+
+```py3
+# Spin up cluster (if running in parallel)
+client=None
+if not serial:
+  cluster = LocalCluster(**lc_kwargs)
+  client = Client(cluster)
+
+client
+```

cupid/run.py

@@ -1,29 +1,34 @@
 #!/usr/bin/env python
 
+import click
 import os
+import sys
 from glob import glob
 import papermill as pm
 import intake
 import cupid.util
-import sys
 from dask.distributed import Client
 import dask
 import time
 import ploomber
 
-def run():
+CONTEXT_SETTINGS = dict(help_option_names=['-h', '--help'])
+@click.command(context_settings=CONTEXT_SETTINGS)
+@click.option("--serial", "-s", is_flag=True, help="Do not use LocalCluster objects")
+@click.option("--time-series", "-ts", is_flag=True,
+              help="Run time series generation scripts prior to diagnostics")
+@click.argument("config_path")
+def run(config_path, serial=False, time_series=False):
     """
-    Main engine to set up running all the notebooks. Called by `cupid-run`.
-
-    Args:
-        none
-    Returns:
-        None
-
+    Main engine to set up running all the notebooks.
     """
 
+    # Abort if run with --time-series (until feature is added)
+    if time_series:
+        sys.tracebacklimit = 0
+        raise NotImplementedError("--time-series option not implemented yet")
+
     # Get control structure
-    config_path = str(sys.argv[1])
     control = cupid.util.get_control_dict(config_path)
     cupid.util.setup_book(config_path)
 
@@ -87,6 +92,7 @@ def run():
 
     for nb, info in all_nbs.items():
 
+        global_params['serial'] = serial
         if "dependency" in info:
             cupid.util.create_ploomber_nb_task(nb, info, cat_path, nb_path_root, output_dir, global_params, dag, dependency = info["dependency"])
 

environments/dev-environment.yml

@@ -2,6 +2,7 @@ name: cupid-dev
 dependencies:
     - python=3.11.4
     - black
+    - click
     - dask
     - dask-jobqueue
     - intake

examples/nblibrary/ocean_surface.ipynb

@@ -65,6 +65,7 @@
    "outputs": [],
    "source": [
     "CESM_output_dir = \"/glade/campaign/cesm/development/cross-wg/diagnostic_framework/CESM_output_for_testing\"\n",
+    "serial = False # use dask LocalCluster\n",
     "Case = \"b.e23_alpha16b.BLT1850.ne30_t232.054\"\n",
     "savefigs = False\n",
     "mom6_tools_config = {}\n",
@@ -130,9 +131,11 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Spin up cluster\n",
-    "cluster = LocalCluster(**lc_kwargs)\n",
-    "client = Client(cluster)\n",
+    "# Spin up cluster (if running in parallel)\n",
+    "client=None\n",
+    "if not serial:\n",
+    "  cluster = LocalCluster(**lc_kwargs)\n",
+    "  client = Client(cluster)\n",
     "\n",
     "client"
    ]

examples/nblibrary/seaice.ipynb

@@ -45,6 +45,7 @@
    "outputs": [],
    "source": [
     "CESM_output_dir = \"/glade/campaign/cesm/development/cross-wg/diagnostic_framework/CESM_output_for_testing\"\n",
+    "serial = False # use dask LocalCluster\n",
     "cases = [\"g.e23_a16g.GJRAv4.TL319_t232_zstar_N65.2024.004\",\"g.e23_a16g.GJRAv4.TL319_t232_hycom1_N75.2024.005\"]\n",
     "\n",
     "lc_kwargs = {}\n",
@@ -63,9 +64,11 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Spin up cluster\n",
-    "cluster = LocalCluster(**lc_kwargs)\n",
-    "client = Client(cluster)\n",
+    "# Spin up cluster (if running in parallel)\n",
+    "client=None\n",
+    "if not serial:\n",
+    "  cluster = LocalCluster(**lc_kwargs)\n",
+    "  client = Client(cluster)\n",
     "\n",
     "client"
    ]

pyproject.toml

@@ -24,6 +24,7 @@ classifiers = [
 ]
 dependencies = [
     "black",
+    "click",
     "dask",
     "dask-jobqueue",
     "intake",