Commit 7171e2c3 authored by Jonas Šukys's avatar Jonas Šukys 💬

Merge branch 'release' into 'master'

v0.4 to master

See merge request !159
parents 8b291cf6 3bdec6a2
[flake8]
max-line-length = 200
max-line-length = 205
ignore = E211, W293, E261, E265, E201, E202, E211, E402, E302, E206, E303, E722, E231, E111, E251, E203, E262, W292, E401, E114, E266, E305, E123, W391, W503, W504, E731, E221, E226, W605
......@@ -22,6 +22,10 @@ notes.txt
**/sandbox/
**/sandboxes/
**/fig*/
**/report/*.dat
**/report/*.txt
**/report/*.tex
**/report/*.cap
**/infos-*.dat
**/samples-*.dat
**/samples-*.csv
......@@ -29,3 +33,6 @@ notes.txt
**.ipynb_checkpoints*
*.pstats
examples/*test*
spux/report/templates/report.pdf
**/latex/*
pytest.log
\ No newline at end of file
image: python:3.7-stretch
before_script:
- echo "deb http://ftp.de.debian.org/debian testing main" >> /etc/apt/sources.list
- apt-get update -qq
......@@ -9,6 +11,9 @@ before_script:
- apt-get install -y -qq graphviz
- apt-get install -y -qq ant
- apt-get install -y -qq r-base
- apt-get install -y -qq sqlite3
- apt-get install -y -qq libssl-dev
- apt-get install -y -qq libffi-dev
- pip3 install -U pip tox
stages:
......
......@@ -5,15 +5,28 @@
Contributing
============
| The source code is available at the Gitlab repository: https://gitlab.com/siam-sc/spux.
| The source code is available at the GitLab repository: https://gitlab.com/siam-sc/spux.
| Contributions are welcome, and they are greatly appreciated!
| Every little bit helps, and credit will always be given.
|
| You can contribute in many ways, listed in the following paragraphs.
The SPUX'onic way
-----------------
When contributing, please always make an effort to adhere the SPUX'onic coding style and ethics:
* think (at least) twice about proper variable names:
* avoid abbreviations and slang,
* prioritize descriptive single-word variables to lengthy "sentence"-variables,
* use docstrings for each class and method you implement,
* place technical methods into ``spux.utils`` or ``spux.io``,
* always use the ``verbosity`` level filter for any (carefully formatted, of course) output to console,
* always clean up (remove debug code and unnecessary comments) before merging to test branch.
Types of contributions
----------------------
You can contribute in many ways, listed in the following paragraphs.
Report bugs
~~~~~~~~~~~
......@@ -28,13 +41,13 @@ If you are reporting a bug, please include:
Fix bugs
~~~~~~~~
Look through the gitlab issues for bugs. Anything tagged with "bug" and "help
Look through the GitLab issues for bugs. Anything tagged with "bug" and "help
wanted" is open to whoever wants to implement it.
Implement features
~~~~~~~~~~~~~~~~~~
Look through the gitlab issues for features. Anything tagged with "enhancement"
Look through the GitLab issues for features. Anything tagged with "enhancement"
and "help wanted" is open to whoever wants to implement it.
Write documentation
......@@ -71,7 +84,7 @@ Get started!
Ready to contribute? Here's how to set up `spux` for local development.
1. Fork the `spux` repo on gitlab.
1. Fork the `spux` repo on GitLab.
2. Clone your fork locally::
$ git clone git@gitlab.com:siam-sc/spux.git
......@@ -100,7 +113,7 @@ Ready to contribute? Here's how to set up `spux` for local development.
You can run tests within your environment::
$ flake8 spux tests examples
$ pytest -m "not mpi:" tests
$ pytest -m "not mpi" tests
$ mpiexec -n 1 --oversubscribe pytest -m "mpi" tests
Or, alternatively (a slower approach), using tox to include testing with Python and MPI versions::
......@@ -109,7 +122,7 @@ Ready to contribute? Here's how to set up `spux` for local development.
To get flake8 and tox, just pip install them into your virtualenv.
7. Commit your changes and push your branch to gitlab::
7. Commit your changes and push your branch to GitLab::
$ git add .
$ git commit -m "Your detailed description of your changes."
......@@ -117,7 +130,7 @@ Ready to contribute? Here's how to set up `spux` for local development.
8. Make sure all tests pass in the `GitLab-CI <https://gitlab.com/siam-sc/spux/pipelines>`_ as well.
9. Submit a merge request (e.g. to the "test" branch) through the gitlab website.
9. Submit a merge request (e.g. to the "test" branch) through the GitLab website.
10. Maintainers: review merge request and activate "Merge automatically when pipeline succeeds".
......@@ -139,11 +152,11 @@ Tips
$ pytest -m "not mpi" tests
or only short module tests, excluding long integrations tests::
or only short module tests, excluding long integration tests::
$ pytest -m "not mpi and not integration" tests
or only long integrations tests using MPI::
or only long integration tests using MPI::
$ pytest -m "mpi and integration" tests
......@@ -174,10 +187,10 @@ A reminder for the maintainers on how to deploy.
* run ``make docs_html`` in the terminal and check generated html pages carefully,
* check all source code snippets that use specific line numbers and fix them,
* check if additional examples, results, or publications should be added for the gallery,
* check if additional contributios should be added in the credits.
* check if additional contributions should be added in the credits.
* Verify all filenames listed in :code:`MANIFEST.in`, including all needed package directories.
* Merge the release version of the code to the :code:`release` brach, make sure all tests pass.
* Make sure all your changes are COMMITED (!), including:
* Merge the release version of the code to the :code:`release` branch, make sure all tests pass.
* Make sure all your changes are COMMITTED (!), including:
* an entry in ``HISTORY.rst``,
* (optionally) the development status change in ``setup.py`` (see `here <https://pypi.org/classifiers/>`_ for options).
* Make sure you have ``texlive-science``, ``latexmk``, and ``image-magick`` installed for PDF documentation.
......
......@@ -18,6 +18,7 @@ Contributors
* Uwe Schmitt <uwe.schmitt@id.ethz.ch>
* Mikołaj Rybiński <mikolaj.rybinski@id.ethz.ch>
* Andreas Scheidegger <andreas.scheidegger@eawag.ch>
* Artur Safin <artur.safin@eawag.ch>
* Mira Kattwinkel <kattwinkel-mira@uni-landau.de>
* Marco Dal Molin <marco.dalmolin@eawag.ch>
* Simone Ulzega <ulzg@zhaw.ch>
......
This diff is collapsed.
......@@ -5,7 +5,7 @@
Gallery
=======
Here we provide a gallery containig selected example results of several applications (a non-exhaustive list)
Here we provide a gallery containing selected example results of several applications (a non-exhaustive list)
using SPUX framework for Bayesian inference and uncertainty quantification.
Randomwalk
......@@ -19,22 +19,17 @@ Randomwalk
A simple one-dimensional randomwalk with uncertain origin, drift, and the observation error.
.. figure:: _static/randomwalk/randomwalk_predictions-posterior-dataset-0-unbiased.png
.. figure:: _static/randomwalk/randomwalk_predictions-posterior.png
:align: center
:scale: 20 %
Plot of the posterior distribution of model predictions for an observational dataset.
.. include:: _static/randomwalk/randomwalk_predictions-posterior.cap
.. figure:: _static/randomwalk/randomwalk_posteriors2d-unbiased.png
.. figure:: _static/randomwalk/randomwalk_posterior2d-origin-drift.png
:align: center
:scale: 15 %
Joint pairwise marginal posterior distributions of :code:`origin`, :code:`drift`, and ``$\sigma$`` parameters,
including the corresponding Markov chains from the EMCEE sampler.
Legend:
blue "+" - initial parameters,
brown "o" - approximate maximum a posteriori (MAP) estimate for parameters,
red "x" - the exact parameters.
.. include:: _static/randomwalk/randomwalk_posterior2d-origin-drift.cap
Linear bucket
-------------
......@@ -87,7 +82,7 @@ Prey-Predator
| Domain: aquatic ecology.
| Authors: Jonas Šukys, Nele Schuwirth, Peter Reichert (Eawag, Switzerland), Mira Kattwinkel (University of Koblenz-Landau, Germany).
| Model: prey-predator model using stochastic individual based model with synthetic data (IBM-Bugs).
| Model: prey-predator model using stochastic individual based model with synthetic dataset (IBM-Bugs).
| Language: Java, with :code:`JPype` bindings to Python.
| Cluster: EULER (ETH Zurich, Switzerland) - up to 1000 cores.
......
......@@ -5,6 +5,12 @@
History
=======
0.4.0 (2019-06-12)
------------------
* Improvements in sandboxing, built-in serialization, report generation, plotting, thinning,
support for legacy connector, and improvements in inference continuation procedure.
0.3.0 (2019-04-10)
------------------
......
......@@ -10,44 +10,49 @@ Python package spux is available at PyPI repository: https://pypi.org/project/sp
Main prerequisites
------------------
- Python, we recommend using Python 3.
- Python, we recommend using Python 3.
- in macOS, pre-installed
- in Debian/Ubuntu, pre-installed
- in Windows, follow instructios in https://www.python.org/downloads/windows/
- to test, run in terminal: :code:`python3 -V`
- in macOS, pre-installed
- in Debian/Ubuntu, pre-installed
- in Windows, follow instructions in https://www.python.org/downloads/windows/
- to test, run in terminal: :code:`python3 -V`
- Open MPI:
- Open MPI:
- in macOS with Homebrew, in terminal: :code:`brew open-mpi`
- in Debian/Ubuntu with Apt, in terminal:
:code:`apt-get install openmpi-bin libopenmpi-dev`
- in Windows, the parallel version of the framework has not been tested yet
- in macOS with Homebrew, in terminal: :code:`brew open-mpi`
- in Debian/Ubuntu with Apt, in terminal:
:code:`apt-get install openmpi-bin libopenmpi-dev`
- in Windows, the parallel version of the framework has not been tested yet
- SPUX Package, in terminal:
- SPUX Package, in terminal:
.. code-block:: console
.. code-block:: console
$ pip3 install --user --upgrade pip
$ pip3 install --user spux
$ pip3 install --user --upgrade pip
$ pip3 install --user spux
Remember, that if you reinstall or somehow else change your MPI library,
you must reinstall :code:`mpi4py` package by running in terminal:
.. code-block:: console
.. code-block:: console
$ pip3 install --user --upgrade pip
$ pip3 install --user --upgrade --force-reinstall --no-cache-dir mpi4py
$ pip3 install --user --upgrade pip
$ pip3 install --user --upgrade --force-reinstall --no-cache-dir mpi4py
Additional prerequisites
------------------------
Depending on the programming language of your model, additional prerequisites might be needed:
- R driver: R package, and in terminal: :code:`$ pip3 install --user rpy2`,
- Julia driver: Julia package :code:`PyCall`, and in terminal: :code:`$ pip3 install --user julia`,
- Fortran driver: Fortran compiler (if needed), and in terminal: :code:`$ pip3 install --user ctypes`,
- C/C++ driver: C/C++ compiler (if needed), and Swig (http://www.swig.org/) code wrapper,
- Java driver: Java SDK, and in terminal: :code:`$ pip3 install --user Jpype1`.
- R driver: R package, and in terminal: :code:`$ pip3 install --user rpy2`,
- Julia driver: Julia package :code:`PyCall`, and in terminal: :code:`$ pip3 install --user julia`,
- Fortran driver: Fortran compiler (if needed), and in terminal: :code:`$ pip3 install --user ctypes`,
- C/C++ driver: C/C++ compiler (if needed), and Swig (http://www.swig.org/) code wrapper,
- Java driver: Java SDK, and in terminal: :code:`$ pip3 install --user Jpype1`.
If you additionally want the generated LaTeX report source files to be compiled to the PDF files,
then you will need to have the ``pdflatex`` installed
(the procedure varies depending on the OS and distribution and hence is not described here).
Stable release
--------------
......@@ -75,7 +80,7 @@ To update when a newer release becomes available, run in your terminal:
Latest release
--------------
To install the latest develpment version of spux, run these commands in your terminal:
To install the latest development version of spux, run these commands in your terminal:
.. code-block:: console
......
......@@ -19,7 +19,7 @@ In the near future,
multi-level methods (e.g. ML(ET)PF, MLCV) will be included in SPUX to enable significant algorithmic acceleration
of the inference and uncertainty quantification for models that support multiple resolution configurations.
An earlier protoptype of spux was already described in a technical paper (preprint available at http://arxiv.org/abs/1711.01410):
An earlier prototype of spux was already described in a technical paper (preprint available at http://arxiv.org/abs/1711.01410):
.. code::
......@@ -40,8 +40,8 @@ Here we briefly introduce mathematical concepts used in the Bayesian inference a
.. figure:: _static/slides/Bayesian-inference.png
:align: center
Bayesian inference: updated the prior distribution of the model parameters to a posterior distribution given model observations (data).
Bayesian theorem allows us to evaluate (or sample from) the posterior parameter distribution by computing the likelihood of the data given candidate model parameters.
Bayesian inference: updated the prior distribution of the model parameters to a posterior distribution given model observations (dataset).
Bayesian theorem allows us to evaluate (or sample from) the posterior parameter distribution by computing the likelihood of the dataset given candidate model parameters.
Algorithms
----------
......@@ -56,8 +56,8 @@ Algorithms
:align: center
Particle Filter (PF) of the stochastic model realizations
in order to estimate the likelihood of the model parmeters marginalized over all possible scenarions.
Note that particles (stochastic model realizations) are adaptively filtered using data,
in order to estimate the likelihood of the model parameters marginalized over all possible scenarios.
Note that particles (stochastic model realizations) are adaptively filtered using dataset,
making this algorithm very computationally efficient.
.. figure:: _static/schemes/MCMC-PF.png
......
......@@ -23,14 +23,14 @@ Scalable Uncertainty Quantification
| SPUX can be coupled with linear and nonlinear, deterministic and stochastic models.
| SPUX supports model in any programming language (e.g. Python, R, Julia, C/C++, Fortran, Java).
| SPUX scales effortlessly from serial run to parallel high performance computing clusters.
| SPUX is application agnostic, with current examples in environmental data sciences.
| SPUX is application agnostic, with current examples in environmental dataset sciences.
|
| SPUX is actively developed at Eawag, Swiss Federal Institute of Aquatic Science and Technology,
| by researchers in the High Performance Scientific Computing Group, https://www.eawag.ch/sc.
| For the scientific website of the SPUX project, please refer to https://eawag.ch/spux.
|
| Documentation is available at https://spux.readthedocs.io.
| Source code respository is available at https://gitlab.com/siam-sc/spux.
| Source code repository is available at https://gitlab.com/siam-sc/spux.
|
| You are welcome to browse through the results gallery of the models already coupled to spux at https://spux.readthedocs.io/en/stable/gallery.html.
|
......
This diff is collapsed.
Maximum A Posteriori (MAP) estimate parameters.
\ No newline at end of file
==============================================
Maximum A Posteriori (MAP) estimate parameters
==============================================
$\sigma$ | drift | origin
-------- + -------- + --------
9.24e+00 | 1.95e-01 | 9.78e+01
==============================================
\ No newline at end of file
Acceptance rate (accross multiple concurrent chains of the sampler)
for the proposed parameters samples.
Average (over dataset snapshots) standard deviations for the estimated marginal observational log-error
using the PF.
The semi-transparent spread indicates the range (minimum and maximumum)
accross multiple concurrent chains of the sampler
and the solid line indicates the value of the chain with the largest estimated log-likelihood.
The solid thick gray line above the same line for a zero value reference
indicates the specified accuracy and
the dashed thick gray lines indicate the specified margins -
all specified within the adaptive PF likelihood.
Autocorrelations of Markov chain parameters samples.
The solid lines indicate the mean
and the semi-transparent spreads indicate the range (minimum and maximum)
accross multiple concurrent chains of the sampler.
SPUX components configuration.
\ No newline at end of file
===================================================================================================================================
SPUX components configuration
===================================================================================================================================
Component | Class | Options
---------- + ---------- + ---------------------------------------------------------------------------------------------------------
Model | Randomwalk | stepsize=1
Likelihood | PF | particles=[4, 128], adaptive=True, accuracy=0.1, margin=0.05, threshold=-5, factor=2, log=1, noresample=0
Sampler | EMCEE | chains=8, a=2.0, attempts=100, reset=10
===================================================================================================================================
\ No newline at end of file
Observational dataset.
\ No newline at end of file
Marginal distributions (prior).
\ No newline at end of file
Computational environment.
\ No newline at end of file
=============================================================
Computational environment
=============================================================
Descriptor | Value
------------------ + ----------------------------------------
Timestamp | 2019-05-23 00:58:01
Version | 0.3.0
GIT branch (plain) | dev_jonas
GIT revision | f98e24ae81841a98a39d7d9e3b655ae6cdc97d4f
=============================================================
\ No newline at end of file
Observational dataset and the associated error model,
evaluated using exact model predictions and exact model parameters.
The circles (or thick dots) indicate the dataset values, the thick solid line indicates the model predictions used in the error model.
The shaded green regions indicate the density of the error model distribution.
Number of model evaluations.
\ No newline at end of file
====================================================
Number of model evaluations
====================================================
Component | Class | tasks | sizes | cumulative
---------- + ---------- + ----- + ----- + ----------
Model | Randomwalk | 1 | 1 | 1
Likelihood | PF | 128 | 1 | 128
Sampler | EMCEE | 1K | 128 | 128K
====================================================
\ No newline at end of file
SPUX infos structure.
\ No newline at end of file
======================================================================================================================================================================================================================
SPUX infos structure
======================================================================================================================================================================================================================
Component | Class | Fields | Iterators for infos
---------- + ----- + --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + -------------------
Sampler | EMCEE | proposes, infos, parameters, posteriors, accepts, likelihoods, timing, priors, timings, index, feedbacks, feedback, resets | 0 - 8
Likelihood | PF | particles, successful, variances, sources, timing, MAP, timings, redraw, weights, predictions_prior, estimates, variance, errors_prior, predictions, traffic, avg_deviation | -
======================================================================================================================================================================================================================
\ No newline at end of file
Log-likelihood and (scaled [TODO: estimate evidence and remove scaling])
log-posterior estimates for the sampled model posterior parameters.
The solid lines indicate the median and the semi-transparent spreads indicate the 10% - 90% percentiles
accross multiple concurrent chains of the sampler.
For log-likelihood, the estimates from the rejected proposed parameters are also taken into account.The brown "o" symbol indicates the posterior estimate at the approximate MAP parameters.
Maximums of the average (over dataset snapshots) marginal observational log-errors
accross multiple concurrent chains of the sampler.
The dashed green line indicates the threshold set in the adaptive PF likelihood.
Metrics for the inference efficiency..
\ No newline at end of file
==================================================================================================
Metrics for the inference efficiency.
==================================================================================================
Metric | Value
----------------------------------------- + ------------------------------------------------------
Maximum A Posteriori (MAP) estimate | batch:52, chain:2, sample:418, log-posterior:-2.01e+02
Multivariate Effective Sample Size (mESS) | not implemented
Multivariate thin period | not implemented
Univariate Effective Sample Size (ESS) | 1 - 125 (across chains), with average 17 and sum 140
Univariate thin period | 1 - 71 (across chains), with mean 44
==================================================================================================
\ No newline at end of file
Markov chain parameters samples.
The solid lines indicate the median and the semi-transparent spreads indicate the 5% - 95% percentiles