Fast marching Anisotropic Acoustic emission Tomography using Standard Optimisation (Faatso) is a package to perform combined active/passive acoustic emission tomography for heterogeneous (weakly) vertical transversely isotropic media.

The code contains two major elements: (1) a 3D VTI eikonal solver, which uses the Fast Marching Method. (2) a specific inverse problem solver which uses the least-square Quasi-Newton method to invert for sources positions and velocity structure iteratively.

All the operating parts of the code are written in C++, and interfaces in Matlab are provided to ease the generation and visualisation of the results.

To run Faatso, you need: (1) a c++ compiler supporting c++11. (2) the c++ Boost library (downloadable from http://www.boost.org/users/download/), or at least the boost/heap library which is used in the fast marching algorithm. (3) the Armadillo library (downloadable from http://arma.sourceforge.net/download.html) together with Lapack, used to perform linear algebra in the inversion algorithm. (4) Matlab (or potentially Octave, but I have not tested that) to run the wrappers and examples.

The path to the Boost header directory (typically something like usr/local/boost_x_xx_x) should be accessible by your compiler, for instance by adding it into the CPATH environment variable.

The Armdillo library should also be in the set of library paths of the compiler.

First clone this repository:

git clone https://github.com/nbrantut/Faatso.git
cd Faatso/

If either Armadillo or Boost libraries are not in the default path of the compiler, you can add them in the Makefile by modifying the variables LIB and/or INC. If you want to customise the name or path for the executables, edit the Makefile and change the variables TARGET_FMM and/or TARGET_TOMO to your liking (note: if you do this, then the Matlab examples won’t run properly since the programs’ names are hard-coded in the scripts).

To build the executables, simply run make or equivalently make all. This will generate object files in the build/ directory, and two executables, fmm and tomo in the bin directory (or whatever name and path you decided if you changed the Makefile).

Either program can be built independently by running make fmm or make tomo. The binaries and object files are cleaned up by running make clean.

The first step is to let your shell access the binaries. This can be done by using the following command:

export PATH=[Faatso root directory]/bin:$PATH

To execute the programs from within Matlab, this is unfortunately not enough, since Matlab uses its own environment variable PATH. To add the exectuables to Matlab’s path, either use the routine put_faatso_on_path located in interface/matlab/, or use Matlab’s command setenv().

The program fmm is the eikonal solver that can be used as an independent tool to perform direct problem computations in 3D regular grids with a weak (elliptic) vertical transverse isotropy.

The program requires 5 input arguments in a specific order (this is clearly not very flexible but in fact not a big deal since it is nearly always wrapped into a Matlab script). For example:

fmm V.bin E.bin 0 1 T.bin

where V.bin and E.bin are two filenames corresponding to the velocity and anisotropy structures (they should both be formed in the same grid dimensions), the third argument (here 0) is the index of the source node in the grid, the fourth argument (here 1) is a boolean (0 or 1) dictating whether a source box is to be used, and the last argument (T.bin) is again a filename where the arrival times will be stored.

The details of the structure of the binary files, the grid indexing and the signification of the source box parameter are reported in the specific documentation of the fmm program.

The program tomo performs the tomographic inversion using the fast marching method for the forward problem and the least square quasi-Newton method for the inverse problem.

The program requires one command line argument, which is the name of a text file containing parameter values (and paths to other input files):

./tomo params.txt

The content of the parameter file and other input files is given in the companion documentation.

A series of examples demonstrating the use of the eikonal solver and inversion program are given here, as Matlab scripts.

Most examples require to add the folder interface/matlab/ to Matlab’s path (using for instance the command addpath()). Before running the examples, make sure that the executables fmm and tomo are accessible by Matlab: to ensure this, either use the routine put_faatso_on_path (after modifying it to set Faatso’s root directory), or use directly Matlab’s function setenv('PATH',...). To run the examples using tomo with synthetic data, a similar procedure is required.

With a conventional installation all matlab codes whould run without modifications: in each case, simply run the script called example.m.

The documentation is given in the folder doc/ which contains a full explanation of the code internals (pdf or html), and methodological choices and details for the eikonal solver (pdf) and the inversion program (pdf).

Nicolas Brantut, Rock and Ice Physics and Seismological Laboratory, University College London, UK. homepage

If you use FaATSO or parts of it for your own research, please cite the following article that describes the code and method: Brantut N., Time-resolved tomography using acoustic emissions in the laboratory, and application to sandstone compaction, submitted to Geophys. J. Int.

Many thanks to Romain Jolivet for his help during the development of the inversion program, and for suggesting the name of the package. Thanks also to Ana Feirrera and Alex Song for their useful discussions about wave propagation, eikonal solvers and tomography.