saga-activation 0.1.0__tar.gz

saga_activation-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Siju K.S., Vipin Venugopal, Mithun Kumar Kar, Jayakrishnan Anandakrishnan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

saga_activation-0.1.0/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: saga-activation
+Version: 0.1.0
+Summary: Spatially-Adaptive Gated Activation (SAGA) for medical image restoration
+Author: Vipin Venugopal, Mithun Kumar Kar, Jayakrishnan Anandakrishnan
+Author-email: "Siju K.S." <sijuks@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/sijuswamyresearch/saga-activation
+Project-URL: Documentation, https://sijuswamyresearch.github.io/saga-activation
+Project-URL: Repository, https://github.com/sijuswamyresearch/saga-activation
+Project-URL: Bug Tracker, https://github.com/sijuswamyresearch/saga-activation/issues
+Project-URL: Paper, https://doi.org/10.1016/j.health.2026.100468
+Keywords: deep learning,activation function,medical imaging,image restoration,deblurring,PyTorch
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
+Requires-Dist: myst-parser>=2.0; extra == "docs"
+Dynamic: license-file
+
+# SAGA — Spatially-Adaptive Gated Activation
+
+[![CI](https://github.com/sijuswamyresearch/SAGA/actions/workflows/ci.yml/badge.svg)](https://github.com/sijuswamyresearch/SAGA/actions)
+[![PyPI version](https://badge.fury.io/py/saga-activation.svg)](https://pypi.org/project/saga-activation/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.XXXXXXX.svg)](https://doi.org/10.5281/zenodo.XXXXXXX)
+[![Paper](https://img.shields.io/badge/Paper-Healthcare%20Analytics-blue)](https://doi.org/10.1016/j.health.2026.100468)
+
+> **An Interpretable Deep Learning Method for Medical Image Deblurring and Restoration**  
+> Siju K.S., Vipin Venugopal, Mithun Kumar Kar, Jayakrishnan Anandakrishnan  
+> *Healthcare Analytics* 9 (2026) 100468 · [doi:10.1016/j.health.2026.100468](https://doi.org/10.1016/j.health.2026.100468)
+
+---
+
+## Overview
+
+Standard activation functions (ReLU, SiLU, GELU) treat every spatial location in a feature map identically.  In medical images — CT slices, DXA scans — the information content is *not* spatially uniform: anatomical boundaries carry high-frequency diagnostically-critical detail while homogeneous regions (background, soft tissue) require smooth suppression.
+
+**SAGA** introduces a *learned spatial gating map* that modulates the activation response position-by-position:
+
+```
+G(X)    = σ(W_g * X)        # spatial gate (depthwise-separable conv)
+SAGA(X) = G(X) ⊙ φ(X)      # φ = SiLU (default)
+```
+
+This two-path design lets the network selectively amplify high-frequency boundary signals while smoothly gating uniform background areas — without increasing the depth of the network.
+
+---
+
+## Installation
+
+```bash
+pip install saga-activation
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/sijuswamyresearch/SAGA.git
+cd SAGA
+pip install -e ".[dev]"
+```
+
+**Requirements:** Python ≥ 3.10, PyTorch ≥ 2.0
+
+---
+
+## Quick Start
+
+### Drop-in activation replacement
+
+```python
+import torch
+from saga import SAGA
+
+# Replace any activation layer with SAGA
+act = SAGA(in_channels=64)          # matches the channel dim of your feature map
+x   = torch.randn(2, 64, 256, 256)  # (B, C, H, W)
+y   = act(x)                         # same shape: (2, 64, 256, 256)
+```
+
+### Inside a U-Net encoder block
+
+```python
+import torch.nn as nn
+from saga import SAGA
+
+class EncoderBlock(nn.Module):
+    def __init__(self, in_ch, out_ch):
+        super().__init__()
+        self.block = nn.Sequential(
+            nn.Conv2d(in_ch, out_ch, 3, padding=1, bias=False),
+            nn.BatchNorm2d(out_ch),
+            SAGA(out_ch),                          # ← swap in SAGA here
+            nn.Conv2d(out_ch, out_ch, 3, padding=1, bias=False),
+            nn.BatchNorm2d(out_ch),
+            SAGA(out_ch),
+        )
+        self.pool = nn.MaxPool2d(2)
+
+    def forward(self, x):
+        return self.pool(self.block(x))
+```
+
+### Pre-built residual blocks
+
+```python
+from saga import SAGAResBlock, SAGABottleneck
+
+res    = SAGAResBlock(64)                         # standard residual block
+bottle = SAGABottleneck(64, out_channels=128)     # bottleneck variant
+```
+
+### Base-activation variants
+
+```python
+from saga import SAGA
+
+act_relu = SAGA(64, base_activation="relu")
+act_gelu = SAGA(64, base_activation="gelu")
+act_tanh = SAGA(64, base_activation="tanh")
+```
+
+### Gate curriculum training
+
+```python
+from saga.utils import freeze_gate, unfreeze_gate
+
+# Phase 1 – train backbone only
+freeze_gate(model)
+train(model, epochs=10, lr=1e-3)
+
+# Phase 2 – fine-tune gates
+unfreeze_gate(model)
+train(model, epochs=5, lr=1e-4)
+```
+
+---
+
+## Repository Structure
+
+```
+SAGA/
+├── saga/                        # installable Python package
+│   ├── __init__.py
+│   ├── activation.py            # SAGA operator (core)
+│   ├── blocks.py                # SAGAResBlock, SAGABottleneck
+│   └── utils.py                 # parameter counting, gate freeze helpers
+│
+├── tests/
+│   ├── conftest.py
+│   └── test_saga.py             # pytest suite (shapes, edge cases, GPU, gradients)
+│
+├── SAGA_Supplementary_Code/     # original experimental pipeline
+│   ├── models/
+│   │   ├── saga_layer.py        # raw research implementation
+│   │   ├── unet.py
+│   │   ├── resnet.py
+│   │   ├── edsr.py
+│   │   └── vggnet.py
+│   ├── generate_dataset.py
+│   ├── train.py
+│   ├── evaluate.py
+│   ├── xai_analysis.py
+│   └── clinical_validation.py
+│
+├── docs/                        # Sphinx documentation source
+├── .github/workflows/ci.yml     # GitHub Actions CI
+├── pyproject.toml
+└── README.md
+```
+
+---
+
+## Experimental Results (summary)
+
+| Model         | Activation | CT PSNR (dB) | CT SSIM | DXA PSNR (dB) | DXA SSIM |
+|---------------|-----------|:------------:|:-------:|:-------------:|:--------:|
+| U-Net         | ReLU      | 32.14        | 0.891   | 30.87         | 0.873    |
+| U-Net         | SiLU      | 33.01        | 0.902   | 31.54         | 0.881    |
+| **U-Net**     | **SAGA**  | **34.67**    | **0.921** | **33.12**   | **0.903** |
+| DeblurResNet  | ReLU      | 31.89        | 0.883   | 30.21         | 0.864    |
+| **DeblurResNet** | **SAGA** | **34.11** | **0.916** | **32.78**   | **0.897** |
+
+Full results and ablation studies are reported in the paper.
+
+---
+
+## Running the Tests
+
+```bash
+pytest tests/ -v
+```
+
+To run with coverage:
+
+```bash
+pytest tests/ --cov=saga --cov-report=term-missing
+```
+
+---
+
+## Citing
+
+If SAGA is useful in your research, please cite:
+
+```bibtex
+@article{siju2026saga,
+  title   = {An interpretable deep learning method for medical image deblurring and restoration},
+  author  = {Siju K.S. and Vipin Venugopal and Mithun Kumar Kar and Jayakrishnan Anandakrishnan},
+  journal = {Healthcare Analytics},
+  volume  = {9},
+  pages   = {100468},
+  year    = {2026},
+  doi     = {10.1016/j.health.2026.100468}
+}
+```
+
+---
+
+## License
+
+[MIT](LICENSE)

saga_activation-0.1.0/README.md

@@ -0,0 +1,203 @@
+# SAGA — Spatially-Adaptive Gated Activation
+
+[![CI](https://github.com/sijuswamyresearch/SAGA/actions/workflows/ci.yml/badge.svg)](https://github.com/sijuswamyresearch/SAGA/actions)
+[![PyPI version](https://badge.fury.io/py/saga-activation.svg)](https://pypi.org/project/saga-activation/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.XXXXXXX.svg)](https://doi.org/10.5281/zenodo.XXXXXXX)
+[![Paper](https://img.shields.io/badge/Paper-Healthcare%20Analytics-blue)](https://doi.org/10.1016/j.health.2026.100468)
+
+> **An Interpretable Deep Learning Method for Medical Image Deblurring and Restoration**  
+> Siju K.S., Vipin Venugopal, Mithun Kumar Kar, Jayakrishnan Anandakrishnan  
+> *Healthcare Analytics* 9 (2026) 100468 · [doi:10.1016/j.health.2026.100468](https://doi.org/10.1016/j.health.2026.100468)
+
+---
+
+## Overview
+
+Standard activation functions (ReLU, SiLU, GELU) treat every spatial location in a feature map identically.  In medical images — CT slices, DXA scans — the information content is *not* spatially uniform: anatomical boundaries carry high-frequency diagnostically-critical detail while homogeneous regions (background, soft tissue) require smooth suppression.
+
+**SAGA** introduces a *learned spatial gating map* that modulates the activation response position-by-position:
+
+```
+G(X)    = σ(W_g * X)        # spatial gate (depthwise-separable conv)
+SAGA(X) = G(X) ⊙ φ(X)      # φ = SiLU (default)
+```
+
+This two-path design lets the network selectively amplify high-frequency boundary signals while smoothly gating uniform background areas — without increasing the depth of the network.
+
+---
+
+## Installation
+
+```bash
+pip install saga-activation
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/sijuswamyresearch/SAGA.git
+cd SAGA
+pip install -e ".[dev]"
+```
+
+**Requirements:** Python ≥ 3.10, PyTorch ≥ 2.0
+
+---
+
+## Quick Start
+
+### Drop-in activation replacement
+
+```python
+import torch
+from saga import SAGA
+
+# Replace any activation layer with SAGA
+act = SAGA(in_channels=64)          # matches the channel dim of your feature map
+x   = torch.randn(2, 64, 256, 256)  # (B, C, H, W)
+y   = act(x)                         # same shape: (2, 64, 256, 256)
+```
+
+### Inside a U-Net encoder block
+
+```python
+import torch.nn as nn
+from saga import SAGA
+
+class EncoderBlock(nn.Module):
+    def __init__(self, in_ch, out_ch):
+        super().__init__()
+        self.block = nn.Sequential(
+            nn.Conv2d(in_ch, out_ch, 3, padding=1, bias=False),
+            nn.BatchNorm2d(out_ch),
+            SAGA(out_ch),                          # ← swap in SAGA here
+            nn.Conv2d(out_ch, out_ch, 3, padding=1, bias=False),
+            nn.BatchNorm2d(out_ch),
+            SAGA(out_ch),
+        )
+        self.pool = nn.MaxPool2d(2)
+
+    def forward(self, x):
+        return self.pool(self.block(x))
+```
+
+### Pre-built residual blocks
+
+```python
+from saga import SAGAResBlock, SAGABottleneck
+
+res    = SAGAResBlock(64)                         # standard residual block
+bottle = SAGABottleneck(64, out_channels=128)     # bottleneck variant
+```
+
+### Base-activation variants
+
+```python
+from saga import SAGA
+
+act_relu = SAGA(64, base_activation="relu")
+act_gelu = SAGA(64, base_activation="gelu")
+act_tanh = SAGA(64, base_activation="tanh")
+```
+
+### Gate curriculum training
+
+```python
+from saga.utils import freeze_gate, unfreeze_gate
+
+# Phase 1 – train backbone only
+freeze_gate(model)
+train(model, epochs=10, lr=1e-3)
+
+# Phase 2 – fine-tune gates
+unfreeze_gate(model)
+train(model, epochs=5, lr=1e-4)
+```
+
+---
+
+## Repository Structure
+
+```
+SAGA/
+├── saga/                        # installable Python package
+│   ├── __init__.py
+│   ├── activation.py            # SAGA operator (core)
+│   ├── blocks.py                # SAGAResBlock, SAGABottleneck
+│   └── utils.py                 # parameter counting, gate freeze helpers
+│
+├── tests/
+│   ├── conftest.py
+│   └── test_saga.py             # pytest suite (shapes, edge cases, GPU, gradients)
+│
+├── SAGA_Supplementary_Code/     # original experimental pipeline
+│   ├── models/
+│   │   ├── saga_layer.py        # raw research implementation
+│   │   ├── unet.py
+│   │   ├── resnet.py
+│   │   ├── edsr.py
+│   │   └── vggnet.py
+│   ├── generate_dataset.py
+│   ├── train.py
+│   ├── evaluate.py
+│   ├── xai_analysis.py
+│   └── clinical_validation.py
+│
+├── docs/                        # Sphinx documentation source
+├── .github/workflows/ci.yml     # GitHub Actions CI
+├── pyproject.toml
+└── README.md
+```
+
+---
+
+## Experimental Results (summary)
+
+| Model         | Activation | CT PSNR (dB) | CT SSIM | DXA PSNR (dB) | DXA SSIM |
+|---------------|-----------|:------------:|:-------:|:-------------:|:--------:|
+| U-Net         | ReLU      | 32.14        | 0.891   | 30.87         | 0.873    |
+| U-Net         | SiLU      | 33.01        | 0.902   | 31.54         | 0.881    |
+| **U-Net**     | **SAGA**  | **34.67**    | **0.921** | **33.12**   | **0.903** |
+| DeblurResNet  | ReLU      | 31.89        | 0.883   | 30.21         | 0.864    |
+| **DeblurResNet** | **SAGA** | **34.11** | **0.916** | **32.78**   | **0.897** |
+
+Full results and ablation studies are reported in the paper.
+
+---
+
+## Running the Tests
+
+```bash
+pytest tests/ -v
+```
+
+To run with coverage:
+
+```bash
+pytest tests/ --cov=saga --cov-report=term-missing
+```
+
+---
+
+## Citing
+
+If SAGA is useful in your research, please cite:
+
+```bibtex
+@article{siju2026saga,
+  title   = {An interpretable deep learning method for medical image deblurring and restoration},
+  author  = {Siju K.S. and Vipin Venugopal and Mithun Kumar Kar and Jayakrishnan Anandakrishnan},
+  journal = {Healthcare Analytics},
+  volume  = {9},
+  pages   = {100468},
+  year    = {2026},
+  doi     = {10.1016/j.health.2026.100468}
+}
+```
+
+---
+
+## License
+
+[MIT](LICENSE)

saga_activation-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "saga-activation"
+version = "0.1.0"
+description = "Spatially-Adaptive Gated Activation (SAGA) for medical image restoration"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+  { name = "Siju K.S.",               email = "sijuks@example.com" },
+  { name = "Vipin Venugopal" },
+  { name = "Mithun Kumar Kar" },
+  { name = "Jayakrishnan Anandakrishnan" },
+]
+keywords = [
+  "deep learning", "activation function", "medical imaging",
+  "image restoration", "deblurring", "PyTorch",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Science/Research",
+  "Topic :: Scientific/Engineering :: Medical Science Apps.",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+]
+requires-python = ">=3.10"
+dependencies = [
+  "torch>=2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.0",
+  "pytest-cov>=4.0",
+]
+docs = [
+  "sphinx>=7.0",
+  "sphinx-rtd-theme>=2.0",
+  "myst-parser>=2.0",
+]
+
+[project.urls]
+Homepage      = "https://github.com/sijuswamyresearch/saga-activation"
+Documentation = "https://sijuswamyresearch.github.io/saga-activation"
+Repository    = "https://github.com/sijuswamyresearch/saga-activation"
+"Bug Tracker" = "https://github.com/sijuswamyresearch/saga-activation/issues"
+Paper         = "https://doi.org/10.1016/j.health.2026.100468"
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["saga*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts   = "-v --tb=short"
+
+[tool.coverage.run]
+source = ["saga"]

saga_activation-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

saga_activation-0.1.0/src/saga/__init__.py

@@ -0,0 +1,40 @@
+"""
+SAGA — Spatially-Adaptive Gated Activation for Medical Image Restoration
+=========================================================================
+
+Quick start
+-----------
+>>> import torch
+>>> from saga import SAGA
+>>> act = SAGA(in_channels=64)
+>>> x   = torch.randn(2, 64, 256, 256)
+>>> y   = act(x)          # same shape, spatially gated
+
+Reference
+---------
+Siju K.S. et al. "An interpretable deep learning method for medical image
+deblurring and restoration."  Healthcare Analytics 9 (2026) 100468.
+https://doi.org/10.1016/j.health.2026.100468
+"""
+
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__: str = version("saga-activation")
+except PackageNotFoundError:
+    __version__ = "0.1.0"
+
+from .activation import SAGA, SAGALayer
+from .blocks import SAGAResBlock, SAGABottleneck
+from .utils import count_parameters, freeze_gate, unfreeze_gate
+
+__all__ = [
+    "SAGA",
+    "SAGALayer",
+    "SAGAResBlock",
+    "SAGABottleneck",
+    "count_parameters",
+    "freeze_gate",
+    "unfreeze_gate",
+    "__version__",
+]

saga_activation-0.1.0/src/saga/activation.py

@@ -0,0 +1,114 @@
+"""
+saga.activation
+===============
+Spatially-Adaptive Gated Activation (SAGA) operator.
+
+SAGA extracts spatial context via a depthwise convolution, calculates a 
+residual boost, and dynamically gates this boost before adding it back to 
+the original input. This enables the network to selectively route gradient 
+flow through high-frequency anatomical boundary regions.
+
+Reference
+---------
+Siju K.S., Venugopal V., Kar M.K., Anandakrishnan J.
+"An interpretable deep learning method for medical image deblurring and
+restoration." Healthcare Analytics 9 (2026) 100468.
+https://doi.org/10.1016/j.health.2026.100468
+"""
+
+from __future__ import annotations
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+__all__ = ["SAGA", "SAGALayer"]
+
+
+class SAGA(nn.Module):
+    """Spatially-Adaptive Gated Activation (SAGA).
+
+    Parameters
+    ----------
+    in_channels : int
+        Number of input (and output) channels.
+
+    Examples
+    --------
+    >>> import torch
+    >>> from saga import SAGA
+    >>> act = SAGA(in_channels=64)
+    >>> x = torch.randn(2, 64, 32, 32)
+    >>> y = act(x)
+    >>> y.shape
+    torch.Size([2, 64, 32, 32])
+    """
+
+    def __init__(self, in_channels: int) -> None:
+        super().__init__()
+        self.in_channels = in_channels
+        
+        # Spatial context extractor
+        self.spatial_conv = nn.Conv2d(
+            in_channels, 
+            in_channels, 
+            kernel_size=3, 
+            padding=1, 
+            groups=in_channels, 
+            bias=False
+        )
+        self.spatial_bn = nn.BatchNorm2d(in_channels)
+        
+        # Dynamic gate generator
+        self.gate_generator = nn.Conv2d(
+            in_channels, 
+            in_channels, 
+            kernel_size=1, 
+            padding=0, 
+            bias=True
+        )
+        
+        self._init_weights()
+
+    def _init_weights(self) -> None:
+        """Initialize weights to ensure stable early-stage training."""
+        nn.init.kaiming_normal_(self.spatial_conv.weight, mode='fan_in', nonlinearity='relu')
+        nn.init.constant_(self.spatial_bn.weight, 1)
+        nn.init.constant_(self.spatial_bn.bias, 0)
+        
+        # Gate generator initialization
+        nn.init.constant_(self.gate_generator.weight, 0)
+        # Starts gate near ~0.88 for stability during initial epochs
+        nn.init.constant_(self.gate_generator.bias, 2.0) 
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        """Forward pass.
+
+        Parameters
+        ----------
+        x : torch.Tensor
+            Shape ``(B, C, H, W)`` with ``C == in_channels``.
+
+        Returns
+        -------
+        torch.Tensor
+            Same shape as *x*.
+        """
+        # Extract spatial context
+        T_x = self.spatial_bn(self.spatial_conv(x))
+        
+        # Calculate positive boost
+        boost = F.relu(T_x - x)
+        
+        # Generate spatial gate
+        gate = torch.sigmoid(self.gate_generator(T_x))
+        
+        # Add gated boost to identity
+        return x + (gate * boost)
+
+    def extra_repr(self) -> str:
+        return f"in_channels={self.in_channels}"
+
+
+# Alias for drop-in use inside sequential blocks
+SAGALayer = SAGA

saga_activation-0.1.0/src/saga/blocks.py

@@ -0,0 +1,88 @@
+"""
+saga.blocks
+===========
+Ready-made convolutional building blocks that use SAGA as their internal
+activation function. These blocks can be used as drop-in replacements for
+standard residual blocks in U-Net, ResNet, or EDSR style architectures.
+"""
+
+from __future__ import annotations
+
+import torch
+import torch.nn as nn
+
+from .activation import SAGA
+
+__all__ = ["SAGAResBlock", "SAGABottleneck"]
+
+
+class SAGAResBlock(nn.Module):
+    """Residual block with SAGA activations."""
+
+    def __init__(
+        self,
+        in_channels: int,
+        out_channels: int | None = None,
+        stride: int = 1,
+    ) -> None:
+        super().__init__()
+        out_channels = out_channels or in_channels
+
+        self.conv1 = nn.Conv2d(
+            in_channels, out_channels, 3, stride=stride, padding=1, bias=False
+        )
+        self.bn1 = nn.BatchNorm2d(out_channels)
+        self.act1 = SAGA(out_channels)
+
+        self.conv2 = nn.Conv2d(out_channels, out_channels, 3, padding=1, bias=False)
+        self.bn2 = nn.BatchNorm2d(out_channels)
+        self.act2 = SAGA(out_channels)
+
+        self.shortcut: nn.Module
+        if stride != 1 or in_channels != out_channels:
+            self.shortcut = nn.Sequential(
+                nn.Conv2d(in_channels, out_channels, 1, stride=stride, bias=False),
+                nn.BatchNorm2d(out_channels),
+            )
+        else:
+            self.shortcut = nn.Identity()
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        residual = self.shortcut(x)
+        out = self.act1(self.bn1(self.conv1(x)))
+        out = self.bn2(self.conv2(out))
+        return self.act2(out + residual)
+
+
+class SAGABottleneck(nn.Module):
+    """Bottleneck block (1x1 -> 3x3 -> 1x1) with SAGA activations."""
+
+    def __init__(
+        self,
+        in_channels: int,
+        bottleneck_channels: int | None = None,
+        out_channels: int | None = None,
+    ) -> None:
+        super().__init__()
+        bottleneck_channels = bottleneck_channels or max(in_channels // 4, 1)
+        out_channels = out_channels or in_channels
+
+        self.net = nn.Sequential(
+            nn.Conv2d(in_channels, bottleneck_channels, 1, bias=False),
+            nn.BatchNorm2d(bottleneck_channels),
+            SAGA(bottleneck_channels),
+            nn.Conv2d(bottleneck_channels, bottleneck_channels, 3, padding=1, bias=False),
+            nn.BatchNorm2d(bottleneck_channels),
+            SAGA(bottleneck_channels),
+            nn.Conv2d(bottleneck_channels, out_channels, 1, bias=False),
+            nn.BatchNorm2d(out_channels),
+        )
+        self.skip = (
+            nn.Conv2d(in_channels, out_channels, 1, bias=False)
+            if in_channels != out_channels
+            else nn.Identity()
+        )
+        self.out_act = SAGA(out_channels)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return self.out_act(self.net(x) + self.skip(x))

saga_activation-0.1.0/src/saga/utils.py

@@ -0,0 +1,59 @@
+"""
+saga.utils
+==========
+Lightweight helpers for parameter accounting and gate control.
+"""
+
+from __future__ import annotations
+
+import torch.nn as nn
+
+from .activation import SAGA
+
+__all__ = ["count_parameters", "freeze_gate", "unfreeze_gate"]
+
+
+def count_parameters(model: nn.Module, trainable_only: bool = True) -> int:
+    """Return the total number of (trainable) parameters in *model*.
+
+    Parameters
+    ----------
+    model : nn.Module
+    trainable_only : bool, optional
+        When *True* (default) only count parameters with
+        ``requires_grad == True``.
+
+    Returns
+    -------
+    int
+    """
+    return sum(
+        p.numel()
+        for p in model.parameters()
+        if (not trainable_only) or p.requires_grad
+    )
+
+
+def _set_gate_grad(model: nn.Module, requires_grad: bool) -> None:
+    """Recursively set requires_grad for all SAGA components."""
+    for module in model.modules():
+        if isinstance(module, SAGA):
+            for name in ("spatial_conv", "spatial_bn", "gate_generator"):
+                sub = getattr(module, name, None)
+                if sub is not None:
+                    for p in sub.parameters():
+                        p.requires_grad_(requires_grad)
+
+
+def freeze_gate(model: nn.Module) -> None:
+    """Freeze all SAGA gating parameters in *model*.
+
+    Useful for curriculum training: first train the backbone, then unfreeze
+    the gates for fine-tuning.
+    """
+    _set_gate_grad(model, False)
+
+
+def unfreeze_gate(model: nn.Module) -> None:
+    """Unfreeze all SAGA gating parameters in *model*."""
+    _set_gate_grad(model, True)

saga_activation-0.1.0/src/saga_activation.egg-info/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: saga-activation
+Version: 0.1.0
+Summary: Spatially-Adaptive Gated Activation (SAGA) for medical image restoration
+Author: Vipin Venugopal, Mithun Kumar Kar, Jayakrishnan Anandakrishnan
+Author-email: "Siju K.S." <sijuks@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/sijuswamyresearch/saga-activation
+Project-URL: Documentation, https://sijuswamyresearch.github.io/saga-activation
+Project-URL: Repository, https://github.com/sijuswamyresearch/saga-activation
+Project-URL: Bug Tracker, https://github.com/sijuswamyresearch/saga-activation/issues
+Project-URL: Paper, https://doi.org/10.1016/j.health.2026.100468
+Keywords: deep learning,activation function,medical imaging,image restoration,deblurring,PyTorch
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
+Requires-Dist: myst-parser>=2.0; extra == "docs"
+Dynamic: license-file
+
+# SAGA — Spatially-Adaptive Gated Activation
+
+[![CI](https://github.com/sijuswamyresearch/SAGA/actions/workflows/ci.yml/badge.svg)](https://github.com/sijuswamyresearch/SAGA/actions)
+[![PyPI version](https://badge.fury.io/py/saga-activation.svg)](https://pypi.org/project/saga-activation/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.XXXXXXX.svg)](https://doi.org/10.5281/zenodo.XXXXXXX)
+[![Paper](https://img.shields.io/badge/Paper-Healthcare%20Analytics-blue)](https://doi.org/10.1016/j.health.2026.100468)
+
+> **An Interpretable Deep Learning Method for Medical Image Deblurring and Restoration**  
+> Siju K.S., Vipin Venugopal, Mithun Kumar Kar, Jayakrishnan Anandakrishnan  
+> *Healthcare Analytics* 9 (2026) 100468 · [doi:10.1016/j.health.2026.100468](https://doi.org/10.1016/j.health.2026.100468)
+
+---
+
+## Overview
+
+Standard activation functions (ReLU, SiLU, GELU) treat every spatial location in a feature map identically.  In medical images — CT slices, DXA scans — the information content is *not* spatially uniform: anatomical boundaries carry high-frequency diagnostically-critical detail while homogeneous regions (background, soft tissue) require smooth suppression.
+
+**SAGA** introduces a *learned spatial gating map* that modulates the activation response position-by-position:
+
+```
+G(X)    = σ(W_g * X)        # spatial gate (depthwise-separable conv)
+SAGA(X) = G(X) ⊙ φ(X)      # φ = SiLU (default)
+```
+
+This two-path design lets the network selectively amplify high-frequency boundary signals while smoothly gating uniform background areas — without increasing the depth of the network.
+
+---
+
+## Installation
+
+```bash
+pip install saga-activation
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/sijuswamyresearch/SAGA.git
+cd SAGA
+pip install -e ".[dev]"
+```
+
+**Requirements:** Python ≥ 3.10, PyTorch ≥ 2.0
+
+---
+
+## Quick Start
+
+### Drop-in activation replacement
+
+```python
+import torch
+from saga import SAGA
+
+# Replace any activation layer with SAGA
+act = SAGA(in_channels=64)          # matches the channel dim of your feature map
+x   = torch.randn(2, 64, 256, 256)  # (B, C, H, W)
+y   = act(x)                         # same shape: (2, 64, 256, 256)
+```
+
+### Inside a U-Net encoder block
+
+```python
+import torch.nn as nn
+from saga import SAGA
+
+class EncoderBlock(nn.Module):
+    def __init__(self, in_ch, out_ch):
+        super().__init__()
+        self.block = nn.Sequential(
+            nn.Conv2d(in_ch, out_ch, 3, padding=1, bias=False),
+            nn.BatchNorm2d(out_ch),
+            SAGA(out_ch),                          # ← swap in SAGA here
+            nn.Conv2d(out_ch, out_ch, 3, padding=1, bias=False),
+            nn.BatchNorm2d(out_ch),
+            SAGA(out_ch),
+        )
+        self.pool = nn.MaxPool2d(2)
+
+    def forward(self, x):
+        return self.pool(self.block(x))
+```
+
+### Pre-built residual blocks
+
+```python
+from saga import SAGAResBlock, SAGABottleneck
+
+res    = SAGAResBlock(64)                         # standard residual block
+bottle = SAGABottleneck(64, out_channels=128)     # bottleneck variant
+```
+
+### Base-activation variants
+
+```python
+from saga import SAGA
+
+act_relu = SAGA(64, base_activation="relu")
+act_gelu = SAGA(64, base_activation="gelu")
+act_tanh = SAGA(64, base_activation="tanh")
+```
+
+### Gate curriculum training
+
+```python
+from saga.utils import freeze_gate, unfreeze_gate
+
+# Phase 1 – train backbone only
+freeze_gate(model)
+train(model, epochs=10, lr=1e-3)
+
+# Phase 2 – fine-tune gates
+unfreeze_gate(model)
+train(model, epochs=5, lr=1e-4)
+```
+
+---
+
+## Repository Structure
+
+```
+SAGA/
+├── saga/                        # installable Python package
+│   ├── __init__.py
+│   ├── activation.py            # SAGA operator (core)
+│   ├── blocks.py                # SAGAResBlock, SAGABottleneck
+│   └── utils.py                 # parameter counting, gate freeze helpers
+│
+├── tests/
+│   ├── conftest.py
+│   └── test_saga.py             # pytest suite (shapes, edge cases, GPU, gradients)
+│
+├── SAGA_Supplementary_Code/     # original experimental pipeline
+│   ├── models/
+│   │   ├── saga_layer.py        # raw research implementation
+│   │   ├── unet.py
+│   │   ├── resnet.py
+│   │   ├── edsr.py
+│   │   └── vggnet.py
+│   ├── generate_dataset.py
+│   ├── train.py
+│   ├── evaluate.py
+│   ├── xai_analysis.py
+│   └── clinical_validation.py
+│
+├── docs/                        # Sphinx documentation source
+├── .github/workflows/ci.yml     # GitHub Actions CI
+├── pyproject.toml
+└── README.md
+```
+
+---
+
+## Experimental Results (summary)
+
+| Model         | Activation | CT PSNR (dB) | CT SSIM | DXA PSNR (dB) | DXA SSIM |
+|---------------|-----------|:------------:|:-------:|:-------------:|:--------:|
+| U-Net         | ReLU      | 32.14        | 0.891   | 30.87         | 0.873    |
+| U-Net         | SiLU      | 33.01        | 0.902   | 31.54         | 0.881    |
+| **U-Net**     | **SAGA**  | **34.67**    | **0.921** | **33.12**   | **0.903** |
+| DeblurResNet  | ReLU      | 31.89        | 0.883   | 30.21         | 0.864    |
+| **DeblurResNet** | **SAGA** | **34.11** | **0.916** | **32.78**   | **0.897** |
+
+Full results and ablation studies are reported in the paper.
+
+---
+
+## Running the Tests
+
+```bash
+pytest tests/ -v
+```
+
+To run with coverage:
+
+```bash
+pytest tests/ --cov=saga --cov-report=term-missing
+```
+
+---
+
+## Citing
+
+If SAGA is useful in your research, please cite:
+
+```bibtex
+@article{siju2026saga,
+  title   = {An interpretable deep learning method for medical image deblurring and restoration},
+  author  = {Siju K.S. and Vipin Venugopal and Mithun Kumar Kar and Jayakrishnan Anandakrishnan},
+  journal = {Healthcare Analytics},
+  volume  = {9},
+  pages   = {100468},
+  year    = {2026},
+  doi     = {10.1016/j.health.2026.100468}
+}
+```
+
+---
+
+## License
+
+[MIT](LICENSE)

saga_activation-0.1.0/src/saga_activation.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/saga/__init__.py
+src/saga/activation.py
+src/saga/blocks.py
+src/saga/utils.py
+src/saga_activation.egg-info/PKG-INFO
+src/saga_activation.egg-info/SOURCES.txt
+src/saga_activation.egg-info/dependency_links.txt
+src/saga_activation.egg-info/requires.txt
+src/saga_activation.egg-info/top_level.txt
+tests/test_saga.py

saga_activation-0.1.0/src/saga_activation.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

saga_activation-0.1.0/src/saga_activation.egg-info/requires.txt

@@ -0,0 +1,10 @@
+torch>=2.0
+
+[dev]
+pytest>=7.0
+pytest-cov>=4.0
+
+[docs]
+sphinx>=7.0
+sphinx-rtd-theme>=2.0
+myst-parser>=2.0

saga_activation-0.1.0/src/saga_activation.egg-info/top_level.txt

@@ -0,0 +1 @@
+saga

saga_activation-0.1.0/tests/test_saga.py

@@ -0,0 +1,244 @@
+"""
+tests/test_saga.py
+==================
+pytest test suite for the SAGA activation package.
+
+Run with:
+    pytest tests/ -v
+"""
+
+import pytest
+import torch
+import torch.nn as nn
+
+from src.saga import SAGA, SAGALayer, SAGAResBlock, SAGABottleneck
+from src.saga.utils import count_parameters, freeze_gate, unfreeze_gate
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+DEVICES = ["cpu"]
+if torch.cuda.is_available():
+    DEVICES.append("cuda")
+
+
+@pytest.fixture(params=DEVICES)
+def device(request):
+    return torch.device(request.param)
+
+
+# ---------------------------------------------------------------------------
+# 1. Output shape tests
+# ---------------------------------------------------------------------------
+
+class TestOutputShape:
+    @pytest.mark.parametrize("B,C,H,W", [
+        (2, 1, 8, 8),      # B=2 to avoid BatchNorm crash during train mode
+        (2, 16, 32, 32),
+        (4, 64, 128, 128),
+        (2, 3, 256, 256),
+    ])
+    def test_shape_preserved(self, B, C, H, W):
+        """SAGA must return a tensor with the same shape as the input."""
+        act = SAGA(in_channels=C)
+        x = torch.randn(B, C, H, W)
+        y = act(x)
+        assert y.shape == x.shape, f"Expected {x.shape}, got {y.shape}"
+
+    def test_single_channel(self):
+        act = SAGA(in_channels=1)
+        x = torch.randn(2, 1, 4, 4)
+        assert act(x).shape == x.shape
+
+    def test_large_channel(self):
+        act = SAGA(in_channels=512)
+        x = torch.randn(2, 512, 8, 8)
+        assert act(x).shape == x.shape
+
+
+# ---------------------------------------------------------------------------
+# 2. Edge-case tensor value tests
+# ---------------------------------------------------------------------------
+
+class TestEdgeCases:
+    def test_zero_input(self):
+        act = SAGA(in_channels=8)
+        x = torch.zeros(2, 8, 16, 16)
+        y = act(x)
+        assert y.shape == x.shape
+        assert torch.isfinite(y).all()
+
+    def test_negative_input(self):
+        act = SAGA(in_channels=8)
+        x = -torch.abs(torch.randn(2, 8, 16, 16))
+        y = act(x)
+        assert torch.isfinite(y).all()
+
+    def test_large_positive_input(self):
+        act = SAGA(in_channels=8)
+        x = torch.full((2, 8, 16, 16), 1e3)
+        y = act(x)
+        assert torch.isfinite(y).all()
+
+    def test_large_negative_input(self):
+        act = SAGA(in_channels=8)
+        x = torch.full((2, 8, 16, 16), -1e3)
+        y = act(x)
+        assert torch.isfinite(y).all()
+
+    def test_nan_free(self):
+        """Confirm no NaN leaks on random inputs."""
+        torch.manual_seed(42)
+        act = SAGA(in_channels=32)
+        for _ in range(10):
+            x = torch.randn(2, 32, 64, 64) * 10
+            y = act(x)
+            assert not torch.isnan(y).any(), "NaN detected in SAGA output"
+
+
+# ---------------------------------------------------------------------------
+# 3. Gradient / backprop tests
+# ---------------------------------------------------------------------------
+
+class TestGradients:
+    def test_backward_cpu(self):
+        act = SAGA(in_channels=16)
+        x = torch.randn(2, 16, 32, 32, requires_grad=True)
+        y = act(x).sum()
+        y.backward()
+        assert x.grad is not None
+        assert torch.isfinite(x.grad).all()
+
+    @pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA not available")
+    def test_backward_cuda(self):
+        act = SAGA(in_channels=16).cuda()
+        x = torch.randn(2, 16, 32, 32, requires_grad=True, device="cuda")
+        y = act(x).sum()
+        y.backward()
+        assert x.grad is not None
+        assert torch.isfinite(x.grad).all()
+
+    def test_gate_parameters_get_gradients(self):
+        act = SAGA(in_channels=8)
+        x = torch.randn(2, 8, 16, 16)
+        act(x).sum().backward()
+        for name, p in act.named_parameters():
+            assert p.grad is not None, f"No gradient for parameter '{name}'"
+
+
+# ---------------------------------------------------------------------------
+# 4. Device tests
+# ---------------------------------------------------------------------------
+
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA not available")
+class TestCUDA:
+    def test_forward_cuda(self):
+        act = SAGA(in_channels=32).cuda()
+        x = torch.randn(2, 32, 64, 64, device="cuda")
+        y = act(x)
+        assert y.device.type == "cuda"
+        assert y.shape == x.shape
+
+    def test_no_memory_leak(self):
+        """Check GPU memory does not grow unboundedly over repeated calls."""
+        act = SAGA(in_channels=64).cuda()
+        torch.cuda.reset_peak_memory_stats()
+        baseline = torch.cuda.memory_allocated()
+
+        for _ in range(50):
+            x = torch.randn(4, 64, 128, 128, device="cuda")
+            _ = act(x)
+            del x
+
+        torch.cuda.synchronize()
+        peak = torch.cuda.max_memory_allocated()
+        # Allow at most 200 MB overhead
+        assert (peak - baseline) < 200 * 1024 ** 2, "Potential memory leak detected"
+
+
+# ---------------------------------------------------------------------------
+# 5. Building-block tests
+# ---------------------------------------------------------------------------
+
+class TestBlocks:
+    def test_resblock_shape(self):
+        block = SAGAResBlock(64)
+        x = torch.randn(2, 64, 32, 32)
+        assert block(x).shape == x.shape
+
+    def test_resblock_projection(self):
+        block = SAGAResBlock(32, out_channels=64, stride=2)
+        x = torch.randn(2, 32, 32, 32)
+        y = block(x)
+        assert y.shape == (2, 64, 16, 16)
+
+    def test_bottleneck_shape(self):
+        block = SAGABottleneck(64)
+        x = torch.randn(2, 64, 32, 32)
+        assert block(x).shape == x.shape
+
+    def test_bottleneck_channel_change(self):
+        block = SAGABottleneck(32, out_channels=128)
+        x = torch.randn(2, 32, 16, 16)
+        assert block(x).shape == (2, 128, 16, 16)
+
+
+# ---------------------------------------------------------------------------
+# 6. Utility tests
+# ---------------------------------------------------------------------------
+
+class TestUtils:
+    def test_count_parameters(self):
+        act = SAGA(in_channels=64)
+        n = count_parameters(act)
+        assert n > 0
+
+    def test_freeze_unfreeze_gate(self):
+        model = nn.Sequential(SAGA(32), SAGA(32))
+        
+        # Test Freeze
+        freeze_gate(model)
+        for module in model.modules():
+            if isinstance(module, SAGA):
+                for p in module.spatial_conv.parameters():
+                    assert not p.requires_grad
+                for p in module.gate_generator.parameters():
+                    assert not p.requires_grad
+
+        # Test Unfreeze
+        unfreeze_gate(model)
+        for module in model.modules():
+            if isinstance(module, SAGA):
+                for p in module.spatial_conv.parameters():
+                    assert p.requires_grad
+                for p in module.gate_generator.parameters():
+                    assert p.requires_grad
+
+
+# ---------------------------------------------------------------------------
+# 7. SAGALayer alias
+# ---------------------------------------------------------------------------
+
+def test_saga_layer_alias():
+    assert SAGALayer is SAGA
+
+
+# ---------------------------------------------------------------------------
+# 8. Serialisation / state-dict round-trip
+# ---------------------------------------------------------------------------
+
+def test_state_dict_round_trip(tmp_path):
+    act = SAGA(in_channels=16)
+    x = torch.randn(2, 16, 8, 8)
+    y_before = act(x)
+
+    path = tmp_path / "saga.pt"
+    torch.save(act.state_dict(), path)
+
+    act2 = SAGA(in_channels=16)
+    act2.load_state_dict(torch.load(path, map_location="cpu"))
+    y_after = act2(x)
+
+    assert torch.allclose(y_before, y_after, atol=1e-6)