Move common functions in example scripts into new module

docs/source/contributing.rst

@@ -100,6 +100,18 @@ Installing a Development Version
 10. For testing see `Tests`_.
 
 
+
+Building Documentation
+----------------------
+
+To build a local copy of the docs, from the repo root directory, do
+
+::
+
+  python setup.py build_sphinx
+
+
+
 Contributing Code
 -----------------
 
@@ -179,6 +191,61 @@ A feature development workflow might look like this:
 11. Delete the branch after it has been merged.
 
 
+Adding Data
+-----------
+
+The following steps show how to add new data, ``new_data.npz``, to the packaged data. We assume the SCICO repository has been cloned to ``scico/``.
+
+Note that the data is located in the scico-data submodule, which is
+symlinked to ``scico/data``.  When adding new data, both the scico and
+scico-data repositories must be updated and kept in sync.
+
+
+1. Add the ``new_data.npz`` file to the ``scico/data`` directory.
+
+2. Navigate to the ``data`` directory and add/commit the new data file:
+
+   ::
+
+      cd scico/data
+      git add new_data.npz
+      git commit -m "Add new data file"
+
+3.  Return to the base SCICO repository, ensure the ``main`` branch is checked out, add/commit the new data and update submodule:
+
+   ::
+
+      cd ..  # pwd now `scico` repo root
+      git checkout main
+      git add data
+      git commit -m "Add data and update data module"
+
+4.  Push both repositories:
+
+   ::
+
+      git submodule foreach --recursive 'git push' && git push
+
+
+Type Checking
+-------------
+
+In the future, we will require all code to pass ``mypy`` type checking. This is not currently enforced.
+
+Install ``mypy``:
+
+::
+
+   conda install mypy
+
+To run the type checker on the ``scico`` module:
+
+::
+
+   mypy -p scico
+
+
+
 Tests
 -----
 
@@ -236,22 +303,6 @@ A coverage report can be obtained by
 
 
 
-Type Checking
--------------
-
-In the future, we will require all code to pass ``mypy`` type checking. This is not currently enforced.
-
-Install ``mypy``:
-
-::
-
-   conda install mypy
-
-To run the type checker on the ``scico`` module:
-
-::
-
-   mypy -p scico
 
 
 Usage Examples
@@ -348,50 +399,3 @@ and ``scico-data`` repositories must be updated and kept in sync.
    ::
 
       git submodule foreach --recursive 'git push' && git push
-
-
-Data
-----
-
-The following steps show how to add new data, ``new_data.npz``, to the packaged data. We assume the SCICO repository has been cloned to ``scico/``.
-
-Note that the data is located in the scico-data submodule, which is
-symlinked to ``scico/data``.  When adding new data, both the scico and
-scico-data repositories must be updated and kept in sync.
-
-
-1. Add the ``new_data.npz`` file to the ``scico/data`` directory.
-
-2. Navigate to the ``data`` directory and add/commit the new data file:
-
-   ::
-
-      cd scico/data
-      git add new_data.npz
-      git commit -m "Add new data file"
-
-3.  Return to the base SCICO repository, ensure the ``main`` branch is checked out, add/commit the new data and update submodule:
-
-   ::
-
-      cd ..  # pwd now `scico` repo root
-      git checkout main
-      git add data
-      git commit -m "Add data and update data module"
-
-4.  Push both repositories:
-
-   ::
-
-      git submodule foreach --recursive 'git push' && git push
-
-
-
-Building Documentation
-----------------------
-
-To build a local copy of the docs, from the repo root directory, do
-
-::
-
-  python setup.py build_sphinx

docs/source/style.rst

@@ -438,8 +438,8 @@ The following components require the recommended markup taken from `NumPy's Conv
 Other components can use *italics*, **bold**, and ``monospace`` if needed, but not for variable names, doctest code, or multi-line code.
 
 
-Documentation Pages
--------------------
+Documentation
+-------------
 
 Documentation that is separate from code (like this page)
 should follow the

examples/README.rst

@@ -10,22 +10,87 @@ Building Notebooks
 The scripts for building Jupyter notebooks from the source example scripts are currently only supported under Linux. All scripts described below should be run from this directory, i.e. ``[repo root]/examples``.
 
 
-The procedure for adding a adding a new notebook to the documentation is:
+Running on a GPU
+^^^^^^^^^^^^^^^^
 
-1. Add an entry for the source file in ``scripts/index.rst``. Note that a script that is not listed in this index will not be converted into a notebook.
+Since some of the examples require a considerable amount of memory (``deconv_microscopy_tv_admm.py`` and ``deconv_microscopy_allchn_tv_admm.py`` in particular), it is recommended to set the following environment variables prior to building the notebooks:
 
-2. Run ``makeindex.py`` to update the example scripts README file, the notebook index file, and the examples index in the docs.
+::
+
+  export XLA_PYTHON_CLIENT_ALLOCATOR=platform
+  export XLA_PYTHON_CLIENT_PREALLOCATE=false
+
+
+Running on a CPU
+^^^^^^^^^^^^^^^^
+
+If a GPU is not available, or if the available GPU does not have sufficient memory to build the notebooks, set the environment variable
+
+::
+
+  JAX_PLATFORM_NAME=cpu
+
+to run on the CPU instead.
+
+
+Building Specific Examples
+--------------------------
+
+To build or rebuild notebooks for specific examples, the example script names can be specified on the command line, e.g.
+
+::
+
+  python makenotebooks.py ct_astra_pcg.py ct_astra_tv_admm.py
+
+When rebuilding notebooks for examples that themselves make use of ``ray``
+for parallelization (e.g. ``deconv_microscopy_allchn_tv_admm.py``), it is recommended to specify serial notebook execution, as in
+
+::
+
+  python makenotebooks.py --no-ray deconv_microscopy_allchn_tv_admm.py
 
-3. Run ``makenotebooks.py`` to build the new notebook, as well as any other notebooks that are out of date with respect to their source scripts, as determined by the respective file timestamps.
 
-4. Add and commit the new script, the ``scripts/index.rst`` script index file, the auto-generated ``scripts/README.rst`` file and ``docs/source/examples.rst`` index file, and the new or updated notebooks and the auto-generated ``notebooks/index.ipynb`` file in the notebooks directory (following the submodule handling procedure as described in the developer docs).
+Building All Examples
+---------------------
 
+By default, ``makenotebooks.py`` only rebuilds notebooks that are out of date with respect to their corresponding example scripts, as determined by their respective file timestamps. However, timestamps for files retrieved from version control may not be meaningful for this purpose. To rebuild all examples, the following commands (assuming that GPUs are available) are recommended:
 
-The procedure for rebuilding notebook(s) after the source file(s) have been modified is:
+::
+
+  export XLA_PYTHON_CLIENT_ALLOCATOR=platform
+  export XLA_PYTHON_CLIENT_PREALLOCATE=false
+
+  touch scripts/*.py
+
+  python makenotebooks.py --no-ray deconv_microscopy_tv_admm.py deconv_microscopy_allchn_tv_admm.py
+
+  python makenotebooks.py
+
+
+Updating Notebooks in the Repo
+------------------------------
+
+The recommended procedure for rebuilding notebooks for inclusion in the ``data`` submodule is:
+
+1. Add and commit the modified script(s).
+
+2. Rebuild the notebook(s) as described above.
+
+2. Add and commit the updated notebooks following the submodule handling procedure described in the developer docs.
+
+
+Adding a New Notebook
+---------------------
+
+The procedure for adding a adding a new notebook is:
+
+1. Add an entry for the source file in ``scripts/index.rst``. Note that a script that is not listed in this index will not be converted into a notebook.
+
+2. Run ``makeindex.py`` to update the example scripts README file, the notebook index file, and the examples index in the docs.
 
-1. Run ``makenotebooks.py`` to build the new notebook, as well as any other notebooks that are out of date with respect to their source scripts, as determined by the respective file timestamps. Note that timestamps for files retrieved from version control may not be meaningful for this purpose. In such cases, ``touch`` the relevant source scripts to force updating on the next run of ``makenotebooks.py``.
+3. Build the corresponding notebook following the instructions above.
 
-2. Add and commit the modified script(s), and the updated notebooks (following the submodule handling procedure as described in the developer docs).
+4. Add and commit the new script, the ``scripts/index.rst`` script index file, the auto-generated ``scripts/README.rst`` file and ``docs/source/examples.rst`` index file, and the new or updated notebooks and the auto-generated ``notebooks/index.ipynb`` file in the notebooks directory, following the submodule handling procedure as described in the developer docs.
 
 
 

examples/scripts/ct_astra_weighted_tv_admm.py

@@ -79,7 +79,7 @@
 
 
 """
-Setup post processing.  For this example, we clip all reconstructions
+Set up post processing. For this example, we clip all reconstructions
 to the range of the ground truth.
 """
 
@@ -134,7 +134,7 @@ def postprocess(x):
 
 where
 
-  $$W = \mathrm{diag}\left\{\exp( \sqrt{\mathbf{y}}) \right\}.$$
+  $$W = \mathrm{diag}\left\{\exp( \sqrt{\mathbf{y}}) \right\} \;.$$
 """
 lambda_weighted = 1.14e2
 
@@ -161,6 +161,7 @@ def postprocess(x):
 
 
 def plot_recon(x, title, ax):
+    """Plot an image with title indicating error metrics."""
     plot.imview(
         x,
         title=f"{title}\nSNR: {metric.snr(x_gt, x):.2f} (dB), MAE: {metric.mae(x_gt, x):.3f}",