The PyZEAL numerical project

Project	Build Status	Coverage	Checkers	Benchmarks

What is PyZEAL?

Welcome to PyZEAL!

This project implements numerical algorithms for the computation of zeros of holomorphic as well as the zeros, poles and residues of meromorphic functions. It aspires to be a successor to and an extension of the original ZEAL (ZEros of AnaLytic functions) package written in Fortran90 by Kravanja, Van Barel, Ragos, Vrahatis, and Zafiropoulos [KVanBarelR+00].

The full documentation of this project is hosted on ReadTheDocs.

While there exists a wealth of theoretical results as well as battle-hardened implementations of such root finding algorithms for e.g. smooth functions (SciPy), the situation in the holomorphic setting is much less comfortable: It appears that most of the algorithms available for holomorphic ones do not possess a readily available, up-to-date, actively maintained implementation.

This (seeming) gap in the software landscape is even more apparant as these types of functions exhibit a rich structure far beyond simple smoothness, opening up the possibility for adapted, more efficient root finding algorithms. The goal of this project then is the practical implementation of such algorithms in an open-source package that is well tested, written in an accessible language, and distributed in a user-friendly manner.

We aim to support two main use cases with this package:

1. Enabling out-of-the-box usage as a tool within any project which requires the calculation of roots or poles of holomorphic or meromorphic functions. In particular this includes seamless integration into the Python ecosystem and a user experience similar to common packages like SciPy or NumPy.
2. Providing a platform for the practical implementation, debugging, testing, and benchmarking of newly developed root finding algorithms as well as their comparison with existing procedures. To this end PyZEAL includes a number of framework elements as well as a plugin mechanism for more light-weight implementations of prototypes.

The approach to achieving these goals will be iterative implementation and optimization of a variety of different algorithms and comparing them, while simultaneously exposing an easy-to-use, accessible, and standardized API.

Installation

First, clone the repository from GitHub using git clone. Then issue the following command in the resulting directory to install the package with pip:

$ python3 -m pip install -e ".[dev]"

This installs the PyZEAL project in editable mode (-e) and including all requirements necessary for local development ([dev]). If you do not wish to conduct your own development on the project, you can safely replace ".[dev]" with a simple ".". Additional installation targets are [docs] (for all dependencies required to build and contribute to the docs) and [all].

You can now import the packages and classes of PyZEAL into your own scripts, run the tests on your local installation, and extend the project by e.g. writing plugins.

Basic Usage

After installation you can use the root finding facilities of PyZEAL by adding just a few lines of code to your Python scripts:

from pyzeal.rootfinders import RootFinder

finder = RootFinder(lambda z: z**2 - 1, lambda z: 2 * z)
finder.calculateRoots((-2, 2), (-2, 2))

print(f"calculated roots: {finder.roots}")

This will calculate numerically those roots of the function mapping z to z^2 - 1 which are contained in the rectangle within the complex plane defined by the conditions -2 <= Re(z) <= 2 and -2 <= Im(z) <= 2 on the real and imaginary parts of the complex variable z.

This minimal example leaves a lot of configuration up to the pre-configured settings. Visit the full documentation to learn more about the possible setups!

Contributing

If you would like to contribute anything from an improvement of the documentation, a new feature request, bug report or (parts of) a root finding algorithm, please feel free to do so. Any collaborations are welcome and the documentation or the open issues might be a good place to start.

To contribute, either clone or fork the repository and create a development branch dev/<your_feature>. Once you have completed your work on this branch create a pull request on the main branch of this repository. At this point your PR requires (at least) one positive review from a core contributor. Once you have received such a review, maybe after addressing some comments and suggestions by the reviewer(s), your PR will be merged effectively making your work part of the mainline PyZEAL package.