emg3d

https://emg3d.emsig.xyz/en/stable/
Admin
emg3d is a 3D multigrid solver and modeller for electromagnetic diffusion, primarily used in...
Tokens:257,520
Snippets:1,360
Trust Score:6
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install development dependencies

Source: https://emg3d.emsig.xyz/en/stable/dev/tests.html

Installs all requirements from requirements_dev.txt to set up the dev toolchain.

```bash
pip install -r requirements_dev.txt

```

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

### Install python3-setuptools if needed

Source: https://emg3d.emsig.xyz/en/stable/dev/release.html

If the conda skeleton build fails, install python3-setuptools with this command.

```bash
sudo apt install python3-setuptools

```

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

### Install development requirements

Source: https://emg3d.emsig.xyz/en/stable/_sources/dev/tests.rst.txt

Installs all development dependencies listed in requirements-dev.txt.

```console
pip install -r requirements_dev.txt
```

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

### Import emg3d, numpy, and matplotlib

Source: https://emg3d.emsig.xyz/en/stable/_sources/manual/usage.rst.txt

Load the emg3d library along with numpy and matplotlib. This example requires that discretize and xarray are installed as well.

```python
import emg3d
import numpy as np
import matplotlib as mpl
```

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

### emg3d.cfg configuration file example

Source: https://emg3d.emsig.xyz/en/stable/_sources/manual/cli.rst.txt

Example configuration file for the emg3d CLI. All values are commented out; remove comment signs to use them. Shows available options for files, simulation, solver options, and gridding options.

```ini
  # Files
  # -----
  # If the files are provided without ending the suffix `.h5` will be appended.
  # The log has the same name as `output`, but with the suffix `.log`.
  [files]
  # path = .               # Path (absolute or relative) to the data
  # survey = survey.h5     # Also via `--survey`
  # model = model.h5       # Also via `--model`
  # output = emg3d_out.h5  # Also via `--output`
  #
  # # You can save the entire simulation with the `save` argument.
  # save = my_sim.h5       # Also via `--save`
  #
  # # You can load an existing simulation with the `load` argument.
  # # Note that if you provide a simulation it will ignore
  # # - The survey and model under [files]
  # # - Sections [simulation], [solver_opts], [gridding_opts], and [data]
  # load = my_sim.h5       # Also via `--load`
  #
  # # Shortcut for `load` and `save` if the same filename is used for both.
  # cache = my_sim.h5    # Also via `--cache`

  # Simulation parameters
  # ---------------------
  # Input parameters for the `Simulation` class, except for `solver_opts`
  # (defined in their own section).
  [simulation]
  # max_workers = 4      # Also via `-n` or `--nproc`.
  # gridding = single
  # name = MyTestSimulation
  # file_dir = None      # For file-based comp; absolute or relative path.
  # receiver_interpolation = cubic  # Set it to <linear> for the gradient.
  # layered = False      # Also via `-l` or `--layered`.

  # Solver options
  # --------------
  # Input parameters for the solver.
  # See https://emg3d.emsig.xyz/en/stable/api/emg3d.solver.solve.html
  # for a list of all parameters. The only parameters that cannot be provided
  # here are grid, model, sfield, efield, and return_info.
  #
  # Note that currently sslsolver, semicoarsening, and linerelaxation only
  # accept True/False through the CLI.
  [solver_opts]
  # sslsolver =            # bool
  # semicoarsening =       # bool
  # linerelaxation =       # bool
  # cycle =                # string
  # tol =                  # float
  # tol_gradient =         # float
  # verb =                 # int
  # maxit =                # int
  # nu_init =              # int
  # nu_pre =               # int
  # nu_coarse =            # int
  # nu_post =              # int
  # clevel =               # int
  # plain =                # bool

  # Gridding options
  # ----------------
  # Input parameters for the automatic gridding.
  # See the description of `gridding_opts` and link therein in
  # https://emg3d.emsig.xyz/en/stable/api/emg3d.simulations.Simulation.html
  # for more details.
  #
  # List of lists: lists are comma-separated values, lists are separated by
  # semi-colons.
  #
  # One of the limitation of the CLI is that `vector` has to be a string.
  [gridding_opts]
  # properties =          # list, e.g.: 0.3, 1, 1e5
  # center =              # list, e.g.: 0, 0, 0
  # cell_number =         # list, e.g.: 8, 16, 32, 64, 128
  # min_width_pps =       # list, e.g.: 5, 3, 3
  # domain =              # list of lists, e.g.: -10000, 10000; None; None
  # distance =            # list of lists, e.g., None; None; -10000, 10000
  # stretching =          # list of lists, e.g.: None; None; 1.05, 1.5
  # min_width_limits =    # list of lists, e.g.: 10, 100; None; 50
  # mapping =             # string, e.g.: Resistivity
  # vector =              # string, e.g.: xy
  # frequency =           # float, e.g.: 1.0
  # seasurface =          # float, e.g.: 0.0
  # max_buffer =          # float, e.g.: 100000.0
  # lambda_factor =       # float, e.g.: 1.0
  # verb =                # int, e.g.: 0
  # lambda_from_center =  # bool, e.g.: False
```

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

### Install python3-setuptools on Debian/Ubuntu

Source: https://emg3d.emsig.xyz/en/stable/_sources/dev/release.rst.txt

Installs the python3-setuptools package, which may be required if the conda skeleton build fails.

```bash
sudo apt install python3-setuptools
```

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

### Install emg3d with all optional dependencies via pip

Source: https://emg3d.emsig.xyz/en/stable/_sources/manual/installation.rst.txt

Use this command to install emg3d with all optional dependencies from PyPI using the 'full' extra. This provides the complete experience.

```console
pip install emg3d[full]
```

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

### Install emg3d in editable mode

Source: https://emg3d.emsig.xyz/en/stable/_sources/dev/tests.rst.txt

Installs the current branch in editable mode using the Makefile.

```console
make install
```

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

### Install emg3d via pip

Source: https://emg3d.emsig.xyz/en/stable/_sources/manual/installation.rst.txt

Use this command to install emg3d from PyPI using pip. It installs the core package and its required dependencies.

```console
pip install emg3d
```

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

### Install emg3d via conda

Source: https://emg3d.emsig.xyz/en/stable/_sources/manual/installation.rst.txt

Use this command to install emg3d from the conda-forge channel. It installs the core package and its required dependencies.

```console
conda install -c conda-forge emg3d
```

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

### Check README rendering with rst2html

Source: https://emg3d.emsig.xyz/en/stable/_sources/dev/release.rst.txt

Use this command to verify the README long description renders correctly as HTML. It pipes the output of setup.py to rst2html and writes to index.html.

```bash
python setup.py --long-description | rst2html.py --no-raw > index.html
```

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

### Build documentation

Source: https://emg3d.emsig.xyz/en/stable/_sources/dev/tests.rst.txt

Builds the HTML documentation using Sphinx.

```console
make html
```

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

### Inspect documentation build environment with emg3d.Report

Source: https://emg3d.emsig.xyz/en/stable/dev/maintenance.html

Use this snippet to check the versions of key packages in the environment where the documentation was built. It prints a formatted report with OS, CPU, memory, and package versions. The output shows the expected format and the versions as of the report date.

```python
In [1]: import emg3d
   ...: emg3d.Report([
   ...:     "ipympl",
   ...:     "sphinx",
   ...:     "numpydoc",
   ...:     "ipykernel",
   ...:     "pickleshare",
   ...:     "sphinx_design",
   ...:     "sphinx_numfig",
   ...:     "sphinx_automodapi",
   ...:     "pydata_sphinx_theme",
   ...: ])
   ...: 
Out[1]: 

--------------------------------------------------------------------------------
  Date: Sat Mar 28 12:51:45 2026 UTC

                 OS : Linux (Ubuntu 22.04)
             CPU(s) : 2
            Machine : x86_64
       Architecture : 64bit
                RAM : 7.6 GiB
        Environment : IPython
        File system : ext4

  Python 3.11.12 (main, May  6 2025, 10:45:53) [GCC 11.4.0]

             ipympl : 0.10.0
             sphinx : 9.0.4
           numpydoc : 1.10.0
          ipykernel : 7.2.0
        pickleshare : 0.7.5
      sphinx_design : 0.7.0
      sphinx_numfig : 0.1.1
  sphinx_automodapi : 0.22.0
pydata_sphinx_theme : 0.16.1
              numpy : 2.4.3
              scipy : 1.17.1
              numba : 0.64.0
              emg3d : 1.9.1
            empymod : 2.6.0
             xarray : 2026.2.0
         discretize : 0.12.0
               h5py : 3.16.0
         matplotlib : 3.10.8
               tqdm : 4.67.3
            IPython : 9.1.1

--------------------------------------------------------------------------------
```

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

### Check documentation build environment with emg3d.Report

Source: https://emg3d.emsig.xyz/en/stable/_sources/dev/maintenance.rst.txt

Use this IPython snippet to inspect the environment in which the documentation was built. It imports emg3d and calls emg3d.Report with a list of package names to verify their presence. This is useful for ensuring the documentation build environment matches expectations.

```ipython
In [1]: import emg3d
   ...: emg3d.Report([
   ...:     "ipympl",
   ...:     "sphinx",
   ...:     "numpydoc",
   ...:     "ipykernel",
   ...:     "pickleshare",
   ...:     "sphinx_design",
   ...:     "sphinx_numfig",
   ...:     "sphinx_automodapi",
   ...:     "pydata_sphinx_theme",
   ...: ])
```

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

### Imports and setup for Cholesky solver benchmark

Source: https://emg3d.emsig.xyz/en/stable/dev/tests.html

Imports numba, numpy, scipy, and the LAPACK functions. Defines a numba setting dictionary used by the solver. This is the setup for the Cholesky solver benchmark.

```python
In [6]: import numba as nb
   ...: import numpy as np
   ...: import scipy as sp
   ...: from numpy.testing import assert_allclose
   ...: from scipy.linalg.lapack import get_lapack_funcs
   ...: 
   ...: _numba_setting = {'nogil': True, 'fastmath': True, 'cache': True}
   ...: 

```

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

### Build documentation

Source: https://emg3d.emsig.xyz/en/stable/dev/tests.html

Builds the HTML documentation using Sphinx via the Makefile.

```makefile
make html

```

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

### Install emg3d with all optional dependencies via conda

Source: https://emg3d.emsig.xyz/en/stable/_sources/manual/installation.rst.txt

Use this command to install emg3d along with all optional dependencies (discretize, xarray, matplotlib, ipympl, h5py, tqdm) from conda-forge. This provides the complete experience.

```console
conda install -c conda-forge emg3d discretize xarray matplotlib ipympl h5py tqdm
```

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

### Example: Solve for electric field with emg3d.solve

Source: https://emg3d.emsig.xyz/en/stable/_modules/emg3d/solver.html

Shows how to create a grid, model, source field, and solve for the electric field using emg3d.solve with plain=True and verb=4.

```python
In [1]: import emg3d
   ...: import numpy as np

In [2]: # Create a simple grid, 8 cells of length 1 in each direction,
   ...: # starting at the origin.
   ...: hx = np.ones(8)
   ...: grid = emg3d.TensorMesh([hx, hx, hx], origin=(0, 0, 0))

In [3]: # Create a fullspace model with triaxial anisotropy.
   ...: model = emg3d.Model(grid, property_x=1.5, property_y=1.8,
   ...:                     property_z=3.3, mapping='Resistivity')

In [4]: # The source is a x-directed, horizontal dipole at (4, 4, 4)
   ...: # with a frequency of 10 Hz.
   ...: coo = (4, 4, 4, 0, 0)  # (x, y, z, azimuth, elevation)
   ...: sfield = emg3d.fields.get_source_field(
   ...:             grid, source=coo, frequency=10)

In [5]: # Solve for the electric field.
   ...: efield = emg3d.solve(model, sfield, plain=True, verb=4)
```

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

### Field.frequency property

Source: https://emg3d.emsig.xyz/en/stable/_modules/emg3d/fields.html

Property to get the frequency in Hz.

```APIDOC
## Field.frequency

### Description
Gets the frequency in Hz.

### Method
N/A (Python property)

### Endpoint
N/A

### Parameters
None

### Request Example
N/A

### Response
#### Success Response
- **frequency** (float or None) - The frequency in Hz, or None if not set.

#### Response Example
```json
1000.0
```
```

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

### Field.fz property

Source: https://emg3d.emsig.xyz/en/stable/_modules/emg3d/fields.html

Property to get or set the field component in the z-direction.

```APIDOC
## Field.fz

### Description
Gets or sets the field component in the z-direction.

### Method
N/A (Python property)

### Endpoint
N/A

### Parameters
#### Parameters (setter)
- **fz** (array) - Required - The new field values in z-direction.

### Request Example
N/A

### Response
#### Success Response (getter)
- **fz** (array) - The field component in z-direction with shape depending on electric/magnetic.

#### Response Example
```json
[[0.1, 0.2], [0.3, 0.4]]
```
```

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

### emg3d --help

Source: https://emg3d.emsig.xyz/en/stable/_sources/manual/cli.rst.txt

Displays the inbuilt help for the emg3d command-line interface.

```console
emg3d --help
```
Tokens:
Raw