Welcome to custEM!

Version: 0.99 ~ Date: Mar 29, 2021

!!! custEM version 1.0 will be available soon !!!
  • support for general CSEM, TEM, and MT modeling already implemented -
  • see Development section -

The Python toolbox custEM is an open-source development for customizable 3D finite-element modeling of controlled-source, transient, and natural-source electromagnetic data. The toolbox is based on the finite-element library FEniCS, see https://fenicsproject.org/ . Different total and secondary electric or magnetic field as well as gauged-potential approaches are implemented. In addition, custEM contains a mesh generation submodule for the straightforward generation of tetrahedral meshes supporting a large number of marine, land-based, airborne or mixed model scenarios. Interpolation and visualization tools simplify the post-processing workflow.

Mesh generation runs on any laptop or desktop PC. Also minimalistic examples can be tested on such machines. Because of using direct solvers, we recommend to get access to a cluster with >= 32 cores/threads and >=256 GB RAM for calculating sufficiently accurate models for more complex 3D setups. However, quite good results for simpler 3D modeling studies often require only 32-64 GB.

Please note that custEM is under continuous development. For information about planned updates and previous development steps we refer to the Development section. Do not hesitate to contact raphael.rochlitz@leibniz-liag.de for any kind of question about custEM or discovered issues in the code, examples, or the documentation.


Getting started

To guide you through setting up the toolbox and making third party dependencies available, please follow the Installation notes. After A successful installation, user could run any of the test files provided in the corresponding directory. In addition to these initial tests for the overall functionality of custEM, we refer to the provided examples. The first four frequency-domain and first three time-domain examples correspond to the ones presented by (Rochlitz et al., 2019) & (Rochlitz et al., 2021), respectively. Further advise to develop solution strategies for user-specific modeling problems is provided by the tutorials.

In addition, we recommend to read the Tips&Tricks section, which contains further practical advise based on our modeling experiences.


Installation

For instructions, it is referred to the Installation section.


Documentation

The python API documentation is available online on ReadtheDocs. In, addition, the complete API documentation is available as “hmtl_doc” zip-file in the docs directory of the custEM repository and can be accessed via opening the “index.html” file in the zip directory with your favorite browser.

The Source code documentation content is generated automatically when publishing new custEM versions. Detailed information about specific functionalities might be accessed with help of the Index or using the Search Page.

_images/custEMoverview.png

Overview of Third-party dependencies and modules in custEM


Tutorials

!!! Tutorials are out-dated and need to be updated to recent syntax changes !!!

Tutorials are available in the tutorials directory in the custEM repository as jupyter notebook, python script, and in html format. The html documentation of the Tutorials can be also accessed in the corresponding section. Please note that the tutorials are still under development and in particular, the usage of jupyter notebooks is not straightforward in combination with multiprocessing. We are about to fix related issues, but for now, secondary field computations and interpolation are not possible if the run_tutorial is started from the jupyter notebook. For running this tutorial, please use the provided run_tutorial.py python script and call it from the command line with the mpirun syntax, e.g.:

–> mpirun -n x python run_tutorial.py

with x, the number of cores.


Examples

A selection of CSEM modeling examples can be found here.


License

Copyright 2016-2020 by R. Rochlitz

The custEM toolbox is licensed under the GNU GENERAL PUBLIC LICENSE (GPL). The terms are listed here License.


Authors

Contributing authors and contacts are listed in the Authors section.


References

Rochlitz, R., Skibbe, N. and Günther, T., (2019), custEM: customizable finite element simulation of complex controlled-source electromagnetic data, GEOPHYSICS Software and Algorithms.

Rochlitz, R. (2020), Analysis and open-source Implementation of Finite Element Modeling techniques for Controlled-Source Electromagnetics, PhD thesis, Westfälische Wilhelms-Universität Münster, Germany.

Rochlitz, R., Skibbe, N. and Günther, T., (2021), Evaluation of three approaches for simulating time-domain electromagnetic data using the open-source software custEM, GJI, under review.

If required, please contact raphael.rochlitz@leibniz-liag.de for access.

Next to us, don’t forget to give credits to the authors of FEniCS, pyGIMLi TetGen and COMET if submodules based on these developments are used for your purposes.