.. role:: hidden
    :class: hidden-section

Synthetic Volcano Creation
===================================

.. automodule:: volcapy.synthetic
.. currentmodule:: volcapy.synthetic

This module provides functionalities to build *synthetic volcanoes* and run
inversion on them.

The goal is to build a synthetic topography with some user defined matter
density field inside it. One can then compute the gravity field that such an
artificial volcano would generate and treat is as artificial observations in an
inverse problem.

The advantage of such *artificial observations* compared to real data is that
one has the access to the ground truth (the synthetic matter density field).
One can thus us this data to check the implementation of different inversion
methodologies.

On a more informal level, one can use this artificial data to get intuition
about the different covariance kernels, by comparing how the inversion results
for different kernels differ for various ground thruth (sharp edges, long range
structures, ...).


We next provide a detailed description of how to work with synthetic volcanoes,
strating with the *static* part (the data that is usually kept fixed among
different experiments).


Building an artificial volcano
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* The main data characterizing an artificial volcano is a **topography**.
  A topography is a collection of contiguous 3-dimensional cells defining a
  discretization of a given domain (the volcano). For simplicity, we here use a
  cone discretized into uniform cubic cells.

* Once a topography has been defined, one has to chose the locations at which
  the measurements of the gravity field will be performed. We do this by
  picking :math:`n_{obs}` locations at random on the surface of the topography.
  Here surface means the *upper* boundary of the cone, i.e. there will be no
  measurements below the cone. Note also that we add a small offset between the
  surface and the measurement location to avoid singularities in the forwarded
  operator.

* Once topography and measurement locations have been defined, the forward
  operator can be computed using the Banerjee formula.

Generating data from an artificial volcano
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* Once the static data has been defined, one has to specify a matter density
  field inside the topography, i.e. to assign a density to each cell.
* Finally, the observations (gravity field) generated by tha matter density
  field can be computed using the forward operator.

--------------------------------------------

We can thus summarize the workflow for working with synthetic volcanoes.

1. Create an artificial topography.
2. Place data measurement sites around the topography.
3. Compute the forward operator relating the cells in the topography to the
   measurement sites.
4. Define a matter density field inside the topography (see
   :code:`build_synth_data.py`).
5. Using the forward, compute the data observations generated by the density
   field.
6. Train a gaussian process model on the generated data (see :code:`train.py`).
7. Use the gausian process as a prior in bayesian inversion (see
   :code:`reconstruct.py`).
8. Compare the inversion results with the true (synthetic) matter density field.


--------------------------------------------

A detailed description of each submodule is provided below.

build_synth_data
------------------

.. automodule:: volcapy.synthetic.build_synth_data
   :members:

grid
------------------

.. automodule:: volcapy.synthetic.grid
   :members:

vtkutils
------------------

.. automodule:: volcapy.synthetic.vtkutils
   :members:

train
------------------

.. automodule:: volcapy.synthetic.train
   :members:

reconstruct
------------------

.. automodule:: volcapy.synthetic.reconstruct
   :members: