Metadata-Version: 2.1
Name: scarfs
Version: 0.1.1
Summary: find approximate fixed points of bounded vector valued functions
License: MIT
Author: Erik Brinkman
Author-email: erik.brinkman@gmail.com
Requires-Python: >=3.8,<3.11
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Requires-Dist: numba (>=0.55.1,<0.56.0)
Requires-Dist: numpy (>=1.18,<1.22)
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)

A library to find an approximate fixed point for a 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
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.

