Refactor metrics imports: Organize signal and image metrics into respective submodules for clarity and maintainability

Enhance API documentation: Add utility functions for constraints and modulation schemes
Update loss modules: Include __all__ definitions for better module exports

Author: selimfirat

docs/api_reference.rst

@@ -20,7 +20,7 @@ several key modules that handle different aspects of communication systems:
 - **Channels**: Model transmission mediums with various noise and distortion characteristics
 - **Constraints**: Enforce practical limitations on transmitted signals
 - **Metrics**: Evaluate quality and performance of communication systems
-- **Models**: Implement neural network architectures for encoding/decoding, forward error correction and end-to-end communication systems
+- **Models**: Implement neural network architectures for encoding/decoding and end-to-end communication systems
 - **Modulations**: Implement digital modulation schemes for wireless transmission
 - **Losses**: Provide objective functions for training neural networks
 - **Utilities**: Helper functions and tools for common operations
@@ -105,6 +105,26 @@ Constraints module for Kaira.
    TotalPowerConstraint
 
 
+Utils
+^^^^^
+
+Utility functions for constraints.
+
+.. currentmodule:: kaira.constraints.utils
+
+.. autosummary::
+   :toctree: generated
+   :template: function.rst
+   :nosignatures:
+
+   apply_constraint_chain
+   combine_constraints
+   create_mimo_constraints
+   create_ofdm_constraints
+   measure_signal_properties
+   verify_constraint
+
+
 Metrics
 -------
 
@@ -117,26 +137,9 @@ Metrics module for Kaira.
    :template: class.rst
    :nosignatures:
 
-   BER
-   BLER
    BaseMetric
-   BitErrorRate
-   BlockErrorRate
    CompositeMetric
-   FER
-   FrameErrorRate
-   LPIPS
-   LearnedPerceptualImagePatchSimilarity
    MetricRegistry
-   MultiScaleSSIM
-   PSNR
-   PeakSignalNoiseRatio
-   SER
-   SNR
-   SSIM
-   SignalToNoiseRatio
-   StructuralSimilarityIndexMeasure
-   SymbolErrorRate
 
 
 Image
@@ -266,23 +269,6 @@ Components module for Kaira models.
    MLPEncoder
 
 
-FEC Algebra
-^^^^^^^^^^^
-
-Finite field algebra utilities for forward error correction.
-
-.. currentmodule:: kaira.models.fec.algebra
-
-.. autosummary::
-   :toctree: generated
-   :template: class.rst
-   :nosignatures:
-
-   BinaryPolynomial
-   FiniteBifield
-   FiniteBifieldElement
-
-
 Decoders
 ^^^^^^^^
 
@@ -328,25 +314,6 @@ Forward Error Correction encoders for Kaira.
    SystematicLinearBlockCodeEncoder
 
 
-FEC Utilities
-^^^^^^^^^^^^^
-
-Utility functions for decoders.
-
-.. currentmodule:: kaira.models.fec.utils
-
-.. autosummary::
-   :toctree: generated
-   :template: function.rst
-   :nosignatures:
-
-   apply_blockwise
-   from_binary_tensor
-   hamming_distance
-   hamming_weight
-   to_binary_tensor
-
-
 Generic
 ^^^^^^^
 
@@ -470,6 +437,27 @@ Digital modulation schemes for wireless communications.
    plot_constellation
 
 
+Utils
+^^^^^
+
+Utility functions for digital modulation schemes.
+
+.. currentmodule:: kaira.modulations.utils
+
+.. autosummary::
+   :toctree: generated
+   :template: function.rst
+   :nosignatures:
+
+   binary_array_to_gray
+   binary_to_gray
+   calculate_spectral_efficiency
+   calculate_theoretical_ber
+   gray_array_to_binary
+   gray_to_binary
+   plot_constellation
+
+
 Data
 ----
 
@@ -484,8 +472,6 @@ Data utilities for Kaira, including data generation and correlation models.
 
    BinaryTensorDataset
    UniformTensorDataset
-   WynerZivCorrelationDataset
-   WynerZivCorrelationModel
 
 
 .. currentmodule:: kaira.data
@@ -498,24 +484,3 @@ Data utilities for Kaira, including data generation and correlation models.
    create_binary_tensor
    create_uniform_tensor
    load_sample_images
-
-
-SNR Utilities
-^^^^^^^^^^^^^
-
-Utility functions for Signal-to-Noise Ratio (SNR) calculations and conversions.
-
-.. currentmodule:: kaira.utils.snr
-
-.. autosummary::
-   :toctree: generated
-   :template: function.rst
-   :nosignatures:
-
-   add_noise_for_snr
-   calculate_snr
-   estimate_signal_power
-   noise_power_to_snr
-   snr_db_to_linear
-   snr_linear_to_db
-   snr_to_noise_power

docs/conf.py

@@ -380,24 +380,3 @@ def setup(app):
     """
     app.connect("autodoc-skip-member", skip_member)
     app.add_config_value("current_date", get_current_date(), "env")
-
-
-# Mock imports for modules that might not be installed
-# This prevents build failures due to missing dependencies
-autodoc_mock_imports = [
-    # Core dependencies that might not be available during doc building
-    "torch",
-    "numpy",
-    "matplotlib",
-    "scipy",
-    "torchmetrics",
-    # Kaira modules that might have import issues
-    "kaira.losses",
-    "kaira.models",
-    "kaira.channels",
-    "kaira.metrics",
-    "kaira.modulations",
-    "kaira.constraints",
-    "kaira.data",
-    "kaira.utils",
-]

examples/channels/plot_awgn_channel.py

@@ -20,7 +20,8 @@
 import torch
 
 from kaira.channels import AWGNChannel
-from kaira.metrics import PSNR, SNR
+from kaira.metrics.image import PSNR
+from kaira.metrics.signal import SNR
 from kaira.utils import snr_to_noise_power
 
 # Set random seed for reproducibility
@@ -91,6 +92,7 @@
     outputs.append((snr_db, output_signal.numpy().flatten()))
     measured_metrics.append({"target_snr_db": snr_db, "measured_snr_db": measured_snr, "measured_psnr_db": measured_psnr})
 
+    # Ensure we're using float values for string formatting
     print(f"Target SNR: {snr_db:.1f} dB, Measured SNR: {measured_snr:.1f} dB, PSNR: {measured_psnr:.1f} dB")
 
 # %%

examples/channels/plot_fading_channels.py

@@ -22,7 +22,7 @@
 from scipy import signal  # Added here to fix E402 error
 
 from kaira.channels import AWGNChannel, FlatFadingChannel, PerfectChannel
-from kaira.metrics import BitErrorRate
+from kaira.metrics.signal import BitErrorRate
 from kaira.modulations import QPSKModulator
 from kaira.modulations.utils import calculate_theoretical_ber
 from kaira.utils import snr_to_noise_power

examples/channels/plot_nonlinear_channel.py

@@ -19,7 +19,7 @@
 from scipy import signal
 
 from kaira.channels import AWGNChannel, NonlinearChannel, PerfectChannel
-from kaira.metrics import SymbolErrorRate
+from kaira.metrics.signal import SymbolErrorRate
 from kaira.modulations import QAMModulator
 
 # Set random seed for reproducibility

examples/channels/plot_poisson_channel.py

@@ -20,7 +20,7 @@
 from scipy.special import erfc
 
 from kaira.channels import AWGNChannel, PoissonChannel
-from kaira.metrics import BitErrorRate
+from kaira.metrics.signal import BitErrorRate
 
 # Set random seed for reproducibility
 torch.manual_seed(42)

examples/channels/plot_rician_fading.py

@@ -20,7 +20,7 @@
 import torch
 
 from kaira.channels import RayleighFadingChannel, RicianFadingChannel
-from kaira.metrics import BitErrorRate, SymbolErrorRate
+from kaira.metrics.signal import BitErrorRate, SymbolErrorRate
 from kaira.modulations import QPSKDemodulator, QPSKModulator
 
 # Set random seed for reproducibility

examples/metrics/plot_composite_metrics.py

@@ -17,7 +17,9 @@
 import numpy as np
 import torch
 
-from kaira.metrics import BER, PSNR, SNR, SSIM, BaseMetric
+from kaira.metrics import BaseMetric
+from kaira.metrics.image import PSNR, SSIM
+from kaira.metrics.signal import BER, SNR
 
 # Set random seed for reproducibility
 torch.manual_seed(42)

examples/metrics/plot_custom_metrics.py

@@ -17,7 +17,8 @@
 import numpy as np
 import torch
 
-from kaira.metrics import BER, BaseMetric
+from kaira.metrics import BaseMetric
+from kaira.metrics.signal import BER
 from kaira.utils import snr_to_noise_power
 
 # Set random seed for reproducibility

examples/metrics/plot_metrics_registry.py

@@ -15,8 +15,9 @@
 import numpy as np
 import torch
 
-from kaira.metrics import BER, SNR, BaseMetric
+from kaira.metrics import BaseMetric
 from kaira.metrics.registry import MetricRegistry
+from kaira.metrics.signal import BER, SNR  # Import from the signal submodule instead
 
 # Set random seed for reproducibility
 torch.manual_seed(42)