README.rst 6.68 KB
Newer Older
Pamphile Roy's avatar
Pamphile Roy committed
1
|CI|_ |Codecov|_ |Python|_ |License|_ |Conda|_ |PyPi|_ |Zulip|_ |Joss|_
Pamphile Roy's avatar
Pamphile Roy committed
2

Pamphile Roy's avatar
Pamphile Roy committed
3
.. |CI| image:: https://gitlab.com/cerfacs/batman/badges/develop/pipeline.svg
Pamphile Roy's avatar
Pamphile Roy committed
4
.. _CI: https://gitlab.com/cerfacs/batman/pipelines
Pamphile Roy's avatar
Pamphile Roy committed
5

Pamphile Roy's avatar
Pamphile Roy committed
6
.. |Codecov| image:: https://gitlab.com/cerfacs/batman/badges/develop/coverage.svg
Pamphile Roy's avatar
Pamphile Roy committed
7
.. _Codecov: https://gitlab.com/cerfacs/batman/pipelines
Pamphile Roy's avatar
Pamphile Roy committed
8

Pamphile Roy's avatar
Pamphile Roy committed
9
.. |Python| image:: https://img.shields.io/badge/python-2.7,_3.7-blue.svg
10
.. _Python: https://python.org
Pamphile Roy's avatar
Pamphile Roy committed
11

12
.. |License| image:: https://img.shields.io/badge/license-CECILL--B_License-blue.svg
Pamphile Roy's avatar
Pamphile Roy committed
13
.. _License: http://www.cecill.info/licences/Licence_CeCILL-B_V1-en.html
14
15

.. |Zulip| image:: https://img.shields.io/badge/zulip-join_chat-brightgreen.svg
Pamphile Roy's avatar
Pamphile Roy committed
16
.. _Zulip: https://batman-cerfacs.zulipchat.com
17

Pamphile Roy's avatar
Pamphile Roy committed
18
19
20
21
22
.. |Conda| image:: https://img.shields.io/badge/install_with-conda-brightgreen.svg
.. _Conda: https://anaconda.org/conda-forge/batman

.. |PyPi| image:: https://img.shields.io/badge/install_with-pypi-brightgreen.svg
.. _PyPi: https://pypi.org/project/ot-batman/
Pamphile Roy's avatar
Pamphile Roy committed
23

24
25
26
.. |Joss| image:: https://joss.theoj.org/papers/a1c4bddc33a1d8ab55fce1a3596196d8/status.svg
.. _Joss: https://joss.theoj.org/papers/a1c4bddc33a1d8ab55fce1a3596196d8

Pamphile Roy's avatar
Pamphile Roy committed
27
Batman
Pamphile Roy's avatar
Pamphile Roy committed
28
======
Jean-Christophe JOUHAUD's avatar
Jean-Christophe JOUHAUD committed
29

Pamphile Roy's avatar
Pamphile Roy committed
30
**Batman** stands for Bayesian Analysis Tool for Modelling and uncertAinty
31
32
33
quaNtification. It is a Python module distributed under the open-source
CECILL-B license (MIT/BSD compatible).

34
35
36
37
38
*batman* seamlessly allows to do statistical analysis (sensitivity analysis,
Uncertainty Quantification, moments) based on non-intrusive ensemble experiment
using any computer solver. It relies on open source python packages dedicated
to statistics (`OpenTURNS <http://www.openturns.org>`_ and
`scikit-learn <http://scikit-learn.org>`_).
39

Pamphile Roy's avatar
Pamphile Roy committed
40
41
42
43
Main features are: 

- Design of Experiment (LHS, low discrepancy sequences, MC),
- Resample the parameter space based on the physic and the sample,
44
- Surrogate Models (Gaussian process, Polynomial Chaos, RBF, *scikit-learn*'s regressors),
45
- Optimization (Expected Improvement),
46
47
- Sensitivity/Uncertainty Analysis (SA, UA) and Uncertainty Quantification (UQ),
- Visualization in *n*-dimensions (HDR, Kiviat, PDF),
Pamphile Roy's avatar
Pamphile Roy committed
48
- *POD* for database optimization or data reduction,
49
- Automatically manage code computations in parallel.
Pamphile Roy's avatar
Pamphile Roy committed
50
51
52

Full documentation is available at: 

Pamphile Roy's avatar
Pamphile Roy committed
53
    http://batman.readthedocs.io
54

55
56
.. inclusion-marker-do-not-remove

Pamphile Roy's avatar
Pamphile Roy committed
57
Getting started
58
===============
Pamphile Roy's avatar
Pamphile Roy committed
59

Pamphile Roy's avatar
Pamphile Roy committed
60
A detailled example can be found in 
61
`tutorial <http://batman.readthedocs.io/en/latest/tutorial.html>`_. The folder ``test_cases``
Pamphile Roy's avatar
Pamphile Roy committed
62
63
contains examples that you can adapt to you needs. You can find more information
about the cases within the respectives ``README.rst`` file. 
Pamphile Roy's avatar
Pamphile Roy committed
64

Pamphile Roy's avatar
Pamphile Roy committed
65
Shoud you be interested by batman's implementation, consider
66
reading the `technical documentation <http://batman.readthedocs.io/en/latest/technical.html>`_.
Pamphile Roy's avatar
Pamphile Roy committed
67
68
69
70

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".
Pamphile Roy's avatar
Pamphile Roy committed
71

Pamphile Roy's avatar
Pamphile Roy committed
72
Last but not least, if you consider contributing check-out
73
`contributing <http://batman.readthedocs.io/en/latest/contributing_link.html>`_.
Pamphile Roy's avatar
Pamphile Roy committed
74

Pamphile Roy's avatar
Pamphile Roy committed
75
Happy batman.
Pamphile Roy's avatar
Pamphile Roy committed
76

Jean-Christophe JOUHAUD's avatar
Jean-Christophe JOUHAUD committed
77
78
How to install BATMAN?
----------------------
Pamphile Roy's avatar
Pamphile Roy committed
79

Pamphile Roy's avatar
Pamphile Roy committed
80
81
82
83
The sources are located on *GitLab*: 

    https://gitlab.com/cerfacs/batman

Pamphile Roy's avatar
Pamphile Roy committed
84
85
86
Latest release
..............

Pamphile Roy's avatar
Pamphile Roy committed
87
88
89
90
91
Install and update using ``pip``::

    pip install -U ot-batman

batman is also distributed through ``conda``, on the ``conda-forge`` channel.
Cyril Fournier's avatar
Cyril Fournier committed
92
93

To install conda::
Pamphile Roy's avatar
Pamphile Roy committed
94
95
96
97

    wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh
    bash Miniconda3-latest-Linux-x86_64.sh

Pamphile Roy's avatar
Pamphile Roy committed
98
To create a new environment and install batman through ``conda``::
Cyril Fournier's avatar
Cyril Fournier committed
99

Pamphile Roy's avatar
Pamphile Roy committed
100
    conda create -n bat_env -c conda-forge batman
Cyril Fournier's avatar
Cyril Fournier committed
101
102

All the above dependencies are automatically handled by ``conda``, 
Pamphile Roy's avatar
Pamphile Roy committed
103
104
except `Antares <http://www.cerfacs.fr/antares>`_. For more information, refer
to its `documentation <https://conda.io/docs/user-guide/getting-started.html>`_.
Pamphile Roy's avatar
Pamphile Roy committed
105
106
107

From sources
............
108

109
Using the latest python version is prefered! Then to install::
110

Pamphile Roy's avatar
Pamphile Roy committed
111
    git clone git@gitlab.com:cerfacs/batman.git
Pamphile Roy's avatar
Pamphile Roy committed
112
    cd batman
113
    python setup.py install
114
    python setup.py test
115
116
    python setup.py build_sphinx

Pamphile Roy's avatar
Pamphile Roy committed
117
The latter is optionnal as it build the documentation. The testing part is also
Pamphile Roy's avatar
Pamphile Roy committed
118
optionnal but is recommanded. (<30mins depending on your configuration).
119

120
.. note:: If you don't have install priviledge, add ``--user`` option after install.
Pamphile Roy's avatar
Pamphile Roy committed
121
    But the simplest way might be to use pip or a conda environment.
122

123
If batman has been correctly installed, you should be able to call it simply::
124

125
    batman -h
126

127
.. warning:: Depending on your configuration, you might have to export your local path: 
Pamphile Roy's avatar
Pamphile Roy committed
128
129
130
131
    ``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.

Pamphile Roy's avatar
Pamphile Roy committed
132
Dependencies
Pamphile Roy's avatar
Pamphile Roy committed
133
````````````
Pamphile Roy's avatar
Pamphile Roy committed
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166

The required dependencies are: 

- `Python <https://python.org>`_ >= 2.7 or >= 3.4
- `OpenTURNS <http://www.openturns.org>`_ >= 1.10
- `scikit-learn <http://scikit-learn.org>`_ >= 0.18
- `numpy <http://www.numpy.org>`_ >= 1.13
- `scipy <http://scipy.org>`_ >= 0.15
- `pathos <https://github.com/uqfoundation/pathos>`_ >= 0.2
- `matplotlib <http://matplotlib.org>`_ >= 2.1
- `Paramiko <http://www.paramiko.org>`_ >= 2.4
- `jsonschema <http://python-jsonschema.readthedocs.io/en/latest/>`_

Appart from OpenTURNS, required dependencies are satisfied by the installer.
Optionnal dependencies are: 

- `Antares <http://www.cerfacs.fr/antares>`_ for extra IO options
- `sphinx <http://www.sphinx-doc.org>`_ >= 1.4 for documentation
- `ffmpeg <https://www.ffmpeg.org>`_ for movie visualizations (*n_features* > 2)

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.

167
168
169
Help and Support
----------------

Pamphile Roy's avatar
Pamphile Roy committed
170
171
About us
........
172

173
See authors and project history at: `about us <http://batman.readthedocs.io/en/latest/about.html>`_.
174

Pamphile Roy's avatar
Pamphile Roy committed
175
176
Community
.........
177

Pamphile Roy's avatar
Pamphile Roy committed
178
179
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!
180

181
Citation
Pamphile Roy's avatar
Pamphile Roy committed
182
........
183

184
If you use batman in a scientific publication, we would appreciate `citations <http://batman.readthedocs.io/en/latest/about.html#citing-batman>`_.