Add subpackage readme files (#36)

Author: hakkelt

DSPOperators/README.md

@@ -0,0 +1,102 @@
+# DSPOperators.jl
+
+[![](https://img.shields.io/badge/docs-stable-blue.svg)](https://kul-optec.github.io/AbstractOperators.jl/stable/operators/#Convolution)
+[![](https://img.shields.io/badge/docs-latest-blue.svg)](https://kul-optec.github.io/AbstractOperators.jl/latest/operators/#Convolution)
+
+Digital Signal Processing operators for the AbstractOperators.jl framework.
+
+## Overview
+
+DSPOperators.jl is a specialized extension package for [AbstractOperators.jl](../README.md) that provides linear operators for common digital signal processing (DSP) operations. It allows DSP operations such as filtering, convolution, and cross-correlation to be expressed using the unified `LinearOperator` interface, making them seamlessly compatible with optimization algorithms and iterative solvers built on AbstractOperators.
+
+## Relationship to AbstractOperators.jl
+
+DSPOperators.jl is a **subpackage** of the AbstractOperators.jl ecosystem. While AbstractOperators.jl provides the core abstract operator framework and basic linear algebra operators, DSPOperators.jl extends this framework with domain-specific functionality for signal processing. This modular design keeps the base package lightweight while allowing users to opt-in to DSP-specific features only when needed.
+
+## Installation
+
+```julia
+pkg> add DSPOperators
+```
+
+## Usage Example
+
+```julia
+using DSPOperators
+
+# Create signals
+signal = randn(100)
+filter_kernel = randn(5)
+
+# Create a convolution operator
+conv_op = Conv(signal, filter_kernel)
+
+# Apply convolution via operator multiplication
+result = conv_op * signal
+
+# Use in optimization or iterative algorithms
+# The operator integrates with AbstractOperators.jl algorithms
+```
+
+## Main Features
+
+### 1. **Conv** - FFT-based Convolution Operator
+Implements 1D convolution using efficient FFT algorithms. Creates a `LinearOperator` that computes the convolution between an input signal and a filter kernel.
+
+- **Efficient computation**: Uses FFTW for fast convolution via the FFT algorithm
+- **Type flexibility**: Supports both real and complex-valued signals
+- **Automatic padding**: Handles dimension expansion automatically
+
+```julia
+using DSPOperators
+op = Conv((10,), randn(5))  # Convolve length-10 signal with length-5 kernel
+```
+
+### 2. **Filt** - IIR/FIR Filtering Operator
+Implements infinite impulse response (IIR) and finite impulse response (FIR) filters for single-input-single-output (SISO) systems.
+
+- **IIR filters**: Specify both numerator (`b`) and denominator (`a`) coefficients
+- **FIR filters**: Specify only numerator coefficients (`b`)
+- **Coefficient normalization**: Automatically normalizes filter coefficients
+- **Stateful operation**: Maintains filter state for sequential filtering
+
+```julia
+using DSPOperators
+# IIR filter
+filt_op = Filt(Float64, (10,), [1.0, 2.0, 1.0], [1.0, -1.0])
+
+# FIR filter
+fir_op = Filt(Float64, (10,), [1.0, 0.5, 0.2])
+```
+
+### 3. **MIMOFilt** - Multiple-Input-Multiple-Output Filtering
+Extends filtering capabilities to multi-channel systems with multiple input and output signals.
+
+- **MIMO systems**: Handles coupled filtering between multiple input/output channels
+- **Flexible specifications**: IIR or FIR filters per channel pair
+- **Matrix operations**: Works directly with signal matrices where columns represent channels
+
+```julia
+using DSPOperators
+m, n = 10, 3  # 10 time samples, 3 inputs
+# 3×2 MIMO system: 3 inputs, 2 outputs (6 filter vectors total)
+B = [[1.; 0.; 1.], [1.; 0.; 1.], [1.; 0.; 1.],
+     [1.; 0.; 1.], [1.; 0.; 1.], [1.; 0.; 1.]]
+op = MIMOFilt((m, n), B)  # FIR filters
+```
+
+### 4. **Xcorr** - Cross-Correlation Operator
+Computes cross-correlation between input signals and a reference signal using DSP.jl's optimized routines.
+
+- **Efficient computation**: Leverages DSP.jl's cross-correlation implementation
+- **Symmetric operation**: Supports both forward and adjoint operations
+- **Flexible mode**: Uses the longest padding mode by default
+
+```julia
+using DSPOperators
+xcorr_op = Xcorr(Float64, (10,), [1.0, 0.5, 0.2])
+```
+
+## License
+
+See LICENSE.md for details.

FFTWOperators/README.md

@@ -0,0 +1,133 @@
+# FFTWOperators.jl
+
+[![](https://img.shields.io/badge/docs-stable-blue.svg)](https://kul-optec.github.io/AbstractOperators.jl/stable/operators/#FFTW)
+[![](https://img.shields.io/badge/docs-latest-blue.svg)](https://kul-optec.github.io/AbstractOperators.jl/latest/operators/#FFTW)
+
+Fast Fourier Transform operators for the AbstractOperators.jl framework.
+
+## Overview
+
+FFTWOperators.jl is a specialized extension package for [AbstractOperators.jl](../README.md) that provides linear operators for efficient Fourier and frequency-domain transforms. It wraps the high-performance FFTW library to offer Discrete Fourier Transforms (DFT), Real FFTs (RDFT), Inverse Real FFTs (IRDFT), and Discrete Cosine Transforms (DCT) as seamlessly integrated `LinearOperator` instances.
+
+## Relationship to AbstractOperators.jl
+
+FFTWOperators.jl is a **subpackage** of the AbstractOperators.jl ecosystem. While AbstractOperators.jl provides the core abstract operator framework, FFTWOperators.jl extends it with domain-specific functionality for Fourier analysis and frequency-domain operations. This modular design allows users to access high-performance FFT capabilities only when needed.
+
+## Installation
+
+```julia
+pkg> add FFTWOperators
+```
+
+## Usage Example
+
+```julia
+using FFTWOperators
+
+# Create input data
+x = randn(64, 64)
+
+# Create a DFT operator
+dft_op = DFT(x)
+
+# Compute the Fourier transform
+X_fft = dft_op * x
+
+# Use in optimization or iterative algorithms
+# The operator integrates with AbstractOperators.jl algorithms
+```
+
+## Main Features
+
+### 1. **DFT** - Discrete Fourier Transform
+Computes the N-dimensional Discrete Fourier Transform using FFTW's optimized algorithms.
+
+- **Multi-dimensional support**: Works on arbitrary-dimensional arrays
+- **Selective dimensions**: Transform over specified dimensions of a multi-dimensional array
+- **Multiple normalizations**: UNNORMALIZED, ORTHO, FORWARD, and BACKWARD schemes
+- **Customizable planning**: Control FFTW planning flags and time limits
+- **Orthogonal properties**: Supports orthogonal DFT operations for optimization algorithms
+
+```julia
+using FFTWOperators
+
+# Complex-valued DFT
+dft_op = DFT(Complex{Float64}, (10, 10))
+
+# Real-valued input (transforms to complex output)
+x = randn(64, 64)
+dft_op = DFT(x)
+X = dft_op * x  # Fourier transform
+
+# Transform along specific dimensions
+dft_op = DFT(x, 1)  # Only along first dimension
+```
+
+### 2. **RDFT** - Real FFT
+Specialized Fast Fourier Transform for real-valued inputs, exploiting Hermitian symmetry for efficiency.
+
+- **Real input efficiency**: Optimized for real-valued signals, outputs complex values
+- **Dimension-selective**: Transform along specific dimensions
+- **Conjugate symmetry**: Automatically exploits Hermitian symmetry properties
+- **Reduced computation**: Approximately 50% faster than complex FFT for real inputs
+
+```julia
+using FFTWOperators
+
+# Real FFT of a real-valued array
+rdft_op = RDFT(Float64, (10, 10))
+
+# Apply along a specific dimension
+x = randn(100, 10, 10)
+rdft_op = RDFT(x, 2)  # Transform along dimension 2
+X = rdft_op * x
+```
+
+### 3. **IRDFT** - Inverse Real FFT
+Transforms complex-valued k-space data back to real-valued spatial domain, inverse of RDFT.
+
+- **Hermitian reconstruction**: Properly reconstructs real values from complex k-space
+- **Adjoint operation**: Acts as the adjoint of RDFT for linear algebra operations
+- **Energy preserving**: Maintains signal energy in the inverse transform
+
+```julia
+using FFTWOperators
+
+# Inverse real FFT - transforms complex-valued input to real-valued output
+# Takes the k-space dimension, the desired output spatial dimension, and optionally the transform dimension
+irdft_op = IRDFT((51,), 100, 1)  # 51 complex input -> 100 real output along dimension 1
+```
+
+### 4. **DCT** - Discrete Cosine Transform
+Computes the Discrete Cosine Transform, useful for image compression and spectral analysis.
+
+- **Real-valued I/O**: Works with real-valued signals for many applications
+- **Complex support**: Also supports complex-valued transforms
+- **Standard DCT**: Implements standard DCT-II (the most common variant)
+- **Orthogonal transform**: Invertible with fast IDCT operation
+
+```julia
+using FFTWOperators
+
+# Real-valued DCT
+dct_op = DCT(Float64, (10, 10))
+x = randn(10, 10)
+y = dct_op * x  # Cosine transform
+
+# Complex DCT
+dct_complex = DCT(Complex{Float64}, (8, 8))
+
+# Inverse DCT
+idct_op = IDCT(Float64, (10, 10))
+```
+
+### 5. **Shift** - Frequency Shift Operator
+Applies frequency shifts and zero-padding to signals.
+
+- **Frequency shifting**: Shift zero-frequency component to the center
+- **Zero-padding**: Efficiently apply padding for zero-padded transforms
+- **Composable**: Combines seamlessly with other operators
+
+## License
+
+See LICENSE.md for details.

NFFTOperators/README.md

@@ -0,0 +1,98 @@
+# NFFTOperators.jl
+
+[![](https://img.shields.io/badge/docs-stable-blue.svg)](https://kul-optec.github.io/AbstractOperators.jl/stable/operators/#NFFT)
+[![](https://img.shields.io/badge/docs-latest-blue.svg)](https://kul-optec.github.io/AbstractOperators.jl/latest/operators/#NFFT)
+
+Non-Uniform Fast Fourier Transform operators for the AbstractOperators.jl framework.
+
+## Overview
+
+NFFTOperators.jl is a specialized extension package for [AbstractOperators.jl](../README.md) that provides linear operators for Non-Uniform Fast Fourier Transforms (NFFT). It wraps the high-performance NFFT.jl library to offer efficient transforms between spatial and non-uniform k-space domains, which is essential for magnetic resonance imaging (MRI), radar, and other applications with non-uniform sampling patterns.
+
+## Relationship to AbstractOperators.jl
+
+NFFTOperators.jl is a **subpackage** of the AbstractOperators.jl ecosystem. While AbstractOperators.jl provides the core abstract operator framework, NFFTOperators.jl extends it with specialized functionality for non-uniform Fourier transforms. This modular design allows users to access advanced NFFT capabilities optimized for applications like MRI reconstruction only when needed.
+
+## Installation
+
+```julia
+pkg> add NFFTOperators
+```
+
+## Usage Example
+
+```julia
+using NFFTOperators, NFFT
+
+# Define MRI parameters
+image_size = (256, 256)
+
+# Create k-space trajectory (normalized to [-0.5, 0.5))
+trajectory = rand(2, 100, 50) .- 0.5  # 2D, 100 points per readout, 50 readouts
+
+# Create NFFT operator
+nfft_op = NFFTOp(image_size, trajectory)
+
+# Transform image to k-space
+x = randn(image_size...)
+k_space = nfft_op * x
+
+# Adjoint operation: k-space to image
+x_recon = nfft_op' * k_space
+```
+
+## Main Features
+
+### 1. **NFFTOp** - Non-Uniform Fast Fourier Transform Operator
+Transforms data between uniform spatial domain and non-uniform k-space domain.
+
+- **Flexible sampling patterns**: Supports arbitrary non-uniform sampling trajectories
+- **Density compensation**: Built-in support for density compensation functions (DCF)
+- **Efficient computation**: Uses the NFFT algorithm for fast transforms
+- **Multi-dimensional support**: Works with 1D, 2D, and 3D data
+- **Threaded operations**: Optional multi-threaded computation for large datasets
+
+```julia
+using NFFTOperators, NFFT
+
+# Create a 2D radial k-space trajectory (normalized to [-0.5, 0.5))
+image_size = (128, 128)
+n_angles = 50
+n_points = 100
+trajectory = zeros(2, n_points, n_angles)
+for i in 1:n_angles
+    angle = (i-1) * π / n_angles
+    trajectory[1, :, i] = cos(angle) .* range(-0.5, 0.5, length=n_points)
+    trajectory[2, :, i] = sin(angle) .* range(-0.5, 0.5, length=n_points)
+end
+
+# Create operator with automatic DCF estimation
+nfft_op = NFFTOp(image_size, trajectory)
+
+# Single-threaded for use in parallel regions
+nfft_op_st = NFFTOp(image_size, trajectory, threaded=false)
+```
+
+### 2. **NormalNFFTOp** - Normal Equations Operator
+Provides efficient implementation of the normal equations (A'A) for NFFT operators.
+
+- **Optimized computation**: Faster than applying NFFT' * NFFT sequentially
+- **Regularization support**: Easily add regularization terms
+- **Iterative algorithms**: Natural fit for iterative reconstruction algorithms
+- **Memory efficient**: Reduces memory footprint for large problems
+
+```julia
+using NFFTOperators, NFFT
+
+# Standard NFFT
+image_size = (128, 128)
+trajectory = rand(2, 100, 50) .- 0.5  # Normalized trajectory: 2D, 100 points, 50 readouts
+nfft_op = NFFTOp(image_size, trajectory)
+
+# Normal operator (implicit A'A)
+normal_op = nfft_op' * nfft_op
+```
+
+## License
+
+See LICENSE.md for details.