[comment]: # (Logo and Title)
<h1 align="center">
<img src="https://github.com/mscaudill/simplexers/blob/main/docs/imgs/logo.png"
style="width:600px;height:auto;"/>
</h1>
<h2 align="center">
<i><font color='gray'>Euclidean Projections onto Positive and Capped Simplices</font></i>
</h2>
[comment]: # (Badges)
<p align="center">
<a href="https://zenodo.org/doi/10.5281/zenodo.13759339"><img
src="https://img.shields.io/badge/DOI-10.5281%2Fzenodo.13759340-lightsteelblue?style=flat&link=https%3A%2F%2Fzenodo.org%2Fdoi%2F10.5281%2Fzenodo.13759339"
alt="DOI"/>
</a>
<a href="https://pypi.org/project/openseize/"><img
src="https://img.shields.io/pypi/v/openseize?color=78437E&logo=pypi&logoColor=white"
alt="Openseize pypi release" />
</a>
<img alt="Python Version from PEP 621 TOML" src="https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fmscaudill%2Fsimplexers%2Fmain%2Fpyproject.toml&style=flat&logo=python&logoColor=gold&labelColor=gray&color=blue">
<a href="https://github.com/mscaudill/simplexers/blob/main/LICENSE"><img
src="https://img.shields.io/badge/License-BSD%203--Clause-teal"
alt="Simplexers is released under the BSD 3-Clause license." />
</a>
<a href="https://github.com/mscaudill/openseize/actions/workflows/test.yml"><img
src="https://img.shields.io/github/actions/workflow/status/mscaudill/simplexers/test.yml?label=CI&logo=github"
alt="Simplexers' test status" />
</a>
<a href="https://github.com/mscaudill/simplexers/pulls"><img
src="https://img.shields.io/badge/PRs-welcome-F8A3A3"
alt="Pull Request Welcomed!" />
</a>
</p>
[comment]: # (Navigation links)
<p align="center" style="font-size: 20px">
<a href="#Key-Features">About</a> |
<a href="#Installation">Installation</a> |
<a href="#Dependencies">Dependencies</a> |
<a href="#Attribution">Attribution</a> |
<a href="#Contributions">Contributions</a> |
<a href="#Issues">Issues</a> |
<a href="#License">License</a> |
<a href="#Acknowledgements">Acknowledgements</a>
</p>
# About
The s-capped simplex is defined as:
```math
\Delta_{s}^{=} := \{\mathbf{x} \in \mathbb{R}^{n} \mid \mathbf{x}^T\mathbf{1} = s,
\mathbf{0} \leq \mathbf{x} \leq \mathbf{1} \}
```
[comment]: # (simplex feasible region image)
<h1 align="center">
<img src="https://github.com/mscaudill/simplexers/blob/main/docs/imgs/simplex_region.png"
style="width:300px;height:auto;"/>
</h1>
Geometrically, the simplex is a slice at $\mathbf{x}^T\mathbf{1} = s$ of
a hypercube $\mathbf{0} \leq \mathbf{x} \leq \mathbf{1}$ shown by the blue
region in the image.
Projecting a vector onto a simplex is an important subproblem that appears in
imaging, statistics, and machine learning applications [1](https://link.springer.com/article/10.1007/s10107-015-0946-6) [2](https://proceedings.neurips.cc/paper/2021/file/52aaa62e71f829d41d74892a18a11d59-Paper.pdf) [3](https://www.sciencedirect.com/science/article/abs/pii/S0167865522002185).
The projection of vector $\mathbf{y}$ onto the simplex amounts to finding a
vector $\mathbf{x}*$ that lives in the blue (feasible) region that is *closest* to y. This vector is
the *shadow* of $\mathbf{y}$. Formally, this projection is
written as:
```math
\mathbf{x}^* = proj_{\Delta_{s}^{=}}\left(\mathbf{y}\right) = \underset{x}{\mathrm{argmin}}\{
\frac{1}{2}\|\mathbf{x} - \mathbf{y}\|^2 \mid \mathbf{x} \in
\Delta_{s}^{=}\}
```
This software computes the projection of vectors onto s-capped and positive
simplices (simplices where $\mathbf{x}^*$'s components can be > 1) using sorting methods and fast root
finding methods of the Lagrangian's critical points.
[2](https://proceedings.neurips.cc/paper/2021/file/52aaa62e71f829d41d74892a18a11d59-Paper.pdf)
[4](https://mblondel.org/publications/mblondel-icpr2014.pdf).
### Example
```python
import numpy as np
from simplexers import capped, positive
rng = np.random.default_rng()
x = rng.uniform(0, 3, size=(4, 100))
# construct capped and positive projections
capped_projection = capped.capped_simplexer(x, s=1, axis=-1)
positive_projection = positive.positive_simplexer(x, s=1, axis=-1)
# validate the sum of each of the 4 vectors is 1
print(np.allclose(np.sum(capped_projection, axis=-1), 1))
print(np.allclose(np.sum(positive_projection, axis=-1), 1))
```
# Installation
Simplexers is available on [pypi](https://pypi.org/project/simplexers/) for easy intallation into virtual environments.
### Python Virtual Environment
1. Create your virtual environment, Here we name it `my_venv`.
```Shell
$ python3 -m venv my_venv
```
2. Activate your 'my_venv' environment
```Shell
$ source my_venv/bin/activate
```
3. Install openseize into your virtual environment
```Shell
(my_venv)$ pip install simplexers
```
### Conda Virtual Environment
1. Download the simplexers environment <a
href=https://github.com/mscaudill/simplexers/blob/master/environment.yml
target=_blank>configuration yaml</a>
2. Create a conda simplexers environment.
```Shell
$ conda env create --file environment.yml
```
3. Activate the `simplexers` environment.
```Shell
$ conda activate simplexers
```
### From Source
To get the development version:
1. Create a virtual environment with latest pip version.
```Shell
$ python3 -m venv env
$ source env/bin/activate
$ pip install --upgrade pip
```
2. Get the source code
```Shell
$ git clone https://github.com/mscaudill/simplexers.git
```
3. CD into the directory containing the pyproject.toml and create an
editable install with `pip` using the development dependencies
```Shell
$ pip install -e .[dev]
```
# Dependencies
Simplexers requires <b>Python <span>≥</span> 3.10</b> and has the
following dependencies:
<table>
<tr>
<th>package</th>
<th>pypi</th>
<th>conda</th>
</tr>
<tr>
<td><a href="https://numpy.org/doc/stable/index.html#"
target=_blank>numpy</a></td>
<td>https://pypi.org/project/numpy/</td>
<td align='center'><span>✓</span></td>
</tr>
<tr>
<td><a href="https://scipy.org/"
target=_blank>scipy</a></td>
<td>https://pypi.org/project/scipy/</td>
<td align='center'><span>✓</span></td>
</tr>
<tr>
<td><a href="https://ipython.org/"
target=_blank>ipython</a></td>
<td>https://pypi.org/project/ipython/</td>
<td align='center'><span>✓</span></td>
</tr>
<tr>
<td><a href=https://jupyter.org/
target=_blank>notebook</a></td>
<td>https://pypi.org/project/jupyter/</td>
<td align='center'><span>✓</span></td>
</tr>
</table>
# Attribution
Please see the *Cite this repository* under the About section or the [citation
file](https://github.com/mscaudill/simplexes/blob/master/CITATION.cff).
# Contributions
Contributions are what makes open-source fun and we would love for you to
contribute. Please check out our [contribution guide](
https://github.com/mscaudill/simplexers/blob/master/.github/CONTRIBUTING.md)
to get started.
# Issues
Simplexers provides custom issue templates for filing bugs, requesting
feature enhancements, suggesting documentation changes, or just asking
questions. You can file an issue <a
href=https://github.com/mscaudill/simplexers/issues/new/choose>here</a>.
# License
Simplexers is licensed under the terms of the 3-Clause BSD License.
# Acknowledgements
**This work is generously supported through the Ting Tsung and Wei Fong Chao
Foundation**
Raw data
{
"_id": null,
"home_page": null,
"name": "simplexers",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "machine learning, large-scale optimization",
"author": null,
"author_email": "Matthew Caudill <mscaudill@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/9b/2d/4b9a9bc5d1a6ff149569f958ddb16b91465e3885010f1c91e3012af7aa97/simplexers-1.0.0.tar.gz",
"platform": null,
"description": "\n[comment]: # (Logo and Title)\n<h1 align=\"center\">\n <img src=\"https://github.com/mscaudill/simplexers/blob/main/docs/imgs/logo.png\" \n style=\"width:600px;height:auto;\"/>\n</h1>\n\n<h2 align=\"center\">\n <i><font color='gray'>Euclidean Projections onto Positive and Capped Simplices</font></i>\n</h2>\n\n\n[comment]: # (Badges)\n<p align=\"center\">\n <a href=\"https://zenodo.org/doi/10.5281/zenodo.13759339\"><img\n src=\"https://img.shields.io/badge/DOI-10.5281%2Fzenodo.13759340-lightsteelblue?style=flat&link=https%3A%2F%2Fzenodo.org%2Fdoi%2F10.5281%2Fzenodo.13759339\"\n alt=\"DOI\"/>\n </a>\n <a href=\"https://pypi.org/project/openseize/\"><img \n src=\"https://img.shields.io/pypi/v/openseize?color=78437E&logo=pypi&logoColor=white\" \n alt=\"Openseize pypi release\" />\n </a>\n <img alt=\"Python Version from PEP 621 TOML\" src=\"https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fmscaudill%2Fsimplexers%2Fmain%2Fpyproject.toml&style=flat&logo=python&logoColor=gold&labelColor=gray&color=blue\">\n <a href=\"https://github.com/mscaudill/simplexers/blob/main/LICENSE\"><img\n src=\"https://img.shields.io/badge/License-BSD%203--Clause-teal\" \n alt=\"Simplexers is released under the BSD 3-Clause license.\" />\n </a>\n <a href=\"https://github.com/mscaudill/openseize/actions/workflows/test.yml\"><img \n src=\"https://img.shields.io/github/actions/workflow/status/mscaudill/simplexers/test.yml?label=CI&logo=github\"\n alt=\"Simplexers' test status\" />\n </a>\n <a href=\"https://github.com/mscaudill/simplexers/pulls\"><img \n src=\"https://img.shields.io/badge/PRs-welcome-F8A3A3\"\n alt=\"Pull Request Welcomed!\" />\n </a>\n</p>\n\n\n[comment]: # (Navigation links)\n<p align=\"center\" style=\"font-size: 20px\">\n<a href=\"#Key-Features\">About</a> | \n<a href=\"#Installation\">Installation</a> | \n<a href=\"#Dependencies\">Dependencies</a> | \n<a href=\"#Attribution\">Attribution</a> | \n<a href=\"#Contributions\">Contributions</a> | \n<a href=\"#Issues\">Issues</a> | \n<a href=\"#License\">License</a> |\n<a href=\"#Acknowledgements\">Acknowledgements</a> \n</p>\n\n# About\n\nThe s-capped simplex is defined as:\n```math\n\\Delta_{s}^{=} := \\{\\mathbf{x} \\in \\mathbb{R}^{n} \\mid \\mathbf{x}^T\\mathbf{1} = s,\n \\mathbf{0} \\leq \\mathbf{x} \\leq \\mathbf{1} \\}\n```\n\n[comment]: # (simplex feasible region image)\n<h1 align=\"center\">\n <img src=\"https://github.com/mscaudill/simplexers/blob/main/docs/imgs/simplex_region.png\" \n style=\"width:300px;height:auto;\"/>\n</h1>\n\nGeometrically, the simplex is a slice at $\\mathbf{x}^T\\mathbf{1} = s$ of\na hypercube $\\mathbf{0} \\leq \\mathbf{x} \\leq \\mathbf{1}$ shown by the blue\nregion in the image.\n\nProjecting a vector onto a simplex is an important subproblem that appears in\nimaging, statistics, and machine learning applications [1](https://link.springer.com/article/10.1007/s10107-015-0946-6) [2](https://proceedings.neurips.cc/paper/2021/file/52aaa62e71f829d41d74892a18a11d59-Paper.pdf) [3](https://www.sciencedirect.com/science/article/abs/pii/S0167865522002185).\nThe projection of vector $\\mathbf{y}$ onto the simplex amounts to finding a \nvector $\\mathbf{x}*$ that lives in the blue (feasible) region that is *closest* to y. This vector is\nthe *shadow* of $\\mathbf{y}$. Formally, this projection is\nwritten as:\n\n```math\n\\mathbf{x}^* = proj_{\\Delta_{s}^{=}}\\left(\\mathbf{y}\\right) = \\underset{x}{\\mathrm{argmin}}\\{\n\\frac{1}{2}\\|\\mathbf{x} - \\mathbf{y}\\|^2 \\mid \\mathbf{x} \\in\n\\Delta_{s}^{=}\\}\n```\n\n\nThis software computes the projection of vectors onto s-capped and positive\nsimplices (simplices where $\\mathbf{x}^*$'s components can be > 1) using sorting methods and fast root \nfinding methods of the Lagrangian's critical points.\n[2](https://proceedings.neurips.cc/paper/2021/file/52aaa62e71f829d41d74892a18a11d59-Paper.pdf)\n[4](https://mblondel.org/publications/mblondel-icpr2014.pdf).\n\n\n### Example\n```python\nimport numpy as np\nfrom simplexers import capped, positive\n\nrng = np.random.default_rng()\nx = rng.uniform(0, 3, size=(4, 100))\n\n# construct capped and positive projections\ncapped_projection = capped.capped_simplexer(x, s=1, axis=-1)\npositive_projection = positive.positive_simplexer(x, s=1, axis=-1)\n\n# validate the sum of each of the 4 vectors is 1\nprint(np.allclose(np.sum(capped_projection, axis=-1), 1))\nprint(np.allclose(np.sum(positive_projection, axis=-1), 1))\n```\n\n# Installation\n\nSimplexers is available on [pypi](https://pypi.org/project/simplexers/) for easy intallation into virtual environments.\n\n### Python Virtual Environment\n\n1. Create your virtual environment, Here we name it `my_venv`. \n```Shell\n$ python3 -m venv my_venv\n```\n\n2. Activate your 'my_venv' environment\n```Shell\n$ source my_venv/bin/activate\n```\n\n3. Install openseize into your virtual environment\n```Shell\n(my_venv)$ pip install simplexers\n```\n\n### Conda Virtual Environment\n\n1. Download the simplexers environment <a\nhref=https://github.com/mscaudill/simplexers/blob/master/environment.yml \ntarget=_blank>configuration yaml</a> \n\n\n2. Create a conda simplexers environment.\n```Shell\n$ conda env create --file environment.yml\n```\n\n3. Activate the `simplexers` environment.\n```Shell\n$ conda activate simplexers\n```\n\n### From Source\n\nTo get the development version:\n\n1. Create a virtual environment with latest pip version.\n```Shell\n$ python3 -m venv env\n$ source env/bin/activate\n$ pip install --upgrade pip\n```\n\n2. Get the source code\n```Shell\n$ git clone https://github.com/mscaudill/simplexers.git\n```\n\n3. CD into the directory containing the pyproject.toml and create an \neditable install with `pip` using the development dependencies\n```Shell\n$ pip install -e .[dev]\n```\n\n# Dependencies\n\nSimplexers requires <b>Python <span>≥</span> 3.10</b> and has the\nfollowing dependencies:\n\n<table>\n\n <tr>\n <th>package</th>\n <th>pypi</th>\n <th>conda</th>\n </tr>\n\n <tr>\n <td><a href=\"https://numpy.org/doc/stable/index.html#\" \n target=_blank>numpy</a></td>\n <td>https://pypi.org/project/numpy/</td>\n <td align='center'><span>✓</span></td>\n </tr>\n\n <tr>\n <td><a href=\"https://scipy.org/\" \n target=_blank>scipy</a></td>\n <td>https://pypi.org/project/scipy/</td>\n <td align='center'><span>✓</span></td>\n </tr>\n\n <tr>\n <td><a href=\"https://ipython.org/\" \n target=_blank>ipython</a></td>\n <td>https://pypi.org/project/ipython/</td>\n <td align='center'><span>✓</span></td>\n </tr>\n\n <tr>\n <td><a href=https://jupyter.org/ \n target=_blank>notebook</a></td>\n <td>https://pypi.org/project/jupyter/</td>\n <td align='center'><span>✓</span></td>\n </tr>\n\n</table>\n\n# Attribution\n\nPlease see the *Cite this repository* under the About section or the [citation\nfile](https://github.com/mscaudill/simplexes/blob/master/CITATION.cff).\n\n\n# Contributions\n\nContributions are what makes open-source fun and we would love for you to\ncontribute. Please check out our [contribution guide](\nhttps://github.com/mscaudill/simplexers/blob/master/.github/CONTRIBUTING.md)\nto get started.\n\n# Issues\n\nSimplexers provides custom issue templates for filing bugs, requesting\nfeature enhancements, suggesting documentation changes, or just asking\nquestions. You can file an issue <a\nhref=https://github.com/mscaudill/simplexers/issues/new/choose>here</a>. \n\n# License\n\nSimplexers is licensed under the terms of the 3-Clause BSD License.\n\n# Acknowledgements\n\n**This work is generously supported through the Ting Tsung and Wei Fong Chao \nFoundation**\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Vector Projections onto Positive and Capped Simplices",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/mscaudill/simplexers"
},
"split_keywords": [
"machine learning",
" large-scale optimization"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "08fb40cca98ec077e254e9211c4fb2cd7c364cc656752c62a885964cb544cd9d",
"md5": "315a9cf52377bdd3ecd2c9a535c4f58c",
"sha256": "cf62d1c599eab48fcb7156ee6ef566ddf17d8dbbdb3a01fb89725815648f8e63"
},
"downloads": -1,
"filename": "simplexers-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "315a9cf52377bdd3ecd2c9a535c4f58c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 11383,
"upload_time": "2024-09-16T12:36:21",
"upload_time_iso_8601": "2024-09-16T12:36:21.854056Z",
"url": "https://files.pythonhosted.org/packages/08/fb/40cca98ec077e254e9211c4fb2cd7c364cc656752c62a885964cb544cd9d/simplexers-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9b2d4b9a9bc5d1a6ff149569f958ddb16b91465e3885010f1c91e3012af7aa97",
"md5": "cc6c187755d461d5384b288b0c06361d",
"sha256": "e5cdacab3181735f0aad004577b525d32a310831dd67f2bf20f5e40b34e18962"
},
"downloads": -1,
"filename": "simplexers-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "cc6c187755d461d5384b288b0c06361d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 14925,
"upload_time": "2024-09-16T12:36:23",
"upload_time_iso_8601": "2024-09-16T12:36:23.639637Z",
"url": "https://files.pythonhosted.org/packages/9b/2d/4b9a9bc5d1a6ff149569f958ddb16b91465e3885010f1c91e3012af7aa97/simplexers-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-16 12:36:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mscaudill",
"github_project": "simplexers",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "simplexers"
}
JSON
