custemx 0.9.5.1__tar.gz

custemx-0.9.5.1/.gitignore

@@ -0,0 +1,26 @@
+**/__pycache__
+*/*.vtu
+*/*.pvtu
+*/*.pvd
+*.pdf
+*.edge
+*.poly
+*.xdmf
+*.h5
+*.pyc
+*instructions.md
+.conda
+.vscode
+.pytest_cache
+default_model_parameter.json
+pytest/results/**
+pytest/fwd/**
+pytest/mwe/fwd/**
+pytest/mwe/meshes/**
+pytest/mwe/results/**
+results/**
+docs/_build/**
+docs/api/**
+uv.lock
+custemx.egg-info/*
+custemx/mod/default_model_parameter_old.json

custemx-0.9.5.1/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changes to custemx
+
+The project changelog is maintained in
+[docs/changelog.md](docs/changelog.md).

custemx-0.9.5.1/CONTRIBUTING.md

@@ -0,0 +1,8 @@
+# Contributing to custemx
+
+The project contribution, engineering, testing, documentation, configuration,
+MPI, and automation-agent policies are maintained in
+[docs/contributing.md](docs/contributing.md).
+
+Read that guide before proposing or implementing a change. For release and
+deployment process, see [docs/development.md](docs/development.md).

custemx-0.9.5.1/INSTALL.md

@@ -0,0 +1,51 @@
+# Installation
+
+**Clone custemx and the corresponding custemx-examples**
+
+```bash
+git clone https://gitlab.com/custem/custemx.git
+git clone https://gitlab.com/custem/custemx-examples.git
+```
+
+**Create conda environment with fenicsx library and its dependencies**
+
+- download Anaconda or Miniconda
+
+```bash
+conda create -n dfx11 -c conda-forge fenics-dolfinx tetgen mpich
+```
+
+**Activate conda environment**
+
+```bash
+conda activate "name"
+```
+
+**Install pygimli via pip and other dependencies**
+
+```bash
+pip install pygimli
+pip install meshio utm pyvista empymod
+```
+
+**Add custemx and datatools to your PYTHONPATH variable and adjust OMP NUM THREADS variable**
+
+```{note}
+We recommended to add the following three commands to your .bashrc file
+```
+
+```bash
+export PYTHONPATH=${PYTHONPATH}:$HOME/"path_to_custemx":$HOME/"path_to_custemx"/datatools
+export OMP_NUM_THREADS=1
+conda activate "name"
+```
+
+<!--
+## add custemx git to environment
+cd custemx
+pip install --no-build-isolation --no-deps -e .
+
+## add pygimli git to environment
+cd ../pygimli
+pip install --no-build-isolation --no-deps -e .
+-->

custemx-0.9.5.1/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: custemx
+Version: 0.9.5.1
+Summary: A library for electromagnetic modeling with FEniCSx and pyGIMLi integration.
+Author-email: Nico Skibbe <nico.skibbe@liag-institut.de>, Raphael Rochlitz <raphael.rochlitz@liag-institut.de>
+License-Expression: LGPL-3.0-only
+Project-URL: Homepage, https://custemx.readthedocs.io
+Project-URL: Repository, https://gitlab.com/custem/custemx
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pygimli
+Requires-Dist: meshio
+Requires-Dist: utm
+Requires-Dist: pyvista
+Requires-Dist: empymod
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Provides-Extra: fenics
+Requires-Dist: dolfinx; extra == "fenics"
+Requires-Dist: fenics-dolfinx; extra == "fenics"
+
+# custemx
+
+custemx is an open-source Python toolkit for 3D electromagnetic forward
+modeling and inversion in geophysics. Built on FEniCSx, it brings together
+finite-element formulations, mesh and model setup, field calculation, and
+post-processing for controlled-source EM (CSEM) and magnetotellurics (MT).
+
+[Documentation](https://custemx.readthedocs.io/) ·
+[Examples](https://gitlab.com/custem/custemx-examples) ·
+[Source code](https://gitlab.com/custem/custemx)
+
+## Capabilities
+
+- Model 3D CSEM and MT problems on unstructured tetrahedral meshes, with
+	utilities for mesh generation, import, and export.
+- Use Nedelec finite elements to calculate complex electric fields and derive
+	magnetic fields and MT responses.
+- Represent isotropic or anisotropic electrical and electromagnetic properties,
+	including VTI and full anisotropy for conductivity, permeability, and
+	permittivity.
+- Include frequency-dependent induced polarization using Cole-Cole parameters.
+- Choose direct PETSc/MUMPS or iterative PETSc solver workflows, and run
+	distributed simulations with MPI.
+- Adapt the Python workflow through configurable model parameters, sources,
+	receivers, formulations, and post-processing components.
+
+## Start with an example
+
+The examples repository is the recommended place to start: each case includes
+working model setup and run scripts, rather than a disconnected API snippet.
+
+- [3D CSEM half-space][halfspace]: a first mesh-generation and
+	forward-modeling workflow.
+- [Layered-earth crooked-loop CSEM][crooked-loop]: a next step with a more
+	involved source and earth model.
+- [Induced-polarization examples][ip-examples]: frequency-domain IP modeling.
+- [Inversion examples][inversion-examples]: workflows from minimal examples
+	to research applications.
+
+See the [examples README](https://gitlab.com/custem/custemx-examples/-/blob/main/README.md)
+for repository layout and run instructions.
+
+[halfspace]: https://gitlab.com/custem/custemx-examples/-/tree/main/modeling/csem/01_hed_halfspace
+[crooked-loop]: https://gitlab.com/custem/custemx-examples/-/tree/main/modeling/csem/02_crooked_loop_layered
+[ip-examples]: https://gitlab.com/custem/custemx-examples/-/tree/main/modeling/fd_ip
+[inversion-examples]: https://gitlab.com/custem/custemx-examples/-/tree/main/inversion
+
+## Installation
+
+custemx requires Python 3.10 or later and a working FEniCSx, PETSc, and MPI
+environment. Create the recommended environment with conda, then install the
+published Python package with pip:
+
+```bash
+conda create -n custemx -c conda-forge fenics-dolfinx tetgen mpich
+conda activate custemx
+python -m pip install custemx
+```
+
+The conda environment provides the FEniCSx runtime; pip installs custemx and
+its declared Python dependencies.
+
+## Project information
+
+- **Maintainers:** Raphael Rochlitz and Nico Skibbe ([team and contact
+	information](https://custemx.readthedocs.io/en/latest/team.html))
+- **License:** [LGPL-3.0-only](https://custemx.readthedocs.io/en/latest/license.html)
+
+See the [full documentation](https://custemx.readthedocs.io/) for more
+information.

custemx-0.9.5.1/README.md

@@ -0,0 +1,70 @@
+# custemx
+
+custemx is an open-source Python toolkit for 3D electromagnetic forward
+modeling and inversion in geophysics. Built on FEniCSx, it brings together
+finite-element formulations, mesh and model setup, field calculation, and
+post-processing for controlled-source EM (CSEM) and magnetotellurics (MT).
+
+[Documentation](https://custemx.readthedocs.io/) ·
+[Examples](https://gitlab.com/custem/custemx-examples) ·
+[Source code](https://gitlab.com/custem/custemx)
+
+## Capabilities
+
+- Model 3D CSEM and MT problems on unstructured tetrahedral meshes, with
+	utilities for mesh generation, import, and export.
+- Use Nedelec finite elements to calculate complex electric fields and derive
+	magnetic fields and MT responses.
+- Represent isotropic or anisotropic electrical and electromagnetic properties,
+	including VTI and full anisotropy for conductivity, permeability, and
+	permittivity.
+- Include frequency-dependent induced polarization using Cole-Cole parameters.
+- Choose direct PETSc/MUMPS or iterative PETSc solver workflows, and run
+	distributed simulations with MPI.
+- Adapt the Python workflow through configurable model parameters, sources,
+	receivers, formulations, and post-processing components.
+
+## Start with an example
+
+The examples repository is the recommended place to start: each case includes
+working model setup and run scripts, rather than a disconnected API snippet.
+
+- [3D CSEM half-space][halfspace]: a first mesh-generation and
+	forward-modeling workflow.
+- [Layered-earth crooked-loop CSEM][crooked-loop]: a next step with a more
+	involved source and earth model.
+- [Induced-polarization examples][ip-examples]: frequency-domain IP modeling.
+- [Inversion examples][inversion-examples]: workflows from minimal examples
+	to research applications.
+
+See the [examples README](https://gitlab.com/custem/custemx-examples/-/blob/main/README.md)
+for repository layout and run instructions.
+
+[halfspace]: https://gitlab.com/custem/custemx-examples/-/tree/main/modeling/csem/01_hed_halfspace
+[crooked-loop]: https://gitlab.com/custem/custemx-examples/-/tree/main/modeling/csem/02_crooked_loop_layered
+[ip-examples]: https://gitlab.com/custem/custemx-examples/-/tree/main/modeling/fd_ip
+[inversion-examples]: https://gitlab.com/custem/custemx-examples/-/tree/main/inversion
+
+## Installation
+
+custemx requires Python 3.10 or later and a working FEniCSx, PETSc, and MPI
+environment. Create the recommended environment with conda, then install the
+published Python package with pip:
+
+```bash
+conda create -n custemx -c conda-forge fenics-dolfinx tetgen mpich
+conda activate custemx
+python -m pip install custemx
+```
+
+The conda environment provides the FEniCSx runtime; pip installs custemx and
+its declared Python dependencies.
+
+## Project information
+
+- **Maintainers:** Raphael Rochlitz and Nico Skibbe ([team and contact
+	information](https://custemx.readthedocs.io/en/latest/team.html))
+- **License:** [LGPL-3.0-only](https://custemx.readthedocs.io/en/latest/license.html)
+
+See the [full documentation](https://custemx.readthedocs.io/) for more
+information.

custemx-0.9.5.1/VERSION.md

@@ -0,0 +1,8 @@
+# custemx release version
+
+The canonical package version is stored in `custemx/__version__` and mirrored
+in `pyproject.toml`.
+
+Release history is in [docs/changelog.md](docs/changelog.md); the release and versioning
+process is documented in [docs/development.md](docs/development.md) and
+[docs/contributing.md](docs/contributing.md).

custemx-0.9.5.1/custemx/Types table.md

@@ -0,0 +1,45 @@
+# Types table
+
+# Numpy
+np.ndarray:
+    Numpy Array
+
+# Petsc
+petsc4py.PETSc.Mat
+    System matrix
+
+petsc4py.PETSc.Vec
+    Right hand side
+
+# dolfinx
+dfx.mesh.Mesh
+    Dolfinx Mesh
+
+dfx.mesh.MeshTags
+    Marker for a mesh
+
+dfx.fem.Constant
+    Constant function on a mesh
+
+dfx.fem.FunctionSpace
+    Function space for dof definition
+
+dfx.fem.function.Function
+    Empty dolfinx function for coeffiecients
+
+# UFL
+ufl.argument.Argument
+    e.g. u = ufl.TrialFunction(V)
+    e.g. v = ufl.TestFunction(V)
+
+# pyGIMLi
+pg.Mesh
+    pyGIMLi mesh
+
+# MPI
+mpi4py.MPI.Intracomm
+    Communicator for the different MPI processes
+
+# custEMx
+cx.mod.ModelParameter
+    Model parameter class instance

custemx-0.9.5.1/custemx/__init__.py

@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+@author: Rochlitz & Skibbe
+
+Main initialization file for the custEMx module.
+Imports submodules and configuration file as well as the logger instance.
+"""
+import logging
+import dolfinx as dx
+from pathlib import Path
+import tempfile
+import json
+import mpi4py.MPI as MPI
+from logging.handlers import MemoryHandler
+
+# CONFIG
+class _cfg():
+    """ Class for handling the configuration of the custemx module."""
+    def __init__(self, config='custemx_config.json') -> dict:
+        # dolfinx mesh partitioner
+        self._partitioner = None
+        with open(Path(__file__).with_name(config), 'r') as infile:
+            self._cfg = json.load(infile)
+
+        for key in self._cfg.keys():
+            setattr(self, key, self._cfg[key])
+
+        if not hasattr(self, 'global_timeout') or self.global_timeout == 0:
+            self.global_timeout = None
+
+        self.basepath = Path(__file__).parent
+        self.testpath = self.basepath.parent.joinpath('pytest')
+
+    @property
+    def partitioner(self):
+        """Get the mesh partitioner for dolfinx meshes."""
+        if self._partitioner is None:
+            # FIXME allow ordering in module config
+            try:
+                from dolfinx.graph import partitioner_scotch
+                log.info('Use partitioner "Scotch"')
+                use_partitioner = partitioner_scotch()
+            except ImportError:
+                try:
+                    from dolfinx.graph import partitioner_kahip
+                    log.info('Use partitioner "Kahip"')
+                    use_partitioner = partitioner_kahip()
+                except ImportError:
+                    try:
+                        from dolfinx.graph import partitioner_parmetis
+                        log.info('Use partitioner "Parmetis"')
+                        use_partitioner = partitioner_parmetis()
+                    except ImportError:
+                        pass
+            finally:
+                if use_partitioner is not None:
+                    self._partitioner =\
+                        dx.mesh.create_cell_partitioner(use_partitioner)
+        return self._partitioner
+
+cfg = _cfg()
+
+# LOGGER
+log = logging.getLogger('cx')
+_MEMORY_EXPORT_FMT = '%(asctime)s %(message)s'
+_MEMORY_EXPORT_DATEFMT = '%Y-%m-%d %H:%M:%S'
+
+# Custom logging level between INFO (20) and WARNING (30)
+NOTICE = 25
+logging.addLevelName(NOTICE, "NOTICE")
+
+
+def _notice(self, message, *args, **kwargs):
+    if self.isEnabledFor(NOTICE):
+        self._log(NOTICE, message, args, **kwargs)
+
+
+def _log_line(self, char="-", length=80):
+    if MPI.COMM_WORLD.rank == 0:
+        """Print a separator line without logging prefix."""
+        if log.level < 24:
+            print(char * length, flush=True)
+
+
+def _log_header(self, text, char="-", length=80):
+    if MPI.COMM_WORLD.rank == 0:
+        """Print header lines without logging prefix."""
+        if log.level < 24:
+            print(char * length, flush=True)
+            print(text, flush=True)
+            print(char * length, flush=True)
+
+
+def _ensure_root_console_handler(root_logger):
+    """Set the formatter of all root console handlers."""
+
+    if not root_logger.handlers:
+        root_logger.addHandler(logging.StreamHandler())
+
+    elif len(root_logger.handlers) > 1:
+        root_logger.handlers = [root_logger.handlers[0]]
+
+    for handler in root_logger.handlers:
+        if isinstance(handler, logging.StreamHandler):
+            handler.setFormatter(
+                logging.Formatter(
+                    fmt='CX - %(levelname)s - %(asctime)s - %(message)s',
+                    datefmt='%H:%M:%S'))
+
+def _ensure_memory_handler(logger):
+    """Keep one MemoryHandler on cx logger for logfile message export."""
+    memory_handlers = [h for h in logger.handlers if
+                       isinstance(h, MemoryHandler)]
+    if memory_handlers:
+        memory_handler = memory_handlers[0]
+    else:
+        memory_handler = MemoryHandler(
+            capacity=99999,
+            flushLevel=logging.CRITICAL,
+        )
+
+    memory_handler.setLevel(logging.NOTSET)
+    memory_handler.setFormatter(
+        logging.Formatter(
+            fmt=_MEMORY_EXPORT_FMT,
+            datefmt=_MEMORY_EXPORT_DATEFMT,
+        )
+    )
+
+    # Keep cx handler setup minimal and deterministic: memory capture locally,
+    # console output through root logger propagation.
+    logger.handlers = [memory_handler]
+    logger.propagate = True
+
+
+def _get_memory_messages(logger):
+    """Return buffered messages from cx MemoryHandler."""
+    memory_handler = next(
+        (h for h in logger.handlers if isinstance(h, MemoryHandler)),
+        None,
+    )
+    messages = []
+    if memory_handler is not None:
+        for record in memory_handler.buffer:
+            try:
+                messages.append(memory_handler.formatter.format(record))
+            except Exception:
+                messages.append(record.getMessage())
+    return messages
+
+logging.Logger.notice = _notice
+log.get_messages = lambda: _get_memory_messages(log)
+log.line = _log_line.__get__(log, logging.Logger)
+log.header = _log_header.__get__(log, logging.Logger)
+log.setLevel(cfg.log_level)
+
+if MPI.COMM_WORLD.rank != 0:
+    log.setLevel(40)
+
+# VERSION
+try:
+    from importlib.metadata import version, PackageNotFoundError
+    __version__ = version("custemx")
+except PackageNotFoundError:
+    __version__ = None
+
+# SUBMODULES
+from . import mod
+from . import misc
+from . import plot
+from . import fe
+from . import meshtools
+from . import io
+from . import solver
+from . import inv
+
+
+_ensure_root_console_handler(log.root)
+_ensure_memory_handler(log)
+
+# init default model parameters
+mod.update_default_model_parameter(version=__version__)

custemx-0.9.5.1/custemx/custemx_config.json

@@ -0,0 +1,21 @@
+{
+    "log_level": 20,
+    "max_cpu": 64,
+    "cpu_per_task": 16,
+    "global_timeout": 86400,
+    "inner_maxiter_warning": 50,
+    "petsc_options": {
+        "mumps": {
+            "ksp_type": "preonly",
+            "mat_mumps_cntl_1": 1e-8,
+            "mat_mumps_cntl_2": 1e-8,
+            "mat_mumps_icntl_8": 0,
+            "mat_mumps_icntl_14": 80,
+            "mat_mumps_icntl_48": 0,
+            "pc_factor_reuse_ordering": true,
+            "pc_factor_reuse_fill": true,
+            "pc_type": "cholesky",
+            "pc_factor_mat_solver_type": "mumps"
+        }
+    }
+}

custemx-0.9.5.1/custemx/fe/__init__.py

@@ -0,0 +1,38 @@
+"""
+This file is part of custemx.
+Licensed under the GNU LGPLv3, see LICENSE for details.
+
+Authors: Nico Skibbe, Raphael Rochlitz
+
+Public finite-element formulations and helper exports.
+"""
+
+from .fe_class import BaseFormulation
+from .fe_forms import FormEFD
+from .fe_lib import (
+    LocalAssembler,
+    adjust_parameter,
+    check_attributes,
+    check_cell_markers,
+    create_delta_sigma,
+    eval_current_dir,
+    find_source_dofs_geometrical,
+    get_boundary_dofs,
+    parameter_to_array,
+)
+from .primary_fields import PF
+
+__all__ = [
+    "BaseFormulation",
+    "FormEFD",
+    "LocalAssembler",
+    "adjust_parameter",
+    "check_attributes",
+    "check_cell_markers",
+    "create_delta_sigma",
+    "eval_current_dir",
+    "find_source_dofs_geometrical",
+    "get_boundary_dofs",
+    "parameter_to_array",
+    "PF",
+]