Skip to main content

PyPI - Python Version PyPI Status PyPI Status license Tests codecov

StochMan - Stochastic Manifolds made easier

StochMan (Stochastic Manifolds) is a collection of elementary algorithms for computations on random manifolds learned from finite noisy data. Each algorithm assume that the considered manifold model implement a specific set of interfaces.

Installation

For the latest release

pip install stochman

For master version with most recent changes we recommend:

git clone https://github.com/MachineLearningLifeScience/stochman
cd stochman
python setup.py install

API overview

StochMan includes a number of modules that each defines a set of functionalities for working with manifold data.

stochman.nnj: torch.nn with jacobians

Key to working with Riemannian geometry is the ability to compute jacobians. The jacobian matrix contains the first order partial derivatives. stochman.nnj provides plug-in replacements for the many used torch.nn layers such as Linear, BatchNorm1d etc. and commonly used activation functions such as ReLU, Sigmoid etc. that enables fast computations of jacobians between the input to the layer and the output.

import torch
from stochman import nnj

model = nnj.Sequential(nnj.Linear(10, 5),
                       nnj.ReLU())
x = torch.randn(100, 10)
y, J = model(x, jacobian=True)
print(y.shape) # output from model: torch.size([100, 5])
print(J.shape) # jacobian between input and output: torch.size([100, 5, 10])

stochman.manifold: Interface for working with Riemannian manifolds

A manifold can be constructed simply by specifying its metric. The example below shows a toy example where the metric grows with the distance to the origin.

import torch
from stochman.manifold import Manifold

class MyManifold(Manifold):
    def metric(self, c, return_deriv=False):
        N, D = c.shape  # N is number of points where we evaluate the metric; D is the manifold dimension
        sq_dist_to_origin = torch.sum(c**2, dim=1, keepdim=True)  # Nx1
        G = (1 + sq_dist_to_origin).unsqueeze(-1) * torch.eye(D).repeat(N, 1, 1)  # NxDxD
        return G
        
model = MyManifold()
p0, p1 = torch.randn(1, 2), torch.randn(1, 2)
c, _ = model.connecting_geodesic(p0, p1)  # geodesic between two random points

If you manifold is embedded (e.g. an autoencoder) then you only have to provide a function for realizing the embedding (i.e. a decoder) and StochMan takes care of the rest (you, however, have to learn the autoencoder yourself).

import torch
from stochman.manifold import EmbeddedManifold

class Autoencoder(EmbeddedManifold):
    def embed(self, c, jacobian = False):
        return self.decode(c)
        
model = Autoencoder()
p0, p1 = torch.randn(1, 2), torch.randn(1, 2)
c, _ = model.connecting_geodesic(p0, p1)  # geodesic between two random points

stochman.geodesic: computing geodesics made easy!

Geodesics are energy-minimizing curves, and StochMan computes them as such. You can use the high-level Manifold interface or the more explicit one:

import torch
from stochman.geodesic import geodesic_minimizing_energy
from stochman.curves import CubicSpline

model = MyManifold()
p0, p1 = torch.randn(1, 2), torch.randn(1, 2)
curve = CubicSpline(p0, p1)
geodesic_minimizing_energy(curve, model)

stochman.curves: Simple curve objects

We often want to manipulate curves when computing geodesics. StochMan provides an implementation of cubic splines and discrete curves, both with the end-points fixed.

import torch
from stochman.curves import CubicSpline

p0, p1 = torch.randn(1, 2), torch.randn(1, 2)
curve = CubicSpline(p0, p1)

t = torch.linspace(0, 1, 50)
ct = curve(t)  # 50x2

Licence

Please observe the Apache 2.0 license that is listed in this repository.

BibTeX

If you want to cite the framework feel free to use this (but only if you loved it 😊):

@article{software:stochman,
  title={StochMan},
  author={Nicki S. Detlefsen and Alison Pouplin and Cilie W. Feldager and Cong Geng and Dimitris Kalatzis and Helene Hauschultz and Miguel González Duque and Frederik Warburg and Marco Miani and Søren Hauberg},
  journal={GitHub. Note: https://github.com/MachineLearningLifeScience/stochman/},
  year={2021}
}

Metadata

Release files for stochman 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for stochman 0.3.0
File Size Uploaded Provenance Actions
stochman-0.3.0.tar.gz 33.4 kB Without provenance Details for stochman-0.3.0.tar.gz

Release files / stochman-0.3.0.tar.gz

Download URL stochman-0.3.0.tar.gz
Size 33.4 kB
Tags Source
SHA-256 checksum
How to use checksums
ea61ac094da19f5552474231ba7be3d9d3adbaa86cc93caeec6356410beb8843
BLAKE2b-256 checksum
How to use checksums
35f50dfe4bfa43ceca1b1e966120008e427a95795645bbf5c1feb2d541a9364d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.3.0 pkginfo/1.7.0 requests/2.25.1 setuptools/58.0.4 requests-toolbelt/0.9.1 tqdm/4.56.0 CPython/3.8.12

Security for stochman 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page