zonolayer 0.1.0__tar.gz

zonolayer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Matthew
+
+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.

zonolayer-0.1.0/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: zonolayer
+Version: 0.1.0
+Summary: Last-layer uncertainty modeling via zonotopic representations.
+Author: Matthew McCann, Marco De Angelis
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/MattCodes03/zonolayer
+Project-URL: Repository, https://github.com/MattCodes03/zonolayer
+Project-URL: Bug Tracker, https://github.com/MattCodes03/zonolayer/issues
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: torch
+Requires-Dist: matplotlib
+Dynamic: license-file
+
+# Zonolayer
+
+[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![PyPI Version](https://img.shields.io/pypi/v/zonolayer)](https://pypi.org/project/zonolayer/)
+
+**Zonolayer** is a Python package for **last-layer uncertainty modeling via zonotopic representations**.  
+It provides **zonotopic output bounds** and **statistical prediction intervals** for neural networks with interval-bounded outputs, enabling precise and interpretable uncertainty quantification in regression tasks.
+
+---
+
+## Features
+
+- Compute **zonotopic bounds** for last-layer outputs.
+- Combine **statistical prediction intervals** with interval uncertainty.
+- Compatible with PyTorch networks exposing latent features.
+- Modular, research-friendly, and easy to use.
+
+By default, Zonolayer relies on **NumPy** for all numerical computations and interval handling.  
+
+If you require more advanced interval arithmetic (e.g., using [`pyinterval`](https://pypi.org/project/pyinterval/) or other specialized packages), you can install the optional dependencies and modify the code accordingly, or submit a request for support to be added. I appreciate any and all feedback.
+
+---
+
+## Installation
+
+Ensure all requirements from `requirements.txt` are installed to reduce any potential issues.
+
+```bash
+pip install zonolayer
+```
+
+---
+## Getting Started
+See `basic_usage.py` in the examples directory for the quickest method to get up and running and start experimenting with the library.
+

zonolayer-0.1.0/README.md

@@ -0,0 +1,36 @@
+# Zonolayer
+
+[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![PyPI Version](https://img.shields.io/pypi/v/zonolayer)](https://pypi.org/project/zonolayer/)
+
+**Zonolayer** is a Python package for **last-layer uncertainty modeling via zonotopic representations**.  
+It provides **zonotopic output bounds** and **statistical prediction intervals** for neural networks with interval-bounded outputs, enabling precise and interpretable uncertainty quantification in regression tasks.
+
+---
+
+## Features
+
+- Compute **zonotopic bounds** for last-layer outputs.
+- Combine **statistical prediction intervals** with interval uncertainty.
+- Compatible with PyTorch networks exposing latent features.
+- Modular, research-friendly, and easy to use.
+
+By default, Zonolayer relies on **NumPy** for all numerical computations and interval handling.  
+
+If you require more advanced interval arithmetic (e.g., using [`pyinterval`](https://pypi.org/project/pyinterval/) or other specialized packages), you can install the optional dependencies and modify the code accordingly, or submit a request for support to be added. I appreciate any and all feedback.
+
+---
+
+## Installation
+
+Ensure all requirements from `requirements.txt` are installed to reduce any potential issues.
+
+```bash
+pip install zonolayer
+```
+
+---
+## Getting Started
+See `basic_usage.py` in the examples directory for the quickest method to get up and running and start experimenting with the library.
+

zonolayer-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zonolayer"
+version = "0.1.0"
+description = "Last-layer uncertainty modeling via zonotopic representations."
+authors = [{ name = "Matthew McCann" }, { name = "Marco De Angelis" }]
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+dependencies = ["numpy", "torch", "matplotlib"]
+
+[project.urls]
+"Homepage" = "https://github.com/MattCodes03/zonolayer"
+"Repository" = "https://github.com/MattCodes03/zonolayer"
+"Bug Tracker" = "https://github.com/MattCodes03/zonolayer/issues"

zonolayer-0.1.0/setup.cfg

@@ -0,0 +1,13 @@
+[metadata]
+name = zonolayer
+version = 0.1.0
+license_files = LICENSE
+
+[options]
+packages = find:
+python_requires = >=3.9
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

zonolayer-0.1.0/zonolayer/__init__.py

@@ -0,0 +1,4 @@
+from .core import Zonolayer
+from .zonotope import Zonotope
+
+__all__ = ["Zonolayer", "Zonotope"]

zonolayer-0.1.0/zonolayer/core.py

@@ -0,0 +1,151 @@
+import numpy as np
+import torch
+from scipy.stats import t
+from .zonotope import Zonotope
+
+
+class Zonolayer:
+    """
+    Zonolayer: Last-layer uncertainty modeling via zonotopic representations.
+
+    This class fits a last-layer affine transformation to interval-bounded data,
+    producing zonotopic output bounds and statistical prediction intervals.
+
+    """
+
+    def __init__(self, centre_net, lambda_reg: float = 1e-6, alpha: float = 0.05):
+        """
+        Parameters
+        ----------
+        centre_net : torch.nn.Module
+            The trained neural network whose last-layer latent features are used.
+
+        lambda_reg : float, optional
+            Regularization strength for the pseudoinverse (default: 1e-6).
+
+        alpha : float, optional
+            Significance level for prediction intervals (default: 0.05 → 95% CI).
+        """
+        self.centre_net = centre_net
+        self.lambda_reg = lambda_reg
+        self.alpha = alpha
+
+    # Core methods
+    def _compute_zonotope_bounds(self, predicted_centre, latent_train, y_lower, y_upper, latent_test):
+        """Internal routine to compute zonotope-based bounds and statistical intervals."""
+
+        latent_train = np.asarray(latent_train)
+        y_lower = np.asarray(y_lower).flatten()
+        y_upper = np.asarray(y_upper).flatten()
+
+        # Center and radii of output intervals
+        centre_y = (y_lower + y_upper) / 2
+        radii_y = (y_upper - y_lower) / 2
+
+        # Create zonotope in output space
+        Y_zono = Zonotope(centre_y, np.diag(radii_y))
+        Phi = latent_train
+
+        # Regularized pseudoinverse
+        M = np.linalg.pinv(Phi.T @ Phi + self.lambda_reg *
+                           np.eye(Phi.shape[1])) @ Phi.T
+
+        # Map zonotope into parameter space
+        Beta_zono = Y_zono.affine_map(M)
+
+        # Map into test feature space
+        Yhat_zono = Beta_zono.affine_map(latent_test)
+        y_lower_pred, y_upper_pred = Yhat_zono.output_interval()
+
+        # Statistical uncertainty
+        predicted_centre = np.asarray(predicted_centre).flatten()
+        y_mid = (y_upper + y_lower) / 2
+        beta_hat = np.linalg.lstsq(Phi, y_mid, rcond=None)[0]
+        residuals = y_mid - Phi @ beta_hat
+        sigma2 = np.mean(residuals**2)
+        sigma = np.sqrt(sigma2)
+
+        # t-value
+        n = len(latent_test)
+        t_val = t.ppf(1 - self.alpha / 2, df=n - 1)
+        r = 0.5 * (y_upper_pred - y_lower_pred)
+
+        # Prediction standard error
+        Phi_T_Phi_inv = np.linalg.inv(
+            Phi.T @ Phi + self.lambda_reg * np.eye(Phi.shape[1]))
+        SE_pred = sigma * \
+            np.sqrt(1 + np.sum((latent_test @ Phi_T_Phi_inv) * latent_test, axis=1))
+
+        # Combine statistical and zonotopic uncertainty
+        y_pred_min_stat = predicted_centre - r - t_val * SE_pred
+        y_pred_max_stat = predicted_centre + r + t_val * SE_pred
+
+        return {
+            "pred_centre": predicted_centre,
+            "Beta_zono": Beta_zono,
+            "Yhat_zono": Yhat_zono,
+            "y_lower_pred": y_lower_pred,
+            "y_upper_pred": y_upper_pred,
+            "pi_lower": y_pred_min_stat,
+            "pi_upper": y_pred_max_stat,
+        }
+
+    def predict(
+        self,
+        x_train: torch.Tensor,
+        y_lower: torch.Tensor,
+        y_upper: torch.Tensor,
+        n_points: int,
+    ):
+        """
+        Compute last-layer zonotope bounds and statistical prediction intervals.
+
+        Parameters
+        ----------
+        x_train : torch.Tensor
+            Training inputs.
+        y_lower, y_upper : numpy.ndarray
+            Lower and upper interval endpoints for training targets.
+        n_points : int, optional
+            Number of points to evaluate for visualization / interpolation.
+
+        Returns
+        -------
+        dict
+            Dictionary containing:
+            - y_lower_pred, y_upper_pred : zonotopic bounds
+            - pi_lower, pi_upper : statistical prediction intervals
+            - Beta_zono, Yhat_zono : zonotopic representations
+        """
+        self.centre_net.eval()
+
+        # Sort by input for clean visualization
+        x_sorted, idx = torch.sort(x_train, dim=0)
+        y_lb_sorted = y_lower[idx]
+        y_ub_sorted = y_upper[idx]
+
+        # Generate uniform test grid
+        x_plot = torch.linspace(
+            x_train.min(), x_train.max(), n_points).unsqueeze(1)
+
+        with torch.no_grad():
+            # Predictions and latents for test points
+            centre_pred, latent_test = self.centre_net(
+                x_plot, return_latent=True)
+
+            # Latents for training points
+            _, latent_train = self.centre_net(x_sorted, return_latent=True)
+
+        # Convert to numpy
+        latent_train_np = latent_train.numpy()
+        latent_test_np = latent_test.numpy()
+        y_lb_np = y_lb_sorted.flatten()
+        y_ub_np = y_ub_sorted.flatten()
+
+        return self._compute_zonotope_bounds(
+            predicted_centre=centre_pred.cpu().numpy(),
+            latent_train=latent_train_np,
+            y_lower=y_lb_np,
+            y_upper=y_ub_np,
+            latent_test=latent_test_np,
+        )

zonolayer-0.1.0/zonolayer/version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

zonolayer-0.1.0/zonolayer/zonotope.py

@@ -0,0 +1,29 @@
+import numpy as np
+
+
+class Zonotope:
+    def __init__(self, centre, generators):
+        self.centre = np.array(centre).reshape(-1)         # shape (n,)
+        self.generators = np.atleast_2d(generators)        # shape (n, m)
+        if self.generators.shape[0] != self.centre.shape[0]:
+            raise ValueError("Generators must have same dimension as centre")
+        self.n = self.centre.shape[0]   # dimension
+        self.m = self.generators.shape[1]  # number of generators
+
+    def minkowski_sum(self, other):
+        new_centre = self.centre + other.centre
+        new_generators = np.hstack((self.generators, other.generators))
+        return Zonotope(new_centre, new_generators)
+
+    # Outer Approx. of the zonotope - Affine Arithmetic Paper
+    def output_interval(self):
+        # sum across generators
+        radius = np.sum(np.abs(self.generators), axis=1)
+        lower = self.centre - radius
+        upper = self.centre + radius
+        return lower, upper
+
+    def affine_map(self, A, b=None):
+        new_centre = A @ self.centre + (b if b is not None else 0)
+        new_generators = A @ self.generators
+        return Zonotope(new_centre, new_generators)

zonolayer-0.1.0/zonolayer.egg-info/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: zonolayer
+Version: 0.1.0
+Summary: Last-layer uncertainty modeling via zonotopic representations.
+Author: Matthew McCann, Marco De Angelis
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/MattCodes03/zonolayer
+Project-URL: Repository, https://github.com/MattCodes03/zonolayer
+Project-URL: Bug Tracker, https://github.com/MattCodes03/zonolayer/issues
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: torch
+Requires-Dist: matplotlib
+Dynamic: license-file
+
+# Zonolayer
+
+[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![PyPI Version](https://img.shields.io/pypi/v/zonolayer)](https://pypi.org/project/zonolayer/)
+
+**Zonolayer** is a Python package for **last-layer uncertainty modeling via zonotopic representations**.  
+It provides **zonotopic output bounds** and **statistical prediction intervals** for neural networks with interval-bounded outputs, enabling precise and interpretable uncertainty quantification in regression tasks.
+
+---
+
+## Features
+
+- Compute **zonotopic bounds** for last-layer outputs.
+- Combine **statistical prediction intervals** with interval uncertainty.
+- Compatible with PyTorch networks exposing latent features.
+- Modular, research-friendly, and easy to use.
+
+By default, Zonolayer relies on **NumPy** for all numerical computations and interval handling.  
+
+If you require more advanced interval arithmetic (e.g., using [`pyinterval`](https://pypi.org/project/pyinterval/) or other specialized packages), you can install the optional dependencies and modify the code accordingly, or submit a request for support to be added. I appreciate any and all feedback.
+
+---
+
+## Installation
+
+Ensure all requirements from `requirements.txt` are installed to reduce any potential issues.
+
+```bash
+pip install zonolayer
+```
+
+---
+## Getting Started
+See `basic_usage.py` in the examples directory for the quickest method to get up and running and start experimenting with the library.
+

zonolayer-0.1.0/zonolayer.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+setup.cfg
+zonolayer/__init__.py
+zonolayer/core.py
+zonolayer/version.py
+zonolayer/zonotope.py
+zonolayer.egg-info/PKG-INFO
+zonolayer.egg-info/SOURCES.txt
+zonolayer.egg-info/dependency_links.txt
+zonolayer.egg-info/requires.txt
+zonolayer.egg-info/top_level.txt

zonolayer-0.1.0/zonolayer.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

zonolayer-0.1.0/zonolayer.egg-info/requires.txt

@@ -0,0 +1,3 @@
+numpy
+torch
+matplotlib

zonolayer-0.1.0/zonolayer.egg-info/top_level.txt

@@ -0,0 +1 @@
+zonolayer