mrtwo 0.260212__py3-none-any.whl

mr2/VERSION

@@ -0,0 +1 @@
+0.260212

mr2/__init__.py

@@ -0,0 +1,12 @@
+from mr2._version import __version__
+from mr2 import algorithms, operators, data, phantoms, utils, nn
+
+__all__ = [
+    "__version__",
+    "algorithms",
+    "data",
+    "nn",
+    "operators",
+    "phantoms",
+    "utils"
+]

mr2/_version.py

@@ -0,0 +1,8 @@
+# This file is used to get the version of the package from the VERSION file
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+try:
+    __version__ = version('mrtwo')
+except PackageNotFoundError:
+    __version__ = Path(__file__).parent.joinpath('VERSION').read_text().strip()

mr2/algorithms/__init__.py

@@ -0,0 +1,6 @@
+"""Algorithms for reconstructions, optimization, density and sensitivity map estimation, etc."""
+
+from mr2.algorithms import csm, optimizers, reconstruction, dcf
+from mr2.algorithms.prewhiten_kspace import prewhiten_kspace
+from mr2.algorithms.total_variation_denoising import total_variation_denoising
+__all__ = ["csm", "dcf", "optimizers", "prewhiten_kspace", "reconstruction", "total_variation_denoising"]

mr2/algorithms/csm/__init__.py

@@ -0,0 +1,5 @@
+"""Coil Sensitivity Estimation."""
+
+from mr2.algorithms.csm.walsh import walsh
+from mr2.algorithms.csm.inati import inati
+__all__ = ["inati", "walsh"]

mr2/algorithms/csm/inati.py

@@ -0,0 +1,70 @@
+"""Inati method for coil sensitivity map calculation."""
+
+import torch
+from einops import einsum
+
+from mr2.data.SpatialDimension import SpatialDimension
+from mr2.utils.sliding_window import sliding_window
+
+
+def inati(
+    coil_img: torch.Tensor,
+    smoothing_width: SpatialDimension[int] | int,
+) -> torch.Tensor:
+    """Calculate a coil sensitivity map (csm) using the Inati method [INA2013]_ [INA2014]_.
+
+    This is for a single set of coil images. The input should be a tensor with dimensions `(coils, z, y, x)`. The output
+    will have the same dimensions. Either apply this function individually to each set of coil images, or see
+    `~mr2.data.CsmData.from_idata_inati` which performs this operation on a whole dataset.
+
+    .. [INA2013] Inati S, Hansen M, Kellman P (2013) A solution to the phase problem in adaptvie coil combination.
+       in Proceedings of the 21st Annual Meeting of ISMRM, Salt Lake City, USA, 2672.
+
+    .. [INA2014] Inati S, Hansen M (2014) A Fast Optimal Method for Coil Sensitivity Estimation and Adaptive Coil
+       Combination for Complex images. in Proceedings of Joint Annual Meeting ISMRM-ESMRMB, Milan, Italy, 7115.
+
+    Parameters
+    ----------
+    coil_img
+        images for each coil element
+    smoothing_width
+        Size of the smoothing kernel
+    """
+    # After 10 power iterations we will have a very good estimate of the singular vector
+    n_power_iterations = 10
+    eps = 1e-8  # for numerical stability
+
+    if isinstance(smoothing_width, int):
+        smoothing_width = SpatialDimension(
+            z=smoothing_width if coil_img.shape[-3] > 1 else 1, y=smoothing_width, x=smoothing_width
+        )
+
+    if any(ks % 2 != 1 for ks in [smoothing_width.z, smoothing_width.y, smoothing_width.x]):
+        raise ValueError('kernel_size must be odd')
+
+    ks_halved = [ks // 2 for ks in smoothing_width.zyx]
+    padded_coil_img = torch.nn.functional.pad(
+        coil_img,
+        (ks_halved[-1], ks_halved[-1], ks_halved[-2], ks_halved[-2], ks_halved[-3], ks_halved[-3]),
+        mode='replicate',
+    )
+    # Get the voxels in an ROI defined by the smoothing_width around each voxel leading to shape
+    # (z y x coils window=prod(smoothing_width))
+    coil_img_roi = sliding_window(padded_coil_img, smoothing_width.zyx, dim=(-3, -2, -1)).flatten(-3)
+    coil_img_cov = einsum(
+        coil_img_roi.conj(),
+        coil_img_roi,
+        '... coils1 window,... coils2 window->... coils1 coils2',
+    )
+
+    singular_vector = torch.sum(coil_img_roi, dim=-1)  # z y x coils
+    singular_vector /= singular_vector.norm(dim=-1, keepdim=True) + eps
+    for _ in range(n_power_iterations):
+        singular_vector = einsum(coil_img_cov, singular_vector, '... coils1 coils2,... coils2->... coils1')
+        singular_vector /= singular_vector.norm(dim=-1, keepdim=True) + eps
+
+    singular_value = einsum(coil_img_roi, singular_vector, '... coils window,... coils->... window')
+    phase = singular_value.sum(-1)
+    phase /= phase.abs() + eps
+    csm = einsum(singular_vector.conj(), phase, '... coils,...->coils ...')  # coils z y x
+    return csm

mr2/algorithms/csm/walsh.py

@@ -0,0 +1,71 @@
+"""(Iterative) Walsh method for coil sensitivity map calculation."""
+
+import torch
+
+from mr2.data.SpatialDimension import SpatialDimension
+from mr2.utils.filters import uniform_filter
+
+
+def walsh(coil_images: torch.Tensor, smoothing_width: SpatialDimension[int] | int) -> torch.Tensor:
+    """Calculate a coil sensitivity map (csm) using an iterative version of the Walsh method.
+
+    This function computes CSMs from a set of complex coil images assuming spatially
+    slowly changing sensitivity maps using Walsh's method [WAL2000]_.
+
+    The algorithm follows these steps:
+
+    1. **Compute Pointwise Covariance**:
+       Calculate the covariance matrix of the coil images at each voxel to capture inter-coil signal relationships.
+
+    2. **Apply Smoothing Filter**:
+       Smooth the covariance matrices across spatial dimensions using a uniform filter of specified width
+       to reduce noise and enforce spatial consistency.
+
+    3. **Dominant Eigenvector Estimation via Power Iteration**:
+       Perform power iterations to approximate the dominant eigenvector of the covariance matrix at each voxel,
+       representing the principal component of the signal.
+
+    4. **Normalize Sensitivity Maps**:
+       Normalize the resulting eigenvectors to produce the final CSMs.
+
+    This function works on a single set of coil images. The input should be a tensor with dimensions
+    `(coils, z, y, x)`. The output will have the same dimensions. Either apply this function individually to each set of
+    coil images, or see `~mr2.data.CsmData.from_idata_walsh` which performs this operation on a whole dataset
+    [WAL2000]_.
+
+    This implementation is inspired by `ismrmrd-python-tools <https://github.com/ismrmrd/ismrmrd-python-tools>`_.
+
+    Parameters
+    ----------
+    coil_images
+        images for each coil element
+    smoothing_width
+        width of the smoothing filter
+
+    References
+    ----------
+    .. [WAL2000] Walsh DO, Gmitro AF, Marcellin MW (2000) Adaptive reconstruction of phased array MR imagery. MRM 43
+    """
+    # After 10 power iterations we will have a very good estimate of the singular vector
+    n_power_iterations = 10
+
+    if isinstance(smoothing_width, int):
+        smoothing_width = SpatialDimension(smoothing_width, smoothing_width, smoothing_width)
+    # Compute the pointwise covariance between coils
+    coil_covariance = torch.einsum('azyx,bzyx->abzyx', coil_images, coil_images.conj())
+
+    # Smooth the covariance along y-x for 2D and z-y-x for 3D data
+    coil_covariance = uniform_filter(coil_covariance, width=smoothing_width.zyx, dim=(-3, -2, -1))
+
+    # At each point in the image, find the dominant eigenvector
+    # of the signal covariance matrix using the power method
+    v = coil_covariance.sum(dim=0)
+    for _ in range(n_power_iterations):
+        v /= v.norm(dim=0)
+        v = torch.einsum('abzyx,bzyx->azyx', coil_covariance, v)
+    csm = v / v.norm(dim=0)
+
+    # Make sure there are no inf or nan-values due to very small values in the covariance matrix
+    # nan_to_num does not work for complexfloat, boolean indexing not with vmap.
+    csm = torch.where(torch.isfinite(csm), csm, 0.0)
+    return csm

mr2/algorithms/dcf/__init__.py

@@ -0,0 +1,4 @@
+"""Density Compensation Calculation."""
+
+from mr2.algorithms.dcf.dcf_voronoi import dcf_1d, dcf_2d3d_voronoi
+__all__ = ["dcf_1d", "dcf_2d3d_voronoi"]

mr2/algorithms/dcf/dcf_voronoi.py

@@ -0,0 +1,140 @@
+"""1D, 2D and 3D density compensation function calculation with voronoi method."""
+
+from concurrent.futures import ProcessPoolExecutor
+from itertools import product
+
+import numpy as np
+import torch
+from numpy.typing import ArrayLike
+from scipy.spatial import ConvexHull, Voronoi
+
+UNIQUE_ROUNDING_DECIMALS = 15
+
+
+def _volume(v: ArrayLike):
+    return ConvexHull(v).volume
+
+
+def dcf_1d(traj: torch.Tensor) -> torch.Tensor:
+    """Calculate sample density compensation function for 1D trajectory.
+
+    This function operates on a single `other` sample.
+    See also `~mr2.data.DcfData` and `~mr2.utils.smap`.
+
+    Parameters
+    ----------
+    traj
+        k-space positions, 1D tensor
+
+    Returns
+    -------
+        density compensation values
+    """
+    traj_sorted, inverse, counts = torch.unique(
+        torch.round(traj, decimals=UNIQUE_ROUNDING_DECIMALS),
+        sorted=True,
+        return_inverse=True,
+        return_counts=True,
+    )
+
+    # For a sorted trajectory: x0 x1 x2 ... xN
+    # we assign the point at x1 the area (x1 - x0) / 2  + (x2 - x1) / 2,
+    # this is done by central differences (-1,0,1).
+    # For the edges, we append/prepend the values afterwards, such that:
+    # we assign the point at x0 the area (x1 - x0) / 2 + (x1 - x0) / 2, and
+    # we assign the point at xN the area (xN - xN-1) / 2 + (xN - xN-1) / 2.
+
+    kernel = torch.tensor([-1 / 2, 0, 1 / 2], dtype=torch.float32, device=traj.device).reshape(1, 1, 3)
+
+    if (elements := len(traj_sorted)) >= 3:
+        central_diff = torch.nn.functional.conv1d(traj_sorted[None, None, :], kernel)[0, 0]
+        first = traj_sorted[1] - traj_sorted[0]
+        last = traj_sorted[-1] - traj_sorted[-2]
+        central_diff = torch.cat((first[None], central_diff, last[None]), -1)
+    elif elements == 2:
+        diff = traj_sorted[1] - traj_sorted[0]
+        central_diff = torch.cat((diff[None], diff[None]), -1)
+    else:
+        central_diff = torch.ones_like(traj_sorted)
+
+    # Repeated points are reduced by the number of repeats
+    dcf = torch.nan_to_num(central_diff / counts)[inverse]
+    return dcf
+
+
+def dcf_2d3d_voronoi(traj: torch.Tensor) -> torch.Tensor:
+    """Calculate sample density compensation function using Voronoi method.
+
+    This function computes the DCF by determining the area around each point in k-space using the Voronoi tessellation.
+    Points at the edge of k-space are detected as outliers and are assigned the area of the 1% largest DCF values.
+
+    The Voronoi tessellation assigns each point in k-space a region based on the proximity to its nearest neighbors. The
+    DCF is then computed based on the inverse of the area of these regions.
+
+    This function operates on a single `other` sample.
+    See also `~mr2.data.DcfData` and `~mr2.utils.smap`.
+
+    Parameters
+    ----------
+    traj
+        k-space positions `(2 or 3, k2, k1, k0)`
+
+    Returns
+    -------
+        density compensation values `(1, k2, k1, k0)`
+    """
+    # 2D and 3D trajectories supported
+    dim = traj.shape[0]
+    if dim not in (2, 3):
+        raise ValueError(f'Only 2D or 3D trajectories supported, not {dim}D.')
+
+    # Calculate dcf only for unique k-space positions
+    traj_dim = traj.shape
+    traj_numpy = np.round(traj.cpu().numpy(), decimals=UNIQUE_ROUNDING_DECIMALS)
+    traj_numpy = traj_numpy.reshape(dim, -1)
+    traj_unique, inverse, counts = np.unique(traj_numpy, return_inverse=True, return_counts=True, axis=1)
+
+    # Especially in 3D, errors in the calculation of the convex hull can occur for edge points. To avoid this,
+    # the corner points of a cube bounding box are added here. The bounding box is chosen very large to ensure these
+    # edge points of the trajectory can still be accurately detected in the outlier detection further down.
+    furthest_corner = np.max(np.abs(traj_unique))
+    corner_points = np.array(list(product([-1, 1], repeat=dim))) * furthest_corner * 10
+    traj_extendend = np.concatenate((traj_unique, corner_points.transpose()), axis=1)
+
+    # Carry out voronoi tessellation
+    vdiagram = Voronoi(traj_extendend.transpose())
+    regions = [vdiagram.regions[r] for r in vdiagram.point_region[: -len(corner_points)]]  # Ignore corner points
+    vertices = [vdiagram.vertices[region] for region in regions]
+
+    if dim == 2:
+        # Shoelace equation for 2d
+        def cross2d(x: np.ndarray, y: np.ndarray) -> np.ndarray:
+            return x[..., 0] * y[..., 1] - x[..., 1] * y[..., 0]
+
+        dcf = np.array([np.abs(cross2d(v[:-1], v[1:]).sum(0) + cross2d(v[-1], v[0])) / 2 for v in vertices])
+
+    else:
+        # Calculate volume/area of voronoi cells using processes, as this is a very time-consuming operation
+        # and ConvexHull is singlethreaded and does not seem to drop the GIL
+        # TODO: this could maybe be made faster as the polyhedrons are known to be convex
+        future = ProcessPoolExecutor(max_workers=torch.get_num_threads()).map(_volume, vertices, chunksize=100)
+        dcf = np.array(list(future))
+
+    # Get outliers (i.e. voronoi cell which are unbound) and set them to a reasonable value
+    # Outliers are defined as values larger than 1.5 * inter quartile range of the values
+    # Outliers are set to the average of the 1% largest values.
+    dcf_sorted = np.sort(dcf)
+    q1, q3 = np.percentile(dcf_sorted, [25, 75])
+    iqr = q3 - q1
+    upper_bound = q3 + 1.5 * iqr
+    idx_outliers = np.nonzero(dcf > upper_bound)
+    n_outliers = len(idx_outliers[0])
+    high_values_start = int(0.99 * (len(dcf_sorted) - n_outliers))
+    high_values_end = len(dcf_sorted) - n_outliers  # this works also for n_outliers==0
+    fill_value = np.average(dcf_sorted[high_values_start:high_values_end])
+    dcf[idx_outliers] = fill_value
+
+    # Sort dcf values back into the original order (i.e. before calling unique)
+    dcf = np.reshape((dcf / counts)[inverse], traj_dim[1:])
+
+    return torch.tensor(dcf, dtype=torch.float32, device=traj.device)

mr2/algorithms/optimizers/OptimizerStatus.py

@@ -0,0 +1,14 @@
+"""Optimizer Status base class."""
+
+import torch
+from typing_extensions import TypedDict
+
+
+class OptimizerStatus(TypedDict):
+    """Base class for OptimizerStatus."""
+
+    solution: tuple[torch.Tensor, ...]
+    """Current estimate(s) of the solution. """
+
+    iteration_number: int
+    """Current iteration of the (iterative) algorithm."""

mr2/algorithms/optimizers/__init__.py

@@ -0,0 +1,10 @@
+"""Optimizers."""
+
+from mr2.algorithms.optimizers.OptimizerStatus import OptimizerStatus
+from mr2.algorithms.optimizers.adam import adam
+from mr2.algorithms.optimizers.bicg import bicg
+from mr2.algorithms.optimizers.cg import cg
+from mr2.algorithms.optimizers.lbfgs import lbfgs
+from mr2.algorithms.optimizers.pdhg import pdhg
+from mr2.algorithms.optimizers.pgd import pgd
+__all__ = ["OptimizerStatus", "adam", "bicg", "cg", "lbfgs", "pdhg", "pgd"]

mr2/algorithms/optimizers/adam.py

@@ -0,0 +1,137 @@
+"""ADAM for solving non-linear minimization problems."""
+
+from collections.abc import Callable, Sequence
+
+import torch
+from torch.optim import Adam, AdamW
+
+from mr2.algorithms.optimizers.OptimizerStatus import OptimizerStatus
+from mr2.operators.Operator import OperatorType
+
+
+def adam(
+    f: OperatorType,
+    initial_parameters: Sequence[torch.Tensor],
+    *,
+    max_iterations: int = 100,
+    learning_rate: float = 1e-3,
+    tolerance_change: float = 0,
+    betas: tuple[float, float] = (0.9, 0.999),
+    eps: float = 1e-8,
+    weight_decay: float = 0,
+    amsgrad: bool = False,
+    decoupled_weight_decay: bool = False,
+    callback: Callable[[OptimizerStatus], bool | None] | None = None,
+) -> tuple[torch.Tensor, ...]:
+    r"""Adam for non-linear minimization problems.
+
+    Adam [KING2015]_ (Adaptive Moment Estimation) is a first-order optimization algorithm that adapts learning rates
+    for each parameter using estimates of the first and second moments of the gradients.
+
+    The parameter update rule is:
+
+    .. math::
+
+        m_t &= \beta_1 m_{t-1} + (1 - \beta_1) g_t \\
+        v_t &= \beta_2 v_{t-1} + (1 - \beta_2) g_t^2 \\
+        \hat{m}_t &= \frac{m_t}{1 - \beta_1^t}, \quad \hat{v}_t = \frac{v_t}{1 - \beta_2^t} \\
+        \theta_{t+1} &= \theta_t - \frac{\eta}{\sqrt{\hat{v}_t} + \epsilon} \hat{m}_t
+
+    where
+    :math:`g_t` is the gradient at step :math:`t`,
+    :math:`m_t` and :math:`v_t` are biased estimates of the first and second moments,
+    :math:`\hat{m}_t` and :math:`\hat{v}_t` are bias-corrected estimates,
+    :math:`\eta` is the learning rate,
+    :math:`\epsilon` is a small constant for numerical stability,
+    :math:`\beta_1` and :math:`\beta_2` are decay rates for the moment estimates.
+
+    Steps of the Adam algorithm:
+
+    1. Initialize parameters and moment estimates (:math:`m_0`, :math:`v_0`).
+    2. Compute the gradient of the objective function.
+    3. Compute bias-corrected estimates of the moments :math:`\hat{m}_t` and :math:`\hat{v}_t`.
+    4. Update parameters using the adaptive step size.
+
+    This function wraps PyTorch's :class:`torch.optim.Adam` and :class:`torch.optim.AdamW` implementations,
+    supporting both standard Adam and decoupled weight decay regularization (AdamW) [LOS2019]_
+
+    References
+    ----------
+    .. [KING2015] Kingma DP, Ba J (2015) Adam: A Method for Stochastic Optimization. ICLR.
+       https://doi.org/10.48550/arXiv.1412.6980
+    .. [LOS2019] Loshchilov I, Hutter F (2019) Decoupled Weight Decay Regularization. ICLR.
+       https://doi.org/10.48550/arXiv.1711.05101
+    .. [REDDI2019] Sashank J. Reddi, Satyen Kale, Sanjiv Kumar (2019) On the Convergence of Adam and Beyond. ICLR.
+       https://doi.org/10.48550/arXiv.1904.09237
+
+    Parameters
+    ----------
+    f
+        scalar-valued function to be optimized.
+    initial_parameters
+        sequence (for example list) of parameters to be optimized.
+        Note that these parameters will not be changed. Instead, we create a copy and
+        leave the initial values untouched.
+    max_iterations
+        maximum number of iterations.
+    learning_rate
+        learning rate.
+    tolerance_change
+        teriminate if the change of objective function is smaller than this tolerance.
+    betas
+        coefficients used for computing running averages of gradient and its square.
+    eps
+        term added to the denominator to improve numerical stability.
+    weight_decay
+        weight decay (L2 penalty if `decoupled_weight_decay` is `False`).
+    amsgrad
+        whether to use the AMSGrad variant [REDDI2019]_.
+    decoupled_weight_decay
+        whether to use Adam (default) or AdamW (if set to `True`) [LOS2019]_.
+    callback
+        function to be called after each iteration. This can be used to monitor the progress of the algorithm.
+        If it returns `False`, the algorithm stops at that iteration.
+
+    Returns
+    -------
+        optimized parameters
+    """
+    parameters = tuple(p.detach().clone().requires_grad_(True) for p in initial_parameters)
+
+    optim: AdamW | Adam
+
+    if not decoupled_weight_decay:
+        optim = Adam(
+            params=parameters, lr=learning_rate, betas=betas, eps=eps, weight_decay=weight_decay, amsgrad=amsgrad
+        )
+    else:
+        optim = AdamW(
+            params=parameters, lr=learning_rate, betas=betas, eps=eps, weight_decay=weight_decay, amsgrad=amsgrad
+        )
+
+    def closure():
+        optim.zero_grad()
+        (objective,) = f(*parameters)
+        objective.backward()
+
+        return objective
+
+    old_objective = float('inf')
+
+    for iteration in range(max_iterations):
+        objective = optim.step(closure)
+
+        if tolerance_change > 0:
+            objective_ = objective.item()
+            change = old_objective - objective_
+            if change < tolerance_change:
+                break
+            old_objective = objective_
+
+        if callback is not None:
+            continue_iterations = callback({'solution': parameters, 'iteration_number': iteration})
+            if continue_iterations is False:
+                break
+
+    parameters = tuple(p.detach() for p in parameters)
+    return parameters

mr2/algorithms/optimizers/bicg.py

@@ -0,0 +1,164 @@
+"""Stabilized Bi-Conjugate Gradient method for non-symmetric linear systems."""
+
+from collections.abc import Callable, Sequence
+from warnings import warn
+
+import torch
+from typing_extensions import TypedDict, Unpack
+
+from mr2.operators import MultiIdentityOp
+from mr2.operators.LinearOperator import LinearOperator
+from mr2.operators.LinearOperatorMatrix import LinearOperatorMatrix
+
+
+def vdot(a: Sequence[torch.Tensor], b: Sequence[torch.Tensor], force_real: bool = False) -> torch.Tensor:
+    """Vector dot product."""
+    if force_real:
+        a = tuple(torch.view_as_real(a_i) if a_i.is_complex() else a_i for a_i in a)
+        b = tuple(torch.view_as_real(b_i) if b_i.is_complex() else b_i for b_i in b)
+    return sum(
+        (torch.vdot(a_i.flatten(), b_i.flatten()) for a_i, b_i in zip(a, b, strict=True)), start=torch.tensor(0.0)
+    )
+
+
+OperatorMatrixLikeCallable = Callable[[Unpack[tuple[torch.Tensor, ...]]], tuple[torch.Tensor, ...]]
+
+
+class BiCGStatus(TypedDict):
+    """BiCG callback status."""
+
+    solution: tuple[torch.Tensor, ...]
+    iteration_number: int
+    residual: tuple[torch.Tensor, ...]
+
+
+def bicg(
+    operator: LinearOperator | LinearOperatorMatrix | OperatorMatrixLikeCallable,
+    right_hand_side: Sequence[torch.Tensor],
+    *,
+    initial_value: Sequence[torch.Tensor] | None = None,
+    preconditioner_inverse: LinearOperator | LinearOperatorMatrix | OperatorMatrixLikeCallable | None = None,
+    max_iterations: int = 128,
+    tolerance: float = 1e-6,
+    callback: Callable[[BiCGStatus], bool | None] | None = None,
+) -> tuple[torch.Tensor, ...]:
+    r"""(Preconditioned) Bi-Conjugate Gradient Stabilized method for :math:`Hx=b`.
+
+    This algorithm solves systems of the form :math:`H x = b`, where :math:`H` is a
+    linear operator (potentially non-symmetric) and :math:`b` is the right-hand side.
+    The method can solve multiple systems jointly if the operator and tensors handle batch dimensions.
+
+    The method performs the following steps (simplified):
+
+    1. Initialize :math:`x_0`, compute residual :math:`r_0 = b - Hx_0`.
+       Set shadow residual :math:`\hat{r}_0 = r_0`.
+    2. Initialize :math:`\rho_0 = \alpha = \omega = 1`, :math:`p_0 = v_0 = 0`.
+    3. For iteration :math:`k = 0, 1, 2, ...`:
+        1. Compute inner product: :math:`\rho_k = \hat{r}_0^H r_{k-1}`.
+        2. Compute step direction modifier: :math:`\beta_{k-1} = (\rho_k / \rho_{k-1}) (\alpha_{k-1} / \omega_{k-1})`.
+        3. Update search direction: :math:`p_k = r_{k-1} + \beta_{k-1} (p_{k-1} - \omega_{k-1} v_{k-1})`.
+        4. Apply preconditioner: :math:`y_k = M^{-1} p_k`.
+        5. Compute operator applied to search direction: :math:`v_k = H y_k`.
+        6. Compute step size :math:`\alpha_k = \rho_k / (\hat{r}_0^H v_k)`.
+        7. Compute intermediate residual: :math:`s_k = r_{k-1} - \alpha_k v_k`.
+        8. Check convergence: If :math:`\|s_k\|_2` is small, update :math:`x_k = x_{k-1} + \alpha_k y_k` and stop.
+        9. Apply preconditioner to intermediate residual: :math:`z_k = M^{-1} s_k`.
+        10. Compute operator applied to preconditioned intermediate residual: :math:`t_k = H z_k`.
+        11. Compute stabilization factor: :math:`\omega_k = (t_k^H s_k) / (t_k^H t_k)`.
+        12. Update solution: :math:`x_k = x_{k-1} + \alpha_k y_k + \omega_k z_k`.
+        13. Update residual: :math:`r_k = s_k - \omega_k t_k`.
+        14. Update :math:`\rho_{k-1} = \rho_k` for the next iteration.
+
+    If `preconditioner_inverse` is provided, it solves :math:`M^{-1}Hx = M^{-1}b`
+    implicitly, where `preconditioner_inverse(r)` computes :math:`M^{-1}r`.
+
+    See [VanDerVorst1992]_ and [WikipediaBiCGSTAB]_ for more details.
+
+    Parameters
+    ----------
+    operator
+        Linear operator :math:`H`. Does not need to be self-adjoint.
+    right_hand_side
+        Right-hand-side :math:`b`. Must be a sequence of tensors.
+    initial_value
+        Initial guess :math:`x_0`. If None, defaults to zeros. Must be a sequence of tensors.
+    preconditioner_inverse
+        Preconditioner :math:`M^{-1}`. If None, no preconditioning is applied (identity operator).
+    max_iterations
+        Maximum number of iterations.
+    tolerance
+        Tolerance for the L2 norm of the residual :math:`\|r_k\|_2`.
+    callback
+        Function called at the end of each iteration. See `BiCGSTABStatus`.
+        If the callback returns `False`, the iteration stops.
+
+    Returns
+    -------
+        An approximate solution :math:`x` of the linear system :math:`Hx=b` as a tuple of tensors.
+
+    References
+    ----------
+    .. [VanDerVorst1992] Van der Vorst, H. A. (1992). Bi-CGSTAB: A Fast and Smoothly Converging Variant of Bi-CG for the
+       Solution of Nonsymmetric Linear Systems. SIAM Journal on Scientific and Statistical Computing, 13(2), 631-644.
+    .. [WikipediaBiCGSTAB] Wikipedia: Bi-conjugate gradient stabilized method https://en.wikipedia.org/wiki/Bi-conjugate_gradient_stabilized_method
+    """
+    right_hand_side_ = tuple(right_hand_side)
+    if tolerance < torch.finfo(right_hand_side[0].dtype).eps:
+        warn(f'Tolerance is very small ({tolerance}), this can cause nan values.', stacklevel=2)
+    if not right_hand_side_:
+        raise ValueError('right_hand_side cannot be empty')
+
+    if initial_value is None:
+        solution = tuple(torch.zeros_like(r) for r in right_hand_side_)
+    else:
+        solution = tuple(initial_value)
+        if len(solution) != len(right_hand_side_):
+            raise ValueError('Length mismatch in initial_value and right_hand_side')
+        if any(s.shape != r.shape for s, r in zip(solution, right_hand_side_, strict=True)):
+            raise ValueError('Shape mismatch in initial_value and right_hand_side')
+    if any(r.is_complex() for r in right_hand_side_) and not all(r.is_complex() for r in right_hand_side_):
+        force_real = True
+    else:
+        force_real = False
+    residual = tuple(r - op_sol for r, op_sol in zip(right_hand_side_, operator(*solution), strict=True))
+    arbitrary = tuple(r for r in residual)
+
+    preconditioner = preconditioner_inverse if preconditioner_inverse is not None else MultiIdentityOp()
+    alpha = omega = previous_product = operator_search = None
+    search_direction = residual
+
+    for iteration in range(max_iterations):
+        if vdot(residual, residual, force_real).real < tolerance**2:
+            break
+
+        arbitrary_dot_residual = vdot(arbitrary, residual, force_real)
+        if (
+            previous_product is not None and alpha is not None and omega is not None and operator_search is not None
+        ):  # not first iteration
+            beta = (arbitrary_dot_residual / previous_product) * (alpha / omega)
+            search_direction = tuple(
+                r + beta * (p - omega * v) for r, p, v in zip(residual, search_direction, operator_search, strict=True)
+            )
+        preconditioned_search = preconditioner(*search_direction)
+        operator_search = operator(*preconditioned_search)
+        alpha = arbitrary_dot_residual / vdot(arbitrary, operator_search, force_real)
+
+        interim = tuple(r - alpha * v for r, v in zip(residual, operator_search, strict=True))
+        preconditioned_interim = preconditioner(*interim)
+        operator_interim = operator(*preconditioned_interim)
+        omega = vdot(operator_interim, interim, force_real) / vdot(operator_interim, operator_interim, force_real).real
+
+        solution = tuple(
+            x + alpha * p + omega * s
+            for x, p, s in zip(solution, preconditioned_search, preconditioned_interim, strict=True)
+        )
+
+        residual = tuple(i - omega * t for i, t in zip(interim, operator_interim, strict=True))
+        previous_product = arbitrary_dot_residual
+
+        if callback is not None:
+            continue_iterations = callback({'solution': solution, 'iteration_number': iteration, 'residual': residual})
+            if continue_iterations is False:
+                break
+
+    return solution