Metadata-Version: 2.4
Name: scarfs
Version: 0.2.0
Summary: find approximate fixed points of bounded vector valued functions
Project-URL: Documentation, https://erikbrinkman.github.io/scarfs/
Project-URL: Repository, https://github.com/erikbrinkman/scarfs
Project-URL: Issues, https://github.com/erikbrinkman/scarfs/issues
Author-email: Erik Brinkman <erik.brinkman@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: brouwer,fixed-point,hypercube,numba,scarf,simplex,simplotope
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.13
Requires-Dist: numba>=0.61.0
Requires-Dist: numpy>=2.1.3
Description-Content-Type: text/markdown

# Scarfs

[![pypi](https://img.shields.io/pypi/v/scarfs)](https://pypi.org/project/scarfs/)
[![build](https://github.com/erikbrinkman/scarfs/actions/workflows/build.yml/badge.svg)](https://github.com/erikbrinkman/scarfs/actions/workflows/build.yml)
[![docs](https://img.shields.io/badge/api-docs-blue)](https://erikbrinkman.github.io/scarfs/)

A library to find an approximate fixed point for a bounded vector valued
function.

## Installation

```bash
pip install scarfs
```

## Usage

Define the function you want to find a fixed point of using numba:

```python
import numpy as np
from numba import njit

@njit
def roll(simp: np.ndarray) -> np.ndarray:
    return np.roll(simp, 1)
```

For performance reasons, this function must be compiled by numba as a cfunc or
in nopython mode. Jitclass functions are currently not supported. The function
must also lie in a bounded space, three default spaces are provided: the
simplex, the simplotope, and the unit hypercube. If your bounded space is not
one of these, you'll need to first compute a homeomorphism between your space
and one of these. The main algorithm runs on the simplex, so you may find it
faster if you can project there directly.

Once your function is defined, simply call one of the fixed point functions
with an initial position and a discretization:

```python
from scarfs import simplex_fixed_point

sol = simplex_fixed_point(roll, np.array([1, 0, 0, 0], float), 100)
```

The result is guaranteed to be within `1 / discretization` of a true fixed
point (or a little larger for the other bounded spaces).

Note that fixed points are difficult to approximate generally, so this may run
for a very long time.

Also note that this library "trusts" you, so if you pass in invalid inputs, you
may get arcane errors.

## Development

```sh
uv run ruff format --check
uv run ruff check
uv run pyright
uv run pytest
```

## Publishing

Releases are cut from the `release` GitHub Actions workflow, which bumps the
version, builds, and publishes to PyPI via trusted publishing.
