{"id":20620588,"url":"https://github.com/lcav/sparsefht","last_synced_at":"2025-04-15T12:14:13.085Z","repository":{"id":12998523,"uuid":"15677656","full_name":"LCAV/SparseFHT","owner":"LCAV","description":"A Fast Hadamard Transform for Signals with Sub-linear Sparsity in the Transform Domain -- Implementation","archived":false,"fork":false,"pushed_at":"2016-10-10T14:43:55.000Z","size":72,"stargazers_count":17,"open_issues_count":0,"forks_count":3,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-15T12:14:03.103Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LCAV.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-01-06T15:38:36.000Z","updated_at":"2025-02-07T01:51:43.000Z","dependencies_parsed_at":"2022-09-18T04:51:16.134Z","dependency_job_id":null,"html_url":"https://github.com/LCAV/SparseFHT","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LCAV%2FSparseFHT","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LCAV%2FSparseFHT/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LCAV%2FSparseFHT/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LCAV%2FSparseFHT/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LCAV","download_url":"https://codeload.github.com/LCAV/SparseFHT/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249067779,"owners_count":21207396,"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":[],"created_at":"2024-11-16T12:14:55.719Z","updated_at":"2025-04-15T12:14:13.053Z","avatar_url":"https://github.com/LCAV.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"SparseFHT Code repo\n===================\n\nThis is the code for SparseFHT algorithm as presented in the following papers.\nThe code is hosted on [github](https://github.com/LCAV/SparseFHT).\n\n[Long] R. Scheibler, S.Haghighatshoar, and M. Vetterli,\n[_A Fast Hadamard Transform for Signals with Sub-linear Sparsity in the Transform Domain_](http://infoscience.epfl.ch/record/204991),\nIEEE Trans. Inf. Theory, vol. 61, 2015.\n\n[Short] R. Scheibler, S. Haghighatshoar, and M. Vetterli,\n[_A Fast Hadamard Transform for Signals with Sub-linear Sparsity_](http://infoscience.epfl.ch/record/189818),\nAllerton Conference on Communication, Control and Computing, 2013.\n\n\nAbstract\n--------\n\nIn this paper, we design a new iterative low-complexity algorithm for\ncomputing the Walsh-Hadamard transform (WHT) of an N dimensional signal with\na K-sparse WHT.  We suppose that N is a power of two and K = O(N^α), scales\nsub-linearly in N for some α ∈ (0,1). Assuming a random support model for the\nnonzero transform-domain components, our algorithm reconstructs the WHT of the\nsignal with a sample complexity O(K log\\_(N/K)) and a computational complexity\nO(K log\\_2(K)log\\_2(N/K)). Moreover, the algorithm succeeds with a high\nprobability approaching 1 for large dimension N.  \n\nOur approach is mainly based on the subsampling (aliasing) property of the WHT,\nwhere by a carefully designed subsampling of the time-domain signal, a suitable\naliasing pattern is induced in the transform domain. We treat the resulting\naliasing patterns as parity-check constraints and represent them by a bipartite\ngraph.  We analyze the properties of the resulting bipartite graphs and borrow\nideas from codes defined over sparse bipartite graphs to formulate the recovery\nof the nonzero spectral values as a peeling decoding algorithm for a specific\nsparse-graph code transmitted over a binary erasure channel (BEC). This enables\nus to use tools from coding theory (belief-propagation analysis) to\ncharacterize the asymptotic performance of our algorithm in the very sparse (α\n∈ (0,1/3]) and the less sparse (α ∈ (1/3,1)) regime. Comprehensive simulation\nresults are provided to assess the empirical performance of the proposed\nalgorithm.\n\nContact\n-------\n\nRobin Scheibler \n([email](mailto:robin[dot]scheibler[at]epfl[dot]ch))\n([homepage](http://lcav.epfl.ch/Robin_Scheibler))\n\nPlease do not hesitate to contact me for help and support!\nI would be happy to help you run the code.\n\nPlateform\n---------\n\nThe code has been tested on Mac OS X 10.7, 10.8, 10.9, and on Ubuntu linux.\n\nPython and Matlab mex wrappers were used for the code generating the figures in\nthe paper. The core of the algorithm is implemented in C.\n\nThe code needs a C99 compatible compiler, which seems not to be the case for\nthe windows version of Matlab currently. There seems to be some\n[workaround](https://stackoverflow.com/questions/3737356/mex-problem-how-to-support-c99matlab),\none possibility being to rename all the `.c` files into `.cpp` and use a C++\ncompiler. All of this is untested as of now.\n\nRun the code in Python\n----------------------\n\nA python wrapper for the C code was written and is available in `python/pysparsefht`.\nThe wrapper must be compiled as follows\n\n    cd python/pysparsefht\n    python setup.py build_ext --inplace\n\n### Dependencies\n\nThe code relies on `numpy`, `scipy`, `matplotlib`, `seaborn`, `pandas`, and\n`ipyparallel` for the parallel simulation. It is also possible to run all the\ncode serially, but this would take a long time.\n\n### Reproduce the figures from the paper\n\nA script is provided to reproduce all the figures in the paper.\nAssuming the python module has been built as explained above, do the following.\n\n    cd python/\n    make_all_figures.sh\n\nAnd that's it pretty much. The simulation scripts are suffixed with `_sim` and produce\na data file stored in `data` that can be reused later to generate the figure using\na second script suffixed with `_plot`. The figures will be stored in the `figures` folder.\n\nThe `make_all_figures.sh` scripts has a few options for testing and number of cores used.\n\n    ./make_all_figures.sh [OPTS]\n    Options:\n      -t    Runs a single loop only for test purpose\n      -s    Runs all the code in a simple for loop. No parallelism\n      -n x  Runs the loops in parallel using x workers. This option is ignored if -s is used\n\nThe number of workers is in general set to the number of threads available minus one. That is\ntwice the number of cores, minus one.\n\nRunning `./make_all_figures.sh -t -n 7` on an Intel Core i7 2.8 GHz took 5 minutes.\n\n### Pysparsefht module\n\nA user-friendly python module was written around the C code and can be used to run the FHT and SparseFHT.\n\n    import numpy as np\n    import pysparsefht\n\n    # Create a sparse Hadamard domain vector\n    y = np.zeros(512)\n    y[[13,72,121, 384]] = [12., -123., 91.5, -37.]\n\n    # We can generate the dense time domain by\n    # applying conventional FHT\n    x = pysparsefht.fht(y)\n\n    # Then, we use the sparse FHT to get back the\n    # original sparse vector\n    # y_val, y_loc contain the magnitude and locations, respectively, of the sparse signal\n    y_val, y_loc = pysparsefht.sparse_fht(xs, 4)\n\n    # The output of the transform is not normalize,\n    # so we need to divide by the square root of the length\n    y_hat = np.zeros(512)\n    y_hat[y_loc] = y_val / np.sqrt(512)\n\n    # says True\n    np.allclose(y_hat, y)\n\nThe docstring for `sparse_fht`:\n\n    Signature: pysparsefht.sparse_fht(x, K, B, C, max_iter=20, algo=3, req_loops=False, req_unsat=False, seed=0)\n    Docstring:\n    Wrapper for the Sparse Fast Hadamard Transform\n\n    Parameters\n    ----------\n    x: ndarray (1D or 2D)\n        Input vector, the size should be a power of two.\n        K: int\n          The sparsity expected\n        B: int\n          The number of buckets\n        C: int\n          The oversampling factor\n        max_iter: int, optional\n          The maximum number of iterations of decoder\n        algo: int, optional\n          The variant of the algorithm to use:\n            * ALGO_RANDOM : Uses random hash functions\n            * ALGO_DETERMINISTIC: Uses deterministic hash functions\n            * ALGO_OPTIMIZED: Uses deterministic hash functions with optimized implementation (default)\n        req_loops: bool, optional\n          Requests to return the number of loops executed by the decoded\n        req_unsat: bool, optional\n          Requests to return the number of unsatisfied check nodes when the algorithm terminates\n        seed: unsigned int, optional\n          A seed for the random number generator to pass to the C code\n\n    Returns\n    -------\n    y: ndarray (1D or 2D)\n      The output vector of magnitudes (size K)\n    support: ndarray (1D or 2D)\n      The output vector of locations of non-zero coefficients (size K)\n    unsat: int or ndarray\n      The number of unsatisfied checks (if req_unsat == True)\n    loops: int or ndarray\n      The number of loops run by decoder (if req_loops == True)\n\nThe docstring for `fht`:\n\n    Signature: pysparsefht.fht(x)\n    Docstring:\n    Fast Hadamard Transform\n\n    This is a wrapper that calls a C implementation of the fast hadamard transform\n\n    If x is a 2D array, the transform operates on the rows.\n\n    The length of the transform should be a power of two.\n\n    Parameters\n    ----------\n    x: ndarray (1D or 2D)\n        The data to transform\n\n        Returns\n        -------\n        A new ndarray containing the Hadamard transform of x\n\n\n\n\nRun the code in Matlab\n----------------------\n\n### Reproduce the figures from the paper\n\nTo reproduce the figures from the paper, type in the following in a matlab shell:\n\n    cd \u003cpath_to_SparseFHT\u003e/matlab/\n    make_mex_files\n    make_figures\n\n__Note__\n\n1. The simulation is fairly time-consuming.\n2. To speed-up the simulation, the parallel toolbox was used. If you do not have the parallel toolbox, replace the `parfor` instructions by `for` in all the Sim scripts.\n\n### Mex files info\n\n* **SparseFHT** The fast sparse Hadamard transform algorithm.\n\n         [Y, S, U, I] = SparseFHT(X, K, B, C, L, T)\n\n         Wrapper for the Sparse Fast Hadamard Transform\n         \n         Input arguments:\n         X: input vector  (size n)\n         K: the sparsity (and size of y)\n         B: number of buckets\n         C: oversampling factor\n         L: maximum number of iterations of decoder\n         T: Type of algorithm to use ('Random' / 'Deterministic' / 'Optimized')\n         \n         Output arguments: \n         Y: output vector (size K)\n         S: support vector (size K)\n         U: the number of unsatisfied checks (optional)\n         I: the number of loops run (optional)\n\n\n* **FastHadamard** A straighforward implementation of the conventional fast\n  Hadamard transform. No scaling factor is applied, i.e. applying the algorithm\n  twice will result in the input vector weighted by its length.\n\n        [Y] = FastHadamard(X)\n\n        Input arguments:\n        X: input vector (size has to be a power of two)\n\n        Output arguments:\n        Y: output vector, the Hadamard transform of X.\n\n* **HadamardBenchmark** Calls a C routine performing a timing comparison of SparseFHT and FastHadamard.\n\n        [Tfht Tsfht] = HadamardBenchmark(N, K, B, C, L, R, SEED)\n\n        Input arguments:\n        N: transform size to investigate (scalar, power of two)\n        K: sparsity parameter, number of non-zero tranform domain coefficients (vector, power of two)\n        B: number of buckets to use in SparseFHT (vector, same size as K, power of two)\n        C: oversampling factor\n        L: maximum number of iterations of decoder\n        R: a length 4 vector containing the following parameters\n            1. Number of repetitions of one measurement\n            2. Number of warm-up run \n            3. Number of iterations for one measurement\n            4. Maximum magnitude of non-zero components in the sparse signal\n        SEED: A seed for the C random number generator\n\n        Output arguments:\n\n        Tfht: The runtime measurement of FastHadamard\n        Tsfht: An array containing the runtime measurement of SparseFHT for every value of K\n\nReuse the C code\n----------------\n\nThe makefile in `./C` folder will compile all the code as well as a number\nof example/test files. This can be used as a basis to reuse the C code directly.\n\n    cd ../C\n    make all\n\nThe libraries included are:\n\n* SparseFHT,\n* Fast Hadamard tranform,\n* Fast linear algebra in GF2 (boolean matrices and vectors algebra),\n* Test files.\n\nLicense\n-------\n\n2013-2015 (c) Robin Scheibler, Saeid Haghighatshoar, Martin, Vetterli.\n\nThis work is licensed under the Creative Commons\nAttribution-NonCommercial-ShareAlike 4.0 International License. To view a copy\nof this license, visit http://creativecommons.org/licenses/by-nc-sa/4.0/.\n\nThe code is free to reuse for non-commercial and academic purposes. However,\nplease acknowledge its use with the following citation.\n\n    @article{EPFL-JOUR-204991,\n       author      = {Scheibler, Robin and Haghighatshoar, Saeid and Vetterli, Martin},\n       title       = {A {F}ast {H}adamard {T}ransform for {S}ignals with\n                     {S}ub-linear {S}parsity in the {T}ransform {D}omain},\n       journal     = {IEEE Trans. Inf. Theory}\n       volume      = 61,\n       year        = 2015,\n       ee          = {http://infoscience.epfl.ch/record/204991}\n    }\n\nFor any other purposes, please contact the authors.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flcav%2Fsparsefht","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flcav%2Fsparsefht","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flcav%2Fsparsefht/lists"}