README.md 10.4 KB
Newer Older
Andreas Dedner's avatar
Andreas Dedner committed
1 2 3
[Repository has been renamed please check our upgrade guide](UPGRADE.md)
========================================================================

4 5 6
Python Bindings for the DUNE Core
=================================

Andreas Dedner's avatar
Andreas Dedner committed
7
dune-python aims to provide Python bindings for the DUNE grid interface:
8 9 10

```python
import math
11
import dune.grid
12
# instanciate a yasp grid on a [0,1]^2 domain
13
grid = dune.grid.structuredGrid([0, 0], [1, 1], [10, 10])
14
# set up a simple grid function providing a global representation
15 16 17
@dune.grid.gridFunction(grid)
def gridfunction(x): return [-(x[1] - 0.5)*math.sin(x[0]*12)]
# iterate over the elements of the grid and output the function at barycenters
18
for element in grid.elements():
19
    x = [0.5,0.5]
20 21
    y = element.geometry.toGlobal(x)
    print("gridfunction( ", y, " ) = ", gridfunction(element,x))
22
# write a vtk file with a piece wise linear representtion of the function
23
grid.writeVTK("output", pointdata={'sin': gridfunction})
24
```
25

Andreas Dedner's avatar
Andreas Dedner committed
26
For a more complete example have a look at our [finite volume][fvcode] example.
Andreas Dedner's avatar
Andreas Dedner committed
27
In addition to bindings for some of the core Dune features dune-python also
28 29
provides tool to easily implement bindings for other Dune modules. This makes
it straightforward to, for example, provide high level bindings for Dune
30
discretization modules. With such bindings performance penalties are minimal
31
while all the flexibility of using Python for high level program flow control is
Andreas Dedner's avatar
Andreas Dedner committed
32
maintained.
Andreas Dedner's avatar
Andreas Dedner committed
33

Andreas Dedner's avatar
Andreas Dedner committed
34 35
See the file COPYING for full copying permissions.

Martin Nolte's avatar
Martin Nolte committed
36

37 38 39
Dependencies
------------

Andreas Dedner's avatar
Andreas Dedner committed
40
dune-python depends on the following DUNE modules:
Martin Nolte's avatar
Martin Nolte committed
41 42 43
- dune-common 2.6+
- dune-geometry 2.6+
- dune-grid 2.6+
44 45 46 47

In addition to the dependencies of these DUNE modules, the following software
packages are required:

Martin Nolte's avatar
Martin Nolte committed
48 49
- a C++14 compatible C++ compiler (e.g., GCC 5+, clang 3.8+)
- Python 2.7+ (regularly tested with 2.7, 3.4, and 3.5)
50 51 52
- The corresponding Python development package (i.e. the Python
  library and header file included for example in the `python-dev`
  package.
53

54 55
To get the most out of the examples we strongly recommend installing the following 
Python packages:
56 57 58 59

- numpy
- mpi4py

60 61 62 63
and also

- jupyter
- matplotlib
64

65 66 67 68

Quick Dive-In Using Docker
--------------------------

Andreas Dedner's avatar
Andreas Dedner committed
69
Users who simply want to use the functionality of `dune-python` as-is, e.g.,
70 71 72 73
for experimenting, can do so using Docker and a web browser.

Just type
```
Andreas Dedner's avatar
Andreas Dedner committed
74
docker run --rm -v dune:/dune -p 127.0.0.1:8888:8888 registry.dune-project.org/staging/dune-python
75 76 77 78 79 80
```
at the command prompt and connect to `localhost:8888` using your favorite web
browser.
Log into Jupyter using the password `dune` and have fun.

For your convenience, the demo notebooks are provided in the folder
Andreas Dedner's avatar
Andreas Dedner committed
81
`dune-python`.
82

83 84 85 86 87 88 89 90
With the above command, your notebooks will be kept persistent in a Docker
volume called `dune`.
To remove this volume, simply type
```
docker volume rm dune
```
at the command prompt.

91 92 93 94 95 96 97
To share python scripts and other files located in the current directory and also
share the output with the docker container use
```
docker run -it -v $PWD:/dune/work registry.dune-project.org/staging/dune-python bash
```
The content of the current directory is then available in the `work`
directory in the docker volume.
98

Andreas Dedner's avatar
Andreas Dedner committed
99 100 101 102
**Note for MAC users:** docker on MAC allocates 2GB to docker by default
which does not suffice for compiling the Dune shared libraries.
Please increase the value to at least 3GB.

Andreas Dedner's avatar
Andreas Dedner committed
103 104
For a quick test of the module
------------------------------
Andreas Dedner's avatar
Andreas Dedner committed
105

Andreas Dedner's avatar
Andreas Dedner committed
106
The following describes a simple procedure for testing `dune-python`
Andreas Dedner's avatar
Andreas Dedner committed
107
without performing a full installation - which is described further down in
108 109
this document.

Andreas Dedner's avatar
Andreas Dedner committed
110
__Note__: You can simply download a short [script][script]
111
which downloads and builds a very basic Dune setup.
Andreas Dedner's avatar
Andreas Dedner committed
112 113 114 115 116

Simply download the module, run `dunecontrol` and set the following
environment variables:

- set `PYTHONPATH` to point to the `python` subfolder in the
Andreas Dedner's avatar
Andreas Dedner committed
117
  `DUNE_PYTHON_BUILD_DIR`.
Andreas Dedner's avatar
Andreas Dedner committed
118
- set `DUNE_CONTROL_PATH` to point to the directory containing the dune core modules
119 120 121 122 123
  (at least `common`, `geometry`, `grid`).  If your core modules are globally installed,
  then your DUNE_CONTROL_PATH needs to include this global installation as well (this
  is different from the usual Dune dependency tracking, which finds globally installed
  modules even if they are not in DUNE_CONTROL_PATH).  On a Debian system, globally
  installed modules are in `/usr/lib/dunecontrol`.
Andreas Dedner's avatar
Andreas Dedner committed
124 125
- It is recommended that you also
  have `dune-alugrid` for some of the demos to work properly - if you want to use
Andreas Dedner's avatar
Andreas Dedner committed
126
  `dune-alugrid` add the build directory of `dune-alugrid` to the
Andreas Dedner's avatar
Andreas Dedner committed
127
  `PYTHONPATH`.
Andreas Dedner's avatar
Andreas Dedner committed
128

Andreas Dedner's avatar
Andreas Dedner committed
129
So use something like (for `bash`)
Andreas Dedner's avatar
Andreas Dedner committed
130

131 132
~~~
export DUNE_CONTROL_PATH=DUNELOCATION
Andreas Dedner's avatar
Andreas Dedner committed
133
export PYTHONPATH=DUNELOCATION/dune-python/build-cmake/python:DUNELOCATION/dune-alugrid/build-cmake/python
134
~~~
Andreas Dedner's avatar
Andreas Dedner committed
135

Andreas Dedner's avatar
Andreas Dedner committed
136 137
__There is one caveat__: since we are generating Python modules to be loaded
dynamically, we need to have all libraries compiled either as shared
138
libraries or from object files containing position independent code (PIC).
139 140 141 142 143
If your Dune modules have been installed globally by a Linux package manager,
they will automatically have these features.  If, on the other hand, you are
building Dune from the source, you need to add
`-DBUILD_SHARED_LIBS=TRUE` to your `CMAKE_FLAGS`.
Alternatively, you can add `-DCMAKE_POSITION_INDEPENDENT_CODE=TRUE`.
Andreas Dedner's avatar
Andreas Dedner committed
144
All Dune modules need to be build in this manner.
Andreas Dedner's avatar
Andreas Dedner committed
145

146
There is a small Python script in the `demo` folder to test your
Andreas Dedner's avatar
Andreas Dedner committed
147 148 149 150 151 152
installation. Go to the `demo` folder and try

~~~
python test.py
~~~

Andreas Dedner's avatar
Andreas Dedner committed
153
If this does not give you an error (e.g. concerning a dune core module that was
Andreas Dedner's avatar
Andreas Dedner committed
154
not found), you have succeeded in setting up `dune-python`.
Andreas Dedner's avatar
Andreas Dedner committed
155 156 157 158 159 160
Note that this can take a moment to run since the `dune-py` is generated
in the `$HOME/.cache` folder. If there was a problem the file `test.log`
should contain additional information.

Examples
--------
Andreas Dedner's avatar
Andreas Dedner committed
161

Andreas Dedner's avatar
Andreas Dedner committed
162 163
Some examples showing how to use `dune-python` can be found in the `demo`
subdirectory of source tree of `dune-python`. More advanced example are
Andreas Dedner's avatar
Andreas Dedner committed
164 165 166 167 168
contained in `jupyter notebooks` in the `notebooks` folder. If you do not
have `jupyter` installed Python scripts are also available.

FULL INSTALLATION
=================
Andreas Dedner's avatar
Andreas Dedner committed
169

Andreas Dedner's avatar
Andreas Dedner committed
170
The approach given above gives you a very simple setup which will allow you to test 
Andreas Dedner's avatar
Andreas Dedner committed
171
the basic features of `dune-python`.
Andreas Dedner's avatar
Andreas Dedner committed
172 173
A more advanced installation using `pip` are explained in the following.

174 175 176
Using a Virtual Env
-------------------

177
If you want to install Dune Python bindings as a user, we recommend using a Python virtual env.
178
This will isolate your Dune packages from other Python modules.
179 180

To use this approach, just create a virtual env and activate it before
181 182 183 184 185 186 187 188
configuring your Dune modules for a system wide installation.
This way, the Python interpreter from your virtual env will automatically be used.
Note that Python packages are installed into a virtual env like system
packages are installed into the system. Therefore, you need to configure
your Dune modules as though you were doing a system wide installation,
but root privileges are not required.

You can also install all your DUNE modules into the virtual env by setting the
189 190 191 192 193
`CMAKE_INSTALL_PREFIX` to the virtual env.

The dune-py Module
------------------

194
The Dune code contains lots of templates and we cannot guess which ones the
195
Python user will instantiate at run time.
196 197 198
To resolve this problem, we build additional Python modules (C++ shared
libraries) on demand. A special Dune module called dune-py is used to build
these Python modules. It is special in the following sense:
199

200
- dune-py cannot be installed into the system, as some code will be generated at run time.
Oliver Sander's avatar
Oliver Sander committed
201
- Each user needs write access to a dune-py module and its build directory.
202 203
- Only one Python process may use a dune-py module at a time.

204
Therefore, we generate one dune-py module per user. The default position
205
is `${HOME}/.cache/dune-py`, but you can customize it through the environment
Oliver Sander's avatar
Oliver Sander committed
206
variable `DUNE_PY_DIR`. Notice that this directory should be exclusive to
207 208 209
each user to avoid race conditions. It is also advisable to locate this
directory on local storage for performance reasons.

Andreas Dedner's avatar
Andreas Dedner committed
210
In the following we describe two approaches for installing dune-python and
211
generating the dune-py module depending on your overall Dune setup.
212

213 214
[Working with a Preinstalled Dune](PACKAGEINSTALL.md)
-----------------------------------------------------
215

216
[Working with Dune Source Modules](SOURCEINSTALL.md)
217
----------------------------------------------------
218 219 220 221

Environment Variables
---------------------

Andreas Dedner's avatar
Andreas Dedner committed
222
When using dune-python from Python, a number of environment variables influence
223
its behaviour:
224 225 226 227 228 229

- `DUNE_LOG_LEVEL`: minimum level for logged messages.
  Choices are `debug`, `info`, `warning`, `error`.
  The default is `warning`.
- `DUNE_LOG_FORMAT`: format string for log messages.
  See documentation of Python's *logging* package.
230 231 232 233 234 235
- `DUNE_PY_DIR`: location of `dune-py` module.
  The default is `$HOME/.cache`.
- `DUNE_FORCE_BUILD`: if set to true, generated modules will be recompiled
  even if they already exist.
  The default is `false`.

Andreas Dedner's avatar
Andreas Dedner committed
236
Further Dune modules based on dune-python
237
-----------------------------------------
238

Andreas Dedner's avatar
Andreas Dedner committed
239
The following dune models can at moment be used together with dune-python:
240 241
- [dune-alugrid][alugridlink]: if you want to use dune-alugrid simply configure
  the module
Ansgar Burchardt's avatar
Ansgar Burchardt committed
242
  with the flags discussed above and run `make install_python` in the build
Andreas Dedner's avatar
Andreas Dedner committed
243
  directory (or use the `setup-dunepy` script in `dune-python`).
244 245
- [dune-spgrid][spgridlink]: also now provideds Python bindings.
- [dune-fempy][fempylink]: this is a new module providing high level Python
246 247
  bindings to the [dune-fem][femlink] module.
  You can use this to solve complex non linear partial
248
  differential equations from within Python. dune-fempy also makes use of the
249 250 251
  unified form language (UFL) to provide a descriptive language for entering
  the mathematical models.

252
Acknowledgements
253 254
---------------

255
For the C++ to Python bindings we use the great project [pybind11][pybind11] -
Andreas Dedner's avatar
Andreas Dedner committed
256
the sources are included in the dune-python module.
257 258 259
The initial code was implemented by Michaël Sghaïer during the
[Google Summer of Code][gsoc] program 2016.

Andreas Dedner's avatar
Andreas Dedner committed
260
[fvcode]: https://gitlab.dune-project.org/michael.sghaier/dune-python/blob/remove-database/demo/finitevolume.py
261
[alugridlink]: https://gitlab.dune-project.org/extensions/dune-alugrid
262
[spgridlink]: https://gitlab.dune-project.org/extensions/dune-spgrid
263
[fempylink]: https://gitlab.dune-project.org/dune-fem/dune-fempy
264
[femlink]: https://gitlab.dune-project.org/dune-fem/dune-fem
265
[pybind11]: https://github.com/pybind/pybind11
266
[gsoc]: https://summerofcode.withgoogle.com/
Oliver Sander's avatar
Oliver Sander committed
267
[script]: buildpy.sh