{"id":15043604,"url":"https://github.com/yhtang/funfact","last_synced_at":"2025-08-22T19:15:10.856Z","repository":{"id":39585496,"uuid":"386047074","full_name":"yhtang/FunFact","owner":"yhtang","description":"Tensor decomposition with arbitrary expressions: inner, outer, elementwise operators; nonlinear transformations; and more.","archived":false,"fork":false,"pushed_at":"2022-09-15T20:40:38.000Z","size":3357,"stargazers_count":58,"open_issues_count":19,"forks_count":4,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-08-15T18:41:16.073Z","etag":null,"topics":["automatic-differentiation","factorization","linear-algebra","machine-learning","numpy","python","scientific-computing","tensor"],"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/yhtang.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-07-14T18:59:16.000Z","updated_at":"2024-12-03T07:51:38.000Z","dependencies_parsed_at":"2022-07-11T02:18:16.588Z","dependency_job_id":null,"html_url":"https://github.com/yhtang/FunFact","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/yhtang/FunFact","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yhtang%2FFunFact","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yhtang%2FFunFact/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yhtang%2FFunFact/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yhtang%2FFunFact/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yhtang","download_url":"https://codeload.github.com/yhtang/FunFact/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yhtang%2FFunFact/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271687771,"owners_count":24803496,"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","status":"online","status_checked_at":"2025-08-22T02:00:08.480Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["automatic-differentiation","factorization","linear-algebra","machine-learning","numpy","python","scientific-computing","tensor"],"created_at":"2024-09-24T20:49:19.831Z","updated_at":"2025-08-22T19:15:10.813Z","avatar_url":"https://github.com/yhtang.png","language":"Python","readme":"# FunFact: Build Your Own Tensor Decomposition Model in a Breeze\n\n[![CI](https://github.com/yhtang/FunFact/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/yhtang/FunFact/actions/workflows/ci.yml)\n[![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/yhtang/839011f3f7a6bab680b18cbd9a45d2d3/raw/coverage-master.json)](https://badge.fury.io/py/funfact)\n[![PyPI version](https://badge.fury.io/py/funfact.svg)](https://badge.fury.io/py/funfact)\n[![Documentation Status](https://readthedocs.org/projects/funfact/badge/?version=latest)](https://funfact.readthedocs.io/en/latest/?badge=latest)\n[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)\n\n[FunFact](https://github.com/yhtang/FunFact.git) is a Python package that aims to simplify the design of matrix and tensor factorization algorithms. It features a powerful programming interface that augments the NumPy API with Einstein notations for writing concise tensor expressions. Given an arbitrary forward calculation scheme, the package will solve the corresponding inverse problem using stochastic gradient descent, automatic differentiation, and multi-replica vectorization. Its application areas include quantum circuit synthesis, tensor decomposition, and neural network compression. It is GPU- and parallelization-ready thanks to modern numerical linear algebra backends such as JAX/TensorFlow and PyTorch.\n\n## Installation\n\n* To use FunFact with the JAX backend:\n  ```bash\n  pip install \"funfact[jax]\"\n  ```\n* To use FunFact with the PyTorch backend:\n  ```bash\n  pip install \"funfact[torch]\"\n  ```\n\nRunning the command as above will install the version of the respective packages hosted on PyPI. Please refer to the [installation page](https://funfact.readthedocs.io/en/latest/pages/installation/) for more details on installation options.\n\nFunFact can also be installed with the NumPy backend, which **only supports forward calculations**. The NumPy backend doesn't support automatic differentiation and is not able to optimize tensor expressions for methods such as `funfact.factorize`.\n\n```bash \npip install -U funfact  # does not install JAX or PyTorch\n```\n\n## Quick start example: semi-nonnegative CP decomposition\n\nPackage import:\n\n``` py\nimport funfact as ff\nimport numpy as np\n```\n\nCreate target tensor:\n\n``` py\nT = np.arange(60, dtype=np.float32).reshape(3, 4, 5); T\n```\n\nDefine abstract tensors and indices:\n\n``` py\nR = 2\na = ff.tensor('a', T.shape[0], R, prefer=ff.conditions.NonNegative())\nb = ff.tensor('b', T.shape[1], R)\nc = ff.tensor('c', T.shape[2], R)\ni, j, k, r = ff.indices('i, j, k, r')\n```\n\nCreate a tensor expression (only specifies the algebra but does **not** carry out the computation immediately):\n\n``` py\ntsrex = (a[i, ~r] * b[j, r]) * c[k, r]; tsrex\n```\n\nFind rank-2 approximation:\n\n``` py\n\u003e\u003e\u003e fac = ff.factorize(tsrex, T, max_steps=1000, vec_size=8, penalty_weight=10)\n\u003e\u003e\u003e fac.factors\n100%|██████████| 1000/1000 [00:03\u003c00:00, 304.00it/s]\n\u003c'data' fields of tensors a, b, c\u003e\n```\n\nReconstruction:\n    \n``` py\n\u003e\u003e\u003e fac()\nDeviceArray([[[-0.234,  0.885,  2.004,  3.123,  4.243],\n              [ 4.955,  5.979,  7.002,  8.025,  9.049],\n              [10.145, 11.072, 12.   , 12.927, 13.855],\n              [15.335, 16.167, 16.998, 17.83 , 18.661]],\n\n             [[20.025, 21.014, 22.003, 22.992, 23.981],\n              [25.019, 26.01 , 27.001, 27.992, 28.983],\n              [30.013, 31.006, 31.999, 32.992, 33.985],\n              [35.007, 36.002, 36.997, 37.992, 38.987]],\n\n             [[40.281, 41.14 , 41.999, 42.858, 43.716],\n              [45.082, 46.04 , 46.999, 47.958, 48.917],\n              [49.882, 50.941, 51.999, 53.058, 54.117],\n              [54.682, 55.841, 56.999, 58.158, 59.316]]], dtype=float32)\n```\n    \nExamine factors:\n\n``` py\n\u003e\u003e\u003e fac['a']\nDeviceArray([[1.788, 1.156],\n             [3.007, 0.582],\n             [4.226, 0.008]], dtype=float32)\n```\n    \n``` py\n\u003e\u003e\u003e fac['b']\nDeviceArray([[-2.923, -4.333],\n             [-3.268, -3.541],\n             [-3.614, -2.749],\n             [-3.959, -1.957]], dtype=float32)\n```\n\n``` py\n\u003e\u003e\u003e fac['c']\nDeviceArray([[-3.271,  3.461],\n             [-3.341,  3.309],\n             [-3.41 ,  3.158],\n             [-3.479,  3.006],\n             [-3.548,  2.855]], dtype=float32)\n```\n    \n## How to cite\n\nIf you use this package for a publication (either in-paper or electronically), please cite it using the following DOI: [https://doi.org/10.11578/dc.20210922.1](https://doi.org/10.11578/dc.20210922.1)\n\n## Contributors\n\nCurrent developers:\n\n- [Yu-Hang \"Maxin\" Tang](https://github.com/yhtang)\n- [Daan Camps](https://github.com/campsd)\n\nPreviou contributors:\n\n- [Elizaveta Rebrova](https://github.com/erebrova)\n\n\n## Copyright\n\nFunFact Copyright (c) 2021, The Regents of the University of California,\nthrough Lawrence Berkeley National Laboratory (subject to receipt of\nany required approvals from the U.S. Dept. of Energy). All rights reserved.\n\nIf you have questions about your rights to use or distribute this software,\nplease contact Berkeley Lab's Intellectual Property Office at\nIPO@lbl.gov.\n\nNOTICE.  This Software was developed under funding from the U.S. Department\nof Energy and the U.S. Government consequently retains certain rights.  As\nsuch, the U.S. Government has been granted for itself and others acting on\nits behalf a paid-up, nonexclusive, irrevocable, worldwide license in the\nSoftware to reproduce, distribute copies to the public, prepare derivative \nworks, and perform publicly and display publicly, and to permit others to do so.\n\n## Funding Acknowledgment\n\nThis work was supported by the Laboratory Directed Research and Development Program of Lawrence Berkeley National Laboratory under U.S. Department of Energy Contract No. DE-AC02-05CH11231.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyhtang%2Ffunfact","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyhtang%2Ffunfact","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyhtang%2Ffunfact/lists"}