search

inlab-geo / espresso

Earth Science PRoblems for the Evaluation of Strategies, Solvers and Optimizers
https://geo-espresso.readthedocs.io
Other
15 stars 9 forks source link
earth-science geoscience inference inversion python

readme

Espresso

PyPI version build Documentation Status Slack

Related repositories by InLab

Introduction

Earth Science PRoblems for the Evaluation of Strategies, Solvers and Optimizers (Espresso) is a collection of datasets, and associated simulation codes, spanning a wide range of geoscience problems. Together they form a suite of real-world test problems that can be used to support the development, evaluation and benchmarking of a wide range of tools and algorithms for inference, inversion and optimisation. All problems are designed to share a common interface, so that changing from one test problem to another requires changing one line of code.

The Espresso project is a community effort - if you think it sounds useful, please consider contributing an example or two from your own research. The project is currently being coordinated by InLab, with support from the CoFI development team.

For more information, please visit our documentation.

Installation

$ pip install geo-espresso

Check Espresso documentation - installation page for details on dependencies and setting up with virtual environments.

Building espresso from source

This is a temporary workaround that should result in a usable espresso. Please note that pip install and python espresso_machine/build_package/build.py do indeed need to be run twice...

git clone https://github.com/inlab-geo/espresso.git espresso.git
cd espresso.git
pip install .
python espresso_machine/build_package/build.py all
pip install .
python espresso_machine/build_package/build.py all

This also assumes that you have the python packages pytest, versioningit and tqdm installed in addition to the packages listed in pyporject.toml. If not the installation script will report them as missing and you need to install them using pip. It also assumes that you have cmake and the gnu compilers installed i.e. gcc and gfortran

Basic usage

Once installed, each test problem can be imported using the following command:

from espresso import <testproblem>

Replace <testproblem> with an actual problem class in Espresso, such as SimpleRegression and FmmTomography. See here for a full list of problems Espresso currently includes.

Once a problem is imported, its main functions can be called using the same structure for each problem. For instance:

from espresso import FmmTomography

problem = FmmTomography(example_number=1)
model = problem.good_model
data = problem.data
pred = problem.forward(model)
fig_model = problem.plot_model(model)

You can access related metadata programatically:

print(FmmTomography.metadata["problem_title"])
print(FmmTomography.metadata["problem_short_description"])
print(FmmTomography.metadata["author_names"])

Other problem-specific parameters can be accessed through the problem instance. For instance:

print(problem.extent)
print(problem.model_shape)

Which additional values are set is highly problem-specific and we suggest to consult the Espresso Documentation on the problems.

Contributing

Interested in contributing? Please check out our contributor's guide.

Licence

Espresso is a community driven project to create a large suite of forward simulations to enable researchers to get example data without the need to understand each individual problem in detail.

Licensing is done individually by each contributor. If a contributor wants to freely share their code example we recommend the MIT licence or a 2-clause BSD licence. To determine the licence of an existing Espresso problem, please consult the documentation section of that problem.

All the other core functions of Espresso written by InLab Espresso developer team are distributed under a 2-clause BSD licence. A copy of this licence is provided with distributions of the software.