API Reference

This section provides the detailed API documentation for the SAGA package, generated directly from the source code.

saga.activation

Spatially-Adaptive Gated Activation (SAGA) operator. Optimized with OpenAI Triton for Fused GPU Execution. Supports standard drop-in usage, post-hoc interpretability, and active gate training.

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

class saga.activation.SAGA(*args: Any, **kwargs: Any)[source]

Bases: Module

Spatially-Adaptive Gated Activation (SAGA).

Parameters:

in_channels (int) – Number of input channels.
return_gate (bool (default: False)) – If True, forward returns a tuple of (output, gate_map). If False, returns only the activated output tensor.
temperature (float (default: 1.0)) – Controls sharpness scaling within the gating function.
init_bias (float (default: 2.0)) – Initial bias for the gating module. Use lower values (e.g., -1.0) for early background suppression or higher values (e.g., 2.0) for an mostly open connection at start.

forward(x: torch.Tensor)[source]

extra_repr() → str[source]

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.

Updated for v0.2.0: Safely unrolled to support dynamic tuple routing when interpretability gate extraction (return_gate=True) is activated globally.

class saga.blocks.SAGAResBlock(*args: Any, **kwargs: Any)[source]

Bases: Module

Residual block with SAGA activations.

forward(x: torch.Tensor)[source]

class saga.blocks.SAGABottleneck(*args: Any, **kwargs: Any)[source]

Bases: Module

Bottleneck block (1x1 -> 3x3 -> 1x1) with SAGA activations.

forward(x: torch.Tensor)[source]

saga.utils

Lightweight helpers for parameter accounting, gate control, and interpretability toggling.

saga.utils.count_parameters(model: torch.nn.Module, trainable_only: bool = True) → int[source]: Returns total parameters found in the target network architecture.

saga.utils.freeze_gate(model: torch.nn.Module) → None[source]: Freeze all SAGA gating parameters in a model. Enables curriculum training sequences by isolating structural backbone tuning.

saga.utils.unfreeze_gate(model: torch.nn.Module) → None[source]: Unfreeze all SAGA gating parameters in the target model infrastructure.

saga.utils.set_return_gate(model: torch.nn.Module, state: bool) → None[source]

Recursively updates the return signature formatting for SAGA instances.

Parameters:

model (nn.Module) – Complete target network container.
state (bool) – If True, layers return a tuple containing (output, gate_map). If False, layers function as drop-in tensor-to-tensor operations.