multipers 2.2.3__cp310-cp310-win_amd64.whl

multipers/torch/diff_grids.py

@@ -0,0 +1,217 @@
+from typing import Literal
+
+import numpy as np
+import torch
+from pykeops.torch import LazyTensor
+
+
+def get_grid(strategy: Literal["exact", "regular_closest", "regular_left", "quantile"]):
+    """
+    Given a strategy, returns a function of signature
+    `(num_pts, num_parameter), int --> Iterable[1d array]`
+    that generates a torch-differentiable grid from a set of points,
+    and a resolution.
+    """
+    match strategy:
+        case "exact":
+            return _exact_grid
+        case "regular_closest":
+            return _regular_closest_grid
+        case "regular_left":
+            return _regular_left_grid
+        case "quantile":
+            return _quantile_grid
+        case _:
+            raise ValueError(
+                f"""
+Unimplemented strategy {strategy}.
+Available ones : exact, regular_closest, regular_left, quantile.
+"""
+            )
+
+
+def todense(grid: list[torch.Tensor]):
+    return torch.cartesian_prod(*grid)
+
+
+def _exact_grid(filtration_values, r=None):
+    grid = tuple(_unique_any(f) for f in filtration_values)
+    return grid
+
+
+def _regular_closest_grid(filtration_values, r: int):
+    grid = tuple(_regular_closest(f, r) for f in filtration_values)
+    return grid
+
+
+def _regular_left_grid(filtration_values, r: int):
+    grid = tuple(_regular_left(f, r) for f in filtration_values)
+    return grid
+
+
+def _quantile_grid(filtration_values, r: int):
+    qs = torch.linspace(0, 1, r)
+    grid = tuple(_unique_any(torch.quantile(f, q=qs)) for f in filtration_values)
+    return grid
+
+
+def _unique_any(x, assume_sorted=False, remove_inf: bool = True):
+    if not assume_sorted:
+        x, _ = x.sort()
+    if remove_inf and x[-1] == torch.inf:
+        x = x[:-1]
+    with torch.no_grad():
+        y = x.unique()
+        idx = torch.searchsorted(x, y)
+    x = torch.cat([x, torch.tensor([torch.inf])])
+    return x[idx]
+
+
+def _regular_left(f, r: int, unique: bool = True):
+    f = _unique_any(f)
+    with torch.no_grad():
+        f_regular = torch.linspace(f[0].item(), f[-1].item(), r, device=f.device)
+        idx = torch.searchsorted(f, f_regular)
+    f = torch.cat([f, torch.tensor([torch.inf])])
+    if unique:
+        return _unique_any(f[idx])
+    return f[idx]
+
+
+def _regular_closest(f, r: int, unique: bool = True):
+    f = _unique_any(f)
+    with torch.no_grad():
+        f_reg = torch.linspace(
+            f[0].item(), f[-1].item(), steps=r, dtype=f.dtype, device=f.device
+        )
+        _f = LazyTensor(f[:, None, None])
+        _f_reg = LazyTensor(f_reg[None, :, None])
+        indices = (_f - _f_reg).abs().argmin(0).ravel()
+    f = torch.cat([f, torch.tensor([torch.inf])])
+    f_regular_closest = f[indices]
+    if unique:
+        f_regular_closest = _unique_any(f_regular_closest)
+    return f_regular_closest
+
+
+def evaluate_in_grid(pts, grid):
+    """Evaluates points (assumed to be coordinates) in this grid.
+    Input
+    -----
+     - pts: (num_points, num_parameters) array
+     - grid: Iterable of 1-d array, for each parameter
+
+    Returns
+    -------
+     - array of shape like points of dtype like grid.
+    """
+    # grid = [torch.cat([g, torch.tensor([torch.inf])]) for g in grid]
+    # new_pts = torch.empty(pts.shape, dtype=grid[0].dtype, device=grid[0].device)
+    # for parameter, pt_of_parameter in enumerate(pts.T):
+    #     new_pts[:, parameter] = grid[parameter][pt_of_parameter]
+    return torch.cat(
+        [
+            grid[parameter][pt_of_parameter][:, None]
+            for parameter, pt_of_parameter in enumerate(pts.T)
+        ],
+        dim=1,
+    )
+
+
+def evaluate_mod_in_grid(mod, grid, box=None):
+    """Given an MMA module, pushes it into the specified grid.
+    Useful for e.g., make it differentiable.
+
+    Input
+    -----
+     - mod: PyModule
+     - grid: Iterable of 1d array, for num_parameters
+    Ouput
+    -----
+    torch-compatible module in the format:
+    (num_degrees) x (num_interval of degree) x ((num_birth, num_parameter), (num_death, num_parameters))
+
+    """
+    if box is not None:
+        grid = tuple(
+            torch.cat(
+                [
+                    box[0][[i]],
+                    _unique_any(
+                        grid[i].clamp(min=box[0][i], max=box[1][i]), assume_sorted=True
+                    ),
+                    box[1][[i]],
+                ]
+            )
+            for i in range(len(grid))
+        )
+    (birth_sizes, death_sizes), births, deaths = mod.to_flat_idx(grid)
+    births = evaluate_in_grid(births, grid)
+    deaths = evaluate_in_grid(deaths, grid)
+    diff_mod = tuple(
+        zip(
+            births.split_with_sizes(birth_sizes.tolist()),
+            deaths.split_with_sizes(death_sizes.tolist()),
+        )
+    )
+    return diff_mod
+
+
+def evaluate_mod_in_grid__old(mod, grid, box=None):
+    """Given an MMA module, pushes it into the specified grid.
+    Useful for e.g., make it differentiable.
+
+    Input
+    -----
+     - mod: PyModule
+     - grid: Iterable of 1d array, for num_parameters
+    Ouput
+    -----
+    torch-compatible module in the format:
+    (num_degrees) x (num_interval of degree) x ((num_birth, num_parameter), (num_death, num_parameters))
+
+    """
+    from pykeops.numpy import LazyTensor
+
+    with torch.no_grad():
+        if box is None:
+            # box = mod.get_box()
+            box = np.asarray([[g[0] for g in grid], [g[-1] for g in grid]])
+        S = mod.dump()[1]
+
+        def get_idx_parameter(A, G, p):
+            g = G[p].numpy() if isinstance(G[p], torch.Tensor) else np.asarray(G[p])
+            la = LazyTensor(np.asarray(A, dtype=g.dtype)[None, :, [p]])
+            lg = LazyTensor(g[:, None, None])
+            return (la - lg).abs().argmin(0)
+
+        Bdump = np.concatenate([s[0] for s in S], axis=0).clip(box[[0]], box[[1]])
+        B = np.concatenate(
+            [get_idx_parameter(Bdump, grid, p) for p in range(mod.num_parameters)],
+            axis=1,
+            dtype=np.int64,
+        )
+        Ddump = np.concatenate([s[1] for s in S], axis=0, dtype=np.float32).clip(
+            box[[0]], box[[1]]
+        )
+        D = np.concatenate(
+            [get_idx_parameter(Ddump, grid, p) for p in range(mod.num_parameters)],
+            axis=1,
+            dtype=np.int64,
+        )
+
+    BB = evaluate_in_grid(B, grid)
+    DD = evaluate_in_grid(D, grid)
+
+    b_idx = tuple((len(s[0]) for s in S))
+    d_idx = tuple((len(s[1]) for s in S))
+    BBB = BB.split_with_sizes(b_idx)
+    DDD = DD.split_with_sizes(d_idx)
+
+    splits = np.concatenate([[0], mod.degree_splits(), [len(BBB)]])
+    splits = torch.from_numpy(splits)
+    out = [
+        list(zip(BBB[splits[i] : splits[i + 1]], DDD[splits[i] : splits[i + 1]]))
+        for i in range(len(splits) - 1)
+    ]  ## For some reasons this kills the gradient ???? pytorch bug
+    return out

multipers/torch/rips_density.py

@@ -0,0 +1,304 @@
+from typing import Callable, Literal, Optional
+
+import numpy as np
+import torch
+from gudhi.rips_complex import RipsComplex
+
+import multipers as mp
+from multipers.ml.convolutions import DTM, KDE
+from multipers.simplex_tree_multi import _available_strategies
+from multipers.torch.diff_grids import get_grid
+
+
+def function_rips_signed_measure_old(
+    x,
+    theta: Optional[float] = None,
+    function: Literal["dtm", "gaussian", "exponential"] | Callable = "dtm",
+    threshold: float = np.inf,
+    grid_strategy: _available_strategies = "regular_closest",
+    resolution: int = 100,
+    return_original: bool = False,
+    return_st: bool = False,
+    safe_conversion: bool = False,
+    num_collapses: int = -1,
+    expand_collapse: bool = False,
+    dtype=torch.float32,
+    **sm_kwargs,
+):
+    """
+    Computes a torch-differentiable function-rips signed measure.
+
+    Input
+    -----
+     - x (num_pts, dim) : The point cloud
+     - theta: For density-like functions : the bandwidth
+     - threshold : rips threshold
+     - function : Either "dtm", "gaussian", or "exponenetial" or Callable.
+       Function to compute the second parameter.
+     - grid_strategy: grid coarsenning strategy.
+     - resolution : when coarsenning, the target resolution,
+     - return_original : Also returns the non-differentiable signed measure.
+     - safe_conversion : Activate this if you encounter crashes.
+     - **kwargs : for the signed measure computation.
+    """
+    assert isinstance(x, torch.Tensor)
+    if function == "dtm":
+        assert theta is not None, "Provide a theta to compute DTM"
+        codensity = DTM(masses=[theta]).fit(x).score_samples_diff(x)[0].type(dtype)
+    elif function in ["gaussian", "exponential"]:
+        assert theta is not None, "Provide a theta to compute density estimation"
+        codensity = (
+            -KDE(
+                bandwidth=theta,
+                kernel=function,
+                return_log=True,
+            )
+            .fit(x)
+            .score_samples(x)
+            .type(dtype)
+        )
+    else:
+        assert callable(function), "Function has to be callable"
+        if theta is None:
+            codensity = function(x).type(dtype)
+        else:
+            codensity = function(x, theta=theta).type(dtype)
+
+    distance_matrix = torch.cdist(x, x).type(dtype)
+    if threshold < np.inf:
+        distance_matrix[distance_matrix > threshold] = np.inf
+
+    st = RipsComplex(
+        distance_matrix=distance_matrix.detach(), max_edge_length=threshold
+    ).create_simplex_tree()
+    # detach makes a new (reference) tensor, without tracking the gradient
+    st = mp.SimplexTreeMulti(st, num_parameters=2, safe_conversion=safe_conversion)
+    st.fill_lowerstar(
+        codensity.detach(), parameter=1
+    )  # fills the codensity in the second parameter of the simplextree
+
+    # simplificates the simplextree for computation, the signed measure will be recovered from the copy afterward
+    st_copy = st.grid_squeeze(
+        grid_strategy=grid_strategy, resolution=resolution, coordinate_values=True
+    )
+    if sm_kwargs.get("degree", None) is None and sm_kwargs.get("degrees", [None]) == [
+        None
+    ]:
+        expansion_degree = st.num_vertices
+    else:
+        expansion_degree = (
+            max(np.max(sm_kwargs.get("degrees", 1)), sm_kwargs.get("degree", 1)) + 1
+        )
+    st.collapse_edges(num=num_collapses)
+    if not expand_collapse:
+        st.expansion(expansion_degree)  # edge collapse
+    sms = mp.signed_measure(st, **sm_kwargs)  # computes the signed measure
+    del st
+
+    simplices_list = tuple(
+        s for s, _ in st_copy.get_simplices()
+    )  # not optimal, we may want to do that in cython to get edges and nodes
+    sms_diff = []
+    for sm, weights in sms:
+        indices, not_found_indices = st_copy.pts_to_indices(
+            sm, simplices_dimensions=[1, 0]
+        )
+        if sm_kwargs.get("verbose", False):
+            print(
+                f"Found {(1-(indices == -1).mean()).round(2)} indices. \
+                Out : {(indices == -1).sum()}, {len(not_found_indices)}"
+            )
+        sm_diff = torch.empty(sm.shape).type(dtype)
+        # sim_dim = sm_diff.shape[1] // 2
+
+        # fills the Rips-filtrations of the signed measure.
+        # the loop is for the rank invariant
+        for i in range(0, sm_diff.shape[1], 2):
+            idxs = indices[:, i]
+            if (idxs == -1).all():
+                continue
+            useful_idxs = idxs != -1
+            # Retrieves the differentiable values from the distance_matrix
+            if useful_idxs.size > 0:
+                edges_filtrations = torch.cat(
+                    [
+                        distance_matrix[*simplices_list[idx], None]
+                        for idx in idxs[useful_idxs]
+                    ]
+                )
+                # fills theses values into the signed measure
+                sm_diff[:, i][useful_idxs] = edges_filtrations
+        # same for the other axis
+        for i in range(1, sm_diff.shape[1], 2):
+            idxs = indices[:, i]
+            if (idxs == -1).all():
+                continue
+            useful_idxs = idxs != -1
+            if useful_idxs.size > 0:
+                nodes_filtrations = torch.cat(
+                    [codensity[simplices_list[idx]] for idx in idxs[useful_idxs]]
+                )
+                sm_diff[:, i][useful_idxs] = nodes_filtrations
+
+        # fills not-found values as constants
+        if len(not_found_indices) > 0:
+            not_found_indices = indices == -1
+            sm_diff[indices == -1] = torch.from_numpy(sm[indices == -1]).type(dtype)
+
+        sms_diff.append((sm_diff, torch.from_numpy(weights)))
+    flags = [True, return_original, return_st]
+    if np.sum(flags) == 1:
+        return sms_diff
+    return tuple(stuff for stuff, flag in zip([sms_diff, sms, st_copy], flags) if flag)
+
+
+def function_rips_signed_measure(
+    x,
+    theta: Optional[float] = None,
+    function: Literal["dtm", "gaussian", "exponential"] | Callable = "gaussian",
+    threshold: Optional[float] = None,
+    grid_strategy: Literal[
+        "regular_closest", "exact", "quantile", "regular_left"
+    ] = "exact",
+    complex: Literal["rips", "delaunay", "weak_delaunay"] = "rips",
+    resolution: int = 100,
+    safe_conversion: bool = False,
+    num_collapses: Optional[int] = None,
+    expand_collapse: bool = False,
+    dtype=torch.float32,
+    plot=False,
+    # return_st: bool = False,
+    *,
+    log_density: bool = True,
+    vineyard: bool = False,
+    pers_backend=None,
+    **sm_kwargs,
+):
+    """
+    Computes a torch-differentiable function-rips signed measure.
+
+    Input
+    -----
+     - x (num_pts, dim) : The point cloud
+     - theta: For density-like functions : the bandwidth
+     - threshold : rips threshold
+     - function : Either "dtm", "gaussian", or "exponenetial" or Callable.
+       Function to compute the second parameter.
+     - grid_strategy: grid coarsenning strategy.
+     - resolution : when coarsenning, the target resolution,
+     - return_original : Also returns the non-differentiable signed measure.
+     - safe_conversion : Activate this if you encounter crashes.
+     - **kwargs : for the signed measure computation.
+    """
+    if num_collapses is None:
+        num_collapses = -1 if complex == "rips" else None
+    assert isinstance(x, torch.Tensor)
+    if function == "dtm":
+        assert theta is not None, "Provide a theta to compute DTM"
+        codensity = DTM(masses=[theta]).fit(x).score_samples_diff(x)[0].type(dtype)
+    elif function in ["gaussian", "exponential"]:
+        assert theta is not None, "Provide a theta to compute density estimation"
+        codensity = (
+            -KDE(
+                bandwidth=theta,
+                kernel=function,
+                return_log=log_density,
+            )
+            .fit(x)
+            .score_samples(x)
+            .type(dtype)
+        )
+    elif isinstance(function, torch.Tensor):
+        assert (
+            function.ndim == 1 and codensity.shape[0] == x.shape[0]
+        ), """
+        When function is a tensor, it is interpreted as the value of some function over x. 
+        """
+        codensity = function
+    else:
+        assert callable(function), "Function has to be callable"
+        if theta is None:
+            codensity = function(x).type(dtype)
+        else:
+            codensity = function(x, theta=theta).type(dtype)
+
+    distance_matrix = torch.cdist(x, x).type(dtype)
+    distances = distance_matrix.ravel()
+    if complex == "rips":
+        threshold = (
+            distance_matrix.max(axis=1).values.min() if threshold is None else threshold
+        )
+        distances = distances[distances <= threshold]
+    elif complex in ["delaunay", "weak_delaunay"]:
+        complex = "delaunay"
+        distances /= 2
+    else:
+        raise ValueError(
+            f"Unimplemented with complex {complex}. You can use rips or delaunay ftm."
+        )
+
+    # simplificates the simplextree for computation, the signed measure will be recovered from the copy afterward
+    reduced_grid = get_grid(strategy=grid_strategy)((distances, codensity), resolution)
+
+    degrees = sm_kwargs.pop("degrees", [])
+    if sm_kwargs.get("degree", None) is not None:
+        degrees = [sm_kwargs.pop("degree", None)] + degrees
+    if complex == "rips":
+        st = RipsComplex(
+            distance_matrix=distance_matrix.detach(), max_edge_length=threshold
+        ).create_simplex_tree()
+        # detach makes a new (reference) tensor, without tracking the gradient
+        st = mp.SimplexTreeMulti(st, num_parameters=2, safe_conversion=safe_conversion)
+        st.fill_lowerstar(
+            codensity.detach(), parameter=1
+        )  # fills the codensity in the second parameter of the simplextree
+        st = st.grid_squeeze(reduced_grid)
+        st.filtration_grid = []
+        if None in degrees:
+            expansion_degree = st.num_vertices
+        else:
+            expansion_degree = max(degrees) + 1
+        st.collapse_edges(num=num_collapses)
+        if not expand_collapse:
+            st.expansion(expansion_degree)  # edge collapse
+
+        s = mp.Slicer(st, vineyard=vineyard, backend=pers_backend)
+    elif complex == "delaunay":
+        s = mp.slicer.from_function_delaunay(
+            x.detach().numpy(), codensity.detach().numpy()
+        )
+        st = mp.slicer.to_simplextree(s)
+        st.flagify(2)
+        s = mp.Slicer(st, vineyard=vineyard, backend=pers_backend).grid_squeeze(
+            reduced_grid
+        )
+
+    s.filtration_grid = []  ## To enforce minpres to be reasonable
+    if None not in degrees:
+        s = s.minpres(degrees=degrees)
+    else:
+        from joblib import Parallel, delayed
+
+        s = tuple(
+            Parallel(n_jobs=-1, backend="threading")(
+                delayed(lambda d: s if d is None else s.minpres(degree=d))(d)
+                for d in degrees
+            )
+        )
+    ## fix previous hack
+    for stuff in s:
+        # stuff.filtration_grid = reduced_grid ## not necessary
+        stuff.filtration_grid = [[1]] * stuff.num_parameters
+
+    sms = tuple(
+        sm
+        for slicer_of_degree, degree in zip(s, degrees)
+        for sm in mp.signed_measure(
+            slicer_of_degree, grid=reduced_grid, degree=degree, **sm_kwargs
+        )
+    )  # computes the signed measure
+    if plot:
+        mp.plots.plot_signed_measures(
+            tuple((sm.detach().numpy(), w.detach().numpy()) for sm, w in sms)
+        )
+    return sms

multipers-2.2.3.dist-info/LICENSE

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

multipers-2.2.3.dist-info/METADATA

@@ -0,0 +1,134 @@
+Metadata-Version: 2.2
+Name: multipers
+Version: 2.2.3
+Summary: Multiparameter Topological Persistence for Machine Learning
+Author-email: David Loiseaux <david.lapous@proton.me>, Hannah Schreiber <hannah.schreiber@inria.fr>
+Maintainer-email: David Loiseaux <david.lapous@proton.me>
+License: MIT License
+        
+        Copyright (c) 2023 David Loiseaux
+        
+        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.
+        
+Project-URL: source, https://github.com/DavidLapous/multipers
+Project-URL: download, https://pypi.org/project/multipers/#files
+Project-URL: tracker, https://github.com/DavidLapous/multipers/issues
+Project-URL: release notes, https://github.com/DavidLapous/multipers/releases
+Keywords: TDA,Persistence,Multiparameter,sklearn
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: gudhi>=3.8
+Requires-Dist: tqdm
+Requires-Dist: scipy
+Requires-Dist: joblib
+Requires-Dist: matplotlib
+Requires-Dist: scikit-learn
+Requires-Dist: filtration-domination
+Requires-Dist: pykeops
+Requires-Dist: pot
+
+# multipers : Multiparameter Persistence for Machine Learning
+[![Documentation](https://img.shields.io/badge/Documentation-website-blue)](https://davidlapous.github.io/multipers)
+[![DOI](https://joss.theoj.org/papers/10.21105/joss.06773/status.svg)](https://doi.org/10.21105/joss.06773)
+[![PyPI](https://img.shields.io/pypi/v/multipers?color=green)](https://pypi.org/project/multipers)
+[![Build, test](https://github.com/DavidLapous/multipers/actions/workflows/python_PR.yml/badge.svg)](https://github.com/DavidLapous/multipers/actions/workflows/python_PR.yml)
+[![Downloads](https://static.pepy.tech/badge/multipers)](https://pepy.tech/project/multipers)
+<br>
+Scikit-style PyTorch-autodiff multiparameter persistent homology python library. 
+This library aims to provide easy to use and performant strategies for applied multiparameter topology.
+<br> Meant to be integrated in [the Gudhi library](https://gudhi.inria.fr/).
+
+## Quick start
+This library allows computing several representations from "geometrical datasets", e.g., point clouds, images, graphs, that have multiple scales.
+We provide some *nice* pictures in the [documentation](https://davidlapous.github.io/multipers/index.html). 
+A non-exhaustive list of features can be found in the **Features** section.
+
+This library is available [on PyPI](https://pypi.org/project/multipers/) for (reasonably up to date) Linux, macOS and Windows, via
+```sh
+pip install multipers
+```
+
+Windows support is experimental, and some core dependencies are not available on Windows.
+We hence recommend Windows user to use [WSL](https://learn.microsoft.com/en-us/windows/wsl/).
+<br>
+A documentation and building instructions are available
+[here](https://davidlapous.github.io/multipers/compilation.html).
+
+
+## Features, and linked projects
+This library features a bunch of different functions and helpers. See below for a non-exhaustive list.
+<br>Filled box refers to implemented or interfaced code.
+ - [x] [[Multiparameter Module Approximation]](https://arxiv.org/abs/2206.02026) provides the multiparameter simplicial structure, as well as technics for approximating modules, via interval-decomposable modules. It is also very useful for visualization.
+ - [x] [[Stable Vectorization of Multiparameter Persistent Homology using Signed Barcodes as Measures, NeurIPS2023]](https://proceedings.neurips.cc/paper_files/paper/2023/hash/d75c474bc01735929a1fab5d0de3b189-Abstract-Conference.html) provides fast representations of multiparameter persistence modules, by using their signed barcodes decompositions encoded into signed measures. Implemented decompositions : Euler surfaces, Hilbert function, rank invariant (i.e. rectangles). It also provides representation technics for Machine Learning, i.e., Sliced Wasserstein kernels, and Vectorizations.
+ - [x] [[A Framework for Fast and Stable Representations of Multiparameter Persistent Homology Decompositions, NeurIPS2023]](https://proceedings.neurips.cc/paper_files/paper/2023/hash/702b67152ec4435795f681865b67999c-Abstract-Conference.html) Provides a vectorization framework for interval decomposable modules, for Machine Learning. Currently implemented as an extension of MMA.
+ - [x] [[Differentiability and Optimization of Multiparameter Persistent Homology, ICML2024]](https://proceedings.mlr.press/v235/scoccola24a.html) An approach to compute a (clarke) gradient for any reasonable multiparameter persistent invariant. Currently, any `multipers` computation is auto-differentiable using this strategy, provided that the input are pytorch gradient capable tensor.
+ - [x] [[Multiparameter Persistence Landscapes, JMLR]](https://jmlr.org/papers/v21/19-054.html) A vectorization technic for multiparameter persistence modules.
+ - [x] [[Filtration-Domination in Bifiltered Graphs, ALENEX2023]](https://doi.org/10.1137/1.9781611977561.ch3) Allows for 2-parameter edge collapses for 1-critical clique complexes. Very useful to speed up, e.g., Rips-Codensity bifiltrations.
+ - [x] [[Chunk Reduction for Multi-Parameter Persistent Homology, SOCG2019]](https://doi.org/10.4230/LIPIcs.SoCG.2019.37) Multi-filtration preprocessing algorithm for homology computations.
+ - [x] [[Computing Minimal Presentations and Bigraded Betti Numbers of 2-Parameter Persistent Homology, JAAG]](https://doi.org/10.1137/20M1388425) Minimal presentation of multiparameter persistence modules, using [mpfree](https://bitbucket.org/mkerber/mpfree/src/master/). Hilbert, Rank Decomposition Signed Measures, and MMA decompositions can be computed using the mpfree backend.
+ - [x] [[Delaunay Bifiltrations of Functions on Point Clouds, SODA2024]](https://epubs.siam.org/doi/10.1137/1.9781611977912.173) Provides an alternative to function rips bifiltrations, using Delaunay complexes. Very good alternative to Rips-Density like bifiltrations.
+ - [x] [[Rivet]](https://github.com/rivetTDA/rivet) Interactive two parameter persistence
+ - [x] [[Kernel Operations on the GPU, with Autodiff, without Memory Overflows, JMLR]](http://jmlr.org/papers/v22/20-275.html) Although not linked, at first glance, to persistence in any way, this library allows computing blazingly fast signed measures convolutions (and more!) with custom kernels. 
+ - [ ] [Backend only] [[Projected distances for multi-parameter persistence modules]](https://arxiv.org/abs/2206.08818) Provides a strategy to estimate the convolution distance between multiparameter persistence module using projected barcodes. Implementation is a WIP.
+ - [ ] [Partial, and experimental] [[Efficient Two-Parameter Persistence Computation via Cohomology, SoCG2023]](https://doi.org/10.4230/LIPIcs.SoCG.2023.15) Minimal presentations for 2-parameter persistence algorithm.
+
+If I missed something, or you want to add something, feel free to open an issue.
+
+## Authors
+[David Loiseaux](https://www-sop.inria.fr/members/David.Loiseaux/index.html),<br>
+[Hannah Schreiber](https://github.com/hschreiber) (Persistence backend code),<br>
+[Luis Scoccola](https://luisscoccola.com/) 
+(Möbius inversion in python, degree-rips using [persistable](https://github.com/LuisScoccola/persistable) and [RIVET](https://github.com/rivetTDA/rivet/)),<br>
+[Mathieu Carrière](https://www-sop.inria.fr/members/Mathieu.Carriere/) (Sliced Wasserstein)<br>
+
+## Citation
+Please cite this library when using it in scientific publications;
+you can use the following journal bibtex entry
+```bib
+@article{multipers,
+  title = {Multipers: {{Multiparameter Persistence}} for {{Machine Learning}}},
+  shorttitle = {Multipers},
+  author = {Loiseaux, David and Schreiber, Hannah},
+  year = {2024},
+  month = nov,
+  journal = {Journal of Open Source Software},
+  volume = {9},
+  number = {103},
+  pages = {6773},
+  issn = {2475-9066},
+  doi = {10.21105/joss.06773},
+  langid = {english},
+}
+```
+## Contributions
+Feel free to contribute, report a bug on a pipeline, or ask for documentation by opening an issue.<br>
+In particular, if you have a nice example or application that is not taken care in the documentation (see the ./docs/notebooks/ folder), please contact me to add it there.
+