README.md 11.1 KB
Newer Older
1
# Boundless Electrical Resistivity Tomography (BERT)
carsten's avatar
carsten committed
2

Thomas Günther's avatar
Thomas Günther committed
3
Build status: [![Build Status](http://jenkins.pygimli.org/job/pyBERT/badge/icon)](http://jenkins.pygimli.org/job/pyBERT/)
Florian Wagner's avatar
Florian Wagner committed
4

Thomas Günther's avatar
Thomas Günther committed
5
6
7
BERT is a software package for modelling & inversion of ERT data.
It has been traditionally used as C++ apps based on the pyGIMLi core plus bash 
scripts for command line, but increasingly uses Python through
Thomas Günther's avatar
Thomas Günther committed
8
9
10
pyGIMLi and pyBERT, not only for visualization but also for meshing and computing.

For simple ERT inversion, you don't need BERT anymore but the `ERTManager` in the
Thomas Günther's avatar
Thomas Günther committed
11
ERT module of pyGIMLi (see [pygimli.org](http://www.pygimli.org) examples). You
Thomas Günther's avatar
Thomas Günther committed
12
13
14
15
16
17
18
might need BERT for
* multi-frequency FD induced polarization with the `FDIP` class
* full-decay TD induced polarization with the `TDIP` class
* importing and exporting a lot of different file formats 
* special ERT-specific data processing, e.g. reciprocal analysis 
* inversions using the command line 

19
20
You may take a look at our 
[Tutorial](http://www.resistivity.net/download/bert-tutorial.pdf) first to learn
Thomas Günther's avatar
Thomas Günther committed
21
the way of doing inversions BERT v2. BERT v2.2 was based upon pyGIMLi 1.0.x, while
Thomas Günther's avatar
Thomas Günther committed
22
BERT v2.3 is based on pyGIMLi 1.1/1.2. 
23
In the future, BERT v3 will avoid binary executables and thus be entirely in Python.
24

25
See also the pyGIMLi webpage
26
[www.pygimli.org](http://www.pygimli.org)
carsten's avatar
carsten committed
27

Florian Wagner's avatar
Florian Wagner committed
28
## Installation with conda [![Anaconda-Server Badge](https://anaconda.org/gimli/pybert/badges/installer/conda.svg)](https://conda.anaconda.org/gimli) [![Anaconda-Server Badge](https://anaconda.org/gimli/pybert/badges/downloads.svg)](https://anaconda.org/gimli/pybert)[![Anaconda-Server Badge](https://anaconda.org/gimli/pybert/badges/version.svg)](https://anaconda.org/gimli/pybert)[![Anaconda-Server Badge](https://anaconda.org/gimli/pybert/badges/latest_release_date.svg)](https://anaconda.org/gimli/pybert)
carsten's avatar
carsten committed
29

Thomas Günther's avatar
Thomas Günther committed
30
The most comfortable way to install BERT is
31
via the conda package manager contained in the [Anaconda
32
distribution](https://docs.continuum.io/anaconda/install#linux-install).
Thomas Günther's avatar
Thomas Günther committed
33
Anaconda is a scientific Python distribution with hundreds of useful packages
34
35
included (~400 Mb). You can also use the lightweight alternative
[Miniconda](http://conda.pydata.org/miniconda.html) (~35 Mb) and only install
Thomas Günther's avatar
Thomas Günther committed
36
the packages you need or like. Notes on how to install Miniconda (without root
37
privileges) can be found
38
[here](https://gitlab.com/resistivity-net/bert/wikis/install-miniconda).
Thomas Günther's avatar
Thomas Günther committed
39
40
pyGIMLi packages are available for Python 3.7, 3.8 and 3.9. We eventually
dropped support for Python 3.5 and 3.6 and will support 3.10 soon.
41

42
```bash
Florian Wagner's avatar
Florian Wagner committed
43
# Install pybert (and all dependencies such as pygimli, numpy, mpl, tetgen)
Thomas Günther's avatar
Thomas Günther committed
44
conda install -c gimli -c conda-forge pybert
Florian Wagner's avatar
Florian Wagner committed
45
46
47
48
49

# After installation, you can try out the examples for testing
cd ~/miniconda3/share/examples/inversion/2dflat/gallery
bert gallery.cfg all
bert gallery.cfg show
50
51

# Update to a newer version
Florian Wagner's avatar
Florian Wagner committed
52
conda update -f pygimli pybert
53
54
```

55
56
57
58
59
60
61
Note that the conda-forge channel is used for installing tetgen.
Consider creating a new environment where all is installed by one line
```bash
conda create -n bert -c gimli -c conda-forge pybert
conda activate bert
```

Thomas Günther's avatar
Thomas Günther committed
62
63
64
If you only working in Python, it is easier to checkout BERT by git
and add the `bert/python` path to the `$PYTHONPATH$`.

65
## Windows binary installers
Thomas Günther's avatar
Thomas Günther committed
66

Thomas Günther's avatar
Thomas Günther committed
67
68
Download the latest binary installer for 64bit Windows (7, 8, 10, 11):

Thomas Günther's avatar
Thomas Günther committed
69
[![Win-Install Badge](https://img.shields.io/badge/Windows%2064bit%20Installer-py3.8%20bert2.3.4-green.svg)](http://www.resistivity.net/download/setup-bert2.3.4win64py38.exe)
Thomas Günther's avatar
Thomas Günther committed
70
[![Win-Install Badge](https://img.shields.io/badge/Windows%2064bit%20Installer-py3.8%20bert2.3.3-green.svg)](http://www.resistivity.net/download/setup-bert2.3.3win64py38.exe)
71
[![Win-Install Badge](https://img.shields.io/badge/Windows%2064bit%20Installer-py3.8%20bert2.3.2-green.svg)](http://www.resistivity.net/download/setup-bert2.3.2win64py38.exe)
72

Thomas Günther's avatar
Thomas Günther committed
73
BERT v2.3 is based on pyGIMLi v1.1-1.2, which brings along some markable changes over v1.0.
Thomas Günther's avatar
Thomas Günther committed
74
In the binary installers, pyGIMLi is included.
75

Thomas Günther's avatar
Thomas Günther committed
76
The current version works with any Python 3.8, we recommend the [Anaconda Distribution](https://www.anaconda.com/download/).
77
There are older installers (for Python 3.6 and 3.7) below bringing along pyGIMLi 1.0.x versions.
78

Thomas Günther's avatar
Thomas Günther committed
79
Please read the [Tutorial](http://www.resistivity.net/download/bert-tutorial.pdf), particularly Appendix A for Windows users:
Thomas Günther's avatar
Thomas Günther committed
80
The path to BERT and to Python must be known to the system by either the System Control (Extended Options) or in the command line of the MSYS shell (download the x86_64 variant from https://msys2.github.io) that is needed to run BERT.
81
82
83
84
85
86
87
88
Assume BERT is installed in `C:\Software\BERT` and Anaconda in `C:\Software\Anaconda`
```bash
export PATH=$PATH:/c/Software/BERT:/c/Software/Anaconda
bert version  # should yield the BERT version
```
Additionally, the BERT directory must be in the search Path for Python modules to find pyGIMLi:
```bash
export PYTHONPATH=$PYTHONPATH:/c/Software/BERT
Thomas Günther's avatar
Thomas Günther committed
89
python -c "import pygimli;print(pygimli.__version__)" # should yield the pyGIMLi version
90
```
Thomas Günther's avatar
Thomas Günther committed
91

Thomas Günther's avatar
Thomas Günther committed
92
To do this for every start, append the lines to your startup file:
93
94
95
96
```bash
echo 'export PATH=$PATH:/c/Software/BERT:/c/Software/Anaconda' >> $HOME/.bashrc
echo 'export PYTHONPATH=$PYTHONPATH:/c/Software/BERT' >> $HOME/.bashrc
```
97
98
99
100
101
If you are unable to view outputs from 'show' commands, you may also need to add the following to your '.bashrc'
```
export PATH=$PATH:$(dirname `which python`)/Scripts
export PATH=$PATH:$(dirname `which python`)/Library/bin
```
102
103

### Older versions (also for other Python versions)
Thomas Günther's avatar
Thomas Günther committed
104
105
[![Win-Install Badge](https://img.shields.io/badge/Windows%2064bit%20Installer-py3.8%20bert2.3.1-green.svg)](http://www.resistivity.net/download/setup-bert2.3.1win64py38.exe)
[![Win-Install Badge](https://img.shields.io/badge/Windows%2064bit%20Installer-py3.7%20bert2.3.1-green.svg)](http://www.resistivity.net/download/setup-bert2.3.1win64py37.exe)
Thomas Günther's avatar
Thomas Günther committed
106
[![Win-Install Badge](https://img.shields.io/badge/Windows%2064bit%20Installer-py3.7%20bert2.3.0-green.svg)](http://www.resistivity.net/download/setup-bert2.3.0win64py37.exe)
107

Thomas Günther's avatar
Thomas Günther committed
108
109
110
[![Win-Install Badge](https://img.shields.io/badge/Windows%2064bit%20Installer-py3.7%20bert2.2.12-green.svg)]
(http://www.resistivity.net/download/setup-bert2.2.12win64py37.exe)
[![Win-Install Badge](https://img.shields.io/badge/Windows%2064bit%20Installer-py3.7%20bert2.2.11-green.svg)](http://www.resistivity.net/download/setup-bert2.2.11win64py37.exe)
111
112
[![Win-Install Badge](https://img.shields.io/badge/Windows%2064bit%20Installer-py3.7%20bert2.2.10-green.svg)](http://www.resistivity.net/download/setup-bert2.2.10win64py37.exe)

Thomas Günther's avatar
Thomas Günther committed
113
[![Win-Install Badge](https://img.shields.io/badge/Windows%2064bit%20Installer-py3.6%20bert2.2.10-green.svg)](http://www.resistivity.net/download/setup-bert2.2.10win64py36.exe)
Thomas Günther's avatar
Thomas Günther committed
114
115
116
[![Win-Install Badge](https://img.shields.io/badge/Windows%2064bit%20Installer-py3.7%20bert2.2.9-green.svg)](http://www.resistivity.net/download/setup-bert2.2.9win64py37.exe)
[![Win-Install Badge](https://img.shields.io/badge/Windows%2064bit%20Installer-py3.6%20bert2.2.9-green.svg)](http://www.resistivity.net/download/setup-bert2.2.9win64py36.exe)

117
118
[![Win-Install Badge](https://img.shields.io/badge/Windows%2064bit%20Installer-py3.6%20bert2.2.8-green.svg)](http://www.resistivity.net/download/setup-bert2.2.8win64py36.exe)
[![Win-Install Badge](https://img.shields.io/badge/Windows%2064bit%20Installer-py3.6%20bert2.2.7-green.svg)](http://www.resistivity.net/download/setup-bert2.2.7win64py36.exe)
119
[![Win-Install Badge](https://img.shields.io/badge/Windows%2064bit%20Installer-py3.6%20bert2.2.6-green.svg)](http://www.resistivity.net/download/setup-bert2.2.6win64py36.exe)
120
[![Win-Install Badge](https://img.shields.io/badge/Windows%2064bit%20Installer-py3.6%20bert2.2.5-green.svg)](http://www.resistivity.net/download/setup-bert2.2.5win64py36.exe)
121
[![Win-Install Badge](https://img.shields.io/badge/Windows%2064bit%20Installer-py3.5%20bert2.2.4-green.svg)](http://www.resistivity.net/download/setup-bert2.2.4win64py35.exe)
122
[![Win-Install Badge](https://img.shields.io/badge/Windows%2064bit%20Installer-py3.4%20bert2.1.1-green.svg)](http://www.resistivity.net/download/setup-bert2.1.1win64py34.exe)
123

124
## Update your installation
carsten's avatar
carsten committed
125

Florian Wagner's avatar
Florian Wagner committed
126
To update your installation go into your BERT source repository.
carsten's avatar
carsten committed
127

128
```bash
carsten's avatar
carsten committed
129
130
131
132
cd bert/bert
git pull
```

Florian Wagner's avatar
Florian Wagner committed
133
Then you need to rebuild BERT.
carsten's avatar
carsten committed
134

135
136
137
    cd ../build
    make
    make bert1
carsten's avatar
carsten committed
138

139
140
If something goes wrong try to clean your build directory and repeat from the
cmake command above.
carsten's avatar
carsten committed
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
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195

# The unified data format

All projects in our working group use a unified format such that data are 
transpararent and transportable. There are a lot of import and export filters 
for third party software or hardware, but internally the following structure 
is used. Since the most applications use multi-electrode systems they are based 
on the way they are addressed (and computed in modeling).

Every data set consists of two mandatory parts: electrode definitions and 
arrangement definition. Subsequently the number of electrodes, 
their positions (x z for 2D, x y z for 3D), the number of data and their 
definitions are given. Comments may be places after the # character. 

After the number of data the definition for each datum is given row-wise 
by the electrode numbers for the current electrodes A and B (C1 and C2) and the 
potential electrodes M and N (P1 and P2). Please not all electrode number starting
from one. Electrodes with a zero number will be treated as infinity electrodes.
They may be followed by other attributes (see list below). 
Standard is the apparent resistivity and optional the relative error as 
exemplified for a tiny dipole-dipole survey.

```
6# Number of electrodes
# x z position for each electrode
0     0
1     0
2     0 # loose ground
3     0
4     0
5     0
6# Number of data
# a b m n rhoa
1   2   3   4  231.2
2   3   4   5  256.7
3   4   5   6  312.8
1   2   4   5  12.1 # possibly an outlier
2   3   5   6  199.7
1   2   5   6  246.2
```

If other fields or order are used, a token string in the line after the data 
number specifies the given fields. The token may be followed by a slash and
a physical unit. The following tokens are allowed (case insensitive).
Tokens	Meaning	possible units

* `a` `c1` electrode number for A (C1)
* `b` `c2` electrode number for B (C2)
* `m` `p1`	electrode number for M (P1)
* `n` `p2`	electrode number for N (P2)
* `rhoa` `Ra`	apparent resistivity	Ohmmeter
* `rho` `r`	Resistance	Ohm
* `err`	relative measurement error in %/100 (default)
* `ip` IP measure	mRad(default)
* `ipErr` absolute IP measure error in mRad(default)
Florian Wagner's avatar
Florian Wagner committed
196
197
* `i` `I` Current	A(default),mA,uA
* `u` `U` Voltage	V(default),mV,uV
carsten's avatar
carsten committed
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227

The following sample contains voltages, currents and a percentage error.

```
...
6# Number of data
# a b m n u i/mA err/% 
  1   2   3   4  -0.5305165 102.2 2.4
  2   3   4   5  -0.5305165 99.9  1.4
  3   4   5   6  -0.5305165 95.6  2.6
  1   2   4   5  -0.1326291 100.1 7.6
  2   3   5   6  -0.1326291 80.2 8.6
  1   2   5   6  -0.05305165 77.3 7.5
```

Topography may be given in two ways.

1. Each electrode can be given a height value as z position (preferred by webinv).
2. Alternatively, the data may be followed by a topo list (preferred by DC2dInvRes).

```
...
  1   2   5   6  -0.05305165  7.5
4# Number of topo points
# x h for each topo point
0 353.2
12 357.1
19 359.9
24.5 350
```