Komment quickstart

.komment/.gitkeep

@@ -0,0 +1 @@
+1715284984746

quant_vis/histograms/hooks/forward_hooks.py

@@ -39,6 +39,59 @@ def activation_forward_histogram_hook(
 
     def hook(module, input):
         # Ensure we are in eval mode, and ensure that this is not during a Shadow conversion check.
+        """
+        calculates and stores histograms for activations during training, to track
+        gradient statistics for quantization-aware training.
+
+        Args:
+            module (ns.Shadow, ns.Module, or torch.Tensor object.): PyTorch module
+                whose activations will be histogrammed.
+
+                		- `training`: Whether the module is in training or not.
+                		- `type`: The type of the input `module`, which can be either
+                `ns.Shadow` or another type.
+                		- `zero_point`: The zero point of the quantization range, which
+                depends on the qparams and the histogram limits.
+                		- `scale`: The scale factor of the quantization range, which
+                depends on the qparams and the histogram limits.
+                		- `bit_res`: The bit resolution of the input `module`, which
+                determines the number of quantization bins.
+                		- `HIST_XMIN`: The minimum value of the histogram, which is
+                dependent on the qrange and the qparams.
+                		- `HIST_XMAX`: The maximum value of the histogram, which is
+                dependent on the qrange and the qparams.
+                		- `HIST_QUANT_BIN_RATIO`: The number of histogram bins per
+                quantization bin, which can be either symmetric or asymmetric.
+                		- `module.scale`: The scale factor of the input `module`.
+                		- `module.zero_point`: The zero point of the input `module`.
+            input (1D tensor of any data type.): 1D tensor of activation values
+                to be processed and histogrammed.
+
+                		- `input`: The input tensor to be processed by the hook function.
+                Its shape and type depend on the specific module and input data.
+                		- `module`: The PyTorch module for which the hook function is
+                defined. It contains information about the module's architecture,
+                parameters, and training state.
+                		- `bit_res`: The number of bits used to represent the quantization
+                values. This determines the range of possible values in the quantized
+                output.
+                		- `qrange`: The full range of possible values in the quantized
+                output, calculated as 2^`bit_res`. This range is used to determine
+                the histogram bins.
+                		- `qparams`: The parameters of the quantization scheme, which
+                include the number of bits for each channel and the symmetric
+                quantization parameter. These parameters affect the quantized
+                output range and histogram bins.
+                		- `HIST_XMIN`, `HIST_XMAX`, `HIST_QUANT_BIN_RATIO`: Constants
+                that define the histogram binning scheme used in the hook function.
+                They determine the number of histogram bins per quantization bin
+                and the offset for symmetric quantization.
+                		- `local_input`: The input tensor after deserialization, which
+                may have undergone additional transformations such as normalization
+                or scaling. Its shape and type depend on the specific module and
+                input data.
+
+        """
         if not module.training and type(module) is not ns.Shadow:
 
             # Get number of quantization bins from the quantization bit width

quant_vis/histograms/hooks/sa_back_hooks.py

@@ -100,6 +100,47 @@ def backwards_SA_histogram_hook(
     """
 
     def hook(module, inp_grad, out_grad):
+        """
+        updates the backpropagation histogram dataclass with the gradients of a
+        module, based on the forward histogram bins and using torch.bincount() to
+        compute the sum of gradients.
+
+        Args:
+            module (instance of a class that defines the module.): 3D tensor of
+                inputs to the hook function.
+
+                		- `module`: This is an instance of a Python class that contains
+                information about the model's forward pass and backward passes.
+                		- `inp_grad`: This is a tensor representing the gradients of the
+                model's inputs with respect to its outputs.
+                		- `out_grad`: This is a tensor representing the gradients of the
+                model's outputs with respect to its inputs.
+
+                	The function then proceeds to compute and store the summed gradients
+                of the histogram bins in the dataclass `act_backward_histograms`.
+            inp_grad (ndarray.): 1-dimensional tensor of gradients to be summed
+                with the forward histogram bins.
+
+                		- `inp_grad` is an instance of the `torch.Tensor` class.
+                		- It has one or more dimensions (depending on the input shape).
+                		- The shape of the tensor is `(1,)` for a single-element tensor
+                or a multi-dimensional tensor with dimensions `inp_grad.shape`.
+                		- The elements of the tensor are floating-point values.
+                		- The tensor may have a specific data type (e.g., `float32`,
+                `float64`, etc.).
+                		- The tensor is either a scalar or a vector, depending on the
+                input shape.
+            out_grad (1D tensor of size ( possibly zero).): 1D tensor of gradients
+                to be summed and stored in the dataclass `act_backward_histograms`.
+
+                		- `out_grad`: A tensor with shape `(1, 2)` containing the gradients
+                for the current forward pass. The first dimension represents the
+                batch size, and the second dimension represents the number of
+                histogram bins.
+                		- `inp_grad`: The input gradient tensor, which is a scalar
+                representing the gradient of the current forward pass.
+
+        """
         if name not in act_forward_histograms.data:
             return
 

quant_vis/histograms/plots/utils.py

@@ -150,6 +150,23 @@ def moving_average(input_tensor, window_size):
 ###########
 
 def create_double_level_plot_folder(file_path: str, lvl_1: str, lvl_2: str) -> str:
+    """
+    generates a plot folder with two levels of subfolders based on input parameters
+    `file_path`, `lvl_1`, and `lvl_2`.
+
+    Args:
+        file_path (str): location where the plot folder will be created.
+        lvl_1 (str): first level of subfolders within which the plot folder will
+            be created.
+        lvl_2 (str): second level of subfolders within the plot folder, and is
+            used to create the final plot folder path through a series of nested
+            directory creations.
+
+    Returns:
+        str: a string representing the path to a double-level folder for storing
+        weight plots.
+
+    """
     weight_plot_folder = (
         file_path / lvl_1 / lvl_2 
     )

tests/evaluate/evaluate.py

@@ -4,6 +4,37 @@
 def evaluate(model, device_str="cuda"):
 
     # Download an example image from the pytorch website
+    """
+    downloads an image from a PyTorch repository and preprocesses it for feeding
+    into a deep learning model. It then moves the input and model to the GPU or
+    CPU, runs the model on the input, and produces probabilities for each of
+    ImageNet's 1000 categories.
+
+    Args:
+        model (nn.Module.): 3D convolutional neural network (CNN) that is being
+            evaluated, and it is expected to be a torch.nn.Module object.
+
+            		- `device_str`: A string representing the device to move the input
+            and model to (either "cpu" or "cuda").
+            		- `input_batch`: A tensor of shape 1000, representing a mini-batch
+            of input images.
+            		- `model`: A PyTorch model that takes the input batch as its argument.
+            The model has various properties, such as:
+            		+ `to(device_str)`: Moves the model to the specified device (either
+            "cpu" or "cuda").
+            		+ `unsqueeze(0)`: Adds a dimension of size 1 to the input batch,
+            which is required by PyTorch models.
+            		+ `dimension` and `dim`: These are not explicitly provided in the
+            code snippet, but can be inferred from the context as the dimension
+            of the output of the `model` function.
+            		+ `torch.nn.functional.softmax(output[0], dim=0)`: Applies a softmax
+            activation function to the output of the model, which produces
+            probabilities for each class.
+        device_str (str): device (either "cpu" or "cuda") to which the input tensor
+            and the model will be moved for computation, allowing the function to
+            take advantage of GPU acceleration when available.
+
+    """
     import urllib
 
     url, filename = (