numba-scipy documentation

This is the numba-scipy documentation. Unless you are already acquainted with numba-scipy perhaps start with the User manual.

User Manual

The numba-scipy user manual.

Reference Manual

The numba-scipy reference manual.

Supported functions from scipy.sparse

Sparse matrix support is currently experimental and limited to boxing and unboxing of the scipy.sparse.csr_matrix and scipy.sparse.csc_matrix types and support for the numpy.shape() function, the property ndim, and the copy() method.

Supported functions from scipy.special

The following functions are supported:

Contributing to numba-scipy

Contributions to numba-scipy are always welcomed! Even simple documentation improvements are encouraged. If you have questions, don’t hesitate to ask them (see below).

Communication

Contact

The Numba community uses Discourse for asking questions and having discussions about numba-scipy. There are various categories available and it can be reached at: numba.discourse.group. There is a category for numba-scipy.

Real-time Chat

numba-scipy uses Gitter for public real-time chat. To help improve the signal-to-noise ratio, there are two channels:

  • numba/numba: General discussion, questions, and debugging help.

  • numba/numba-dev: Discussion of PRs, planning, release coordination, etc.

Both channels are public.

Note that the Github issue tracker is the best place to report bugs. Bug reports in chat are difficult to track and likely to be lost.

Bug tracker

The Github issue tracker is used to track both bug reports and feature requests.

Getting set up

If you want to contribute, it’s best to fork the Github repository, then create a branch representing your work. When your work is ready, you should submit it as a pull request from the Github interface.

If you want, you can submit a pull request even when you haven’t finished working. This can be useful to gather feedback, or to stress your changes against the continuous integration platform. In this case, please prepend [WIP] to your pull request’s title.

Build environment

numba-scipy has a number of dependencies (mostly Numba and SciPy). Unless you want to build those dependencies yourself, it’s recommended you use conda to create a dedicated development environment and install pre-compiled versions of those dependencies there.

First add the Anaconda Cloud numba channel so as to get development builds of the numba library:

$ conda config --add channels numba

Then create an environment with the right dependencies:

$ conda create -n numba-scipy python=3.7 scipy numba

Note

This installs an environment based on Python 3.7, but you can of course choose another version supported by Numba.

To activate the environment for the current shell session:

$ conda activate numba-scipy

Note

These instructions are for a standard Linux shell. You may need to adapt them for other platforms.

Once the environment is activated, you have a dedicated Python with the required dependencies.

Building numba-scipy

For a convenient development workflow, it’s recommended that you build numba-scipy inside its source checkout:

$ git clone git://github.com/numba/numba-scipy.git
$ cd numba-scipy
$ python setup.py develop

Running tests

numba-scipy is validated using a test suite comprised of various kind of tests (unit tests, functional tests). The test suite is written using the standard unittest framework and rely on pytest for execution. The pytest package will need installing to run the tests, using conda this can be achieved by:

$ conda install pytest

The tests can then be executed via python -m pytest.

Development rules

Code reviews

Any non-trivial change should go through a code review by one or several of the core developers. The recommended process is to submit a pull request on github.

A code review should try to assess the following criteria:

  • general design and correctness

  • code structure and maintainability

  • coding conventions

  • docstrings, comments

  • test coverage

Coding conventions

All Python code should follow PEP 8. Code and documentation should generally fit within 80 columns, for maximum readability with all existing tools (such as code review UIs).

Stability

The repository’s main branch is expected to be stable at all times. This translates into the fact that the test suite passes without errors on all supported platforms (see below). This also means that a pull request also needs to pass the test suite before it is merged in.

Platform support

Every commit to the main branch is automatically tested on a selection of platforms. Azure is used to to provide public continuous integration information for as many combinations as can be supported by the service. If you see problems on platforms with which you are unfamiliar, feel free to ask for help in your pull request. The numba-scipy core developers can help diagnose cross-platform compatibility issues.

Documentation

This documentation is under the docs directory of the numba-scipy repository. It is built with Sphinx, which is available using conda or pip.

To build the documentation, you need the bootstrap theme:

$ pip install sphinx_bootstrap_theme

You can edit the source files under docs/source/, after which you can build and check the documentation:

$ make html
$ open _build/html/index.html

Release Notes

Version 0.4

In development

Version 0.3.1

This is a maintenance release that:

  • Updates the maximum SciPy dependency to 1.7.3.

  • Updates Azure CI.

Contributors:

  • Benda Xu

  • Siu Kwan Lam

  • Valentin Haenel

Version 0.3

This release adds:

  • Dynamic generation of scipy.special.signatures (with thanks to Brandon T. Willard)

  • Github Actions CI

Importantly, the dynamic generation of the signatures now makes numba-scipy compatible with multiple SciPy releases simultaneously.

Contributors:

  • Brandon T. Willard

  • Valentin Haenel

Version 0.2

This release adds the start of real functionality and builds out the project infrastructure.

  • Support for a large number of scipy.special functions (with thanks to Josh Wilson).

  • Entry point registration system in use to auto-register this as a Numba extension project.

  • Documentation.

  • CI builds.

  • Conda package.

Contributors:

  • Josh Wilson

  • Stan Seibert (core dev)

  • Stuart Archibald (core dev)

Version 0.1

This is the initial demo release.

  • Initial Release.

  • Demonstrative support for a couple of example scipy.special functions.

  • Basic project infrastructure.

Contributors:

  • Stuart Archibald (core dev)