Merge pull request #134 from dkazanc/docs_update

Change to calendar versioning and docs update

Author: dkazanc

.scripts/conda_upload.sh

@@ -10,7 +10,7 @@ export CONDA_BLD_PATH=~/conda-bld
 $CONDA/bin/conda install conda-build
 $CONDA/bin/conda install -c anaconda anaconda-client
 
-export VERSION=$(date +%Y.%m)
+export VERSION=1.0.0
 $CONDA/bin/conda build .
 
 # upload packages to conda

CHANGELOG.md

@@ -1,6 +1,10 @@
 # Change Log
 All notable changes in ToMoBAR project will be documented in this file.
 
+## v.1.0
+
+To better communicate breaking changes, ToMoBAR is moving from calendar versioning to semantic versioning. The initial `1.0` release is based on the `2025.12` version.
+
 ## v.2025.10
 
 ### Changed

Readme.md

@@ -7,7 +7,7 @@
         </td>
         <td>
         <font size="5"><b> TOmographic MOdel-BAsed Reconstruction software <a href="https://github.com/dkazanc/ToMoBAR/tree/master/docs/Kazantsev_CT_20.pdf">PAPER (CT Meeting 2020)</a></b></font>
-        <br><font size="3" face="verdana" color="green"><b> ToMoBAR</b> is a Python and Matlab (not currently maintained) 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 handle multi-GPU parallel reconstruction in Python and also device-to-device methods operating on CuPy arrays. </font></br>
+        <br><font size="3" face="verdana" color="green"><b> ToMoBAR</b> is a Python library of fast direct and model-based regularised iterative  algorithms with a plug-and-play capability for reconstruction of parallel-beam geometry data. ToMoBAR offers you a selection of various data models and regularisers resulting in complex objectives for tomographic reconstruction. ToMoBAR can handle multi-GPU parallel reconstruction in Python and also device-to-device methods operating on CuPy arrays. It is currently used in production at <a href="https://www.diamond.ac.uk/Home.html">Diamond Light Source</a> as a part of the <a href="https://diamondlightsource.github.io/httomo/">HTTomo</a> framework for big-data processing and reconstruction.</font></br>
         </td>
     </tr>
 </table>
@@ -16,21 +16,23 @@
 |--------|-------------------|
 | ![Github Actions](https://github.com/dkazanc/ToMoBAR/actions/workflows/tomobar_conda_upload.yml/badge.svg) | ![conda version](https://anaconda.org/httomo/tomobar/badges/version.svg) ![conda last release](https://anaconda.org/httomo/tomobar/badges/latest_release_date.svg) [![conda platforms](https://anaconda.org/httomo/tomobar/badges/platforms.svg) ![conda dowloads](https://anaconda.org/httomo/tomobar/badges/downloads.svg)](https://anaconda.org/httomo/tomobar/) |
 
-### Updates: 
-There are $\sf\color{red}BREAKING$ $\sf\color{red}CHANGES$ from ToMoBAR $\sf\color{red}v.2025.08$, see [CHANGELOG](https://github.com/dkazanc/ToMoBAR/blob/master/CHANGELOG.md) for all detailed changes.
+### Updates:
+* $\sf\color{red}!$ To better communicate breaking changes, ToMoBAR is moving from calendar versioning to semantic versioning. The initial 1.0 release is based on the 2025.12 version.
+* There are $\sf\color{red}BREAKING$ $\sf\color{red}CHANGES$ from ToMoBAR $\sf\color{red}v.2025.08$, see [CHANGELOG](https://github.com/dkazanc/ToMoBAR/blob/master/CHANGELOG.md) for all detailed changes.
 
 ## ToMoBAR highlights:
 Check what ToMoBAR can [do](https://dkazanc.github.io/ToMoBAR/introduction/about.html#what-tomobar-can-do). Please also see [Tutorials](https://dkazanc.github.io/ToMoBAR/tutorials/direct_recon.html) and [Demos](https://github.com/dkazanc/ToMoBAR/tree/master/Demos/Python).
+ToMoBAR
 
 ## Installation
 Please check the detailed [installation](https://dkazanc.github.io/ToMoBAR/howto/installation.html) guide where all [software dependencies](https://dkazanc.github.io/ToMoBAR/introduction/dependencies.html) are listed.
 
 ### Software includes:
- * A wrapper around [ASTRA-toolbox](https://www.astra-toolbox.com/) to simplify access to various reconstruction methods available in ASTRA
+ * Wrappers around [ASTRA-toolbox](https://www.astra-toolbox.com/) to simplify access to various reconstruction methods available in ASTRA-Toolbox
+ * Optimised CUDA/CuPy implementation of the fast [Log-Polar]( https://epubs.siam.org/doi/10.1137/15M1023762) (Fourier-based) direct reconstruction method.
  * Regularised iterative ordered-subsets [FISTA](https://epubs.siam.org/doi/10.1137/080716542) reconstruction algorithm with linear and non-linear data fidelities
  * Regularised iterative [ADMM](https://ieeexplore.ieee.org/document/7744574/) reconstruction algorithm
- * CuPy driven [forward/backward projectors](https://github.com/dkazanc/ToMoBAR/blob/master/Demos/Python/Demo_CuPy_3D.py) to enable faster device-to-device operations and all in GPU memory protoyping of algorithms
-* [Access to multi-GPU capability through mpi4py library](https://github.com/dkazanc/ToMoBAR/blob/master/Demos/Python/MultiGPU_demo.py)
+ * CuPy driven [forward/backward projectors](https://github.com/dkazanc/ToMoBAR/blob/master/Demos/Python/Demo_CuPy_3D.py) to enable faster device-to-device operations and all-in-GPU memory prototyping of algorithms.
  * [Demos](https://github.com/dkazanc/ToMoBAR/tree/master/Demos) to reconstruct synthetic and also real data [4-6]
 
 <div align="center">
@@ -40,24 +42,5 @@ Please check the detailed [installation](https://dkazanc.github.io/ToMoBAR/howto
   <img src="docs/source/_static/TomoRec_surf2.jpg" width="600">
 </div>
 
-### References:
- 1. [D. Kazantsev and N. Wadeson 2020. TOmographic MOdel-BAsed Reconstruction (ToMoBAR) software for high resolution synchrotron X-ray tomography. CT Meeting 2020](https://github.com/dkazanc/ToMoBAR/tree/master/docs/Kazantsev_CT_20.pdf)
- 2. [P. Paleo and A. Mirone 2015. Ring artifacts correction in compressed sensing tomographic reconstruction. Journal of synchrotron radiation, 22(5), pp.1268-1278.](https://doi.org/10.1107/S1600577515010176)
- 3. [D. Kazantsev et al. 2017. A Novel Tomographic Reconstruction Method Based on the Robust Student's t Function For Suppressing Data Outliers. IEEE TCI, 3(4), pp.682-693.](https://doi.org/10.1109/TCI.2017.2694607)
- 4. [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.](https://doi.org/10.1088/1361-6501/aa7fa8)
- 5. [H. Om Aggrawal et al. 2017. A Convex Reconstruction Model for X-ray tomographic Imaging with Uncertain Flat-fields", IEEE Transactions on Computational Imaging](http://ieeexplore.ieee.org/document/7967846/)
- 6. [V. Van Nieuwenhove et al. 2015. Dynamic intensity normalization using eigen flat fields in X-ray imaging. Optics express 23(21)](https://visielab.uantwerpen.be/sites/default/files/ffc_2016.pdf).
-
-### Applications (where ToMoBAR software have been used or referenced):
- 7. [D. Kazantsev et al. 2019. CCPi-Regularisation toolkit for computed tomographic image reconstruction with proximal splitting algorithms. SoftwareX, 9, pp.317-323.](https://doi.org/10.1016/j.softx.2019.04.003)
- 8. [E. Guo et al. 2018. The influence of nanoparticles on dendritic grain growth in Mg alloys. Acta Materialia.](https://doi.org/10.1016/j.actamat.2018.04.023)
- 9. [E. Guo et al. 2018. Revealing the microstructural stability of a three-phase soft solid (ice cream) by 4D synchrotron X-ray tomography. Journal of Food Engineering](https://www.sciencedirect.com/science/article/pii/S0260877418302309)
- 10. [E. Guo et al. 2017. Dendritic evolution during coarsening of Mg-Zn alloys via 4D synchrotron tomography. Acta Materialia](https://doi.org/10.1016/j.actamat.2016.10.022)
- 11. [E. Guo et al. 2017. Synchrotron X-ray tomographic quantification of microstructural evolution in ice cream–a multi-phase soft solid. Rsc Advances](https://doi.org/10.1039/C7RA00642J)
- 12. [Liu Shi et al. 2020. Review of CT image reconstruction open source toolkits, Journal of X-Ray Science and Technology](https://content.iospress.com/articles/journal-of-x-ray-science-and-technology/xst200666)
-
-### License:
-GNU GENERAL PUBLIC LICENSE v.3
-
-### Questions/Comments
-can be addressed to Daniil Kazantsev at [email protected]
+### To cite software please use:
+ [D. Kazantsev and N. Wadeson 2020. TOmographic MOdel-BAsed Reconstruction (ToMoBAR) software for high resolution synchrotron X-ray tomography. CT Meeting 2020](https://github.com/dkazanc/ToMoBAR/tree/master/docs/Kazantsev_CT_20.pdf)

docs/source/howto/installation.rst

@@ -2,8 +2,9 @@
 
 Installation Guide
 ------------------
-ToMoBAR is a Python package with several :ref:`ref_dependencies`. To ensure its full functionality it is recommended to install them.
-It mostly relies on the GPU-enabled computations and therefore we suggest using a decent NVIDIA graphics card to support it.
+ToMoBAR is a Python package with several :ref:`ref_dependencies`. To enable full functionality, it is recommended to install a subset of these dependencies.
+
+.. note:: ToMoBAR relies on GPU-accelerated computations; therefore, we also recommend using a capable NVIDIA graphics card to take full advantage of its features.
 
 .. _ref_python:
 

docs/source/introduction/about.rst

@@ -5,32 +5,42 @@ 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]_.
 
-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]_ .
+Where it is used:
+=================
+
+ToMoBAR is currently used in production at `Diamond Light Source <https://www.diamond.ac.uk/Home.html>`_, which is
+the United Kingdom's national synchrotron science facility. ToMoBAR is exposed through the
+`HTTomolibGPU <https://diamondlightsource.github.io/httomolibgpu/>`_ library which is the backend for the
+`HTTomo <https://diamondlightsource.github.io/httomo/>`_'s framework for big-data processing and
+reconstruction.
 
-.. figure::  ../_static/TomoRec_surf2.jpg
-    :scale: 30 %
-    :alt: ToMoBAR in action
 
-What ToMoBAR can do:
+What can ToMoBAR do:
 ====================
 
+ToMoBAR can operate in GPU device-to-device fashion on CuPy arrays therefore ensuring a better computational
+efficiency. With the GPU device controlling :ref:`ref_api` exposed it can also support multi-GPU parallel computing [CT2020]_ .
+
 * 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`.
+  reconstruction :func:`FOURIER_INV` [NIKITIN2017]_ 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.
 
+.. figure::  ../_static/TomoRec_surf2.jpg
+    :scale: 30 %
+    :alt: ToMoBAR in action
+
 See more on ToMoBAR's API in :ref:`ref_api`.

docs/source/introduction/dependencies.rst

@@ -5,43 +5,58 @@ Dependencies
 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 major dependency
-  as ToMoBAR heavily relies on the GPU-accelerated projection/backprojection routines of the toolbox. With
+* 1. `ASTRA-toolbox <https://www.astra-toolbox.com/>`_ is the important dependency
+  as ToMoBAR 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`.
+  note that for regularised iterative methods you either need
+  `CCPi-Regularisation-Toolkit <https://github.com/TomographicImaging/CCPi-Regularisation-Toolkit/>`_ [KAZ2019]_
+  or a CuPy installation, see bellow for more details.
 
-  Normally ASTRA included into the list of dependencies, but one can install it with:
+  Normally ASTRA Toolbox is included into the list of dependencies of ToMoBAR, but one can install it with:
 
 .. code-block:: console
 
-   $ conda install conda-forge::astra-toolbox
+   $ conda install -c astra-toolbox -c nvidia 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 `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:
+  and `conda-ccpi <https://anaconda.org/ccpi/ccpi-regulariser>`_  pages.
 
 .. code-block:: console
 
-   $ 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)
+   $ conda install httomo::ccpi-regulariser #  linux/windows
+
 
+.. note:: For faster device-to-device regularised iterative reconstruction, consider using the CuPy-based version of ToMoBAR (see point 3).
 
-If one needs to install only CuPy modules (see 6.), the quickest way will be
+* 3. `CuPy <https://cupy.dev/>`_ dependency provides access to GPU-accelerated routines that are separate from the main host-device-host implementation approach. The CuPy-driven algorithms operate on CuPy arrays that remain on the GPU, rather than on NumPy arrays stored in CPU memory.
+  When the CuPy dependency is available, users can access methods from the following classes:
+  :mod:`tomobar.methodsDIR_CuPy` and :mod:`tomobar.methodsIR_CuPy`. For example, the ultra-fast reconstruction method
+  :func:`tomobar.methodsDIR_CuPy.RecToolsDIRCuPy.FOURIER_INV`, based on the Fourier transform [NIKITIN2017]_, is available in :mod:`tomobar.methodsDIR_CuPy`.
+  In addition, faster regularised iterative reconstruction methods are also provided (see point 4).
+  We plan to continue developing and supporting this capability, as it offers significant efficiency gains f
+  or GPU-based computations without requiring explicit software builds.
+
+  For Python installation see `conda-cupy <https://anaconda.org/anaconda/cupy>`_ page.
 
 .. code-block:: console
 
-   $ pip install ccpi-regularisation-cupy # all OS but CuPy modules only
+   $ conda install conda-forge::cupy
+
+* 4. CuPy-enabled CCPi-Regularisation-Toolkit can be used when point 3 is satisfied. This will give you an access to
+  :mod:`tomobar.methodsIR_CuPy` modules, where more efficient iterative regularisation methods are implemented.
+  Note, however, that modules in :mod:`tomobar.methodsIR` won't be accessible without installation of CCPi-Regularisation-Toolkit (see point 2).
 
-* 3. `TomoPhantom <https://github.com/dkazanc/TomoPhantom>`_  is optional but can be very
+
+* 5. `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.
+  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>`_.
 
@@ -50,7 +65,13 @@ If one needs to install only CuPy modules (see 6.), the quickest way will be
    $ conda install httomo::tomophantom # linux/windows
 
 
-* 4. Wavelet toolbox `pypwt <https://github.com/pierrepaleo/pypwt>`_ or **pycudwt** is optional and required only
+* 6. `HTTomolibGPU <https://diamondlightsource.github.io/httomolibgpu/>`_ is a library of GPU accelerated methods for tomography which uses ToMoBAR as a backend for `reconstruction <https://diamondlightsource.github.io/httomolibgpu/reference/methods_list/reconstruction_methods.html>`_. This library can be useful if one builds the full pipeline for raw data processing, including pre-processing, reconstruction and post-processing.
+
+.. code-block:: console
+
+   $ pip install httomolibgpu
+
+* 7. 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.
 
@@ -62,29 +83,7 @@ If one needs to install only CuPy modules (see 6.), the quickest way will be
    $ 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 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
-
-   $ 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.
+* 8. `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.