congrads 0.1.0__py3-none-any.whl → 1.0.1__py3-none-any.whl

congrads/descriptor.py

@@ -1,65 +1,130 @@
+"""
+This module defines the `Descriptor` class, which is designed to manage
+the mapping between neuron names, their corresponding layers, and additional
+properties such as constant or variable status. It provides a way to easily 
+place constraints on parts of your network, by referencing the neuron names
+instead of indices.
+
+The `Descriptor` class allows for easy constraint definitions on parts of
+your neural network. It supports registering neurons with associated layers, 
+indices, and optional attributes, such as whether the layer is constant 
+or variable.
+
+Key Methods:
+
+    - `__init__`: Initializes the `Descriptor` object with empty mappings
+      and sets for managing neurons and layers.
+    - `add`: Registers a neuron with its associated layer, index, and
+      optional constant status.
+
+"""
+
+from .utils import validate_type
+
+
 class Descriptor:
     """
-    A class to manage the mapping of neurons to layers and their properties
-    (e.g., output, constant, or variable) in a neural network.
+    A class to manage the mapping between neuron names, their corresponding
+    layers, and additional properties (such as min/max values, output,
+    and constant variables).
 
-    This class enables the organization and description of network elements,
-    such as associating neurons with specific layers and categorizing layers
-    as outputs, constants, or variables.
+    This class is designed to track the relationship between neurons and
+    layers in a neural network. It allows for the assignment of properties
+    (like minimum and maximum values, and whether a layer is an output,
+    constant, or variable) to each neuron. The data is stored in
+    dictionaries and sets for efficient lookups.
 
-    This allows users to easily place constraints on parts of the network by
-    referencing the name that is configured in this class.
+    Attributes:
+        neuron_to_layer (dict): A dictionary mapping neuron names to
+            their corresponding layer names.
+        neuron_to_index (dict): A dictionary mapping neuron names to
+            their corresponding indices in the layers.
+        constant_layers (set): A set of layer names that represent
+            constant layers.
+        variable_layers (set): A set of layer names that represent
+            variable layers.
     """
 
     def __init__(
         self,
     ):
         """
-        Initialize the Descriptor class with empty mappings for neurons and layers.
-
-        This includes:
-            - `neuron_to_layer`: A dictionary mapping neuron names to their corresponding layer names.
-            - `neuron_to_index`: A dictionary mapping neuron names to their corresponding index within a layer.
-            - `output_layers`: A set that holds the names of layers marked as output layers.
-            - `constant_layers`: A set that holds the names of layers marked as constant layers.
-            - `variable_layers`: A set that holds the names of layers marked as variable layers.
+        Initializes the Descriptor object.
         """
 
-        # Define dictionaries that will translate neuron names to layer and index
+        # Define dictionaries that will translate neuron
+        # names to layer and index
         self.neuron_to_layer: dict[str, str] = {}
         self.neuron_to_index: dict[str, int] = {}
 
         # Define sets that will hold the layers based on which type
-        self.output_layers: set[str] = set()
         self.constant_layers: set[str] = set()
         self.variable_layers: set[str] = set()
 
     def add(
         self,
         layer_name: str,
-        neuron_names: list[str],
-        output: bool = False,
+        index: int,
+        neuron_name: str,
         constant: bool = False,
     ):
         """
-        Add a layer to the descriptor, associating it with neurons and marking it
-        as an output or constant layer.
+        Adds a neuron to the descriptor with its associated layer,
+        index, and properties.
+
+        This method registers a neuron name and associates it with a
+        layer, its index, and optional properties such as whether
+        the layer is an output or constant layer.
 
         Args:
-            layer_name (str): The name of the layer to be added.
-            neuron_names (list[str]): A list of neuron names that belong to the layer.
-            output (bool, optional): If True, mark this layer as an output layer. Defaults to False.
-            constant (bool, optional): If True, mark this layer as a constant layer. Defaults to False.
+            layer_name (str): The name of the layer where the neuron is located.
+            index (int): The index of the neuron within the layer.
+            neuron_name (str): The name of the neuron.
+            constant (bool, optional): Whether the layer is a constant layer.
+                Defaults to False.
+
+        Raises:
+            TypeError: If a provided attribute has an incompatible type.
+            ValueError: If a layer or index is already assigned for a neuron
+                or a duplicate index is used within a layer.
+
         """
 
-        if output:
-            self.output_layers.add(layer_name)
+        # Type checking
+        validate_type("layer_name", layer_name, str)
+        validate_type("index", index, int)
+        validate_type("neuron_name", neuron_name, str)
+        validate_type("constant", constant, bool)
+
+        # Other validations
+        if neuron_name in self.neuron_to_layer:
+            raise ValueError(
+                "There already is a layer registered for the neuron with name "
+                f"'{neuron_name}'. Please use a unique name for each neuron."
+            )
+
+        if neuron_name in self.neuron_to_index:
+            raise ValueError(
+                "There already is an index registered for the neuron with name "
+                f"'{neuron_name}'. Please use a unique name for each neuron."
+            )
+
+        for existing_neuron, assigned_index in self.neuron_to_index.items():
+            if (
+                assigned_index == index
+                and self.neuron_to_layer[existing_neuron] == layer_name
+            ):
+                raise ValueError(
+                    f"The index {index} in layer {layer_name} is already "
+                    "assigned. Every neuron must be assigned a different "
+                    "index that matches the network's output."
+                )
 
+        # Add to dictionaries and sets
         if constant:
             self.constant_layers.add(layer_name)
         else:
             self.variable_layers.add(layer_name)
 
-        for index, neuron_name in enumerate(neuron_names):
-            self.neuron_to_layer[neuron_name] = layer_name
-            self.neuron_to_index[neuron_name] = index
+        self.neuron_to_layer[neuron_name] = layer_name
+        self.neuron_to_index[neuron_name] = index

congrads/metrics.py

@@ -1,64 +1,211 @@
-from torch import Tensor, tensor, sum, numel
-from torchmetrics import Metric
+"""
+This module defines the `Metric` and `MetricManager` classes, which are 
+used to track and aggregate performance metrics during model training or 
+evaluation in machine learning. These classes support the accumulation of 
+metric values, aggregation using customizable functions (such as mean), 
+and resetting of the metrics.
 
-# NOTE
+Classes:
 
+    - Metric: A class that tracks and aggregates a specific metric over 
+      multiple samples, allowing for accumulation, aggregation, and 
+      resetting of values.
+    - MetricManager: A class that manages and tracks multiple metrics 
+      during model training or evaluation, supporting registration, 
+      accumulation, aggregation, and resetting of metrics.
 
-class ConstraintSatisfactionRatio(Metric):
+Key Methods:
+
+    - `Metric.__init__`: Initializes a metric with a specified name and 
+      optional accumulator function (defaults to `nanmean`).
+    - `Metric.accumulate`: Accumulates a new value for the metric, 
+      typically a tensor of model output or performance.
+    - `Metric.aggregate`: Aggregates the accumulated values using the 
+      specified accumulator function.
+    - `Metric.reset`: Resets the accumulated values and sample count for 
+      the metric.
+    - `MetricManager.__init__`: Initializes a manager for multiple metrics.
+    - `MetricManager.register`: Registers a new metric with a name, group, 
+      and optional accumulator function.
+    - `MetricManager.accumulate`: Accumulates a new value for the specified 
+      metric.
+    - `MetricManager.aggregate`: Aggregates all metrics in a specified group.
+    - `MetricManager.reset`: Resets all registered metrics in a specified 
+      group.
+
+Each class provides functionality to efficiently track, aggregate, and reset 
+metrics during the training and evaluation phases of machine learning tasks, 
+supporting flexible aggregation strategies and group-based management of 
+metrics.
+"""
+
+from typing import Callable
+
+from torch import Tensor, cat, nanmean
+
+from .utils import validate_callable, validate_type
+
+
+class Metric:
     """
-    A custom metric to calculate the ratio of satisfied constraints in a neural network model.
-    It computes the proportion of constraints that have been satisfied,
-    where satisfaction is determined based on the provided constraint results.
+    A class that tracks and aggregates a specific metric over multiple samples.
 
-    This metric tracks the number of unsatisfied constraints and the total number of constraints
-    during the training process, and computes the ratio of satisfied constraints once all updates
-    have been made.
+    This class allows the accumulation of values, their aggregation using a
+    specified function (e.g., mean), and the ability to reset the metrics.
+    It is typically used to track performance metrics during training or
+    evaluation processes in machine learning.
+
+    Args:
+        name (str): The name of the metric.
+        accumulator (Callable[..., Tensor], optional): A function used to
+        aggregate values (defaults to `nanmean`).
 
     Attributes:
-        unsatisfied (Tensor): Tracks the number of unsatisfied constraints.
-        total (Tensor): Tracks the total number of constraints processed.
+        name (str): The name of the metric.
+        accumulator (Callable[..., Tensor]): The function used to aggregate
+            values.
+        values (list): A list to store accumulated values.
+        sample_count (int): The count of accumulated samples.
 
-    Note:
-        For more information about custom metrics, we refer to the Pytorch Lightning documentation
-        at https://lightning.ai/docs/torchmetrics/stable/pages/implement.html
     """
 
-    def __init__(self, **kwargs):
+    def __init__(
+        self,
+        name: str,
+        accumulator: Callable[..., Tensor] = nanmean,
+    ) -> None:
+        """
+        Constructor method
+        """
+
+        # Type checking
+        validate_type("name", name, str)
+        validate_callable("accumulator", accumulator)
+
+        self.name = name
+        self.accumulator = accumulator
+
+        self.values = []
+        self.sample_count = 0
+
+    def accumulate(self, value: Tensor) -> None:
         """
-        Initializes the ConstraintSatisfactionRatio metric by setting up the
-        state variables to track the number of unsatisfied and total constraints.
+        Accumulates a new value for the metric.
 
         Args:
-            **kwargs: Additional arguments to pass to the base Metric class constructor.
+            value (Tensor): The new value to accumulate, typically a
+                tensor of model output or performance.
         """
 
-        # Init parent class
-        super().__init__(**kwargs)
+        self.values.append(value)
+        self.sample_count += value.size(0)
 
-        # Init scalar tensors that will hold metric values
-        self.add_state("unsatisfied", default=tensor(0), dist_reduce_fx="sum")
-        self.add_state("total", default=tensor(0), dist_reduce_fx="sum")
+    def aggregate(self) -> Tensor:
+        """
+        Aggregates the accumulated values using the specified
+        accumulator function.
 
-    def update(self, constraint_result: Tensor) -> None:
+        Returns:
+            Tensor: The aggregated result of the accumulated values.
+        """
+
+        combined = cat(self.values)
+        return self.accumulator(combined)
+
+    def reset(self) -> None:
+        """
+        Resets the accumulated values and sample count for the metric.
         """
-        Updates the state of the metric with the latest constraint results.
+
+        self.values = []
+        self.sample_count = 0
+
+
+class MetricManager:
+    """
+    A class to manage and track multiple metrics during model
+    training or evaluation.
+
+    This class allows registering metrics, accumulating values for each metric,
+    and recording the aggregated values. It also supports the reset of metrics
+    after each epoch or training step.
+
+    Attributes:
+        metrics (dict[str, Metric]): A dictionary of registered metrics.
+        groups (dict[str, str]): A dictionary mapping metric names to groups.
+    """
+
+    def __init__(self) -> None:
+        """
+        Constructor method
+        """
+
+        self.metrics: dict[str, Metric] = {}
+        self.groups: dict[str, str] = {}
+
+    def register(
+        self,
+        name: str,
+        group: str,
+        accumulator: Callable[..., Tensor] = nanmean,
+    ) -> None:
+        """
+        Registers a new metric with the specified name and accumulator function.
 
         Args:
-            constraint_result (Tensor): A tensor representing the result of
-                                         the constraint checks, where each
-                                         element indicates whether a constraint
-                                         is satisfied (e.g., 0 for satisfied,
-                                         1 for unsatisfied).
+            name (str): The name of the metric to register.
+            group (str): The name of the group to assign the metric to.
+            accumulator (Callable[..., Tensor], optional): The function used
+                to aggregate values for the metric (defaults to `nanmean`).
+        """
+
+        # Type checking
+        validate_type("name", name, str)
+        validate_type("group", group, str)
+        validate_callable("accumulator", accumulator)
+
+        self.metrics[name] = Metric(name, accumulator)
+        self.groups[name] = group
+
+    def accumulate(self, name: str, value: Tensor) -> None:
         """
-        self.unsatisfied += sum(constraint_result)
-        self.total += numel(constraint_result)
+        Accumulates a new value for the specified metric.
 
-    def compute(self) -> Tensor:
+        Args:
+            name (str): The name of the metric.
+            value (Tensor): The new value to accumulate.
         """
-        Computes the constraint satisfaction ratio, defined as:
-        1 - (number of unsatisfied constraints / total constraints).
+
+        self.metrics[name].accumulate(value)
+
+    def aggregate(self, group: str) -> dict[str, Tensor]:
+        """
+        Aggregates all metrics in a group using the accumulators
+        specified during registration.
+
+        Args:
+            group (str): The name of the group.
 
         Returns:
-            Tensor: The satisfaction ratio as a scalar tensor.
+            dict[str, Tensor]: A dictionary with the metric names and the
+                corresponding aggregated values of the selected group.
+        """
+
+        return {
+            name: metric.aggregate()
+            for name, metric in self.metrics.items()
+            if self.groups[name] == group
+        }
+
+    def reset(self, group: str) -> None:
+        """
+        Resets all registered metrics in a group.
+
+        Args:
+            group (str): The name of the group.
         """
-        return 1 - (self.unsatisfied.float() / self.total)
+
+        for name, metric in self.metrics.items():
+            if self.groups[name] == group:
+                metric.reset()
+                metric.reset()

congrads/networks.py

@@ -1,4 +1,32 @@
-from torch.nn import Linear, Sequential, ReLU, Module
+"""
+This module defines the `MLPNetwork` class, which constructs and
+operates a multi-layer perceptron (MLP) neural network model. The MLP
+network consists of an input layer, multiple hidden layers, and an
+output layer. It allows for configurable hyperparameters such as the
+number of input features, output features, number of hidden layers,
+and the dimensionality of the hidden layers.
+
+Classes:
+
+    - MLPNetwork: A neural network model that implements a multi-layer
+      perceptron with customizable layers and dimensionalities.
+
+Key Methods:
+
+    - `__init__`: Initializes the MLP network with specified input size,
+      output size, number of hidden layers, and hidden layer dimensionality.
+    - `forward`: Performs a forward pass through the network, returning
+      both the input and output of the model.
+    - `linear`: Creates a basic linear block consisting of a Linear layer
+      followed by a ReLU activation function.
+
+The `MLPNetwork` class constructs a fully connected neural network with 
+multiple hidden layers, providing flexibility in designing the network 
+architecture. It can be used for regression, classification, or other 
+machine learning tasks that require a feedforward neural network structure.
+"""
+
+from torch.nn import Linear, Module, ReLU, Sequential
 
 
 class MLPNetwork(Module):
@@ -11,33 +39,26 @@ class MLPNetwork(Module):
     the dimensionality of hidden layers. It provides methods for both
     building the model and performing a forward pass through the network.
 
-    Attributes:
-        n_inputs (int): The number of input features.
-        n_outputs (int): The number of output features.
-        n_hidden_layers (int): The number of hidden layers in the network.
-        hidden_dim (int): The dimensionality of the hidden layers.
-        input (nn.Module): The input layer (linear transformation followed by ReLU).
-        hidden (nn.Module): The sequential hidden layers (each consisting of
-                             a linear transformation followed by ReLU).
-        out (nn.Module): The output layer (linear transformation).
+    Args:
+        n_inputs (int, optional): The number of input features. Defaults to 25.
+        n_outputs (int, optional): The number of output features. Defaults to 2.
+        n_hidden_layers (int, optional): The number of hidden layers.
+            Defaults to 2.
+        hidden_dim (int, optional): The dimensionality of the hidden layers.
+            Defaults to 35.
     """
 
     def __init__(
         self,
-        n_inputs=25,
-        n_outputs=2,
-        n_hidden_layers=2,
+        n_inputs,
+        n_outputs,
+        n_hidden_layers=3,
         hidden_dim=35,
     ):
         """
-        Initializes the MLP network with the given hyperparameters.
-
-        Args:
-            n_inputs (int, optional): The number of input features. Defaults to 25.
-            n_outputs (int, optional): The number of output features. Defaults to 2.
-            n_hidden_layers (int, optional): The number of hidden layers. Defaults to 2.
-            hidden_dim (int, optional): The dimensionality of the hidden layers. Defaults to 35.
+        Initializes the MLPNetwork.
         """
+
         super().__init__()
 
         # Init object variables
@@ -47,7 +68,7 @@ class MLPNetwork(Module):
         self.hidden_dim = hidden_dim
 
         # Set up the components of our model
-        self.input = self.linear(self.n_inputs, self.hidden_dim)
+        self.input = Linear(self.n_inputs, self.hidden_dim)
         self.hidden = Sequential(
             *(
                 self.linear(self.hidden_dim, self.hidden_dim)
@@ -56,21 +77,21 @@ class MLPNetwork(Module):
         )
         self.out = Linear(self.hidden_dim, self.n_outputs)
 
-    def forward(self, X):
+    def forward(self, data):
         """
         Performs a forward pass through the network.
 
         Args:
-            X (Tensor): The input tensor to be passed through the network.
+            data (Tensor): The input tensor to be passed through the network.
 
         Returns:
             dict: A dictionary containing the 'input' (original input) and
-                  'output' (predicted output) of the network.
+            'output' (predicted output) of the network.
         """
-        input = X
-        output = self.out(self.hidden(self.input(X)))
 
-        return {"input": input, "output": output}
+        output = self.out(self.hidden(self.input(data)))
+
+        return {"input": data, "output": output}
 
     @staticmethod
     def linear(in_features, out_features):
@@ -83,8 +104,10 @@ class MLPNetwork(Module):
             out_features (int): The number of output features.
 
         Returns:
-            nn.Module: A sequential module consisting of a Linear layer and ReLU activation.
+            nn.Module: A sequential module consisting of a Linear layer
+            and ReLU activation.
         """
+
         return Sequential(
             Linear(in_features, out_features),
             ReLU(),

congrads/requirements.txt

@@ -0,0 +1,6 @@
+numpy==2.2.2
+pandas==2.2.3
+setuptools==75.6.0
+torch==2.5.0
+torchvision==0.20.0
+tqdm==4.66.5