TorchSOM refactoring:

- Introduced core components including `SOM` and `BaseSOM` classes for SOM functionality.
- Implemented configuration management using Pydantic with `SOMConfig` for parameter validation.
- Added utility functions for distance calculations, neighborhood functions, and weight initialization.
- Created visualization tools for SOM outputs, including a `SOMVisualizer` class.
- Established versioning with `__version__` in `version.py`.
- Organized code into modular files for better maintainability and clarity.
- Included necessary utility functions for grid management and decay functions.
- Set up initial structure for hierarchical and growing SOM variants.
- Ensured compatibility with PyTorch for tensor operations and GPU support.
- Added comprehensive inline documentation and type hints for improved code readability.

Author: LouisTier

torchsom/__init__.py

@@ -0,0 +1,17 @@
+from .core import SOM, BaseSOM
+from .utils.decay import DECAY_FUNCTIONS
+from .utils.distances import DISTANCE_FUNCTIONS
+from .utils.neighborhood import NEIGHBORHOOD_FUNCTIONS
+from .version import __version__
+from .visualization import SOMVisualizer, VisualizationConfig
+
+# Define what should be imported when using 'from torchsom import *'
+__all__ = [
+    "SOM",
+    "BaseSOM",
+    "DISTANCE_FUNCTIONS",
+    "DECAY_FUNCTIONS",
+    "NEIGHBORHOOD_FUNCTIONS",
+    "SOMVisualizer",
+    "VisualizationConfig",
+]

torchsom/configs/__init__.py

@@ -0,0 +1,3 @@
+from .som_config import SOMConfig
+
+__all__ = ["SOMConfig"]

torchsom/configs/som_config.py

@@ -0,0 +1,70 @@
+from typing import Literal, Optional, Union
+
+import torch
+from pydantic import BaseModel, Field, validator
+
+
+class SOMConfig(BaseModel):
+    """Configuration for SOM parameters using pydantic for validation."""
+
+    # Map structure parameters
+    x: int = Field(..., description="Number of rows in the map", gt=0)
+    y: int = Field(..., description="Number of columns in the map", gt=0)
+    topology: Literal["rectangular", "hexagonal"] = Field(
+        "rectangular", description="Grid topology"
+    )
+
+    # Training parameters
+    epochs: int = Field(10, description="Number of training epochs", ge=1)
+    batch_size: int = Field(5, description="Batch size for training", ge=1)
+    learning_rate: float = Field(0.5, description="Initial learning rate", gt=0)
+    sigma: float = Field(1.0, description="Initial neighborhood radius", gt=0)
+
+    # Function choices
+    neighborhood_function: Literal["gaussian", "mexican_hat", "bubble", "triangle"] = (
+        Field(
+            "gaussian",
+            description="Function to determine neuron neighborhood influence",
+        )
+    )
+    distance_function: Literal["euclidean", "cosine", "manhattan", "chebyshev"] = Field(
+        "euclidean", description="Function to compute distances"
+    )
+    lr_decay_function: Literal[
+        "lr_inverse_decay_to_zero", "lr_linear_decay_to_zero", "asymptotic_decay"
+    ] = Field("asymptotic_decay", description="Learning rate decay function")
+    sigma_decay_function: Literal[
+        "sig_inverse_decay_to_one", "sig_linear_decay_to_one", "asymptotic_decay"
+    ] = Field("asymptotic_decay", description="Sigma decay function")
+    initialization_mode: Literal["random", "pca"] = Field(
+        "random", description="Weight initialization method"
+    )
+
+    # Other parameters
+    neighborhood_order: int = Field(
+        1, description="Neighborhood order for distance calculations", ge=1
+    )
+    device: str = Field(
+        "cuda" if torch.cuda.is_available() else "cpu",
+        description="Device for tensor computations",
+    )
+    random_seed: int = Field(42, description="Random seed for reproducibility")
+
+
+# SOM:
+
+#   x: 100 # Number of rows: 100
+#   y: 75 # Number of columns: 75
+#   topology: "rectangular" # Grid topology: "rectangular" or "hexagonal"
+#   epochs: 50 # Number of epochs to train the model: 50
+#   batch_size: 256 # Number of samples to train the model: 64
+#   learning_rate: 0.95 # Initial learning rate: 0.95
+#   sigma: 5.0 # Initial spread of the neighborhood function: 5.0
+#   neighborhood_function: "gaussian" # Neighborhood function: "gaussian", "mexican_hat", "bubble", "triangle"
+#   distance_function: "euclidean" # Function to calculate distance between data and neurons: "euclidean" "cosine" "manhattan" "chebyshev" "weighted_euclidean" (need to provide weights_proportion)
+#   lr_decay_function: "asymptotic_decay" # Learning rate scheduler: "lr_inverse_decay_to_zero", "lr_linear_decay_to_zero", "asymptotic_decay"
+#   sigma_decay_function: "asymptotic_decay" # Sigma scheduler: "sig_inverse_decay_to_one" "sig_linear_decay_to_one" "asymptotic_decay"
+#   initialization_mode: "pca" # Weights initialization method: "random" or "pca"
+#   neighborhood_order: 3 # Indicate which neighbors should be considered in SOM distance map and JITL buffer: 1
+# !  device: "cuda" # Device for tensor computations: "cuda" or "cpu"
+# !  random_seed: 42 # Random seed for reproducibility

torchsom/core/__init__.py

@@ -0,0 +1,4 @@
+from .base_som import BaseSOM
+from .som import SOM
+
+__all__ = ["SOM", "BaseSOM"]

torchsom/core/base_som.py

@@ -0,0 +1,114 @@
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+import torch
+import torch.nn as nn
+
+
+class BaseSOM(nn.Module, ABC):
+    """Abstract base class for all SOM variants."""
+
+    @abstractmethod
+    def fit(
+        self,
+        data: torch.Tensor,
+    ) -> Tuple[List[float], List[float]]:
+        """Train the SOM on the given data.
+
+        Args:
+            data (torch.Tensor): Input data tensor [batch_size, num_features]
+
+        Returns:
+            Tuple[List[float], List[float]]: Quantization and topographic errors [epoch]
+        """
+        pass
+
+    @abstractmethod
+    def identify_bmus(
+        self,
+        data: torch.Tensor,
+    ) -> torch.Tensor:
+        """Find best matching units for input data.
+
+        Args:
+            data (torch.Tensor): Input data tensor [batch_size, num_features] or [num_features]
+
+        Returns:
+            torch.Tensor: For single sample: Tensor of shape [2] with [row, col].
+                          For batch: Tensor of shape [batch_size, 2] with [row, col] pairs
+        """
+        pass
+
+    @abstractmethod
+    def quantization_error(
+        self,
+        data: torch.Tensor,
+    ) -> float:
+        """Calculate quantization error.
+
+        Args:
+            data (torch.Tensor): Input data tensor [batch_size, num_features] or [num_features]
+
+        Returns:
+            float: Average quantization error value
+        """
+        pass
+
+    @abstractmethod
+    def topographic_error(
+        self,
+        data: torch.Tensor,
+    ) -> float:
+        """Calculate topographic error.
+
+        Args:
+            data (torch.Tensor): Input data tensor [batch_size, num_features] or [num_features]
+
+        Returns:
+            float: Topographic error ratio
+        """
+        pass
+
+    @abstractmethod
+    def initialize_weights(
+        self,
+        data: torch.Tensor,
+        mode: str = None,
+    ) -> None:
+        """Initialize the SOM weights.
+
+        Args:
+            data (torch.Tensor): Input data tensor [batch_size, num_features]
+            mode (str, optional): Weight initialization method. Defaults to None.
+        """
+        pass
+
+    @abstractmethod
+    def build_hit_map(
+        self,
+        data: torch.Tensor,
+    ) -> torch.Tensor:
+        """Build a hit map showing neuron activation frequencies.
+
+        Args:
+            data (torch.Tensor): Input data tensor [batch_size, num_features] or [num_features]
+
+        Returns:
+            torch.Tensor: Hit map [row_neurons, col_neurons]
+        """
+        pass
+
+    @abstractmethod
+    def build_distance_map(
+        self,
+        scaling: str = "sum",
+    ) -> torch.Tensor:
+        """Build a distance map (U-matrix) showing neuron similarities.
+
+        Args:
+            scaling (str, optional): Scaling method for distances. Defaults to "sum".
+
+        Returns:
+            torch.Tensor: Distance map [row_neurons, col_neurons]
+        """
+        pass