pyautoencoder 1.0.0__py3-none-any.whl

pyautoencoder/__init__.py

@@ -0,0 +1,4 @@
+from . import loss
+from . import models
+
+__all__ = ['loss', 'models']

pyautoencoder/loss.py

@@ -0,0 +1,92 @@
+import math
+import torch
+import torch.nn.functional as F
+
+def log_likelihood(x: torch.Tensor, 
+                   x_hat: torch.Tensor, 
+                   likelihood: str = 'gaussian') -> torch.Tensor:
+    """
+    Computes the log-likelihood of the reconstructed tensor x_hat given the original tensor x,
+    under either a Bernoulli or Gaussian likelihood assumption with unit variance and i.i.d. samples,
+    without applying any reduction.
+
+    Args:
+        x (torch.Tensor): Ground truth input tensor.
+        x_hat (torch.Tensor): Reconstructed tensor.
+        likelihood (str): Type of likelihood model to use: 'bernoulli' or 'gaussian'.
+
+    Returns:
+        torch.Tensor: The log-likelihood value (i.e., negative of the appropriate loss function 
+                      with normalization constant included for Gaussian).
+
+    Raises:
+        ValueError: If the likelihood type is not one of 'bernoulli' or 'gaussian'.
+
+    Notes:
+        - Bernoulli likelihood uses binary cross-entropy loss.
+        - Gaussian likelihood assumes unit variance and computes:
+              log p(x | x_hat) = -0.5 * ||x - x_hat||^2 - (D/2) * log(2pi)
+          where D is the number of features per sample.
+    """
+    likelihood = likelihood.lower()
+    if likelihood not in ['bernoulli', 'gaussian']:
+        raise ValueError(f"Unknown likelihood: '{likelihood}'. Choose 'bernoulli' or 'gaussian'.")
+
+    if likelihood == 'bernoulli':
+        return -F.binary_cross_entropy(x_hat, x, reduction='none')
+    
+    if likelihood == 'gaussian':
+        D = x[0].numel()
+        mse = F.mse_loss(x_hat, x, reduction='none')
+        norm_constant = 0.5 * D * math.log(2 * math.pi)
+        return -0.5 * mse - norm_constant
+    
+def ELBO(x: torch.Tensor, 
+         x_hat: torch.Tensor, 
+         mu: torch.Tensor, 
+         log_var: torch.Tensor,
+         likelihood: str = 'gaussian',
+         beta: float = 1.0) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+    """
+    Computes the Evidence Lower Bound (ELBO) for a Variational Autoencoder.
+
+    Args:
+        x (torch.Tensor): Original input tensor of shape [B, ...].
+        x_hat (torch.Tensor): Reconstructed samples of shape [B, L, ...], where L is the number of latent samples.
+        mu (torch.Tensor): Mean of the approximate posterior q(z|x), shape [B, latent_dim].
+        log_var (torch.Tensor): Log-variance of q(z|x), shape [B, latent_dim].
+        likelihood (str): Likelihood model to use: 'gaussian' or 'bernoulli'.
+        beta (float): Weighting factor for the KL divergence term (used in beta-VAE).
+
+    Returns:
+        tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+            - ELBO (scalar): The final ELBO estimate averaged over the batch.
+            - log_p_x_given_z (scalar): Expected log-likelihood term.
+            - kl_divergence (scalar): KL divergence term.
+
+    Notes:
+        The reconstruction term is averaged over the latent samples L and the batch.
+        The KL divergence is computed assuming a standard normal prior p(z).
+    """
+    B, L = x_hat.size(0), x_hat.size(1)
+
+    # Log-likelihood E_q[log p(x|z)]
+    x_exp = x.unsqueeze(1).expand(-1, L, *([-1] * (x.ndim - 1)))
+    log_p_x_given_z = log_likelihood(x_exp, x_hat, likelihood=likelihood)
+    log_p_x_given_z = log_p_x_given_z.view(B, L, -1).sum(-1)
+    log_p_x_given_z = log_p_x_given_z.mean(dim=1)
+
+    # KL divergence KL(q(z|x) || p(z)) = log q(z|x) - log p(z)
+    kl_divergence = -0.5 * torch.sum(1 + log_var - mu.pow(2) - log_var.exp(), dim=-1)
+
+    # ELBO
+    elbo_per_sample = log_p_x_given_z - beta * kl_divergence
+
+    # Final metrics
+    elbo = elbo_per_sample.mean()
+    log_p_x_given_z = log_p_x_given_z.mean()
+    kl_divergence = kl_divergence.mean()
+
+    return elbo, log_p_x_given_z, kl_divergence
+
+__all__ = ['log_likelihood', 'ELBO']

pyautoencoder/models/__init__.py

@@ -0,0 +1,4 @@
+from .autoencoder import Autoencoder
+from .variational import VariationalAutoencoder
+
+__all__ = ['VariationalAutoencoder', 'Autoencoder']

pyautoencoder/models/autoencoder.py

@@ -0,0 +1,39 @@
+from typing import Tuple
+import torch
+import torch.nn as nn
+
+class Autoencoder(nn.Module):
+    """
+    A simple Autoencoder model.
+
+    This class encapsulates an autoencoder composed of a user-defined encoder and decoder.
+    The encoder maps the input to a latent representation, and the decoder reconstructs the input from the latent space.
+
+    Args:
+        encoder (nn.Module): A neural network that encodes the input into a latent representation.
+        decoder (nn.Module): A neural network that decodes the latent representation back to the input space.
+
+    Methods:
+        forward(x): Computes the reconstructed input and latent representation.
+        encode(x): Returns the latent representation without computing gradients (inference mode) and in eval mode.
+
+    Returns:
+        Tuple[torch.Tensor, torch.Tensor]:
+            - x_hat: The reconstructed input.
+            - z: The latent representation.
+    """
+    def __init__(self, encoder: nn.Module, decoder: nn.Module):
+        super().__init__()
+        
+        self.encoder = encoder
+        self.decoder = decoder
+
+    def forward(self, x: torch.Tensor) -> Tuple[torch.Tensor, torch.Tensor]:
+        z = self.encoder(x)
+        x_hat = self.decoder(z)
+        return x_hat, z
+    
+    @torch.inference_mode()
+    def encode(self, x: torch.Tensor) -> torch.Tensor:
+        self.eval()
+        return self.encoder(x)

pyautoencoder/models/variational/__init__.py

@@ -0,0 +1,3 @@
+from .vae import VariationalAutoencoder
+
+__all__ = ['VariationalAutoencoder']

pyautoencoder/models/variational/stochastic_layers.py

@@ -0,0 +1,33 @@
+import torch
+import torch.nn as nn
+
+class FullyFactorizedGaussian(nn.Module):
+    def __init__(self, latent_dim: int):
+        super().__init__()
+        self.mu = nn.LazyLinear(latent_dim)
+        self.log_var = nn.LazyLinear(latent_dim)
+
+    def forward(self, x: torch.Tensor, L: int = 1):
+        """
+        Applies the reparameterization trick to sample latent variables z ~ N(mu, exp(log_var)).
+
+        Args:
+            x (torch.Tensor): Input tensor of shape [B, ...], where B is the batch size.
+            L (int): Number of samples per input in the latent space.
+
+        Returns:
+            torch.Tensor: Sampled latent variables z of shape [B, L, latent_dim].
+        """
+        mu = self.mu(x)
+        log_var = self.log_var(x)
+
+        if self.training:
+            std = torch.exp(0.5 * log_var)
+            mu = mu.unsqueeze(1).expand(-1, L, -1)
+            std = std.unsqueeze(1).expand(-1, L, -1)
+            eps = torch.randn_like(std)
+            z = mu + std * eps
+        else:
+            z = mu.unsqueeze(1).expand(-1, L, -1)
+            
+        return z, mu, log_var

pyautoencoder/models/variational/vae.py

@@ -0,0 +1,65 @@
+from .stochastic_layers import FullyFactorizedGaussian
+from typing import Tuple
+import torch
+import torch.nn as nn
+
+class VariationalAutoencoder(nn.Module):
+    """
+    Standard Variational Autoencoder (VAE) implementation using the reparameterization trick.
+
+    This model assumes a single latent layer and consists of:
+    - an encoder producing parameters of the approximate posterior q(z|x),
+    - a decoder reconstructing the input from latent samples z.
+
+    Args:
+        encoder (nn.Module): Encoder network mapping input x to a latent representation.
+        decoder (nn.Module): Decoder network reconstructing x from latent variable z.
+        latent_dim (int): Dimensionality of the latent space.
+    """
+    def __init__(self, 
+                 encoder: nn.Module, 
+                 decoder: nn.Module, 
+                 latent_dim: int,
+                 sampling_layer: str = 'fully_factorized_gaussian'):
+        super().__init__()
+
+        self.latent_dim = latent_dim
+        self.encoder = encoder
+        self.decoder = decoder
+        if sampling_layer == 'fully_factorized_gaussian':
+            self.sampling_layer = FullyFactorizedGaussian(latent_dim=latent_dim)
+        else:
+            raise ValueError(f'Sampling layer {sampling_layer} not available.')
+        
+    def forward(self, 
+                x: torch.Tensor, 
+                L: int = 1) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]:
+        """
+        Forward pass of the VAE.
+
+        Encodes the input to obtain parameters of q(z|x), samples latent variables z using
+        the reparameterization trick, and decodes z to reconstruct the input.
+
+        Args:
+            x (torch.Tensor): Input tensor of shape [B, ...], where B is the batch size.
+            L (int): Number of samples per input for Monte Carlo estimates (default: 1).
+
+        Returns:
+            Tuple containing:
+                - x_hat (torch.Tensor): Reconstructed inputs, shape [B, L, ...].
+                - z (torch.Tensor): Sampled latent variables, shape [B, L, latent_dim].
+                - mu (torch.Tensor): Mean of q(z|x), shape [B, latent_dim].
+                - log_var (torch.Tensor): Log-variance of q(z|x), shape [B, latent_dim].
+        """
+        B = x.size(0)
+
+        # z ~ q(z|x)
+        x_f = self.encoder(x)
+        z, mu, log_var = self.sampling_layer(x=x_f, L=L)
+
+        # p(x|z)
+        z_flat = z.reshape(B * L, -1)
+        x_hat = self.decoder(z_flat)
+        x_hat = x_hat.view(B, L, *x.shape[1:])
+
+        return x_hat, z, mu, log_var

pyautoencoder-1.0.0.dist-info/METADATA

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: pyautoencoder
+Version: 1.0.0
+Summary: A Python package offering implementations of state-of-the-art autoencoder architectures in PyTorch.
+Home-page: https://github.com/andrea-pollastro/pyautoencoder
+Author: Andrea Pollastro
+License: MIT
+Keywords: autoencoder,vae,pytorch,deep learning,machine learning,representation learning,dimensionality reduction,generative models
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.0.0
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+<p align="center">
+  <img src="assets/logo_nobackground.png" alt="pyautoencoders_logo" width="500"/>
+</p>
+
+**pyautoencoder** is a lightweight Python package offering clean, minimal implementations of foundational autoencoder architectures in PyTorch. 
+It is designed for researchers, educators, and practitioners seeking a reliable base for experimentation, extension, or instruction.
+
+## 📦 Installation
+
+```bash
+pip install pyautoencoder
+```
+
+Or install from source:
+```bash
+git clone https://github.com/andrea-pollastro/pyautoencoder.git
+cd pyautoencoder
+pip install -e .
+```
+
+## 🚀 Quick Example
+
+```python
+import torch
+from pyautoencoder.models import Autoencoder
+
+# Define encoder and decoder
+encoder = torch.nn.Sequential(
+    torch.nn.Flatten(),
+    torch.nn.Linear(784, 32)
+)
+
+decoder = torch.nn.Sequential(
+    torch.nn.Linear(32, 784),
+    torch.nn.Unflatten(1, (1, 28, 28))
+)
+
+# Initialize model
+model = Autoencoder(encoder, decoder)
+
+# Forward pass
+x = torch.randn(64, 1, 28, 28)
+x_hat, z = model(x)
+```
+
+## 🗺️ Roadmap
+- [x] Autoencoder (AE)
+- [x] Variational Autoencoder (VAE)
+- [ ] Hierarchical VAE (HVAE)
+- [ ] Importance-Weighted AE (IWAE)
+- [ ] Denoising Autoencoder (DAE)
+- [ ] Sparse Autoencoder (SAE)
+
+## 🤝 Contributing
+Contributions are welcome — especially new autoencoder variants, training examples, and documentation improvements.
+Please open an issue or pull request to discuss any changes.
+
+## 📝 Citing
+```bibtex
+@misc{pollastro2025pyautoencoder,
+  Author = {Andrea Pollastro},
+  Title = {pyautoencoder},
+  Year = {2025},
+  Publisher = {GitHub},
+  Journal = {GitHub repository},
+  Howpublished = {\url{https://github.com/andrea-pollastro/pyautoencoder}}
+}
+```
+
+## 📄 License
+This project is licensed under the MIT License. See the LICENSE file for details.

pyautoencoder-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+pyautoencoder/__init__.py,sha256=GaNI1Tfw-HsmpUDJhpfQObQQAOqrvswIZQLbT6-Y5FM,72
+pyautoencoder/loss.py,sha256=vu7tF9XpoVLc4IL0LInGLI3T1GpNaiGHTMgPlfIlars,3892
+pyautoencoder/models/__init__.py,sha256=LkoZn8E3ZKd4rR2o8WaaFwwPywwHvo9Id9iPnok7-lA,140
+pyautoencoder/models/autoencoder.py,sha256=Yo0gc6LG6QcJhSgvT4sL9KCa_MEyfxiA4JB6KKSSMSs,1431
+pyautoencoder/models/variational/__init__.py,sha256=2Fo7yTZf8ps4qBKI60qkUH_1k2g5V5057jhUqv6z4OI,79
+pyautoencoder/models/variational/stochastic_layers.py,sha256=QM8jklRE25z-NMGjDXlfmNwl2rCrxHKeL3cg79swV-U,1128
+pyautoencoder/models/variational/vae.py,sha256=Mp9Bh07jFmVivpiFrAoWc2OdVQbXFxa0ncRMPKiYT8I,2616
+pyautoencoder-1.0.0.dist-info/licenses/LICENSE,sha256=gZFB44cBo3AAs5_m9gUl8QEv4uwK69BzO97FMh3plM4,1094
+pyautoencoder-1.0.0.dist-info/METADATA,sha256=UBafRlML_tG1ffP7lGqtzY24GEYnySdnZ4jOFgJUWeA,3290
+pyautoencoder-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pyautoencoder-1.0.0.dist-info/top_level.txt,sha256=PwjW6SQ7aRZohAwWaqtZDP8qpn4dWIUHrVVOqWfwMdo,14
+pyautoencoder-1.0.0.dist-info/RECORD,,

pyautoencoder-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pyautoencoder-1.0.0.dist-info/licenses/LICENSE

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

pyautoencoder-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pyautoencoder