httomolibgpu 5.2__tar.gz → 5.4__tar.gz

{httomolibgpu-5.2/httomolibgpu.egg-info → httomolibgpu-5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: httomolibgpu
-Version: 5.2
+Version: 5.4
 Summary: Commonly used tomography data processing methods at DLS.
 Author-email: Daniil Kazantsev <daniil.kazantsev@diamond.ac.uk>, Yousef Moazzam <yousef.moazzam@diamond.ac.uk>, Naman Gera <naman.gera@diamond.ac.uk>
 License: BSD-3-Clause

{httomolibgpu-5.2 → httomolibgpu-5.4}/httomolibgpu/cupywrapper.py

@@ -2,6 +2,7 @@ cupy_run = False
 try:
     import cupy as cp
     import nvtx
+    from cupyx.scipy.fft import next_fast_len
 
     try:
         cp.cuda.Device(0).compute_capability
@@ -15,5 +16,6 @@ except ImportError as e:
     )
     from unittest.mock import Mock
     import numpy as cp
+    from scipy.fft import next_fast_len
 
     nvtx = Mock()

{httomolibgpu-5.2 → httomolibgpu-5.4}/httomolibgpu/misc/rescale.py

@@ -27,7 +27,6 @@ cp = cupywrapper.cp
 
 from typing import Literal, Optional, Tuple, Union
 
-
 __all__ = [
     "rescale_to_int",
 ]

{httomolibgpu-5.2 → httomolibgpu-5.4}/httomolibgpu/prep/normalize.py

@@ -34,7 +34,6 @@ else:
 
 from numpy import float32
 
-
 __all__ = ["dark_flat_field_correction", "minus_log"]
 
 
@@ -47,7 +46,7 @@ def dark_flat_field_correction(
     cutoff: float = 10.0,
 ) -> cp.ndarray:
     """
-    Normalize raw projection data using the flat and dark field projections.
+    Perform dark/flat field correction of raw projection data.
 
     Parameters
     ----------
@@ -67,7 +66,7 @@ def dark_flat_field_correction(
             Returns
     -------
     cp.ndarray
-        Normalised by dark/flat fields 3D tomographic data as a CuPy array.
+        dark/flat field corrected 3D tomographic data as a CuPy array.
     """
     _check_valid_input_normalise(data, flats, darks)
 

{httomolibgpu-5.2 → httomolibgpu-5.4}/httomolibgpu/prep/phase.py

@@ -26,6 +26,7 @@ from httomolibgpu.memory_estimator_helpers import _DeviceMemStack
 
 cp = cupywrapper.cp
 cupy_run = cupywrapper.cupy_run
+next_fast_len = cupywrapper.next_fast_len
 
 from unittest.mock import Mock
 
@@ -38,7 +39,7 @@ else:
     fftshift = Mock()
 
 from numpy import float32
-from typing import Optional, Tuple
+from typing import Literal, Optional, Tuple
 import math
 
 __all__ = [
@@ -56,6 +57,10 @@ def paganin_filter(
     distance: float = 1.0,
     energy: float = 53.0,
     ratio_delta_beta: float = 250,
+    calculate_padding_value_method: Literal[
+        "next_power_of_2", "next_fast_length", "use_pad_x_y"
+    ] = "next_power_of_2",
+    pad_x_y: Optional[list] = None,
     calc_peak_gpu_mem: bool = False,
 ) -> cp.ndarray:
     """
@@ -74,6 +79,10 @@ def paganin_filter(
         Beam energy in keV.
     ratio_delta_beta : float
         The ratio of delta/beta, where delta is the phase shift and real part of the complex material refractive index and beta is the absorption.
+    calculate_padding_value_method: str
+        Method to calculate the padded size of the input data. Accepted values are 'next_power_of_2', 'next_fast_length' and 'use_pad_x_y`.
+    pad_x_y list | None:
+        Padding values in pixels horizontally and vertically. Must be None, unless `calculate_padding_value_method` is 'use_pad_x_y'.
     calc_peak_gpu_mem: bool
         Parameter to support memory estimation in HTTomo. Irrelevant to the method itself and can be ignored by user.
 
@@ -93,9 +102,9 @@ def paganin_filter(
         mem_stack.malloc(np.prod(tomo) * np.float32().itemsize)
     dz_orig, dy_orig, dx_orig = tomo.shape if not mem_stack else tomo
 
-    # Perform padding to the power of 2 as FFT is O(n*log(n)) complexity
-    # TODO: adding other options of padding?
-    padded_tomo, pad_tup = _pad_projections_to_second_power(tomo, mem_stack)
+    padded_tomo, pad_tup = _pad_projections(
+        tomo, calculate_padding_value_method, pad_x_y, mem_stack
+    )
 
     dz, dy, dx = padded_tomo.shape if not mem_stack else padded_tomo
 
@@ -219,21 +228,59 @@ def _shift_bit_length(x: int) -> int:
     return 1 << (x - 1).bit_length()
 
 
-def _calculate_pad_size(datashape: tuple) -> list:
+def _calculate_pad_size(
+    datashape: tuple,
+    calculate_padding_value_method: Literal[
+        "next_power_of_2", "next_fast_length", "use_pad_x_y"
+    ],
+    pad_x_y: Optional[list],
+) -> list:
     """Calculating the padding size
 
     Args:
-        datashape (tuple): the shape of the 3D data
+        datashape (tuple):
+            the shape of the 3D data
+        calculate_padding_value_method: str
+            Method to calculate the padded size of the input data. Accepted values are 'next_power_of_2', 'next_fast_length' and 'use_pad_x_y`.
+        pad_x_y (int, int) | None:
+            Padding values in pixels horizontally and vertically. Must be None, unless `calculate_padding_value_method` is 'use_pad_x_y'.
 
     Returns:
         list: the padded dimensions
     """
+    if pad_x_y is not None and calculate_padding_value_method != "use_pad_x_y":
+        raise ValueError(
+            'calculate_padding_value_method must be "use_pad_x_y" when pad_x_y is specified'
+        )
+    elif calculate_padding_value_method == "use_pad_x_y":
+        if pad_x_y is None:
+            raise ValueError(
+                'pad_x_y must be provided when calculate_padding_value_method is "use_pad_x_y"'
+            )
+        elif (
+            not isinstance(pad_x_y, list)
+            or len(pad_x_y) != 2
+            or not isinstance(pad_x_y[0], int)
+            or not isinstance(pad_x_y[1], int)
+        ):
+            raise ValueError("pad_x_y must be a list of two integers")
+
+    if calculate_padding_value_method == "next_power_of_2":
+        calculate_padded_dim = lambda _, size: _shift_bit_length(size + 1)
+    elif calculate_padding_value_method == "next_fast_length":
+        calculate_padded_dim = lambda _, size: next_fast_len(size)
+    elif calculate_padding_value_method == "use_pad_x_y":
+        calculate_padded_dim = lambda dim, size: size + 2 * pad_x_y[2 - dim]
+    else:
+        raise ValueError(
+            f'Unexpected calculate_padding_value_method: "{calculate_padding_value_method}"'
+        )
     pad_list = []
     for index, element in enumerate(datashape):
         if index == 0:
             pad_width = (0, 0)  # do not pad the slicing dim
         else:
-            diff = _shift_bit_length(element + 1) - element
+            diff = calculate_padded_dim(index, element) - element
             if element % 2 == 0:
                 pad_width_scalar = diff // 2
                 pad_width = (pad_width_scalar, pad_width_scalar)
@@ -248,17 +295,27 @@ def _calculate_pad_size(datashape: tuple) -> list:
     return pad_list
 
 
-def _pad_projections_to_second_power(
-    tomo: cp.ndarray, mem_stack: Optional[_DeviceMemStack]
+def _pad_projections(
+    tomo: cp.ndarray,
+    calculate_padding_value_method: Literal[
+        "next_power_of_2", "next_fast_length", "use_pad_x_y"
+    ],
+    pad_x_y: Optional[list],
+    mem_stack: Optional[_DeviceMemStack],
 ) -> Tuple[cp.ndarray, Tuple[int, int]]:
     """
-    Performs padding of each projection to the next power of 2.
+    Performs padding of each projection to a size optimal for FFT.
     If the shape is not even we also care of that before padding.
 
     Parameters
     ----------
     tomo : cp.ndarray
         3d projection data
+    calculate_padding_value_method: str
+        Method to calculate the padded size of the input data. Accepted values are 'next_power_of_2', 'next_fast_length' and 'use_pad_x_y`.
+    pad_x_y: list | None:
+        Padding values in pixels horizontally and vertically. Must be None, unless `calculate_padding_value_method` is 'use_pad_x_y'.
+
 
     Returns
     -------
@@ -268,7 +325,9 @@ def _pad_projections_to_second_power(
     """
     full_shape_tomo = cp.shape(tomo) if not mem_stack else tomo
 
-    pad_list = _calculate_pad_size(full_shape_tomo)
+    pad_list = _calculate_pad_size(
+        full_shape_tomo, calculate_padding_value_method, pad_x_y
+    )
 
     if mem_stack:
         padded_tomo = [

{httomolibgpu-5.2 → httomolibgpu-5.4}/httomolibgpu/prep/stripe.py

@@ -845,7 +845,7 @@ def _detect_stripe(listdata, snr):
     listsorted = cp.sort(listdata)[::-1]
     xlist = cp.arange(0, numdata, 1.0)
     ndrop = cp.int16(0.25 * numdata)
-    (_slope, _intercept) = _mpolyfit(
+    _slope, _intercept = _mpolyfit(
         xlist[ndrop : -ndrop - 1], listsorted[ndrop : -ndrop - 1]
     )
 
@@ -869,7 +869,7 @@ def _rs_large(sinogram, snr, size, matindex, drop_ratio=0.1, norm=True):
     Remove large stripes.
     """
     drop_ratio = max(min(drop_ratio, 0.8), 0)  # = cp.clip(drop_ratio, 0.0, 0.8)
-    (nrow, ncol) = sinogram.shape
+    nrow, ncol = sinogram.shape
     ndrop = int(0.5 * drop_ratio * nrow)
     sinosort = cp.sort(sinogram, axis=0)
     sinosmooth = median_filter(sinosort, (1, size))
@@ -907,7 +907,7 @@ def _rs_large(sinogram, snr, size, matindex, drop_ratio=0.1, norm=True):
 def _rs_dead(sinogram, snr, size, matindex, norm=True):
     """remove unresponsive and fluctuating stripes"""
     sinogram = cp.copy(sinogram)  # Make it mutable
-    (nrow, _) = sinogram.shape
+    nrow, _ = sinogram.shape
     sinosmooth = uniform_filter1d(sinogram, 10, axis=0)
 
     listdiff = cp.sum(cp.abs(sinogram - sinosmooth), axis=0)

{httomolibgpu-5.2 → httomolibgpu-5.4}/httomolibgpu/recon/algorithm.py

@@ -40,7 +40,6 @@ else:
 from numpy import float32
 from typing import Optional, Type, Union
 
-
 __all__ = [
     "FBP2d_astra",
     "FBP3d_tomobar",
@@ -48,6 +47,7 @@ __all__ = [
     "SIRT3d_tomobar",
     "CGLS3d_tomobar",
     "FISTA3d_tomobar",
+    "ADMM3d_tomobar",
 ]
 
 input_data_axis_labels = ["angles", "detY", "detX"]  # set the labels of the input data
@@ -272,9 +272,7 @@ def SIRT3d_tomobar(
 ) -> cp.ndarray:
     """
     Perform Simultaneous Iterative Recostruction Technique (SIRT) using ASTRA toolbox :cite:`van2016fast` and
-    ToMoBAR :cite:`kazantsev2020tomographic` wrappers.
-    This is 3D recon directly from a CuPy array while using ASTRA GPUlink capability to avoid host-device
-    transactions for projection and backprojection.
+    ToMoBAR :cite:`kazantsev2020tomographic` wrappers. For more information see :ref:`method_SIRT3d_tomobar`.
 
     Parameters
     ----------
@@ -345,9 +343,7 @@ def CGLS3d_tomobar(
 ) -> cp.ndarray:
     """
     Perform Conjugate Gradient Least Squares (CGLS) using ASTRA toolbox :cite:`van2016fast` and
-    ToMoBAR :cite:`kazantsev2020tomographic` wrappers.
-    This is 3D recon directly from a CuPy array while using ASTRA GPUlink capability to avoid host-device
-    transactions for projection and backprojection.
+    ToMoBAR :cite:`kazantsev2020tomographic` wrappers. For more information see :ref:`method_CGLS3d_tomobar`.
 
     Parameters
     ----------
@@ -418,6 +414,7 @@ def FISTA3d_tomobar(
     """
     A Fast Iterative Shrinkage-Thresholding Algorithm :cite:`beck2009fast` with various types of regularisation or
     denoising operations :cite:`kazantsev2019ccpi` (currently accepts ROF_TV and PD_TV regularisations only).
+    For more information see :ref:`method_FISTA3d_tomobar`.
 
     Parameters
     ----------
@@ -489,6 +486,158 @@ def FISTA3d_tomobar(
     return cp.require(cp.swapaxes(reconstruction, 0, 1), requirements="C")
 
 
+## %%%%%%%%%%%%%%%%%%%%%%% ADMM reconstruction %%%%%%%%%%%%%%%%%%%%%%%%%%%%  ##
+def ADMM3d_tomobar(
+    data: cp.ndarray,
+    angles: np.ndarray,
+    center: Optional[float] = None,
+    detector_pad: Union[bool, int] = False,
+    recon_size: Optional[int] = None,
+    recon_mask_radius: float = 0.95,
+    iterations: int = 3,
+    subsets_number: int = 24,
+    initialisation: Optional[str] = "FBP",
+    ADMM_rho_const: float = 1.0,
+    ADMM_relax_par: float = 1.7,
+    regularisation_type: str = "PD_TV",
+    regularisation_parameter: float = 0.0025,
+    regularisation_iterations: int = 40,
+    regularisation_half_precision: bool = True,
+    nonnegativity: bool = False,
+    gpu_id: int = 0,
+) -> cp.ndarray:
+    """
+    An Alternating Direction Method of Multipliers method with various types of regularisation or
+    denoising operations :cite:`kazantsev2019ccpi` (currently accepts ROF_TV and PD_TV regularisations only).
+    For more information see :ref:`_method_ADMM3d_tomobar`.
+
+    Parameters
+    ----------
+    data : cp.ndarray
+        Projection data as a CuPy array.
+    angles : np.ndarray
+        An array of angles given in radians.
+    center : float, optional
+        The center of rotation (CoR).
+    detector_pad : bool, int
+        Detector width padding with edge values to remove circle/arc type artifacts in the reconstruction. Set to True to perform
+        an automated padding or specify a certain value as an integer.
+    recon_size : int, optional
+        The [recon_size, recon_size] shape of the reconstructed slice in pixels.
+        By default (None), the reconstructed size will be the dimension of the horizontal detector.
+    recon_mask_radius: float
+        The radius of the circular mask that applies to the reconstructed slice in order to crop
+        out some undesirable artifacts. The values outside the given diameter will be set to zero.
+        To implement the cropping one can use the range [0.7-1.0] or set to 2.0 when no cropping required.
+    iterations : int
+        The number of ADMM algorithm iterations. The recommended range is between 3 to 5 with initialisation and
+        more than 10 without. Assuming that the subsets_number is reasonably large (>12).
+    subsets_number: int
+        The number of the ordered subsets to accelerate convergence. The recommended range is between 12 to 24.
+    initialisation: str, optional
+        Initialise ADMM with the reconstructed image to reduce the number of iterations and accelerate. Choose between 'CGLS' when data
+        is noisy and undersampled, 'FBP' when data is of better quality (default) or None.
+    ADMM_rho_const: float
+        Convergence related parameter for ADMM, higher values lead to slower convergence, but too small values can destabilise the iterations.
+        Recommended range is between 0.9 and 2.0.
+    ADMM_relax_par: Relaxation parameter which can lead to acceleration of the algorithm, keep it in the range between 1.5 and 1.8 to avoid divergence.     regularisation_type: str
+        A method to use for regularisation. Currently PD_TV and ROF_TV are available.
+    regularisation_parameter: float
+        The main regularisation parameter to control the amount of smoothing/noise removal. Larger values lead to stronger smoothing.
+    regularisation_iterations: int
+        The number of iterations for regularisers (aka INNER iterations).
+    regularisation_half_precision: bool
+        Perform faster regularisation computation in half-precision with a very minimal sacrifice in quality.
+    nonnegativity : bool
+        Impose nonnegativity constraint (set to True) on the reconstructed image. Default False.
+    gpu_id : int
+        A GPU device index to perform operation on.
+
+    Returns
+    -------
+    cp.ndarray
+        The ADMM reconstructed volume as a CuPy array.
+    """
+    if initialisation not in ["FBP", "CGLS", None]:
+        raise ValueError(
+            "The acceptable values for initialisation are 'FBP','CGLS' and None"
+        )
+
+    if initialisation is not None:
+        if detector_pad == True:
+            detector_pad = __estimate_detectorHoriz_padding(data.shape[2])
+
+        if detector_pad > 0:
+            # if detector_pad is not zero we need to reconstruct the image on the recon+2*detector_pad size
+            recon_size = data.shape[2] + 2 * detector_pad
+
+        if initialisation == "FBP":
+            initialisation_vol = cp.require(
+                cp.swapaxes(
+                    FBP3d_tomobar(
+                        data,
+                        angles=angles,
+                        center=center,
+                        detector_pad=detector_pad,
+                        recon_size=recon_size,
+                        recon_mask_radius=recon_mask_radius,
+                    ),
+                    0,
+                    1,
+                ),
+                requirements="C",
+            )
+        elif initialisation == "CGLS":
+            initialisation_vol = cp.require(
+                cp.swapaxes(
+                    CGLS3d_tomobar(
+                        data,
+                        angles=angles,
+                        center=center,
+                        detector_pad=detector_pad,
+                        recon_size=recon_size,
+                        recon_mask_radius=recon_mask_radius,
+                        iterations=15,
+                    ),
+                    0,
+                    1,
+                ),
+                requirements="C",
+            )
+    else:
+        initialisation_vol = None
+
+    RecToolsCP = _instantiate_iterative_recon_class(
+        data, angles, center, detector_pad, recon_size, gpu_id, datafidelity="LS"
+    )
+
+    _data_ = {
+        "projection_norm_data": data,
+        "OS_number": subsets_number,
+        "data_axes_labels_order": input_data_axis_labels,
+    }
+
+    _algorithm_ = {
+        "initialise": initialisation_vol,
+        "iterations": iterations,
+        "nonnegativity": nonnegativity,
+        "recon_mask_radius": recon_mask_radius,
+        "ADMM_rho_const": ADMM_rho_const,
+        "ADMM_relax_par": ADMM_relax_par,
+    }
+
+    _regularisation_ = {
+        "method": regularisation_type,  # Selected regularisation method
+        "regul_param": regularisation_parameter,  # Regularisation parameter
+        "iterations": regularisation_iterations,  # The number of regularisation iterations
+        "half_precision": regularisation_half_precision,  # enabling half-precision calculation
+    }
+
+    reconstruction = RecToolsCP.ADMM(_data_, _algorithm_, _regularisation_)
+    cp._default_memory_pool.free_all_blocks()
+    return cp.require(cp.swapaxes(reconstruction, 0, 1), requirements="C")
+
+
 ## %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%  ##
 def _instantiate_direct_recon_class(
     data: cp.ndarray,

{httomolibgpu-5.2 → httomolibgpu-5.4}/httomolibgpu/recon/rotation.py

@@ -171,7 +171,7 @@ def find_center_vo(
 
 
 def _search_coarse(sino, smin, smax, ratio, drop):
-    (nrow, ncol) = sino.shape
+    nrow, ncol = sino.shape
     flip_sino = cp.ascontiguousarray(cp.fliplr(sino))
     comp_sino = cp.ascontiguousarray(cp.flipud(sino))
 
@@ -206,7 +206,7 @@ def _search_coarse(sino, smin, smax, ratio, drop):
 
 
 def _search_fine(sino, srad, step, init_cen, ratio, drop):
-    (nrow, ncol) = sino.shape
+    nrow, ncol = sino.shape
 
     flip_sino = cp.ascontiguousarray(cp.fliplr(sino))
     comp_sino = cp.ascontiguousarray(cp.flipud(sino))
@@ -397,7 +397,7 @@ def _downsample(image, dsp_fact0, dsp_fact1):
     ---------
         image_dsp : Downsampled image.
     """
-    (height, width) = image.shape
+    height, width = image.shape
     dsp_fact0 = cp.clip(cp.int16(dsp_fact0), 1, height // 2)
     dsp_fact1 = cp.clip(cp.int16(dsp_fact1), 1, width // 2)
     height_dsp = height // dsp_fact0
@@ -477,11 +477,11 @@ def find_center_360(
     else:
         _sino = data[:, ind, :]
 
-    (nrow, ncol) = _sino.shape
+    nrow, ncol = _sino.shape
     nrow_180 = nrow // 2 + 1
     sino_top = _sino[0:nrow_180, :]
     sino_bot = cp.fliplr(_sino[-nrow_180:, :])
-    (overlap, side, overlap_position) = _find_overlap(
+    overlap, side, overlap_position = _find_overlap(
         sino_top, sino_bot, win_width, side, denoise, norm, use_overlap
     )
     cor = ncol - overlap / 2
@@ -531,7 +531,7 @@ def _find_overlap(
     win_width = int(np.clip(win_width, 6, min(ncol1, ncol2) // 2))
 
     if side == "right":
-        (list_metric, offset) = _search_overlap(
+        list_metric, offset = _search_overlap(
             mat1,
             mat2,
             win_width,
@@ -544,7 +544,7 @@ def _find_overlap(
         overlap_position += offset
         overlap = ncol1 - overlap_position + win_width // 2
     elif side == "left":
-        (list_metric, offset) = _search_overlap(
+        list_metric, offset = _search_overlap(
             mat1,
             mat2,
             win_width,
@@ -557,7 +557,7 @@ def _find_overlap(
         overlap_position += offset
         overlap = overlap_position + win_width // 2
     else:
-        (list_metric1, offset1) = _search_overlap(
+        list_metric1, offset1 = _search_overlap(
             mat1,
             mat2,
             win_width,
@@ -566,7 +566,7 @@ def _find_overlap(
             norm=norm,
             use_overlap=use_overlap,
         )
-        (list_metric2, offset2) = _search_overlap(
+        list_metric2, offset2 = _search_overlap(
             mat1,
             mat2,
             win_width,
@@ -576,9 +576,9 @@ def _find_overlap(
             use_overlap=use_overlap,
         )
 
-        (curvature1, overlap_position1) = _calculate_curvature(list_metric1)
+        curvature1, overlap_position1 = _calculate_curvature(list_metric1)
         overlap_position1 += offset1
-        (curvature2, overlap_position2) = _calculate_curvature(list_metric2)
+        curvature2, overlap_position2 = _calculate_curvature(list_metric2)
         overlap_position2 += offset2
 
         if curvature1 > curvature2:
@@ -638,8 +638,8 @@ def _search_overlap(
         mat1 = cp.ascontiguousarray(mat1, dtype=cp.float32)
         mat2 = cp.ascontiguousarray(mat2, dtype=cp.float32)
 
-    (nrow1, ncol1) = mat1.shape
-    (nrow2, ncol2) = mat2.shape
+    nrow1, ncol1 = mat1.shape
+    nrow2, ncol2 = mat2.shape
 
     if nrow1 != nrow2:
         raise ValueError("Two images are not at the same height!!!")

{httomolibgpu-5.2 → httomolibgpu-5.4/httomolibgpu.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: httomolibgpu
-Version: 5.2
+Version: 5.4
 Summary: Commonly used tomography data processing methods at DLS.
 Author-email: Daniil Kazantsev <daniil.kazantsev@diamond.ac.uk>, Yousef Moazzam <yousef.moazzam@diamond.ac.uk>, Naman Gera <naman.gera@diamond.ac.uk>
 License: BSD-3-Clause