{"id":19863579,"url":"https://github.com/sandialabs/qml","last_synced_at":"2025-06-12T01:38:17.745Z","repository":{"id":67765417,"uuid":"546278342","full_name":"sandialabs/QML","owner":"sandialabs","description":"Quantum Manifold Learning","archived":false,"fork":false,"pushed_at":"2024-09-27T19:54:23.000Z","size":195494,"stargazers_count":3,"open_issues_count":1,"forks_count":2,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-06T22:38:39.865Z","etag":null,"topics":["scr-2809","snl-data-analysis","snl-visualization"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sandialabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-05T20:42:16.000Z","updated_at":"2024-08-14T18:06:01.000Z","dependencies_parsed_at":null,"dependency_job_id":"b609b2bd-0d45-4ece-b1c6-561ed38788fd","html_url":"https://github.com/sandialabs/QML","commit_stats":{"total_commits":34,"total_committers":4,"mean_commits":8.5,"dds":"0.47058823529411764","last_synced_commit":"d438145d9894577d1dee6badb22d7e45d16b9cc3"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandialabs%2FQML","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandialabs%2FQML/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandialabs%2FQML/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandialabs%2FQML/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sandialabs","download_url":"https://codeload.github.com/sandialabs/QML/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251986792,"owners_count":21675951,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["scr-2809","snl-data-analysis","snl-visualization"],"created_at":"2024-11-12T15:15:15.336Z","updated_at":"2025-05-02T04:31:08.121Z","avatar_url":"https://github.com/sandialabs.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Python package](https://github.com/sandialabs/sbovqaopt/actions/workflows/python-package.yml/badge.svg)](https://github.com/sandialabs/sbovqaopt/actions/workflows/python-package.yml)\n\n# QML: Implementation of quantum manifold learning (QML)\n\nThe `QML` package provides an implementation of manifold learning via quantum dynamics as introduced in [[SLoD](#slod)] and [[QCC](#qcc)]. This is an implementation without any parallelization.\n\n## Installation\n\nThe `QML` package only consists of one file qml_serial.py, which contains all functions required.\n\n## Usage\n\nThe QML code is executed on data stored in a CSV, h5, sql, xlsx, or json file. The data must just store a matrix as more complex formats are not processed.\nThe code is called with a input file that specifies all parameters, e.g.,\n\n```\npython3 qml_serial.py QML_test_input.data\n```\n\nFor an example input file and required parameters see `QML_test_input.dat`. Some useful parameters are described below. For a full discribtion refer to psuedocode in Appendix VI of [[SLoD](#slod)] for interpretation of code and parameters.\n\n* `logepsilon` : This sets the scale length (`logepsilon` $= 2 \\log \\sqrt{\\epsilon}$) at which the $\\sqrt{\\epsilon}$-nearest-neighbour graph, and hence the graph Laplacian, is constructed from the dataset.\n* `alpha` : This scales with `logepsilon` to determine the error term $h$. This term bounds the error on the geodesics found through propagation.\n* `dt` : Determines time step size for propagating geodesics. Paths are found at an unit speed, so time step is equivilant to distance.\n* `nProp` : Number of time steps taken. Taking more steps along geodesics increases the number of paths found between points as more distance is covered.\n* `nColl` : Number of initial momenta for geodesics. Each starting momentum is a direction towards its \"nColl\" nearest neighbors. Increasing this parameter will start the propagation in more directions.\n* `H_test` : Boolean to autmatically tune error terms. The optimal values may not be the minimum found from this test, but they are often close to the minimum.\n\nThe outputs of QML are:\n\n- the geodesic distance matrix is saved to file `f.out`, where `f` is the input file name and\n- optionally, a visualization of the embedding of the graph is also shown as a plot, if `SHOW_EMBEDDING` = 2 or 3 (this number sets the embedding dimension) in the input file.\n\n## Development\n\nFor development purposes, the package can be obtained by cloning the repository locally:\n\n```\ngit clone https://github.com/sandialabs/QML.git\n```\n\n## Manfold learning comparison\nFor the [Swissroll dataset](https://scikit-learn.org/stable/modules/generated/sklearn.datasets.make_swiss_roll.html) of 2000 points, QML is better able to *unroll* the dataset than other manifold learning techniques, when embedding into three dimensions. QML works by approximating wave dynamics on the dataset. Using this, a wavepacket localized at a sample point, with large oscillations in a prescribed direction, can be propagated to reveal the geodesic flow on the manifold. The hitting time between points gives a sparse graph of the data that can be embedded, giving a low-dimensional representation; here, we use the method of [1](#oostema) for the embedding.\n\nWe compare this with other popular graph embedding techniques: UMAP, Laplacian Eigenmaps, Diffusion Maps and $t$-SNE.\n\n- [UMAP](https://umap-learn.readthedocs.io/en/latest/) ([3](#umap)) aims to preserve the topological structure of the manifold and approximates it with a *fuzzy topological structure*, which it then embeds into a lower-dimensional Euclidean space. The assumptions are that the data is uniformly distribued on the manifold and that the manifold is locally connected and its Riemannian metric is a scalar matrix in ambient coordinates in some neighbourhood of each point.\n- [t-SNE](https://lvdmaaten.github.io/tsne/) ([4](#tsne)) aims to reduce dimensionality by placing Gaussian affinities between points in the high-dimensional ambient space and finding lower-dimensional coordinates that minimize the Kullback-Liebler divergence between the high-dimensional Gaussian distributions and lower-dimensional Student $t$-distributions.\n- Laplacian Eigenmaps ([5](#lap-eigmaps)) produces lower dimensional coordinates by using the values of some of the eigenfunctions of the graph Laplacian of a graph on the dataset constructed by connecting points within a certain scale-length based on the density of point samples.\n- Diffusion Maps ([6](#diffmaps)) works in the same way as Laplacian Eigenmaps, but scales each eigenfunction that provides coordinates, by a power of the corresponding eigenvalue, corresponding to time of diffusion of the diffusive process underlying the method.\n\nOn the Swiss roll with 2000 uniformly sampled points, QML, UMAP, Laplacian Eigenmaps, and Diffusion Maps all embed the dataset into a roughly flat two-dimensional submanifold of three-dimensional coordinate space. The embeddings produced by Laplacian Eigenmaps and Diffusion Maps *lose* an additional dimension of the ground truth, due to the initial two chosen eigenfunctions having dependence only on one of the directions of the manifold. This is a noted drawback of these methods (see *e.g.*, [7](#eigen-redundancy)).  The embedding by $t$-SNE retains the dimensionality, but the mapping from the original dataset onto the lower dimensional representation is not faithful to the intrinsic local structure of the dataset (note the color-coding of points from one end of the roll to the other and the corresponding $t$-SNE embedding in the figure below). QML and UMAP retain information along the flat dimension of the data. However, only QML maintains a uniform distribution of the data and manages to straighten the Swiss roll, while all the others result in a curved and less uniform representation (see the gaps in the embedding by UMAP in the figure below).\n\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"images/MLcompareFull.PNG\" alt=\"drawing\" style=\"width:600px;\"/\u003e\n\u003c/p\u003e\n\n## Geodesic method comparison\n\nQuantum Manifold Learning (QML) computes geodesics using quantum dynamics derived from a diffusion process. The accuracy of the geodesics scales with the amount of data in the input. QML scales to higher-dimensional data more efficiently than common geodesic methods. We compare the resolution of geodesics by QML to the *Heat Method* (our terminology) of [2](#crane-heat) and shortest paths on local neighbourhood graphs. The Heat Method attempts to recover geodesic distances to a given point by approximately solving the heat equation on the dataset with a singular point source as the initial condition, computing its normalized gradient vector field and then approximately solving the Poisson equation with respect to this gradient field. This method needs structured approximations to the manifold, or proceeds by an initial Voronoi cell decomposition from the dataset. Dijkstra's algorithm can also be used on a nearest neighbours graph of Euclidean distances to approximate geodesic distance.\n\nWe apply these methods to two sets of discrete point coordinates on the unit sphere in $\\mathbb{R}^3$. When applied to a structured approximation to the sphere, which is a natural setting for the Heat Method as described in [2](#crane-heat), QML recovers geodesics distances with roughly the same accuracy as the Heat Method. When points are sampled uniformly at random, the Heat Method is applied to a Voronoi cell decomposition given by a sub-sampling of points, while QML is applied directly on the full, *unstructured* sample set. Again, in this setting, QML and Heat Method recover geodesic distances with similar accuracy. Both methods outperform distances obtained from using Dijkstra's method on a nearest neighbor graph of degree 6. Additionally, QML can output a geodesic path, as shown on the top row of the figure below. This is constructed by propagating a directed and localized wavepacket for multiple time steps and plotting the position along the way.\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"images/geoCompareFull.PNG\" alt=\"drawing\" style=\"width:600px;\"/\u003e\n\u003c/p\u003e\n\n## Citations\n\nIf you use or refer to this project in any publication, please cite the corresponding papers:\n\n\u003e [SLoD] \u003ca id=\"slod\"\u003e\u003c/a\u003e Akshat Kumar, Mohan Sarovar. _Shining light on data: Geometric data analysis through quantum dynamics_ [arXiv:2212.00682](https://arxiv.org/abs/2212.00682) (2022).\n\n\u003e [QCC] \u003ca id=\"qcc\"\u003e\u003c/a\u003e Akshat Kumar. *On a quantum-classical correspondence: from graphs to manifolds* [arXiv:2112.10748](https://arxiv.org/abs/2112.10748) (2022).\n\n## References\n\n\u003e 1. \u003ca id=\"oostema\"\u003e\u003c/a\u003e Peter Oostema, Franz Franchetti. _Leveraging High Dimensional Spatial Graph Embedding as a Heuristic for Graph Algorithms_, [IEEE IPDPSW](https://spiral.ece.cmu.edu/pub-spiral/pubfile/PDCO2021_338.pdf) (2021).\n\n\u003e 2. \u003ca id=\"crane-heat\"\u003e\u003c/a\u003e Keenan Crane, Clarisse Weischedel, Max Wardetzky. _The Heat Method for Distance Computation_, [CACM](https://www.cs.cmu.edu/~kmcrane/Projects/HeatMethod/paperCACM.pdf) (2017).\n\n\u003e 3. \u003ca id=\"umap\"\u003e\u003c/a\u003e Leland McInnes, John Healy, James Melville. *Umap: Uniform manifold approximation and projection for dimension reduction*, [arXiv:1802.03426](https://arxiv.org/abs/1802.03426) (2018).\n\n\u003e 4. \u003ca id=\"tsne\"\u003e\u003c/a\u003e L.J.P. van der Maaten, G.E. Hinton. *Visualizing High-Dimensional Data Using t-SNE*, [JMLR](https://www.jmlr.org/papers/volume9/vandermaaten08a/vandermaaten08a.pdf) (2008).\n\n\u003e 5. \u003ca id=\"lap-eigmaps\"\u003e\u003c/a\u003e Mikhail Belkin, Partha Niyogi. *Laplacian eigenmaps for dimensionality reduction and data representation*, Neural Computation (2003).\n\n\u003e 6. \u003ca id=\"diffmaps\"\u003e\u003c/a\u003e Ronald Coifman, Stéphane Lafon. *Diffusion maps*, ACHA (2006).\n\n\u003e 7. \u003ca id=\"eigen-redundancy\"\u003e\u003c/a\u003e Y. Goldberg, A. Zakai, D. Kushnir, Y. Ritov, *Manifold learning: The price of normalization*, JMLR (2008).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsandialabs%2Fqml","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsandialabs%2Fqml","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsandialabs%2Fqml/lists"}