finishing documentation corrections

README.rst

@@ -1,23 +1,16 @@
 ToMoBAR's documentation
 =======================
 
-**ToMoBAR** (cite [CT2020]_, [SX2022]_) is a Python library of direct and model-based 
-regularised iterative reconstruction algorithms with a 
-plug-and-play capability. ToMoBAR offers you a selection 
-of various data models and regularisers resulting in complex 
+**ToMoBAR** (cite [CT2020]_, [SX2022]_) is a Python library of direct and model-based
+regularised iterative reconstruction algorithms with a
+plug-and-play capability. ToMoBAR offers you a selection
+of various data models and regularisers resulting in complex
 objectives for tomographic reconstruction. ToMoBAR can operate
 in GPU device-to-device fashion on CuPy arrays therefore ensuring
-a better computational efficiency. With GPU device controlling API 
+a better computational efficiency. With GPU device controlling API
 exposed it can also support multi-GPU parallel computing.
 
-Although ToMoBAR does offer a variety of reconstruction methods, 
-the FISTA algorithm [BT2009]_ specifically provides various useful modifications, e.g.:
-convergence acceleration with ordered-subsets, different 
-data fidelities: PWLS, Kullback-Leibler, Huber, Group-Huber [PM2015]_, 
-Students't [KAZ1_2017]_, and SWLS [HOA2017]_ to deal with noise and reconstruction artefacts 
-(rings, streaks). Together with the regularisers from the CCPi-Regularisation toolkit [KAZ2019]_
-one can construct up to a hundred of complex combinations for the objective function. 
-
+See more in :ref:`intro_about` or go directly to :ref:`ref_installation` and try `Demos <https://github.com/dkazanc/ToMoBAR/tree/master/Demos/Python>`_.
 
 .. figure::  _static/recsFISTA_stud.png
     :scale: 85 %

docs/source/conf.py

@@ -1,6 +1,3 @@
-# -- General configuration ------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
-
 #!/usr/bin/env python
 import os
 import sys
@@ -49,6 +46,7 @@
     "tomobar.astra_wrappers.astra_tools3d",
 ]
 
+
 class CustomMock(mock.Mock):
     def __repr__(self):
         return "<cp.ndarray>"
@@ -60,8 +58,9 @@ def __repr__(self):
 
 # ------------------------------------------------------------------------------
 
-project = "Tomobar"
-# copyright = f"{date.today().year}, Diamond Light Source"
+project = "ToMoBAR"
+author = "Daniil Kazantsev"
+copyright = f"{date.today().year}, Diamond Light Source and Manchester University, UK"
 
 # Specify a base language to help assistive technology
 language = "en"
@@ -111,14 +110,6 @@ def __repr__(self):
 html_static_path = ["_static"]
 html_use_smartypants = True
 
-"""
-html_theme_options = {
-    "logo_only": True,
-    "display_version": False,
-    "githuburl": "https://github.com/dkazanc/ToMoBAR",
-}
-"""
-
 html_theme_options = {
     "logo": {
         "image_dark": "_static/tomobar_logo_dark.png",

docs/source/howto/installation.rst

@@ -34,6 +34,8 @@ the installation above is tested on Linux and Windows, but one can also try:
 
    $ conda install -c httomo -c ccpi -c conda-forge tomophantom tomobar astra-toolbox ccpi-regulariser
 
+.. warning:: Packages installed from the CCPi channel might be of different versions and incompatible with the demos.
+
 Install ToMoBAR from PyPi:
 ++++++++++++++++++++++++++
 

docs/source/howto/use.rst

@@ -2,13 +2,16 @@
 
 Using ToMoBAR
 ------------------
-In :ref:`tutorials`, we provide few examples how to reconstruct tomographic data collected using parallel-beam geometry. 
-ToMoBAR offers direct and iterative reconstructors which are build around `ASTRA-Toolbox <https://astra-toolbox.com/>`_ projection/backprojection modules, see the ASTRA wrappers at :mod:`tomobar.astra_wrappers`.
+In :ref:`tutorials`, we provide few examples how to reconstruct synthetic and real tomographic data collected with the parallel-beam geometry.
 
-The very general recipe to perform reconstruction in Python with ToMoBAR follows:
+The general recipe to perform reconstruction in Python with ToMoBAR is the following:
 
-* 1. Import a module related to the reconstruction task chosen, e.g., direct (DIR), iterative (IR), or `CuPy <https://cupy.dev/>`_-enabled.
-* 2. Instantiate the reconstructor class, while providing parameters normally related to the parallel-beam 2D and 3D scanning geometry.
-* 3. After class instantiation you will get an access to different reconstruction methods of that class. Run the selected reconstruction method providing data as an input and additional parameters, if needed.
+* 1. Import a module related to the reconstruction task chosen, e.g., direct (:code:`DIR`) modules :mod:`tomobar.methodsDIR`, iterative (:code:`IR`) :mod:`tomobar.methodsIR`,
+  or `CuPy <https://cupy.dev/>`_-enabled modules :mod:`tomobar.methodsDIR_CuPy` and :mod:`tomobar.methodsIR_CuPy`.
+* 2. Instantiate a reconstructor class while providing parameters related to the parallel-beam 2D and 3D scanning geometries.
+* 3. After instantiation you will get an access to different reconstruction methods of that class. Run selected reconstruction method providing data as an input and additional parameters.
+  For all :code:`DIR` methods parameters are passed directly, while for :code:`IR` methods you will need to form dictionaries:
+  :data:`_data_`, :data:`_algorithm_`, and :data:`_regularisation_`. See :mod:`tomobar.supp.dicts` for the list of parameters accepted.
 
-As the main aim for ToMoBAR is to reconstruct the data from the synchrotron X-ray or neutron imaging instruments, where the radiation beam is approximately parallel. So far, we do not provide API for the divergent beam geometries, however ASTRA supports it and the wrappers at :mod:`tomobar.astra_wrappers` can be extended. 
+
+.. note:: As the main aim for ToMoBAR is to reconstruct the data from the synchrotron X-ray or neutron imaging instruments, with the beam being approximately parallel. So far, we do not provide API for the divergent beam geometries, however as ASTRA supports it, the wrappers at :mod:`tomobar.astra_wrappers` can be extended. The contributions are welcome!

docs/source/introduction/about.rst

@@ -1,15 +1,20 @@
+.. _intro_about:
+
 About ToMoBAR
-*******************
+**************
+
+The general concept:
+====================
+ToMoBAR is a Python library (Matlab is not currently supported) of direct and model-based
+regularised iterative reconstruction algorithms with a plug-and-play capability.
+ToMoBAR offers you a selection of various data models and regularisers resulting in
+complex objectives for tomographic reconstruction. ToMoBAR uses ASTRA-Toolbox [VanAarle2015]_,
+for projection-backprojection parallel-beam geometry routines, which is
+a common geometry for X-ray synchrotron imaging [SX2022]_.
 
-The general concept
-=====================
-ToMoBAR is a Python library (Matlab is not currently maintained) of direct and model-based 
-regularised iterative reconstruction algorithms with a plug-and-play capability. 
-ToMoBAR offers you a selection of various data models and regularisers resulting in 
-complex objectives for tomographic reconstruction. ToMoBAR can operate
-in GPU device-to-device fashion on CuPy arrays therefore ensuring
-a better computational efficiency. With GPU device controlling API 
-exposed it can also support multi-GPU parallel computing.
+ToMoBAR can operate in GPU device-to-device fashion on CuPy arrays therefore ensuring
+a better computational efficiency. With GPU device controlling :ref:`ref_api`
+exposed it can also support multi-GPU parallel computing [CT2020]_ .
 
 .. figure::  ../_static/TomoRec_surf2.jpg
     :scale: 30 %
@@ -18,13 +23,14 @@ exposed it can also support multi-GPU parallel computing.
 What ToMoBAR can do:
 ====================
 
-* Reconstruct parallel-beam projection data in 2D and 3D using GPU-accelerated routines from ASTRA-toolbox.
-* Employ the basic direct and iterative schemes to perform reconstruction.
-* Employ advanced model-based regularised iterative schemes such as FISTA and ADMM proximal splitting algorithms.
-* The FISTA algorithm offers various modifications: 
-  convergence acceleration with ordered-subsets method,
-  different data fidelities: PWLS, Kullback-Leibler, Huber, Group-Huber [PM2015]_, Students't [KAZ1_2017]_, and SWLS [HOA2017]_
-  to deal with noise and imaging artefacts (rings, streaks).
-* Together with regularisers from the CCPi-Regularisation Toolkit [KAZ2019]_ one can construct up to a hundred of complex combinations for the objective function.
+* Reconstruct parallel-beam projection data in 2D and 3D using GPU-accelerated routines from ASTRA-toolbox [VanAarle2015]_.
+* Employ fast GPU-accelerated direct methods, such as FBP method in :mod:`tomobar.methodsDIR` and CuPy accelerated Fourier
+  reconstruction :func:`FOURIER_INV` in :mod:`tomobar.methodsDIR_CuPy`.
+* Use advanced model-based regularised iterative schemes such as FISTA and ADMM proximal splitting algorithms in :mod:`tomobar.methodsIR` or
+  even faster implementations with CuPy in :mod:`tomobar.methodsIR_CuPy`.
+* The FISTA algorithm [BT2009]_, [Xu2016]_ offers various modifications: convergence acceleration with ordered-subsets,
+  different data fidelities: PWLS, Huber, Group-Huber [PM2015]_, Students't [KAZ1_2017]_, and SWLS [HOA2017]_
+  to deal with noise and various imaging artefacts, such as, rings, streaks.
+* Combine FISTA and ADMM methods with regularisers from the CCPi-Regularisation Toolkit [KAZ2019]_. It is possible to construct different combinations of the objective function.
 
-See more on API of ToMoBAR in :ref:`ref_api`.
+See more on ToMoBAR's API in :ref:`ref_api`.

docs/source/introduction/dependencies.rst

@@ -2,77 +2,92 @@
 
 Dependencies
 ************
-ToMoBAR relies on several dependencies which we list bellow in the order of priority. 
-In general, we would recommend installing 1,2 and 4 packages.
+ToMoBAR relies on several dependencies which we list bellow in the order of priority.
+In general, we would recommend installing 1,2 and 3 packages.
 
-* 1. `ASTRA-toolbox <https://www.astra-toolbox.com/>`_ is the most critical dependency
-  as ToMoBAR heavily relies on the GPU-accelerated projection/backprojection routines of the toolbox. With 
-  the package installed, one can perform :ref:`tutorials_direct` and :ref:`examples_basic_iter`, 
-  however the regularisation will not be available for :ref:`examples_regul_iter`.
+* 1. `ASTRA-toolbox <https://www.astra-toolbox.com/>`_ is the major dependency
+  as ToMoBAR heavily relies on the GPU-accelerated projection/backprojection routines of the toolbox. With
+  the package installed, one can perform :ref:`tutorials_direct` and :ref:`examples_basic_iter`,
+  however, the regularisation will not be available for :ref:`examples_regul_iter`.
 
-  For Python installation, see this `conda <https://anaconda.org/astra-toolbox/astra-toolbox>`_ page.
+  Normally ASTRA included into the list of dependencies, but one can install it with:
 
 .. code-block:: console
-   
-   $ conda install astra-toolbox::astra-toolbox
 
-* 2. `CCPi-Regularisation-Toolkit <https://github.com/vais-ral/CCPi-Regularisation-Toolkit>`_ [KAZ2019]_ provides 
-  CPU and GPU regularisers (2D/3D) to enable :ref:`examples_regul_iter` in ToMoBAR. 
-  Once installed, one will have an access to more than 10 plug-and-play regularisers to 
+   $ conda install conda-forge::astra-toolbox
+
+* 2. `CCPi-Regularisation-Toolkit <https://github.com/TomographicImaging/CCPi-Regularisation-Toolkit/>`_ [KAZ2019]_ provides
+  CPU and GPU regularisers (2D/3D) to enable :ref:`examples_regul_iter` in ToMoBAR.
+  Once installed, one gets an access to more than 10 plug-and-play regularisers to
   compliment ToMoBAR's iterative reconstruction algorithms.
 
-  For Python installation, see this `conda-ccpi <https://anaconda.org/ccpi/ccpi-regulariser>`_ and this
-  `conda-httomo <https://anaconda.org/httomo/ccpi-regulariser>`_ pages. Either of them should work:
+  For Python installation, see `conda-httomo <https://anaconda.org/httomo/ccpi-regulariser>`_
+  and `conda-ccpi <https://anaconda.org/ccpi/ccpi-regulariser>`_  pages. It is recommended
+  to install using the :code:`httomo` channel first as this combination is normally tested
+  by the ToMoBAR's author:
 
 .. code-block:: console
-   
-   $ conda install ccpi::ccpi-regulariser # linux/windows
-   $ conda install httomo::ccpi-regulariser # linux
-   $ conda install httomo::ccpi-regularisation-cupy # all OS / CuPy modules only
 
-* 3. Wavelet toolbox `pypwt <https://github.com/pierrepaleo/pypwt>`_ or **pycudwt** is required if 
-  the soft/hard thresholding of Wavelets coefficients is added to the regularisers above. In some cases 
-  it can be beneficial for the reconstruction quality.
-
-  For Python installation one can try `pip install pycudwt` or:
+   $ conda install httomo::ccpi-regulariser #  linux/windows
+   $ conda install httomo::ccpi-regularisation-cupy # all OS but CuPy modules only
+   $ conda install ccpi::ccpi-regulariser # linux/windows (in case if above doesn't work)
+
+
+If one needs to install only CuPy modules (see 6.), the quickest way will be
 
 .. code-block:: console
-   
-   $ conda install httomo::pypwt # linux only
 
-* 4. `TomoPhantom <https://github.com/dkazanc/TomoPhantom>`_  is optional but can be 
-  helpful for generating synthethic tomographic data and play with :ref:`examples_synth_iter`.
-  Also most of the Demos in ToMoBAR presented by using TomoPhantom. 
+   $ pip install ccpi-regularisation-cupy # all OS but CuPy modules only
+
+* 3. `TomoPhantom <https://github.com/dkazanc/TomoPhantom>`_  is optional but can be very
+  handy to generate synthethic tomographic data and play with :ref:`examples_synth_iter`.
+  Also most of the `Demos <https://github.com/dkazanc/ToMoBAR/tree/master/Demos/Python>`_ in ToMoBAR using TomoPhantom.
 
   For Python installation see the `installation guide <https://dkazanc.github.io/TomoPhantom/howto/installation.html>`_.
 
 .. code-block:: console
-   
+
    $ conda install httomo::tomophantom # linux/windows
 
-* 5. `CuPy <https://cupy.dev/>`_  dependency is optional to be able to use algorithms operating on CuPy array kept on the GPU device instead of Numpy arrays. 
-  It is a work in progress to fully support the feature in ToMoBAR, however, many main reconstruction methods such as direct and basic were already ported. 
-  FISTA ordered-subsets with some regularisres has been exposed and offers up to several times acceleration compared to the version in :mod:`tomobar.methodsIR`.
-  We have plans to continue developing and supporting this new capability as it offers promising efficiency for GPU computations. 
+
+* 4. Wavelet toolbox `pypwt <https://github.com/pierrepaleo/pypwt>`_ or **pycudwt** is optional and required only
+  if the CCPi-Regularisation-Toolkit already installed. It adds soft/hard thresholding of Wavelets coefficients to the available regularisers.
+  In some cases it can be beneficial for the reconstruction quality.
+
+  For Python installation one can try:
+
+.. code-block:: console
+
+   $ pip install pycudwt
+   $ conda install httomo::pypwt # if above didn't work (linux only)
+
+
+* 5. `CuPy <https://cupy.dev/>`_  dependency is optional and used to write high-level code in Python for GPU computations.
+  Those algorithms operating on CuPy arrays that are kept on the GPU device as opposed to Numpy arrays kept in the CPU memory.
+  It is a work in progress to fully support the CuPy compute in ToMoBAR, however, some reconstruction methods, such as direct and iterative
+  were already ported, see :mod:`tomobar.methodsDIR_CuPy` and :mod:`tomobar.methodsIR_CuPy`, respectively.
+  We have plans to continue developing and supporting this new capability as it offers promising efficiency for GPU computations, no OS-specific builds required,
+  and simplicity of the implementation.
 
   For Python installation see the `conda-cupy <https://anaconda.org/anaconda/cupy>`_ page.
 
 .. code-block:: console
-   
-   $ conda install conda-forge::cupy # linux/windows  
 
-* 6. CuPy-enabled CCPi-Regularisation-Toolkit is required when (5) is satisfied. 
-  This extension doesn't depend on (2) and can co-exist with (2) installation or standalone.
-  Note, however, it is also WIP and not all regularisers :mod:`tomobar.regularisersCuPy` have been ported.
+   $ conda install conda-forge::cupy # linux/windows
+
+* 6. CuPy-enabled CCPi-Regularisation-Toolkit can be used when (5) is satisfied. This will give you an access to
+  :mod:`tomobar.methodsDIR_CuPy` and :mod:`tomobar.methodsIR_CuPy` modules, while regularisation methods of
+  :mod:`tomobar.methodsIR` won't be accessible.
 
 .. code-block:: console
-   
-   $ conda install httomo::ccpi-regularisation-cupy # all OS supported
 
-* 7. `mpi4py <https://mpi4py.readthedocs.io/en/stable/>`_ is a Python extension for parallel computing using MPI. 
+   $ pip install ccpi-regularisation-cupy # all OS but CuPy modules only
+
+
+* 7. `mpi4py <https://mpi4py.readthedocs.io/en/stable/>`_ is a Python extension for parallel computing using MPI.
   Install only if you are planning to use multi-GPU computing. ToMoBAR in itself doesn't offer
   any parallelisation and you might want to check the `HTTomo <https://github.com/DiamondLightSource/httomo>`_ package.
-  HTTomo supports MPI-based reconstruction and uses ToMoBAR as a backend. 
+  HTTomo supports MPI-based reconstruction and uses ToMoBAR as a backend.
 
 
 

docs/source/introduction/references.rst

@@ -3,10 +3,15 @@
 References
 ***********
 
+.. note:: To cite ToMoBAR please use [CT2020]_ paper.
+
 .. [CT2020] D. Kazantsev and N. Wadeson. 2020, Tomographic MOdel-BAsed Reconstruction (ToMoBAR) software for high resolution
    synchrotron X-ray tomography, CT Meeting 2020.
    Download `here <https://github.com/dkazanc/ToMoBAR/tree/master/docs/Kazantsev_CT_20.pdf>`_.
 
+.. [VanAarle2015] W. Van Aarle, et.al., 2015. The ASTRA Toolbox: A platform for advanced algorithm
+   development in electron tomography. Ultramicroscopy, 157, pp.35-47.
+
 .. [SX2022] D. Kazantsev, N. Wadeson, M. Basham, 2022.
     High performance Savu software for fast 3D model-based
     iterative reconstruction of large data at Diamond Light Source.
@@ -16,7 +21,7 @@ References
     algorithm for linear inverse problems, SIAM Journal on Imaging Sciences, vol. 2,
     no. 1, pp. 183–202.
 
-.. [Boyd2011] Boyd, N. Parikh, E. Chu, B. Peleato, J. Eckstein, 2011, Distributed optimization and
+.. [Boyd2011] N. Boyd et. al., 2011, Distributed optimization and
    statistical learning via the alternating direction method of multipliers, Found. Trends Mach. Learn.,
    vol. 3, no. 1, pp. 1-122
 
@@ -46,4 +51,8 @@ References
 
 .. [KAZ2017] D. Kazantsev et al. 2017. Model-based iterative
    reconstruction using higher-order regularization of dynamic
-   synchrotron data. Measurement Science and Technology, 28(9), p.094004.
+   synchrotron data. Measurement Science and Technology, 28(9), p.094004.
+
+.. [NIKITIN2017] V.V. Nikitin, et. al., 2017. Fast hyperbolic Radon transform
+   represented as convolutions in log-polar coordinates. Computers & Geosciences,
+   105, pp.21-33.

docs/source/reference/api.rst

@@ -18,8 +18,5 @@ ToMoBAR Modules
    ../api/tomobar.methodsIR_CuPy
    ../api/tomobar.regularisers
    ../api/tomobar.regularisersCuPy
-   ../api/tomobar.astra_wrappers.astra_base
-   ../api/tomobar.astra_wrappers.astra_tools2d
-   ../api/tomobar.astra_wrappers.astra_tools3d
    ../api/tomobar.supp.dicts
    ../api/tomobar.supp.suppTools

tests/test_RecToolsIR.py

@@ -362,8 +362,8 @@ def test_FISTA_PWLS_2D(angles, raw_data, flats, darks):
 
     Iter_rec = RecTools.FISTA(_data_, _algorithm_)
     assert 17000 <= lc <= 17100
-    assert_allclose(np.min(Iter_rec), -0.0003682454, rtol=eps)
-    assert_allclose(np.max(Iter_rec), 0.010147439, rtol=eps)
+    assert_allclose(np.min(Iter_rec), -0.0003682454, rtol=0, atol=eps)
+    assert_allclose(np.max(Iter_rec), 0.010147439, rtol=0, atol=eps)
     assert Iter_rec.dtype == np.float32
     assert Iter_rec.shape == (160, 160)