[Repository has been renamed please check our upgrade guide](UPGRADE.md) ======================================================================== Python Bindings for the DUNE Core ================================= dune-python aims to provide Python bindings for the DUNE grid interface: ```python import math import dune.grid # instanciate a yasp grid on a [0,1]^2 domain grid = dune.grid.structuredGrid([0, 0], [1, 1], [10, 10]) # set up a simple grid function providing a global representation @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 for element in grid.elements(): x = [0.5,0.5] y = element.geometry.toGlobal(x) print("gridfunction( ", y, " ) = ", gridfunction(element,x)) # write a vtk file with a piece wise linear representtion of the function grid.writeVTK("output", pointdata={'sin': gridfunction}) ``` For a more complete example have a look at our [finite volume][fvcode] example. In addition to bindings for some of the core Dune features dune-python also provides tool to easily implement bindings for other Dune modules. This makes it straightforward to, for example, provide high level bindings for Dune discretization modules. With such bindings performance penalties are minimal while all the flexibility of using Python for high level program flow control is maintained. See the file COPYING for full copying permissions. Dependencies ------------ dune-python depends on the following DUNE modules: - dune-common 2.6+ - dune-geometry 2.6+ - dune-grid 2.6+ In addition to the dependencies of these DUNE modules, the following software packages are required: - 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) - The corresponding Python development package (i.e. the Python library and header file included for example in the `python-dev` package. To get the most out of the examples we strongly recommend installing the following Python packages: - numpy - mpi4py and also - jupyter - matplotlib Quick Dive-In Using Docker -------------------------- Users who simply want to use the functionality of `dune-python` as-is, e.g., for experimenting, can do so using Docker and a web browser. Just type ``` docker run --rm -v dune:/dune -p 127.0.0.1:8888:8888 registry.dune-project.org/staging/dune-python ``` 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 `dune-python`. 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. 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. **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. For a quick test of the module ------------------------------ The following describes a simple procedure for testing `dune-python` without performing a full installation - which is described further down in this document. __Note__: You can simply download a short [script][script] which downloads and builds a very basic Dune setup. Simply download the module, run `dunecontrol` and set the following environment variables: - set `PYTHONPATH` to point to the `python` subfolder in the `DUNE_PYTHON_BUILD_DIR`. - set `DUNE_CONTROL_PATH` to point to the directory containing the dune core modules (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`. - It is recommended that you also have `dune-alugrid` for some of the demos to work properly - if you want to use `dune-alugrid` add the build directory of `dune-alugrid` to the `PYTHONPATH`. So use something like (for `bash`) ~~~ export DUNE_CONTROL_PATH=DUNELOCATION export PYTHONPATH=DUNELOCATION/dune-python/build-cmake/python:DUNELOCATION/dune-alugrid/build-cmake/python ~~~ __There is one caveat__: since we are generating Python modules to be loaded dynamically, we need to have all libraries compiled either as shared libraries or from object files containing position independent code (PIC). 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`. All Dune modules need to be build in this manner. There is a small Python script in the `demo` folder to test your installation. Go to the `demo` folder and try ~~~ python test.py ~~~ If this does not give you an error (e.g. concerning a dune core module that was not found), you have succeeded in setting up `dune-python`. 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 -------- 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 contained in `jupyter notebooks` in the `notebooks` folder. If you do not have `jupyter` installed Python scripts are also available. FULL INSTALLATION ================= The approach given above gives you a very simple setup which will allow you to test the basic features of `dune-python`. A more advanced installation using `pip` are explained in the following. Using a Virtual Env ------------------- If you want to install Dune Python bindings as a user, we recommend using a Python virtual env. This will isolate your Dune packages from other Python modules. To use this approach, just create a virtual env and activate it before 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 `CMAKE_INSTALL_PREFIX` to the virtual env. The dune-py Module ------------------ The Dune code contains lots of templates and we cannot guess which ones the Python user will instantiate at run time. 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: - dune-py cannot be installed into the system, as some code will be generated at run time. - Each user needs write access to a dune-py module and its build directory. - Only one Python process may use a dune-py module at a time. Therefore, we generate one dune-py module per user. The default position is `${HOME}/.cache/dune-py`, but you can customize it through the environment variable `DUNE_PY_DIR`. Notice that this directory should be exclusive to each user to avoid race conditions. It is also advisable to locate this directory on local storage for performance reasons. In the following we describe two approaches for installing dune-python and generating the dune-py module depending on your overall Dune setup. [Working with a Preinstalled Dune](PACKAGEINSTALL.md) ----------------------------------------------------- [Working with Dune Source Modules](SOURCEINSTALL.md) ---------------------------------------------------- Environment Variables --------------------- When using dune-python from Python, a number of environment variables influence its behaviour: - `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. - `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`. Further Dune modules based on dune-python ----------------------------------------- The following dune models can at moment be used together with dune-python: - [dune-alugrid][alugridlink]: if you want to use dune-alugrid simply configure the module with the flags discussed above and run `make install_python` in the build directory (or use the `setup-dunepy` script in `dune-python`). - [dune-spgrid][spgridlink]: also now provideds Python bindings. - [dune-fempy][fempylink]: this is a new module providing high level Python bindings to the [dune-fem][femlink] module. You can use this to solve complex non linear partial differential equations from within Python. dune-fempy also makes use of the unified form language (UFL) to provide a descriptive language for entering the mathematical models. Acknowledgements --------------- For the C++ to Python bindings we use the great project [pybind11][pybind11] - the sources are included in the dune-python module. The initial code was implemented by Michaël Sghaïer during the [Google Summer of Code][gsoc] program 2016. [fvcode]: https://gitlab.dune-project.org/michael.sghaier/dune-python/blob/remove-database/demo/finitevolume.py [alugridlink]: https://gitlab.dune-project.org/extensions/dune-alugrid [spgridlink]: https://gitlab.dune-project.org/extensions/dune-spgrid [fempylink]: https://gitlab.dune-project.org/dune-fem/dune-fempy [femlink]: https://gitlab.dune-project.org/dune-fem/dune-fem [pybind11]: https://github.com/pybind/pybind11 [gsoc]: https://summerofcode.withgoogle.com/ [script]: buildpy.sh