Getting Started¶

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.

Note

A pip-installable version of PyZEAL will be published on PyPI as part of release v1.0.0 (soon).

Using PyZEAL in Scripts¶

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 \(z\mapsto z^2 - 1\) that are contained in the rectangle within the complex plane \(\mathbb{C}\) defined by:

\[\{z\in\mathbb{C}: -2 \leq \mathrm{Re}(z) \leq 2, -2 \leq \mathrm{Im}(z) \leq 2\} .\]

In this minimal example a lot of configuration was not specified explicitly and is therefore determined by settings. If you want to know more about customizing the root finding process the User API Guide is a good place to start. If you are interested in learning more about the mathematical background of the different root finding modes visit Theoretical Background. There you can also find a list of original references.

A more comprehensive getting started example is contained in the following notebook:

Getting started example

Project Overview¶

The project can roughly be divided into the user-facing API (supporting the first use case mentioned in the Introduction) and the framework elements (supporting both the first and second use cases). Here is a rather rough overview over the components making up PyZEAL using class and package diagrams:

API: rootfinders, algorithms, algorithms.estimators, plugins (api classes, api packages)
Framework: utils, pyzeal_logging, settings, pyzeal_types (framework classes, framework packages)
Command line interface: cli (cli classes, cli packages)

More detailed information can be found in the respective sections of either the User API Guide or the (slightly) more developer-oriented Package Reference.

If you have concrete questions on topics like how to use PyZEAL given some concrete use case you might want to consider having a look at our Frequently Asked Questions section. If you want to find out more about how this project was conceived check out Origins of the PyZEAL Project.