A wrapper for the MEPACK (Matrix Equation Package) library
Project description
python-mepack (pyMEPACK)
Version: 1.1.0
Copyright 2023 by Martin Köhler, MPI-Magdeburg
Description
Python Interface for MEPACK
- a Fortran software library for the solution of dense Sylvester-like matrix equations.
The pyMEPACK interfaces routines solving the following equations:
- Standard Lyapunov equations (
gelyap
) $AX + XA^T = Y
$ - Standard Stein (Discrete-Time Lyapunov) equations (
gestein
)$AXA^T - X = Y
$ - Generalized Lyapunov equations (
gglyap
) $AXB^T + BXA^T = Y
$ - Generalized Stein (Discrete-Time Lyapunov) Equation (
ggstein
) $AXA^T - BXB^T = Y
$ - Standard Sylvester equations (
gesylv
) $AX + XB = Y
$ - Discrete-time Sylvester equations (
gesylv2
) $AXB + X = Y
$ - Generalized Sylvester equations (
ggsylv
) $AXB + CXD = Y
$ - Generalized coupled Sylvester equations (
ggcsylv
) $AR + LB = E, CR + LD = F
$ - Dual generalized coupled Sylvester equations (
ggcsylv_dual
) $AR + CL = E, RB + LD = F
$
The library includes single and double precision solvers with iterative refinement for the above equations.
Dependencies
To install and run pyMEPACK the following components are required:
- MEPACK Version 1.1.0
- a BLAS and LAPACK implementation
- Python 3.7.0 +
- Cython 0.29.28 +
- numpy 1.20.0 +
- scipy 1.6.0 +
- setuptools 59.0.0 +
- configparser 5.2.0 +
- parameterized 0.8.0 + (only for tests)
- h5py 3.6.0 + (only for benchmarks)
- slycot 0.4.0 (only for benchmarks)
- Sphinx 5.0.2 + (for documentation)
Installation
pyMEPACK requires MEPACK to be installed on your system. See MEPACK's installation guide for detail (https://gitlab.mpi-magdeburg.mpg.de/software/mepack-release/-/blob/master/doc/install.md?ref_type=heads).
If MEPACK is not installed in a default location or the BLAS and LAPACK library
are not named blas
and lapack
the pymepack.cfg
file can be used to setup
these differences. See pymepack.cfg-sample for details.
The installation of pyMEPACK is done by executing the following commands in the root directory of the project:
pip install .
or
pip install --user .
After a successful installation, pyMEPACK can be imported via import pymepack
.
Documentation
Documentation of the pyMEPACK functions is accessible in the form of __doc__ strings.
HTML Documentation can be build with Sphinx inside the docs
directory:
(cd ./docs && make html)
How to use pyMEPACK
The interface of pyMEPACK is very concise and easy to work with. The following code snippet solves a Lyapunov equation and computes the relative residual of the solution.
#!/usr/bin/env python3
import pymepack as pme
import numpy as np
import scipy as sp
n = 1000
# Prepare
A = np.triu(np.ones((n,n))) + np.diag(np.ones((n)))
X = np.ones((n,n))
Y = A @ X + X @ A.conj().T
# Solve
Xcomp, *_ = pme.gelyap(A, Y)
# Compute the residual
RelRes = pme.res_gelyap(A, Xcomp, Y)
print("Size = {:d} RelRes = {:e}".format(n, RelRes))
Testing
pyMEPACK contains a test suite. This is executed via
(cd /tmp && python3 -m unittest -v pymepack.tests)
The test suite cannot run from the root of source code after installation.
Test data
gelyap
, gglyap
, gestein
and ggstein
solvers, as well as their
respective versions with iterative refinement are tested on examples provided
in SLICOT benchmark collections, namely BB03AD
and BB04AD
[1,2].
All the Sylvester solvers are tested using randomization. We use numpy.random
module and supply the random generator with a seed to avoid build instability.
Last tested with numpy.version = 1.24.1. The non-symmetric stable matrices are
constructed as in the example 4.1 in [1].
Tuning and Benchmarks
See Benchmark and Tuning.
License
pyMEPACK, like MEPACK it self, is license under GPLv3.
Authors
- Martin Köhler, MPI Magdeburg
- Aleksey Maleyko, MPI Magdeburg
Citation
Martin Köhler. (2023). MEPACK: Matrix Equation PACKage (1.1.0). Zenodo. https://doi.org/10.5281/zenodo.10016456
References
[1] Benner, P., 2004. Factorized solution of Sylvester equations with applications in control. sign (H), 1, p.2.
[2] D. Kressner, V. Mehrmann, and T. Penzl. CTLEX - a Collection of Benchmark Examples for Continuous-Time Lyapunov Equations. SLICOT Working Note 1999-6, 1999.
[3] D. Kressner, V. Mehrmann, and T. Penzl. DTLEX - a Collection of Benchmark Examples for Discrete-Time Lyapunov Equations. SLICOT Working Note 1999-7, 1999.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Hashes for pymepack-1.1.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ddfd6fd1bea92a8fafe3d5b5cb92ba183e92c887855ccaa00b7eee5f0456ff38 |
|
MD5 | 1e19a333ad1222ddb1cadcf145e969b4 |
|
BLAKE2b-256 | 8b72648d6e9152f93d9bf9df202808043c89083c9b121f0c9d4525fb8e415596 |
Hashes for pymepack-1.1.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 060cdf30d7f119ce38721bb67646c782247c1880754fb713b8ef3816122b5a82 |
|
MD5 | a00c321eb15ffb0cdc7d5efe1bcdd61a |
|
BLAKE2b-256 | d1b9acfafd523418b095a4363824ad7128b1caef95c98804fdabbab555ed3357 |
Hashes for pymepack-1.1.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c31de64e963214a3e124db2b7ded366fdba0eda9a4ed5456001085ef93de11b5 |
|
MD5 | f1fc9936466f8c7eef8a0e04fdec790d |
|
BLAKE2b-256 | 24a678c46e8697c5399a65730c76cf99ec485d8ca30b01189fd0287e349e1c9b |
Hashes for pymepack-1.1.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 83804dd606892cd0e6932a9fe2325c042d8a131580cf474dd433759fe3f295dc |
|
MD5 | 7e657bd4d389283be8ad7178d7d1c8f8 |
|
BLAKE2b-256 | afa904449055d9ee95a8e0cbec91d62a2186bd766e745ef9e9d2107f4575e582 |
Hashes for pymepack-1.1.0-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 911f8075cdc62b8f6d0aa4b4b6ccd952a88fd58ab60b4f697fa9fad453cacc72 |
|
MD5 | 85acb10b55d91b8044035650f336f5cb |
|
BLAKE2b-256 | 64eb7eb8d3a5da8bbbfa17160b720794b73abd0a36d68d5573aba6b281a5bde0 |
Hashes for pymepack-1.1.0-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 91559e4df74b880430de7d9346a859ec6858f15457bb5618b7ce63d0feac3ef4 |
|
MD5 | ff228677a158f177b44828b9cca56cba |
|
BLAKE2b-256 | 0130ee009b503107a9b5db1ae7fdc270cecc85ed45a1679c803e677d652107b1 |