README.md 10 KB
Newer Older
1
pyMOR - Model Order Reduction with Python
Stephan Rave's avatar
Stephan Rave committed
2
=========================================
Rene Milk's avatar
Rene Milk committed
3

René Fritze's avatar
René Fritze committed
4 5 6 7
pyMOR is a software library for building model order
reduction applications with the Python programming language. Implemented
algorithms include reduced basis methods for parametric linear and non-linear
problems, as well as system-theoretic methods such as balanced truncation or
8 9 10 11 12
IRKA (Iterative Rational Krylov Algorithm).  All algorithms in pyMOR are
formulated in terms of abstract interfaces for seamless integration with
external PDE (Partial Differential Equation) solver packages.  Moreover, pure
Python implementations of FEM (Finite Element Method) and FVM (Finite Volume
Method) discretizations using the NumPy/SciPy scientific computing stack are
René Fritze's avatar
René Fritze committed
13
provided for getting started quickly.
Stephan Rave's avatar
Stephan Rave committed
14

Stephan Rave's avatar
Stephan Rave committed
15 16
[![PyPI](https://img.shields.io/pypi/pyversions/pymor.svg)](https://pypi.python.org/pypi/pymor)
[![PyPI](https://img.shields.io/pypi/v/pymor.svg)](https://pypi.python.org/pypi/pymor)
17
[![Docs](https://img.shields.io/endpoint?url=https%3A%2F%2Fdocs.pymor.org%2Fbadge.json)](https://docs.pymor.org/latest)
Stephan Rave's avatar
Stephan Rave committed
18
[![DOI](https://zenodo.org/badge/9220688.svg)](https://zenodo.org/badge/latestdoi/9220688)
19 20
[![GitLab Pipeline](https://zivgitlab.uni-muenster.de/pymor/pymor/badges/master/pipeline.svg)](https://zivgitlab.uni-muenster.de/pymor/pymor/commits/master)
[![Azure Pipeline](https://dev.azure.com/pymor/pymor/_apis/build/status/pymor.pymor?branchName=master)](https://dev.azure.com/pymor/pymor/_build/latest?definitionId=1&branchName=master)
21

Stephan Rave's avatar
Stephan Rave committed
22 23 24
License
-------

25
Copyright 2013-2020 pyMOR developers and contributors. All rights reserved.
26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
following conditions are met:

* Redistributions of source code must retain the above copyright notice, this list of conditions and the following
  disclaimer.
* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
  disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Stephan Rave's avatar
Stephan Rave committed
43

44 45 46
The following files contain source code originating from other open source software projects:

* docs/source/pymordocstring.py  (sphinxcontrib-napoleon)
Stephan Rave's avatar
Stephan Rave committed
47
* src/pymor/algorithms/genericsolvers.py (SciPy)
48 49 50

See these files for more information.

Stephan Rave's avatar
Stephan Rave committed
51

Stephan Rave's avatar
Stephan Rave committed
52 53 54
Citing
------

55
If you use pyMOR for academic work, please consider citing our
56
[publication](https://doi.org/10.1137/15M1026614):
Stephan Rave's avatar
Stephan Rave committed
57 58 59

	R. Milk, S. Rave, F. Schindler
	pyMOR - Generic Algorithms and Interfaces for Model Order Reduction
60
	SIAM J. Sci. Comput., 38(5), pp. S194--S216, 2016
Stephan Rave's avatar
Stephan Rave committed
61 62


63 64
Installation via pip
--------------------
65

Felix Schindler's avatar
Felix Schindler committed
66
We recommend installation of pyMOR in a [virtual environment](https://virtualenv.pypa.io/en/latest/).
René Fritze's avatar
René Fritze committed
67 68

pyMOR can easily be installed with the [pip](https://pip.pypa.io/en/stable/)
69
command:
70

René Fritze's avatar
René Fritze committed
71
    pip install --upgrade pip  # make sure that pip is reasonably new
Stephan Rave's avatar
Stephan Rave committed
72
    pip install pymor[full]
73

74 75
(Please note that pip must be at least version 9.0.0)

René Fritze's avatar
René Fritze committed
76 77 78 79
This will install the latest release of pyMOR on your system with most optional
dependencies.
For Linux we provide binary wheels, so no further system packages should
be required. Use
Stephan Rave's avatar
Stephan Rave committed
80 81 82

    pip install pymor

René Fritze's avatar
René Fritze committed
83 84 85 86
for an installation with minimal dependencies.
There are some optional packages not included with `pymor[full]`
because they need additional setup on your system:

87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102
- for support of MPI distributed models and parallelization of greedy algorithms
  (requires MPI development headers and a C compiler):

      pip install mpi4py

- dense matrix equation solver for system-theoretic MOR methods, required for
  H-infinity norm calculation (requires OpenBLAS headers and a Fortran
  compiler):

      pip install slycot

- dense and sparse matrix equation solver for system-theoretic MOR methods
  (other backends available):
    - from [source](https://gitlab.mpi-magdeburg.mpg.de/mess/cmess-releases)
      (recommended)
    - using a [wheel](https://www.mpi-magdeburg.mpg.de/projects/mess)
René Fritze's avatar
René Fritze committed
103 104

If you are not operating in a virtual environment, you can pass the optional `--user`
105 106 107 108
argument to pip. pyMOR will then only be installed for your
local user, not requiring administrator privileges.

To install the latest development version of pyMOR, execute
109

Stephan Rave's avatar
Stephan Rave committed
110
    pip install git+https://github.com/pymor/pymor#egg=pymor[full]
111

112 113
which will require that the [git](https://git-scm.com/) version control system is
installed on your system.
114

115 116 117 118 119
From time to time, the master branch of pyMOR undergoes major changes and things
might break (this is usually announced on our
[mailing list](http://listserv.uni-muenster.de/mailman/listinfo/pymor-dev)),
so you might prefer to install pyMOR from the current release branch:

120
    pip install git+https://github.com/pymor/pymor@2020.1.x#egg=pymor[full]
121 122 123 124

Release branches will always stay stable and will only receive bugfix commits
after the corresponding release has been made.

125

126 127 128 129 130 131 132 133
Installation via conda
----------------------

pyMOR can be installed using `conda` by running

    conda install -c conda-forge pymor


Stephan Rave's avatar
Stephan Rave committed
134 135 136
Documentation
-------------

René Fritze's avatar
René Fritze committed
137 138 139
Documentation is available online at [Read the Docs](https://pymor.readthedocs.org/)
or you can build it yourself from inside the root directory of the pyMOR source tree
by executing:
Stephan Rave's avatar
Stephan Rave committed
140

141
    make docs
142

René Fritze's avatar
René Fritze committed
143
This will generate HTML documentation in `docs/_build/html`.
144 145


Christian's avatar
Christian committed
146 147 148
Useful Links
------------

149 150
* [Latest Changelog](https://docs.pymor.org/latest/release_notes.html)
* [Getting Started](https://docs.pymor.org/latest/getting_started.html)
151
* [Dependencies](https://github.com/pymor/pymor/blob/2020.1.x/requirements.txt)
Christian's avatar
Christian committed
152 153


154 155 156 157 158 159 160 161 162
External PDE solvers
--------------------

pyMOR has been designed with easy integration of external PDE solvers
in mind.

A basic approach is to use the solver only to generate high-dimensional
system matrices which are then read by pyMOR from disk (`pymor.discretizers.disk`).
Another possibility is to steer the solver via an appropriate network
163
protocol.
164

165 166 167
Whenever possible, we recommend to recompile the solver as a
Python extension module which gives pyMOR direct access to the solver without
any communication overhead. A basic example using
René Fritze's avatar
René Fritze committed
168 169
[pybind11](https://github.com/pybind/pybind11) can be found in
`src/pymordemos/minimal_cpp_demo`. Moreover,
170 171
we provide bindings for the following solver libraries:

172
* [FEniCS](https://fenicsproject.org)
173 174

    MPI-compatible wrapper classes for dolfin linear algebra data structures are
175
    shipped with pyMOR (`pymor.bindings.fenics`).
176
    For an example see `pymordemos.thermalbock`, `pymordemos.thermalblock_simple`.
177
    It is tested using version 2019.1.0.
178 179 180 181 182 183

* [deal.II](https://dealii.org)

    Python bindings and pyMOR wrapper classes can be found
    [here](https://github.com/pymor/pymor-deal.II).

184 185 186 187 188
* [NGSolve](https://ngsolve.org)

    Wrapper classes for the NGSolve finite element library are shipped with pyMOR
    (`pymor.bindings.ngsolve`).
    For an example see `pymordemos.thermalblock_simple`.
189
    It is tested using version v6.2.2006.
190 191


192 193 194 195 196
Do not hesitate to contact
[us](http://listserv.uni-muenster.de/mailman/listinfo/pymor-dev) if you
need help with the integration of your PDE solver.


197 198 199
External Matrix Equation Solvers
--------------------------------

Christian's avatar
Christian committed
200 201
pyMOR also provides bindings to matrix equation solvers (in `pymor.bindings`),
which are needed for the system-theoretic methods and need to be installed
Christian's avatar
Christian committed
202
separately. Bindings for the following solver libraries are included:
203

Christian's avatar
Christian committed
204
* [Py-M.E.S.S.](https://www.mpi-magdeburg.mpg.de/projects/mess)
205

Christian's avatar
Christian committed
206
    The Matrix Equation Sparse Solver library is intended for solving large sparse matrix equations (`pymor.bindings.pymess`).
207 208 209

* [Slycot](https://github.com/python-control/Slycot)

210
    Python wrapper for the Subroutine Library in Systems and Control Theory (SLICOT) is also used for Hardy norm computations (`pymor.bindings.slycot`).
211 212


213 214 215
Setting up an Environment for pyMOR Development
-----------------------------------------------

216
If you already installed a pyMOR release version, please uninstall it
217

218 219 220
    pip uninstall pyMOR

Then, clone the pyMOR git repository using
221 222 223 224 225 226

    git clone https://github.com/pymor/pymor $PYMOR_SOURCE_DIR
    cd $PYMOR_SOURCE_DIR

and, optionally, switch to the branch you are interested in, e.g.

227
    git checkout 2020.1.x
228

René Fritze's avatar
René Fritze committed
229
Then, make an editable installation of pyMOR with
230

René Fritze's avatar
René Fritze committed
231
    pip install -e .[full]
232

233

Rene Milk's avatar
Rene Milk committed
234 235
Tests
-----
236

René Fritze's avatar
René Fritze committed
237
pyMOR uses [pytest](https://pytest.org/) for unit testing. To run the test suite,
238 239 240 241 242 243 244
simply execute `make test` in the base directory of the pyMOR repository. This will
run the pytest suite with the default hypothesis profile "dev". For available profiles
see `src/pymortests/conftest.py`. A profile is selected by running `make PYMOR_HYPOTHESIS_PROFILE=PROFILE_NAME test`.
If docker is available, use `make PYMOR_HYPOTHESIS_PROFILE=PROFILE_NAME docker_test` to execute the test suite
in the same environment as on pyMOR's CI infrastructure. Additional customization points are listed at the top of the
`Makefile`.
Run `make full-test` which will also enable
Stephan Rave's avatar
Stephan Rave committed
245
[pyflakes](https://pypi.python.org/pypi/pyflakes) and
René Fritze's avatar
René Fritze committed
246
[pep8](https://www.python.org/dev/peps/pep-0008/) checks.
Stephan Rave's avatar
Stephan Rave committed
247 248 249

All tests are contained within the `src/pymortests` directory and can be run
individually by executing `py.test src/pymortests/the_module.py`.
Stephan Rave's avatar
Stephan Rave committed
250 251 252 253 254


Contact
-------

255
Should you have any questions regarding pyMOR or wish to contribute,
Stephan Rave's avatar
Stephan Rave committed
256 257
do not hestitate to contact us via our development mailing list:

258
<http://listserv.uni-muenster.de/mailman/listinfo/pymor-dev>