Commit 80993ec0 authored by Pamphile Roy's avatar Pamphile Roy
Browse files

Readme as inclusion and final paper

parent 8390ab1b
......@@ -7,6 +7,7 @@
.. _Codecov: https://gitlab.com/cerfacs/batman/pipelines
.. |Python| image:: https://img.shields.io/badge/python-2.7,_3.6-blue.svg
.. _Python: https://python.org
.. |License| image:: https://img.shields.io/badge/license-CECILL--B_License-blue.svg
.. _License: http://www.cecill.info/licences/Licence_CeCILL-B_V1-en.html
......@@ -17,9 +18,6 @@
BATMAN
======
Introduction
------------
**BATMAN** stands for Bayesian Analysis Tool for Modelling and uncertAinty
quaNtification. It is a Python module distributed under the open-source
CECILL-B license (MIT/BSD compatible).
......@@ -42,8 +40,10 @@ Full documentation is available at:
https://cerfacs.gitlab.io/batman
.. inclusion-marker-do-not-remove
Getting started
---------------
===============
A detailled example can be found in
`tutorial <https://cerfacs.gitlab.io/batman/tutorial.html>`_. The folder ``test_cases``
......
......@@ -4,5 +4,5 @@ BATMAN package
"""
__version__ = '1.7'
__branch__ = 'heads/develop'
__commit__ = '1.7-Lucius-23-g99718bf'
__branch__ = None
__commit__ = None
Welcome to BATMAN's documentation!
==================================
|CI|_ |Codecov|_ |Python|_ |License|_ |Zulip|_
.. |CI| image:: https://gitlab.com/cerfacs/batman/badges/develop/pipeline.svg
.. _CI: https://gitlab.com/cerfacs/batman/pipelines
.. |Codecov| image:: https://gitlab.com/cerfacs/batman/badges/develop/coverage.svg
.. _Codecov: https://gitlab.com/cerfacs/batman/pipelines
.. |Python| image:: https://img.shields.io/badge/python-2.7,_3.6-blue.svg
.. _Python: https://python.org
.. |License| image:: https://img.shields.io/badge/license-CECILL--B_License-blue.svg
.. _License: http://www.cecill.info/licences/Licence_CeCILL-B_V1-en.html
.. |Zulip| image:: https://img.shields.io/badge/zulip-join_chat-brightgreen.svg
.. _Zulip: https://batman-cerfacs.zulipchat.com
BATMAN
======
Introduction
------------
**BATMAN** stands for Bayesian Analysis Tool for Modelling and uncertAinty
quaNtification. It is a Python module distributed under the open-source
CECILL-B license (MIT/BSD compatible).
batman seamlessly allows to do statistical analysis (sensitivity analysis,
Uncertainty Quantification, moments) using any computer solver.
Main features are:
- Design of Experiment (LHS, low discrepancy sequences, MC),
- Resample the parameter space based on the physic and the sample,
- Surrogate Models (Gaussian process, Polynomial Chaos, RBF),
- Optimization (Expected Improvement),
- Realizing Sensitivity Analysises (SA) and Uncertainty Quantifications (UQ),
- Visualization in *n*-dimensions (HDR, Kiviat),
- *POD* for database optimization or data reduction,
- Automatically managing code computations in parallel.
Full documentation is available at:
https://cerfacs.gitlab.io/batman
.. include:: ../README.rst
:end-before: inclusion-marker-do-not-remove
Contents
--------
......
Getting started
===============
A detailled example can be found in
`tutorial <https://cerfacs.gitlab.io/batman/tutorial.html>`_. The folder ``test_cases``
contains examples that you can adapt to you needs. You can find more information
about the cases within the respectives ``README.rst`` file.
Shoud you be interested by batman's implementation, consider
reading `introduction <https://cerfacs.gitlab.io/batman/introduction.html>`_.
If you encounter a bug (or have a feature request), please report it via
`GitLab <https://gitlab.com/cerfacs/batman/issues>`_. Or it might be you
falling but "Why do we fall sir? So we can learn to pick ourselves up".
Last but not least, if you consider contributing check-out
`contributing <https://cerfacs.gitlab.io/batman/contributing_link.html>`_.
Happy batman.
How to install BATMAN?
----------------------
The sources are located on *GitLab*:
https://gitlab.com/cerfacs/batman
Dependencies
............
The required dependencies are:
- `Python <https://python.org>`_ >= 2.7 or >= 3.3
- `scikit-learn <http://scikit-learn.org>`_ >= 0.18
- `numpy <http://www.numpy.org>`_ >= 1.13
- `scipy <http://scipy.org>`_ >= 0.15
- `OpenTURNS <http://www.openturns.org>`_ >= 1.9
- `pathos <https://github.com/uqfoundation/pathos>`_ >= 0.2
- `matplotlib <http://matplotlib.org>`_ >= 1.5
- `jsonschema <http://python-jsonschema.readthedocs.io/en/latest/>`_
- `sphinx <http://www.sphinx-doc.org>`_ >= 1.4
Appart from OpenTURNS, required dependencies are satisfied by the installer.
Optionnal dependencies are:
- `Antares <http://www.cerfacs.fr/antares>`_ for extra IO options
- `ffmpeg <https://www.ffmpeg.org>`_ for movie visualizations
Testing dependencies are:
- `pytest <https://docs.pytest.org/en/latest/>`_ >= 2.8
- `mock <https://pypi.python.org/pypi/mock>`_ >= 2.0
Extra testing flavours:
- `coverage <http://coverage.readthedocs.io>`_ >= 4.4
- `pylint <https://www.pylint.org>`_ >= 1.6.0
.. note:: OpenTURNS and ffmpeg are available on *conda* through
the *conda-forge* channel.
User installation
.................
Using the latest python version is prefered! Then to install::
git clone git@gitlab.com:cerfacs/batman.git
cd batman
python setup.py build_fortran
python setup.py install
python setup.py test
python setup.py build_sphinx
The latter is optionnal as it build the documentation. The testing part is also
optionnal but is recommanded. (<30mins depending on your configuration).
.. note:: If you don't have install priviledge, add ``--user`` option after install.
But the simplest way might be to use a conda environment.
Finally, if you want to install the optionnal package ``Antares`` (not provided)::
pip install --editable .[antares] --process-dependency-links
If batman has been correctly installed, you should be able to call it simply::
batman -h
.. warning:: Depending on your configuration, you might have to export your local path:
``export PATH=$PATH:~/.local/bin``. Care to be taken with both your ``PATH``
and ``PYTHONPATH`` environment variables. Make sure you do not call different
installation folders. It is recommanded that you leave your ``PYTHONPATH`` empty.
Otherwize you can create your ``conda`` environment::
wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh
conda create -n bat_env -c conda-forge openturns matplotlib numpy scipy scikit-learn pathos jsonschema sphinx sphinx_rtd_theme pytest pytest-runner mock ffmpeg
Then you can install all packages without ``root`` access. You can access
the newly created environment with ``source activate bat_env``.
Help and Support
----------------
About us
........
See authors and project history at: `about us <https://cerfacs.gitlab.io/batman/about.html>`_.
Community
.........
If you use batman, come and say hi at https://batman-cerfacs.zulipchat.com.
Or send us an email. We would really appreciate that as we keep record of the users!
Citation
........
If you use batman in a scientific publication, we would appreciate `citations <https://cerfacs.gitlab.io/batman/about.html#citing-batman>`_.
\ No newline at end of file
.. include:: ../README.rst
:start-after: inclusion-marker-do-not-remove
......@@ -74,6 +74,8 @@ Thus BATMAN is launched using::
batman settings.json
.. seealso:: The definition of the case is to be filled in ``settings.json``. Refer to :ref:`CLI <cli>`.
An ``output`` directory is created and it contains the results of the computation splited across the following folders:
* ``snapshots``,
......
@article{scikit-learn,
title={Scikit-learn: Machine Learning in {P}ython},
author={Pedregosa, F. and Varoquaux, G. and Gramfort, A. and Michel, V.
and Thirion, B. and Grisel, O. and Blondel, M. and Prettenhofer, P.
and Weiss, R. and Dubourg, V. and Vanderplas, J. and Passos, A. and
Cournapeau, D. and Brucher, M. and Perrot, M. and Duchesnay, E.},
journal={Journal of Machine Learning Research},
volume={12},
pages={2825--2830},
year={2011}
}
@ARTICLE{openturns,
author = {{Baudin}, M. and {Dutfoy}, A. and {Iooss}, B. and {Popelin}, A.-L.
},
title = "{Open TURNS: An industrial software for uncertainty quantification in simulation}",
journal = {ArXiv e-prints},
archivePrefix = "arXiv",
eprint = {1501.05242},
primaryClass = "stat.CO",
keywords = {Statistics - Computation, Mathematics - Statistics Theory},
year = 2015,
month = jan,
adsurl = {http://adsabs.harvard.edu/abs/2015arXiv150105242B},
adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}
@article{Roy2017a,
author = {Roy, Pamphile Tupui and Segui, Luis Miguel and Jouhaud, Jean-Christophe and Gicquel, Laurent},
journal = {In review in: International Journal for Numerical Methods in Fluids},
......
---
title: 'BATMAN: Bayesian Analysis Tool for Modelling and uncertAinty
quaNtification'
title: 'BATMAN: Statistical analysis for expensive computer codes made easy'
tags:
- Python
- Uncertainty Quantification
- Statistical analysis
- Statistical Analysis
- Surrogate Model
- Design of Experiments
- Computational Fluid Dynamics
- Uncertainty Visualization
authors:
- name: Pamphile T. Roy
orcid: 0000-0001-9816-1416
affiliation: 1
- name: Sophie Ricci
orcid: 0000-0002-4232-5626
affiliation: 1
- name: Romain Dupuis
affiliation: 2
- name: Robain Campet
- name: Robin Campet
orcid: 0000-0002-4434-0854
affiliation: 1
- name: Jean-Christophe Jouhaud
affiliation: 1
......@@ -25,7 +26,7 @@ authors:
affiliations:
- name: CERFACS, Toulouse, France
index: 1
- name: IRT/CERFACS, Toulouse, France
- name: IRT Saint Exupéry/CERFACS, Toulouse, France
index: 2
date: 12 November 2017
bibliography: paper.bib
......@@ -33,10 +34,18 @@ bibliography: paper.bib
# Summary
Numerical codes have reached a sufficient maturity to represent physical phenomena, and complex simulations on high-resolution grid is becoming possible with continuous developments in numerical methods and in High Performance Computing (HPC). Still, deterministic simulations only provide limited knowledge on a system as uncertainties in the numerical model and its inputs translate into uncertainties in the outputs.
Bayesian Analysis Tool for Modelling and uncertAinty
quaNtification (batman) is an open source Python package dedicated to statistical analysis based on non-intrusive ensemble experiment.
Batman is a python module that allows to seamlessly perform statistical analysis using any experiment. From a simple setting file, it handles all necessary steps automatically. Another possibility is to access batman API to independently use all functionalities. Last but not least, batman can make use of existing results from both in vivo and in silico experimentations.
Numerical software has reached a sufficient maturity to represent physical phenomena. High fidelity simulation is possible with continuous advances in numerical methods and in High Performance Computing (HPC). Still, deterministic simulations only provide limited knowledge on a system as uncertainties in the numerical model and its inputs translate into uncertainties in the outputs. Ensemble-based methods are used to construct a numerical or experimental dataset from which statistics are inferred.
Along with state-of-the-art algorithms for creating design of experiments (DoE), constructing a surrogate model (SM) and performing uncertainty quantification (UQ), it implements new methods for resampling the parameter space and new data visualization methods to assess uncertainties [@roy2017a]. Batman has been successfully used to treat complex Computational Fluid Dynamics applications [@roy2017a, @roy2017b, @roy2017c].
*batman* library provides a convenient, modular and efficient framework for design of experiments, surrogate model and uncertainty quantification. *batman* relies on open source python packages dedicated to statistics (*openTURNS* and *scikit-learn* [@openturns, @scikit-learn]). It also implements advanced methods for resampling, robust optimization and uncertainty visualization [@roy2017a].
*batman* handles the workflow for statistical analysis. It makes the most of HPC resources by managing asynchronous parallel tasks. The internal parallelism of each task does not conflict with *batman*'s parallel environment.
*batman* analysis is launched from a *command line interface* and a setting file. *batman* functionalities can also be accessed through an API. *batman* has been successfully used for geosciences and turbomachinery Computational Fluid Dynamics applications [@roy2017a, @roy2017b, @roy2017c].
*batman* is CECILL-B licensed; it is actively developed and maintained by researchers at CERFACS.
# References
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment