Clean up examples (#297)

* Rename some example scripts

* Update submodule

* Switch from anisotropic to isotropic TV, and various minor improvements

* Fix weighted CT example

* Lint

* Rebuild weighted notebook

* Restore submodule with renamed notebooks

Co-authored-by: Michael McCann <mccann@lanl.gov>

docs/source/examples.rst

@@ -67,10 +67,10 @@ Miscellaneous
    :maxdepth: 1
 
    examples/demosaic_ppp_bm3d_admm
-   examples/denoise_l1tv_iso_admm
-   examples/denoise_tv_iso_admm
-   examples/denoise_tv_iso_pgm
-   examples/denoise_tv_iso_multi
+   examples/denoise_l1tv_admm
+   examples/denoise_tv_admm
+   examples/denoise_tv_pgm
+   examples/denoise_tv_multi
    examples/superres_ppp_dncnn_admm
    examples/video_rpca_admm
 
@@ -114,10 +114,10 @@ Total Variation
    examples/deconv_microscopy_allchn_tv_admm
    examples/deconv_tv_admm
    examples/deconv_tv_admm_tune
-   examples/denoise_l1tv_iso_admm
-   examples/denoise_tv_iso_admm
-   examples/denoise_tv_iso_pgm
-   examples/denoise_tv_iso_multi
+   examples/denoise_l1tv_admm
+   examples/denoise_tv_admm
+   examples/denoise_tv_pgm
+   examples/denoise_tv_multi
 
 
 Sparsity
@@ -161,9 +161,9 @@ ADMM
    examples/deconv_tv_admm
    examples/deconv_tv_admm_tune
    examples/demosaic_ppp_bm3d_admm
-   examples/denoise_l1tv_iso_admm
-   examples/denoise_tv_iso_admm
-   examples/denoise_tv_iso_multi
+   examples/denoise_l1tv_admm
+   examples/denoise_tv_admm
+   examples/denoise_tv_multi
    examples/sparsecode_admm
    examples/superres_ppp_dncnn_admm
    examples/video_rpca_admm
@@ -176,7 +176,7 @@ Linearized ADMM
    :maxdepth: 1
 
    examples/ct_svmbir_tv_multi
-   examples/denoise_tv_iso_multi
+   examples/denoise_tv_multi
 
 
 PDHG
@@ -186,7 +186,7 @@ PDHG
    :maxdepth: 1
 
    examples/ct_svmbir_tv_multi
-   examples/denoise_tv_iso_multi
+   examples/denoise_tv_multi
 
 
 PGM
@@ -196,7 +196,7 @@ PGM
    :maxdepth: 1
 
    examples/deconv_ppp_bm3d_pgm
-   examples/denoise_tv_iso_pgm
+   examples/denoise_tv_pgm
    examples/sparsecode_pgm
    examples/sparsecode_poisson_pgm
 

examples/scripts/README.rst

@@ -66,13 +66,13 @@ Miscellaneous
 
    `demosaic_ppp_bm3d_admm.py <demosaic_ppp_bm3d_admm.py>`_
       Image Demosaicing (ADMM Plug-and-Play Priors w/ BM3D)
-   `denoise_l1tv_iso_admm.py <denoise_l1tv_iso_admm.py>`_
+   `denoise_l1tv_admm.py <denoise_l1tv_admm.py>`_
       ℓ1 Total Variation (ADMM)
-   `denoise_tv_iso_admm.py <denoise_tv_iso_admm.py>`_
+   `denoise_tv_admm.py <denoise_tv_admm.py>`_
       Isotropic Total Variation (ADMM)
-   `denoise_tv_iso_pgm.py <denoise_tv_iso_pgm.py>`_
+   `denoise_tv_pgm.py <denoise_tv_pgm.py>`_
       Isotropic Total Variation (Accelerated PGM)
-   `denoise_tv_iso_multi.py <denoise_tv_iso_multi.py>`_
+   `denoise_tv_multi.py <denoise_tv_multi.py>`_
       Comparison of Optimization Algorithms for Total Variation Denoising
    `superres_ppp_dncnn_admm.py <superres_ppp_dncnn_admm.py>`_
       Image Superresolution (ADMM Plug-and-Play Priors w/ DnCNN)
@@ -128,13 +128,13 @@ Total Variation
       Image Deconvolution (ADMM w/ Total Variation)
    `deconv_tv_admm_tune.py <deconv_tv_admm_tune.py>`_
       Image Deconvolution Parameter Tuning
-   `denoise_l1tv_iso_admm.py <denoise_l1tv_iso_admm.py>`_
+   `denoise_l1tv_admm.py <denoise_l1tv_admm.py>`_
       ℓ1 Total Variation (ADMM)
-   `denoise_tv_iso_admm.py <denoise_tv_iso_admm.py>`_
+   `denoise_tv_admm.py <denoise_tv_admm.py>`_
       Isotropic Total Variation (ADMM)
-   `denoise_tv_iso_pgm.py <denoise_tv_iso_pgm.py>`_
+   `denoise_tv_pgm.py <denoise_tv_pgm.py>`_
       Isotropic Total Variation (Accelerated PGM)
-   `denoise_tv_iso_multi.py <denoise_tv_iso_multi.py>`_
+   `denoise_tv_multi.py <denoise_tv_multi.py>`_
       Comparison of Optimization Algorithms for Total Variation Denoising
 
 
@@ -190,11 +190,11 @@ ADMM
       Image Deconvolution Parameter Tuning
    `demosaic_ppp_bm3d_admm.py <demosaic_ppp_bm3d_admm.py>`_
       Image Demosaicing (ADMM Plug-and-Play Priors w/ BM3D)
-   `denoise_l1tv_iso_admm.py <denoise_l1tv_iso_admm.py>`_
+   `denoise_l1tv_admm.py <denoise_l1tv_admm.py>`_
       ℓ1 Total Variation (ADMM)
-   `denoise_tv_iso_admm.py <denoise_tv_iso_admm.py>`_
+   `denoise_tv_admm.py <denoise_tv_admm.py>`_
       Isotropic Total Variation (ADMM)
-   `denoise_tv_iso_multi.py <denoise_tv_iso_multi.py>`_
+   `denoise_tv_multi.py <denoise_tv_multi.py>`_
       Comparison of Optimization Algorithms for Total Variation Denoising
    `sparsecode_admm.py <sparsecode_admm.py>`_
       Non-negative Basis Pursuit DeNoising (ADMM)
@@ -209,7 +209,7 @@ Linearized ADMM
 
     `ct_svmbir_tv_multi.py <ct_svmbir_tv_multi.py>`_
        CT Reconstruction with TV Regularization
-    `denoise_tv_iso_multi.py <denoise_tv_iso_multi.py>`_
+    `denoise_tv_multi.py <denoise_tv_multi.py>`_
        Comparison of Optimization Algorithms for Total Variation Denoising
 
 
@@ -218,7 +218,7 @@ PDHG
 
     `ct_svmbir_tv_multi.py <ct_svmbir_tv_multi.py>`_
        CT Reconstruction with TV Regularization
-    `denoise_tv_iso_multi.py <denoise_tv_iso_multi.py>`_
+    `denoise_tv_multi.py <denoise_tv_multi.py>`_
        Comparison of Optimization Algorithms for Total Variation Denoising
 
 
@@ -227,7 +227,7 @@ PGM
 
    `deconv_ppp_bm3d_pgm.py <deconv_ppp_bm3d_pgm.py>`_
       Image Deconvolution (PGM Plug-and-Play Priors w/ BM3D)
-   `denoise_tv_iso_pgm.py <denoise_tv_iso_pgm.py>`_
+   `denoise_tv_pgm.py <denoise_tv_pgm.py>`_
       Isotropic Total Variation (Accelerated PGM)
    `sparsecode_pgm.py <sparsecode_pgm.py>`_
       Basis Pursuit DeNoising (Accelerated PGM)

examples/scripts/ct_abel_tv_admm.py

@@ -41,12 +41,13 @@
 """
 Set up ADMM solver object.
 """
-λ = 1.9e01  # L1 norm regularization parameter
-ρ = 4.9e01  # ADMM penalty parameter
+λ = 1.9e1  # L1 norm regularization parameter
+ρ = 4.9e1  # ADMM penalty parameter
 maxiter = 100  # number of ADMM iterations
 cg_tol = 1e-4  # CG relative tolerance
 cg_maxiter = 25  # maximum CG iterations per ADMM iteration
 
+# Note the use of anisotropic TV. Isotropic TV would require use of L21Norm.
 g = λ * functional.L1Norm()
 C = linop.FiniteDifference(input_shape=x_gt.shape)
 

examples/scripts/ct_astra_tv_admm.py

@@ -38,6 +38,7 @@
 Create a ground truth image.
 """
 N = 512  # phantom size
+np.random.seed(1234)
 x_gt = discrete_phantom(Foam(size_range=[0.075, 0.0025], gap=1e-3, porosity=1), size=N)
 x_gt = jax.device_put(x_gt)  # convert to jax type, push to GPU
 
@@ -54,14 +55,17 @@
 """
 Set up ADMM solver object.
 """
-λ = 2e-0  # L1 norm regularization parameter
-ρ = 5e-0  # ADMM penalty parameter
+λ = 2e0  # L1 norm regularization parameter
+ρ = 5e0  # ADMM penalty parameter
 maxiter = 25  # number of ADMM iterations
 cg_tol = 1e-4  # CG relative tolerance
 cg_maxiter = 25  # maximum CG iterations per ADMM iteration
 
-g = λ * functional.L1Norm()  # regularization functionals gi
-C = linop.FiniteDifference(input_shape=x_gt.shape)  # analysis operators Ci
+# The append=0 option makes the results of horizontal and vertical
+# finite differences the same shape, which is required for the L21Norm,
+# which is used so that g(Cx) corresponds to isotropic TV.
+C = linop.FiniteDifference(input_shape=x_gt.shape, append=0)
+g = λ * functional.L21Norm()
 
 f = loss.SquaredL2Loss(y=y, A=A)
 

examples/scripts/ct_astra_weighted_tv_admm.py

@@ -103,18 +103,18 @@ def postprocess(x):
 # Note that rho and lambda were selected via a parameter sweep (not
 # shown here).
 ρ = 2.5e3  # ADMM penalty parameter
-lambda_unweighted = 2.56e2  # regularization strength
+lambda_unweighted = 3e2  # regularization strength
 
-maxiter = 50  # number of ADMM iterations
+maxiter = 100  # number of ADMM iterations
 cg_tol = 1e-5  # CG relative tolerance
 cg_maxiter = 10  # maximum CG iterations per ADMM iteration
 
 f = loss.SquaredL2Loss(y=y, A=A)
 
 admm_unweighted = ADMM(
     f=f,
-    g_list=[lambda_unweighted * functional.L1Norm()],
-    C_list=[linop.FiniteDifference(x_gt.shape)],
+    g_list=[lambda_unweighted * functional.L21Norm()],
+    C_list=[linop.FiniteDifference(x_gt.shape, append=0)],
     rho_list=[ρ],
     x0=x0,
     maxiter=maxiter,
@@ -141,15 +141,15 @@ def postprocess(x):
 use to maintain balance between the data and regularization terms if
 $I_0$ changes.
 """
-lambda_weighted = 1.14e2
+lambda_weighted = 5e1
 
 weights = jax.device_put(counts / Io)
 f = loss.SquaredL2Loss(y=y, A=A, W=linop.Diagonal(weights))
 
 admm_weighted = ADMM(
     f=f,
-    g_list=[lambda_weighted * functional.L1Norm()],
-    C_list=[linop.FiniteDifference(x_gt.shape)],
+    g_list=[lambda_weighted * functional.L21Norm()],
+    C_list=[linop.FiniteDifference(x_gt.shape, append=0)],
     rho_list=[ρ],
     maxiter=maxiter,
     x0=x0,

examples/scripts/deconv_circ_tv_admm.py

@@ -59,7 +59,7 @@
 """
 Set up an ADMM solver object.
 """
-λ = 2e-2  # L1 norm regularization parameter
+λ = 2e-2  # L21 norm regularization parameter
 ρ = 5e-1  # ADMM penalty parameter
 maxiter = 50  # number of ADMM iterations
 

examples/scripts/deconv_tv_admm.py

@@ -58,15 +58,18 @@
 """
 Set up an ADMM solver object.
 """
-λ = 2e-2  # L1 norm regularization parameter
-ρ = 5e-1  # ADMM penalty parameter
+λ = 2.7e-2  # L1 norm regularization parameter
+ρ = 1.4e-1  # ADMM penalty parameter
 maxiter = 50  # number of ADMM iterations
 
 f = loss.SquaredL2Loss(y=y, A=A)
 # Penalty parameters must be accounted for in the gi functions, not as
 # additional inputs.
-g = λ * functional.L1Norm()  # regularization functionals gi
-C = linop.FiniteDifference(input_shape=x_gt.shape)  # analysis operators Ci
+g = λ * functional.L21Norm()
+# The append=0 option makes the results of horizontal and vertical
+# finite differences the same shape, which is required for the L21Norm,
+# which is used so that g(Cx) corresponds to isotropic TV.
+C = linop.FiniteDifference(input_shape=x_gt.shape, append=0)
 solver = ADMM(
     f=f,
     g_list=[g],

examples/scripts/deconv_tv_admm_tune.py

@@ -70,8 +70,8 @@ def eval_params(config, reporter):
     # Set up problem to be solved.
     A = linop.Convolve(h=psf, input_shape=x_gt.shape)
     f = loss.SquaredL2Loss(y=y, A=A)
-    g = λ * functional.L1Norm()
-    C = linop.FiniteDifference(input_shape=x_gt.shape)
+    g = λ * functional.L21Norm()
+    C = linop.FiniteDifference(input_shape=x_gt.shape, append=0)
     # Define solver.
     solver = ADMM(
         f=f,

examples/scripts/denoise_tv_iso_pgm.py → examples/scripts/denoise_tv_pgm.py

@@ -68,7 +68,7 @@
 """
 # The append=0 option appends 0 to the input along the axis
 # prior to performing the difference to make the results of
-# horizontal and vertical finite differences the same shape
+# horizontal and vertical finite differences the same shape.
 C = linop.FiniteDifference(input_shape=x_gt.shape, append=0)
 A = C.adj
 

examples/scripts/index.rst

@@ -45,10 +45,10 @@ Miscellaneous
 ^^^^^^^^^^^^^
 
    - demosaic_ppp_bm3d_admm.py
-   - denoise_l1tv_iso_admm.py
-   - denoise_tv_iso_admm.py
-   - denoise_tv_iso_pgm.py
-   - denoise_tv_iso_multi.py
+   - denoise_l1tv_admm.py
+   - denoise_tv_admm.py
+   - denoise_tv_pgm.py
+   - denoise_tv_multi.py
    - superres_ppp_dncnn_admm.py
    - video_rpca_admm.py
 
@@ -83,10 +83,10 @@ Total Variation
    - deconv_microscopy_allchn_tv_admm.py
    - deconv_tv_admm.py
    - deconv_tv_admm_tune.py
-   - denoise_l1tv_iso_admm.py
-   - denoise_tv_iso_admm.py
-   - denoise_tv_iso_pgm.py
-   - denoise_tv_iso_multi.py
+   - denoise_l1tv_admm.py
+   - denoise_tv_admm.py
+   - denoise_tv_pgm.py
+   - denoise_tv_multi.py
 
 
 Sparsity
@@ -121,9 +121,9 @@ ADMM
    - deconv_tv_admm.py
    - deconv_tv_admm_tune.py
    - demosaic_ppp_bm3d_admm.py
-   - denoise_l1tv_iso_admm.py
-   - denoise_tv_iso_admm.py
-   - denoise_tv_iso_multi.py
+   - denoise_l1tv_admm.py
+   - denoise_tv_admm.py
+   - denoise_tv_multi.py
    - sparsecode_admm.py
    - superres_ppp_dncnn_admm.py
    - video_rpca_admm.py
@@ -133,21 +133,21 @@ Linearized ADMM
 ^^^^^^^^^^^^^^^
 
     - ct_svmbir_tv_multi.py
-    - denoise_tv_iso_multi.py
+    - denoise_tv_multi.py
 
 
 PDHG
 ^^^^
 
     - ct_svmbir_tv_multi.py
-    - denoise_tv_iso_multi.py
+    - denoise_tv_multi.py
 
 
 PGM
 ^^^
 
    - deconv_ppp_bm3d_pgm.py
-   - denoise_tv_iso_pgm.py
+   - denoise_tv_pgm.py
    - sparsecode_pgm.py
    - sparsecode_poisson_pgm.py