PyArmadillo: linear algebra library for Python

Jump to:

Bug Reports

I found a possible bug in the code and/or documentation. How do I report it ?
Please make a small and self-contained program which exposes the bug, and then open an issue at the GitLab repo, or inform the developers via email. The small program should use only functions/classes from PyArmadillo and the standard Python libraries (no other libraries). We appreciate your time to make a bug report.

Citation

How do I cite PyArmadillo in my work ?
Please cite the following article if you use PyArmadillo in your research and/or software.
Citations are useful for the continued development and maintenance of the library.
Jason Rumengan, Terry Yue Zhuo, Conrad Sanderson.
PyArmadillo: a streamlined linear algebra library for Python.
Journal of Open Source Software, Vol. 6, No. 66, 2021.

Distribution License

What is the distribution license for PyArmadillo ?
PyArmadillo is licensed under the Apache License 2.0.
The Apache license is a permissive license; its main conditions simply require preservation of copyright and license notices. See also a Quick Summary of the license.

Can I use PyArmadillo in commercial products without releasing the source code ?
Yes. PyArmadillo can be used in proprietary software, without releasing the source code. However, any software that incorporates or distributes PyArmadillo in source or binary form must include a readable copy of the attributions in the NOTICE.txt file that comes with PyArmadillo. The attributions can be placed in the documentation and/or other materials provided with the software.

How is the Apache License related to the GPL ?
The Apache license and the GPL are completely separate and distinct licenses. Unlike the GPL, the Apache license does not "infect" your source code. See also the comparison of open-source software licenses on Wikipedia.

How is the Apache license related to the MIT and BSD licenses ?
The Apache license is a permissive license similar to the MIT and BSD licenses, but also provides a grant of patent rights from contributors to users. As such, the Apache license can be thought of as an improved version of the MIT and BSD licenses.

Is PyArmadillo a product from the Apache Software Foundation ?
No. We just use the Apache license.

Installation

Can I use PyArmadillo with Python 2.x ?
No. PyArmadillo requires at least Python 3.6. We recommend using Python 3.8 or newer.

How do I upgrade PyArmadillo via pip ?
In general, use this command:
   pip3 install --upgrade --user pyarma
or
   pip3 install --upgrade pyarma

NOTE: it's possible that pip may erroneously not find the newest version. In that case, try the following command:
   pip3 install --no-cache-dir --upgrade --user pyarma
or
   pip3 install --no-cache-dir --upgrade pyarma

The pip3 command seems to be missing on my system ?
If pip3 cannot be found, try using the following alternatives:
python3 -m pip
or
py -m pip

How do I install PyArmadillo from source ?
See the README file in the PyArmadillo archive or at the GitLab repository.

Speed

How fast is PyArmadillo's matrix multiplication ?
PyArmadillo uses BLAS for matrix multiplication, meaning the speed is dependent on the implementation of BLAS. You can use high-speed BLAS replacements to obtain considerably higher performance, such as the multi-threaded (parallelised) OpenBLAS or MKL. Under macOS, the Accelerate framework can be used. If no BLAS library is available, PyArmadillo will use a rudimentary built-in implementation of matrix multiplication.

How fast is PyArmadillo's eigen decomposition, matrix inversion, etc ?
PyArmadillo uses LAPACK for various matrix decompositions and factorisations, meaning the speed is dependent on the implementation of LAPACK and/or BLAS. You can use high-speed LAPACK and BLAS replacements to obtain considerably higher performance, such as the multi-threaded OpenBLAS or MKL. Under macOS, the Accelerate framework can be used.

Development

Can I contribute new functionality ?
Contributions are welcome, provided they are cleanly written, tested, and have accompanying documentation.
New functionality which goes beyond the glue between C++ and Python should be first implemented in the underlying Armadillo C++ library.

Is there a source code repository ?
Yes. See gitlab.com/jason-rumengan/pyarma. Note that the repository may contain work-in-progress code that has not been tested thoroughly.

Features / Functions

I need a specific function, but can't find in the documentation.
If it's not in the documentation, it doesn't exist yet. You can contribute the functionality -- see the answers to development questions.

Is there support for sparse matrices ?
Support for sparse matrices is planned for a future version.

Is it possible to use PyArmadillo matrices with user-defined/custom element types ?
PyArmadillo supports matrices with the following element types: float, double, std::complex<float>, std::complex<double>, int, and unsigned int. Support for other types is beyond the scope of PyArmadillo.

Is the API stable ?
Yes, within each major version. See the documentation for more details.

Miscellaneous

Are there code examples ?
See the code snippets within the documentation, including the short example program.

How can I do ... ?
Check the documentation and/or the README file that comes with the PyArmadillo archive.

What was the motivation for PyArmadillo ?
PyArmadillo was conceived to provide a more user-friendly approach for linear algebra in Python. It takes advantage of the well-tested Armadillo C++ library for the underlying implementation of matrix objects and associated functions. pybind11 is used for providing the glue between C++ and Python.