Skip to main content

A wrapper for the MEPACK (Matrix Equation Package) library

Project description

python-mepack (pyMEPACK)

Version: 1.1.1

Copyright 2023-2024 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.1
  • a BLAS and LAPACK implementation
  • Python 3.7.0 +
  • Cython 0.29.28 +
  • numpy 1.20.3 +
  • scipy 1.5.4 +
  • 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. (2024). MEPACK: Matrix Equation PACKage (1.1.1). Zenodo. https://doi.org/10.5281/zenodo.10568848

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


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pymepack-1.1.1.post2.tar.gz (1.0 MB view hashes)

Uploaded Source

Built Distributions

pymepack-1.1.1.post2-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (18.4 MB view hashes)

Uploaded CPython 3.12 manylinux: glibc 2.17+ x86-64

pymepack-1.1.1.post2-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (18.6 MB view hashes)

Uploaded CPython 3.11 manylinux: glibc 2.17+ x86-64

pymepack-1.1.1.post2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (18.1 MB view hashes)

Uploaded CPython 3.10 manylinux: glibc 2.17+ x86-64

pymepack-1.1.1.post2-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (18.1 MB view hashes)

Uploaded CPython 3.9 manylinux: glibc 2.17+ x86-64

pymepack-1.1.1.post2-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (18.4 MB view hashes)

Uploaded CPython 3.8 manylinux: glibc 2.17+ x86-64

pymepack-1.1.1.post2-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (17.4 MB view hashes)

Uploaded CPython 3.7m manylinux: glibc 2.17+ x86-64

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page