### 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
```

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

### 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)
```

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

### 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}
   ...: 

```

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

### 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
```

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

### 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
```

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

### Custom map registration example

Source: https://emg3d.emsig.xyz/en/stable/api/emg3d.maps.BaseMap.html

Shows how to define a custom map by subclassing BaseMap, implementing forward, backward, and derivative_chain, and registering it with the @emg3d.maps.register_map decorator so it can be loaded via emg3d.io.load.

```python
@emg3d.maps.register_map
class MapProperty(emg3d.maps.BaseMap):
    '''Description'''
    def __init__(self):
        super().__init__('property')

    def forward(self, conductivity):
        return # Mapping from your property to conductivity.

    def backward(self, mapped):
        return # Mapping from conductivity to your property.

    def derivative_chain(self, gradient, mapped):
        gradient *= # Chain rule of your backward mapping.
```

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

### Load data with emg3d.load and inspect keys

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

Loads a saved file into a dictionary. The returned dict contains the user-defined keys plus private keys like '_date', '_format', '_version'. The example shows the resulting keys.

```ipython
In [1]: data = emg3d.load('/path/to/filename.ending')
  Out[1]: Data loaded from «/path/to/filename.ending»

  In [2]: data.keys()
  Out[2]: dict_keys(['_date', '_format', '_version', 'efield', 'inp_model', 'out_model', 'survey'])
```

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

### Clone the emg3d repository

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

Clones the emg3d GitHub repository locally to start development.

```console
git clone git@github.com:emsig/emg3d.git
```

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

### emg3d.solver.solve_source shortcut

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

Shows the equivalent two-step process that solve_source wraps: first get the source field, then solve for the electric field. Use this when you need to understand what the shortcut does internally.

```python
sfield = emg3d.get_source_field(grid, source, frequency, **kwargs)
efield = emg3d.solve(model, sfield, **kwargs)
```

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

### Create a grid and an electric dipole source

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

This example creates a simple 8x8x8 grid with 100 m cells centered around the origin, and then creates an electric dipole source from (0,0,0) to (100,0,0) with a strength of 100 A. The grid and source are displayed for quality control.

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

In [2]: # Create a simple grid, 8 cells of length 100 m in each
   ...: # direction, centered around the origin.
   ...: hx = np.ones(8)*100
   ...: grid = emg3d.TensorMesh([hx, hx, hx], origin=(-400, -400, -400))
   ...: grid  # For QC
   ...: 
Out[2]: 

  TensorMesh: 512 cells

                      MESH EXTENT             CELL WIDTH      FACTOR
  dir    nC        min           max         min       max      max
  ---   ---  ---------------------------  ------------------  ------
   x      8       -400.00        400.00    100.00    100.00    1.00
   y      8       -400.00        400.00    100.00    100.00    1.00
   z      8       -400.00        400.00    100.00    100.00    1.00


In [3]: # Create an electric dipole source from
   ...: # x1=y1=z1=0 to x2=100, y2=z2=0; strength=100 A.
   ...: source = emg3d.TxElectricDipole(
   ...:             [[0, 0, 0], [100, 0, 0]], strength=100)
   ...: source  # For QC
   ...: 
Out[3]: 
TxElectricDipole: 100.0 A;
    e1={0.0; 0.0; 0.0} m; e2={100.0; 0.0; 0.0} m
```

```python
In [4]: # Get the corresponding source field for f=0.5 Hz.
   ...: sfield = emg3d.get_source_field(grid, source, frequency=0.5)
   ...: sfield  # For QC
   ...: 
Out[4]: Field: electric; 8 x 8 x 8; 1,944
```

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

### Create a simple grid with BaseMesh

Source: https://emg3d.emsig.xyz/en/stable/api/emg3d.meshes.BaseMesh.html

Shows how to create a BaseMesh with 8 cells of length 100 m in each direction, centered around the origin. The example uses numpy and emg3d, and the output is a TensorMesh of size 8x8x8 (512 cells).

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

In [2]: # Create a simple grid, 8 cells of length 100 m in each
   ...: # direction, centered around the origin.
   ...: hx = np.ones(8)*100
   ...: grid = emg3d.meshes.BaseMesh(
   ...:            [hx, hx, hx], origin=(-400, -400, -400))
   ...: grid  # QC grid
   ...: 
Out[2]: TensorMesh: 8 x 8 x 8 (512)
```

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

### origin_and_widths(frequency, properties, center, domain=None, vector=None, seasurface=None, **kwargs)

Source: https://emg3d.emsig.xyz/en/stable/api/emg3d.meshes.origin_and_widths.html

Calculates and returns the starting point (origin) and cell widths for a mesh given the input parameters. The output can be used as input for one dimension to create a TensorMesh.

```APIDOC
## [FUNCTION] origin_and_widths(frequency, properties, center, domain=None, vector=None, seasurface=None, **kwargs)

### Description
Calculates and returns the starting point (origin) and cell widths for a mesh given the input parameters. The output can be used as input for one dimension to create a TensorMesh. This function is used by `construct_mesh` once in each direction.

### Method
FUNCTION

### Endpoint
origin_and_widths(frequency, properties, center, domain=None, vector=None, seasurface=None, **kwargs)

### Parameters
#### Path Parameters
- **frequency** (float) - Required - Frequency for the mesh calculation.
- **properties** (dict) - Required - Properties for the mesh calculation.
- **center** (float) - Required - Center of the mesh.
- **domain** (float, optional) - Optional - Domain size.
- **vector** (ndarray, optional) - Optional - Vector for mesh generation.
- **seasurface** (float, optional) - Optional - Sea surface elevation.
- **kwargs** (dict) - Optional - Additional keyword arguments.

#### Query Parameters
- **verb** (int, default: 0) - Optional - If 1 verbose, if 0 silent, if -1 it returns the info as string instead of printing it.
- **raise_error** (bool, default: True) - Optional - If True, an error is raised if no suitable grid is found. Otherwise it just returns None's (used by `construct_mesh`).

### Request Example
```python
origin, widths = origin_and_widths(frequency, properties, center, domain, vector, seasurface, verb=0, raise_error=True)
```

### Response
#### Success Response (200)
- **origin** (float) - Origin of the mesh.
- **widths** (ndarray) - Cell widths of mesh.
- **info** (str) - Info, returned if verb<0.

#### Response Example
```python
(origin, widths, info)
```

### Error Handling
- If `raise_error` is True and no suitable grid is found, an error is raised.
- If `raise_error` is False, returns None's for origin and widths.
```

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

### Solve for electric field with emg3d.solve

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

This example creates a simple 8x8x8 tensor mesh, defines a fullspace model with triaxial anisotropy (property_x=1.5, property_y=1.8, property_z=3.3), sets up a horizontal electric dipole source at (4,4,4) with a frequency of 10 Hz, and solves for the electric field using emg3d.solve with plain=True and verb=4. The solver output shows convergence after 6 F-cycles with a final relative error of 1.415e-07.

```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)
   ...: 
```

```text
:: emg3d START :: 12:51:37 :: v1.9.1

   MG-cycle       : 'F'                 sslsolver : False
   semicoarsening : False [0]           tol       : 1e-06
   linerelaxation : False [0]           maxit     : 50
   nu_{i,1,c,2}   : 0, 2, 1, 2          verb      : 4
   Original grid  :   8 x   8 x   8     => 512 cells
   Coarsest grid  :   2 x   2 x   2     => 8 cells
   Coarsest level :   2 ;   2 ;   2     :: Grid not optimal for MG solver ::

   [hh:mm:ss]  rel. error                  [abs. error, last/prev]   l s

       h_
      2h_ \    /
      4h_  \/\/ 

   [12:51:44]   2.284e-02  after   1 F-cycles   [1.275e-06, 0.023]   0 0
   [12:51:44]   1.565e-03  after   2 F-cycles   [8.739e-08, 0.069]   0 0
   [12:51:44]   1.295e-04  after   3 F-cycles   [7.232e-09, 0.083]   0 0
   [12:51:44]   1.197e-05  after   4 F-cycles   [6.685e-10, 0.092]   0 0
   [12:51:44]   1.233e-06  after   5 F-cycles   [6.886e-11, 0.103]   0 0
   [12:51:44]   1.415e-07  after   6 F-cycles   [7.899e-12, 0.115]   0 0

   > CONVERGED
   > MG cycles        : 6
   > Final rel. error : 1.415e-07

:: emg3d END   :: 12:51:44 :: runtime = 0:00:07

```

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

### emg3d.meshes.skin_depth

Source: https://emg3d.emsig.xyz/en/stable/api/emg3d.meshes.skin_depth.html

Documentation for the emg3d.meshes.skin_depth function, including its parameters, return value, and usage example.

```APIDOC
## emg3d.meshes.skin_depth

### Description
Returns the skin depth in meters as a function of frequency and conductivity. The skin depth is calculated using the formula δ = sqrt(2 / (ω * σ * μ)), where ω = 2πf is the angular frequency, σ is the conductivity, and μ is the magnetic permeability (μ = μ0 * μr).

### Signature
`emg3d.meshes.skin_depth(frequency, conductivity, mu_r=1.0)`

### Parameters
- **frequency** (float) - Required - Frequency in Hz.
- **conductivity** (float) - Required - Conductivity in S/m.
- **mu_r** (float, optional) - Default: 1.0 - Relative magnetic permeability (dimensionless).

### Returns
- **skindepth** (float) - Skin depth in meters.

### Example
```python
import emg3d
# Compute skin depth at 100 Hz in a medium with conductivity 0.01 S/m
skin_depth = emg3d.meshes.skin_depth(100, 0.01)
print(skin_depth)
```
```

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

### Create electric dipole sources with txrx_coordinates_to_dict

Source: https://emg3d.emsig.xyz/en/stable/api/emg3d.surveys.txrx_coordinates_to_dict.html

Example usage of emg3d.surveys.txrx_coordinates_to_dict to create five electric dipole sources at offsets from 2000 to 10000 meters with a strength of 100 A. The output shows the resulting dictionary of TxElectricDipole instances.

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

In [2]: # Create 10 electric dipole sources from x=2000:2000:10,000, of
   ...: # strength 100 A.
   ...: offsets = np.arange(1, 6)*2000
   ...: sources = emg3d.surveys.txrx_coordinates_to_dict(
   ...:                 emg3d.TxElectricDipole,
   ...:                 (offsets, 0, 0, 0, 0), strength=100)
   ...: sources  # QC the source dict
   ...: 
Out[2]: 
{'TxED-1': TxElectricDipole: 100.0 A;
     center={2,000.0; 0.0; 0.0} m; θ=0.0°, φ=0.0°; l=1.0 m,
 'TxED-2': TxElectricDipole: 100.0 A;
     center={4,000.0; 0.0; 0.0} m; θ=0.0°, φ=0.0°; l=1.0 m,
 'TxED-3': TxElectricDipole: 100.0 A;
     center={6,000.0; 0.0; 0.0} m; θ=0.0°, φ=0.0°; l=1.0 m,
 'TxED-4': TxElectricDipole: 100.0 A;
     center={8,000.0; 0.0; 0.0} m; θ=0.0°, φ=0.0°; l=1.0 m,
 'TxED-5': TxElectricDipole: 100.0 A;
     center={10,000.0; 0.0; 0.0} m; θ=0.0°, φ=0.0°; l=1.0 m}
```

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

### Monkey-patch Simulation.misfit with custom misfit function

Source: https://emg3d.emsig.xyz/en/stable/api/emg3d.simulations.Simulation.html

Shows how to replace the default misfit property with a custom implementation by monkey-patching the Simulation class. The example defines a property function that computes the misfit, patches it onto the class, then demonstrates usage with a Simulation instance. The comment notes that the custom misfit will also be used for the adjoint-state gradient.

```python
@property  # misfit is a property
def my_misfit_function(self):
    '''Returns the misfit as a float.'''

    if self._misfit is None:
        self.compute()  # Ensures fields are computed.

        # Computing your misfit...
        self._misfit = your misfit

    return self._misfit

# Monkey patch simulation.misfit:
emg3d.simulation.Simulation.misfit = my_misfit_function

# And now all the regular stuff, initiate a Simulation etc
simulation = emg3d.Simulation(survey, grid, model)
simulation.misfit
# => will return your misfit
#   (will also be used for the adjoint-state gradient).
```

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

### 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",
   ...: ])
```

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

### Build documentation

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

Builds the HTML documentation using Sphinx via the Makefile.

```makefile
make html

```

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

### 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
```
```

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

### 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
```

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

### 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]]
```
```

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

### Field.fy property

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

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

```APIDOC
## Field.fy

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

### Method
N/A (Python property)

### Endpoint
N/A

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

### Request Example
N/A

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

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

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

### Field.fx property

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

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

```APIDOC
## Field.fx

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

### Method
N/A (Python property)

### Endpoint
N/A

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

### Request Example
N/A

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

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

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

### emg3d.surveys.txrx_coordinates_to_dict

Source: https://emg3d.emsig.xyz/en/stable/api/emg3d.surveys.txrx_coordinates_to_dict.html

Documentation for the emg3d.surveys.txrx_coordinates_to_dict function, including its signature, parameters, return value, and an example.

```APIDOC
## emg3d.surveys.txrx_coordinates_to_dict

### Description
Creates a dictionary of TxRx instances (sources or receivers) from provided coordinates. This helper function is used to generate source and receiver dictionaries for input into a `emg3d.surveys.Survey`.

### Signature
`emg3d.surveys.txrx_coordinates_to_dict(TxRx, coordinates, **kwargs)`

### Parameters
- **TxRx** (class) - Required - Any of the available sources or receivers, e.g., `emg3d.electrodes.TxElectricDipole`.
- **coordinates** (tuple) - Required - Tuple containing the input coordinates for the defined TxRx class. Each element of the tuple must either have length `1` or `n`.
- **kwargs** - Optional - Other parameters passed through to TxRx; again, each must be of size `1` or `n`.

### Returns
- **out** (dict) - Dict where the keys consist of a TxRx-prefix followed by a number, and the values contain the corresponding TxRx instances.

### Example
```python
import emg3d
import numpy as np

# Create 10 electric dipole sources from x=2000:2000:10,000, of
# strength 100 A.
offsets = np.arange(1, 6)*2000
sources = emg3d.surveys.txrx_coordinates_to_dict(
                emg3d.TxElectricDipole,
                (offsets, 0, 0, 0, 0), strength=100)
sources  # QC the source dict
```

Output:
```
{'TxED-1': TxElectricDipole: 100.0 A;
     center={2,000.0; 0.0; 0.0} m; θ=0.0°, φ=0.0°; l=1.0 m,
 'TxED-2': TxElectricDipole: 100.0 A;
     center={4,000.0; 0.0; 0.0} m; θ=0.0°, φ=0.0°; l=1.0 m,
 'TxED-3': TxElectricDipole: 100.0 A;
     center={6,000.0; 0.0; 0.0} m; θ=0.0°, φ=0.0°; l=1.0 m,
 'TxED-4': TxElectricDipole: 100.0 A;
     center={8,000.0; 0.0; 0.0} m; θ=0.0°, φ=0.0°; l=1.0 m,
 'TxED-5': TxElectricDipole: 100.0 A;
     center={10,000.0; 0.0; 0.0} m; θ=0.0°, φ=0.0°; l=1.0 m}
```
```

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

### Model constructor

Source: https://emg3d.emsig.xyz/en/stable/api/emg3d.models.Model.html

Creates a new Model instance with specified grid, electrical properties, and optional magnetic/permittivity parameters.

```APIDOC
## Model Constructor

### Description
Initializes a Model object with the given grid and material properties.

### Parameters
- **grid** (TensorMesh) - Required - The grid; a `emg3d.meshes.TensorMesh` instance.
- **property_x** (array_like, default: 1.0) - Optional - Electrical material property in x-direction. Must be broadcastable to `grid.shape`.
- **property_y** (array_like, default: None) - Optional - Electrical material property in y-direction. Must be broadcastable to `grid.shape`.
- **property_z** (array_like, default: None) - Optional - Electrical material property in z-direction. Must be broadcastable to `grid.shape`.
- **mu_r** (array_like, default: None) - Optional - Relative magnetic permeability. Must be broadcastable to `grid.shape`.
- **epsilon_r** (array_like, default: None) - Optional - Relative electric permittivity. Must be broadcastable to `grid.shape`.
- **mapping** (str, default: 'Resistivity') - Optional - Defines the type of electrical input. One of: 'Resistivity', 'Conductivity', 'LgResistivity', 'LgConductivity', 'LnResistivity', 'LnConductivity'.

### Notes
- Properties must be finite and > 0 on linear scale.
- Supports isotropic, VTI, HTI, and triaxial anisotropy.
- If a property is not initiated, it cannot be set later.
- Default mu_r = 1, epsilon_r = 0 (diffusive approximation).
```

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

### Report

Source: https://emg3d.emsig.xyz/en/stable/api/emg3d.utils.Report.html

Creates a Report instance to display system and package version information. Use this to generate a report in notebooks or consoles.

```APIDOC
## Report

### Description
Print date, time, and version information using scooby. Shows OS, CPU count, and versions of numpy, scipy, emg3d, numba, Python, and optionally IPython, matplotlib, and other soft dependencies. Also shows MKL information if available.

### Method
Constructor

### Endpoint
Report(add_pckg=None, ncol=3, text_width=80, sort=False)

### Parameters
#### Constructor Parameters
- **add_pckg** (package or str) - Optional - Package or list of packages to add to output information (must be imported beforehand or provided as string).
- **ncol** (int) - Optional - Number of package-columns in html table (no effect in text-version). Default: 3.
- **text_width** (int) - Optional - The text width for non-HTML display modes. Default: 80.
- **sort** (bool) - Optional - Sort the packages when the report is shown. Default: False.

### Request Example
```python
from emg3d.utils import Report
report = Report(add_pckg=['my_package'], ncol=4, text_width=100, sort=True)
```

### Response
#### Success Response
- **report** (Report) - A Report instance that when displayed (e.g., in a notebook or console) prints the version information.

#### Response Example
```python
report  # In Jupyter, this displays an HTML table; in console, plain text.
```
```

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

### Field.smu0 property

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

Property to get s*mu_0, where mu_0 is the magnetic permeability of free space.

```APIDOC
## Field.smu0

### Description
Gets s*mu_0, where mu_0 is the magnetic permeability of free space.

### Method
N/A (Python property)

### Endpoint
N/A

### Parameters
None

### Request Example
N/A

### Response
#### Success Response
- **smu0** (float or None) - The product of s and mu_0, or None if not available.

#### Response Example
```json
1.2566370614359173e-06
```
```

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

### List all Makefile targets

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

Displays all available Makefile targets.

```console
make
```

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

### Field.sval property

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

Property to get the Laplace parameter s (s=iw in frequency domain, s=f in Laplace domain).

```APIDOC
## Field.sval

### Description
Gets the Laplace parameter s.

### Method
N/A (Python property)

### Endpoint
N/A

### Parameters
None

### Request Example
N/A

### Response
#### Success Response
- **sval** (complex or None) - The Laplace parameter, or None if not set.

#### Response Example
```json
(0+6283.185307179586j)
```
```

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

### List all Makefile targets

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

Displays all available Makefile targets.

```makefile
make

```

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

### Field.field property

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

Property to get or set the entire field as a 1D array [fx, fy, fz].

```APIDOC
## Field.field

### Description
Gets or sets the entire field as a 1D array [fx, fy, fz].

### Method
N/A (Python property)

### Endpoint
N/A

### Parameters
#### Parameters (setter)
- **field** (array) - Required - The new field values as a 1D array.

### Request Example
N/A

### Response
#### Success Response (getter)
- **field** (array) - The field data as a 1D array.

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

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

### standard_deviation

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

Property that gets or sets the standard deviation of the data. When set, it validates that all values are positive. When not set, it computes the standard deviation from noise_floor and relative_error if provided.

```APIDOC
## Property: standard_deviation

### Description
Gets or sets the standard deviation of the data. When set, it validates that all values are positive. When not set, it computes the standard deviation from noise_floor and relative_error if provided.

### Getter
Returns the standard deviation array if set, otherwise computes it from noise_floor and relative_error. Returns None if neither is set.

### Setter
Sets the standard deviation. The value must be an array of positive numbers with shape (nsrc, nrec, nfreq) or broadcastable to that shape.

### Raises
- **ValueError** - If any value in the provided standard deviation is less than or equal to zero.
```

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

### Simulation.from_file

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

Loads a Simulation from a file. Returns the simulation instance and optionally an info string if verbosity is negative.

```APIDOC
## Simulation.from_file

### Description
Loads a Simulation from a file. Returns the simulation instance and optionally an info string if verbosity is negative.

### Method
Not applicable (Python classmethod)

### Endpoint
Not applicable (Python classmethod)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **fname** (str) - Required - Absolute or relative file name including extension.
- **name** (str) - Optional - Name under which the simulation is stored within the file. Default: 'simulation'.
- **kwargs** (keyword arguments) - Optional - Passed through to :func:`io.load`.

### Request Example
```python
sim = Simulation.from_file('sim.h5', name='simulation')
```

### Response
#### Success Response (200)
- **simulation** (Simulation) - A :class:`emg3d.simulations.Simulation` instance.
- **info** (str) - Returned if verb<0, containing info-string.

#### Response Example
```python
sim = Simulation.from_file('sim.h5', name='simulation', verb=-1)
# sim is a Simulation instance, and info is a string
```
```

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

### Check README long description

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

Command to verify the README renders correctly by generating the long description and converting to HTML. Useful before a release to ensure the README is valid.

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

```

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

### Load Survey from file with from_file

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

Loads a Survey instance from disk using the from_file class method.

```ipython
In [1]: my_survey = emg3d.Survey.from_file('mydata.h5')
```