Metadata-Version: 2.1
Name: pentapy
Version: 1.1.2
Summary: pentapy: A toolbox for pentadiagonal matrizes.
Home-page: https://github.com/GeoStat-Framework/pentapy
Author: Sebastian Müller
Author-email: info@geostat-framework.org
Maintainer: Sebastian Müller
Maintainer-email: info@geostat-framework.org
License: MIT
Project-URL: Documentation, https://pentapy.readthedocs.io
Project-URL: Source, https://github.com/GeoStat-Framework/pentapy
Project-URL: Tracker, https://github.com/GeoStat-Framework/pentapy/issues
Project-URL: Changelog, https://github.com/GeoStat-Framework/pentapy/blob/main/CHANGELOG.md
Project-URL: Conda-Forge, https://anaconda.org/conda-forge/pentapy
Platform: any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Utilities
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy (<2,>=1.14.5)
Provides-Extra: all
Requires-Dist: scipy ; extra == 'all'
Requires-Dist: scikit-umfpack ; extra == 'all'
Provides-Extra: doc
Requires-Dist: m2r2 (<1,>=0.2.8) ; extra == 'doc'
Requires-Dist: scipy (<2,>=1.1.0) ; extra == 'doc'
Requires-Dist: matplotlib (<4,>=3) ; extra == 'doc'
Requires-Dist: perfplot (<1,>=0.8) ; extra == 'doc'
Requires-Dist: numpydoc (<2,>=1.1) ; extra == 'doc'
Requires-Dist: sphinx (<4,>=3) ; extra == 'doc'
Requires-Dist: sphinx-gallery (<1,>=0.8) ; extra == 'doc'
Requires-Dist: sphinx-rtd-theme (<1,>=0.5) ; extra == 'doc'
Provides-Extra: scipy
Requires-Dist: scipy ; extra == 'scipy'
Provides-Extra: test
Requires-Dist: coverage[toml] (<6,>=5.2.1) ; extra == 'test'
Requires-Dist: pytest (<7,>=6.0) ; extra == 'test'
Requires-Dist: pytest-cov (<3,>=2.11.0) ; extra == 'test'
Provides-Extra: umfpack
Requires-Dist: scikit-umfpack ; extra == 'umfpack'

# Welcome to pentapy

[![status](https://joss.theoj.org/papers/57c3bbdd7b7f3068dd1e669ccbcf107c/status.svg)](https://joss.theoj.org/papers/57c3bbdd7b7f3068dd1e669ccbcf107c)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.2587158.svg)](https://doi.org/10.5281/zenodo.2587158)
[![PyPI version](https://badge.fury.io/py/pentapy.svg)](https://badge.fury.io/py/pentapy)
[![Build Status](https://github.com/GeoStat-Framework/pentapy/workflows/Continuous%20Integration/badge.svg?branch=main)](https://github.com/GeoStat-Framework/pentapy/actions)
[![Coverage Status](https://coveralls.io/repos/github/GeoStat-Framework/pentapy/badge.svg?branch=main)](https://coveralls.io/github/GeoStat-Framework/pentapy?branch=main)
[![Documentation Status](https://readthedocs.org/projects/pentapy/badge/?version=latest)](https://geostat-framework.readthedocs.io/projects/pentapy/en/latest/?badge=latest)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)

<p align="center">
<img src="https://github.com/GeoStat-Framework/GeoStat-Framework.github.io/raw/master/docs/source/pics/pentapy.png" alt="pentapy-LOGO" width="251px"/>
</p>


## Purpose

pentapy is a toolbox to deal with pentadiagonal matrices in Python.

Pentadiagonal linear equation systems arise in many areas of science and engineering:
e.g. when solving differential equations, in interpolation problems, or in numerical schemes like finite difference.


## Installation

The package can be installed via [pip][pip_link].
On Windows you can install [WinPython][winpy_link] to get Python and pip running.

    pip install pentapy

There are pre-built wheels for Linux, MacOS and Windows for most Python versions (2.7, 3.4-3.7).

If your system is not supported and you want to have the Cython routines of
pentapy installed, you have to provide a c-compiler and run:

    pip install numpy cython
    pip install pentapy

To get the scipy solvers running, you have to install scipy or you can use the
following extra argument:

    pip install pentapy[all]

Instead of "all" you can also typ "scipy" or "umfpack" to get one of these specific packages.


## Citation

If you use `pentapy` in your publication, please cite it:

> Müller, (2019). pentapy: A Python toolbox for pentadiagonal linear systems. Journal of Open Source Software, 4(42), 1759, https://doi.org/10.21105/joss.01759

To cite a certain release, have a look at the Zenodo site: https://doi.org/10.5281/zenodo.2587158


## References

The solver is based on the algorithms PTRANS-I and PTRANS-II
presented by [Askar et al. 2015][ref_link].


## Documentation and Examples

You can find the documentation under [https://pentapy.readthedocs.org][doc_link].

### Solving a pentadiagonal linear equation system

This is an example of how to solve a LES with a pentadiagonal matrix.

```python
import numpy as np
import pentapy as pp

size = 1000
# create a flattened pentadiagonal matrix
M_flat = (np.random.random((5, size)) - 0.5) * 1e-5
V = np.random.random(size) * 1e5
# solve the LES with M_flat as row-wise flattened matrix
X = pp.solve(M_flat, V, is_flat=True)

# create the corresponding matrix for checking
M = pp.create_full(M_flat, col_wise=False)
# calculate the error
print(np.max(np.abs(np.dot(M, X) - V)))
```

This should give something like:
```python
4.257890395820141e-08
```

### Performance

In the following a couple of solvers for pentadiagonal systems are compared:

* Solver 1: Standard linear algebra solver of Numpy [``np.linalg.solve``](https://www.numpy.org/devdocs/reference/generated/numpy.linalg.solve.html)
* Solver 2: [``scipy.sparse.linalg.spsolve``](http://scipy.github.io/devdocs/generated/scipy.sparse.linalg.spsolve.html)
* Solver 3: Scipy banded solver [``scipy.linalg.solve_banded``](scipy.github.io/devdocs/generated/scipy.linalg.solve_banded.html)
* Solver 4: pentapy.solve with ``solver=1``
* Solver 5: pentapy.solve with ``solver=2``

<p align="center">
<img src="https://raw.githubusercontent.com/GeoStat-Framework/pentapy/main/examples/perfplot_simple.png" alt="Performance" width="600px"/>
</p>

The implementations of pentapy are almost one order of magnitude faster than the
scipy algorithms for banded or sparse matrices.

The performance plot was created with [``perfplot``](https://github.com/nschloe/perfplot).
Have a look at the script: [``examples/03_perform_simple.py``](https://github.com/GeoStat-Framework/pentapy/blob/main/examples/03_perform_simple.py).



## Requirements:

- [NumPy >= 1.14.5](https://www.numpy.org)

### Optional

- [SciPy](https://www.scipy.org/)
- [scikit-umfpack](https://github.com/scikit-umfpack/scikit-umfpack)

## Contact

You can contact us via <info@geostat-framework.org>.


## License

[MIT][licence_link] © 2019 - 2021

[ref_link]: http://dx.doi.org/10.1155/2015/232456
[pip_link]: https://pypi.org/project/pentapy
[winpy_link]: https://winpython.github.io/
[licence_link]: https://github.com/GeoStat-Framework/pentapy/blob/main/LICENSE
[doc_link]: https://pentapy.readthedocs.org

