solve¶
- emg3d.solver.solve(model, sfield, sslsolver=True, semicoarsening=True, linerelaxation=True, verb=0, **kwargs)[source]¶
Solver for three-dimensional electromagnetic diffusion.
The principal solver of emg3d is using the multigrid method as presented in [Muld06]. Multigrid can be used as a standalone solver, or as a preconditioner for an iterative solver from the
scipy.sparse.linalg
-library, e.g.,scipy.sparse.linalg.bicgstab
. Alternatively, these Krylov subspace solvers can also be used without multigrid at all (see thecycle
andsslsolver
parameters).Implemented are the F-, V-, and W-cycle schemes for multigrid (
cycle
parameter), and the amount of smoothing steps (initial smoothing, pre-smoothing, coarsest-grid smoothing, and post-smoothing) can be set individually (nu_init
,nu_pre
,nu_coarse
, andnu_post
, respectively). The maximum level of coarsening can be restricted with theclevel
parameter.Semicoarsening and line relaxation, as presented in [Muld07], are implemented, see the
semicoarsening
andlinerelaxation
parameters. Using the BiCGSTAB solver together with multigrid preconditioning, semicoarsening, and line relaxation is generally the most robust solution, albeit not necessarily the fastest. It is the default setting for its robustness. Just using traditional multigrid without BiCGSTAB nor semicoarsening nor line relaxation uses the least memory and is often faster but may fail on stretched grids or for models with strong anisotropy. However, only testing the parameters for a given model can give certainty to which parameters are best.- Parameters
- modelModel
The model; a
emg3d.models.Model
instance.- sfieldField
The source field. See
emg3d.fields.get_source_field
.- sslsolver{str, bool}, default: True
A
scipy.sparse.linalg
-solver, to use with multigrid as pre-conditioner or on its own (ifcycle=None
).Current possibilities:
True
or'bicgstab'
: BiConjugate Gradient STABilized (scipy.sparse.linalg.bicgstab
).'cgs'
: Conjugate Gradient Squared (scipy.sparse.linalg.cgs
).'gcrotmk'
: GCROT: Generalized Conjugate Residual with inner Orthogonalization and Outer Truncation (scipy.sparse.linalg.gcrotmk
).
It does currently not work with
'cg'
,'bicg'
,'qmr'
, and'minres'
for various reasons (e.g., some requirermatvec
in addition tomatvec
).- semicoarsening{int, bool}, default: True
Semicoarsening.
True
: Cycling over 1, 2, 3.0
orFalse
: No semicoarsening.1
: Semicoarsening in x direction.2
: Semicoarsening in y direction.3
: Semicoarsening in z direction.Multi-digit number containing digits from 0 to 3. Multigrid will cycle over these values, e.g.,
semicoarsening=1213
will cycle over [1, 2, 1, 3].
- linerelaxation{int, bool}, default: True
Line relaxation.
True
: Cycling over [4, 5, 6].0
orFalse
: No line relaxation.1
: line relaxation in x direction.2
: line relaxation in y direction.3
: line relaxation in z direction.4
: line relaxation in y and z directions.5
: line relaxation in x and z directions.6
: line relaxation in x and y directions.7
: line relaxation in x, y, and z directions.Multi-digit number containing digits from 0 to 7. Multigrid will cycle over these values, e.g.,
linerelaxation=1213
will cycle over [1, 2, 1, 3].
Note: Smoothing is generally done in lexicographical order, except for line relaxation in y direction; the reason is speed (memory access).
- verbint, default: 0
Level of verbosity (the higher the more verbose).
-1
: Nothing.0
: Warnings.1
: One-liner at the end.2
: One-liner, dynamically updated.3
: Information about the method plus dynamic one-liner.4
: Additional information for each MG-cycle.5
: Everything (slower due to additional error computations).
- cycle{str, None}, default: ‘F’
Type of multigrid cycle.
'V'
: V-cycle, simplest version.'W'
: W-cycle, most expensive version.'F'
: F-cycle, sort of a compromise between V- and W-cycle.None
: Does not use multigrid, only the chosensslsolver
.
A
sslsolver
has to be provided ifcycle=None
, and thesslsolver
will then be used without multigrid pre-conditioning.Comparison of V (left), F (middle), and W (right) cycles for the case of four grids (three relaxation and prolongation steps):
h_ 2h_ \ / \ / \ / 4h_ \ / \ /\ / \ /\ / 8h_ \/ \/\/ \/ \/\/ \/\/
- efieldField, default: None
Initial electric field. If is initiated with zeroes if not provided.
If an initial efield is provided nothing is returned, but the final efield is directly put into the provided efield.
If an initial field is provided and a sslsolver is used, then it first carries out one multigrid cycle without semicoarsening nor line relaxation. The sslsolver is at times unstable with an initial guess, carrying out one multigrid cycle helps to stabilize it.
Note that the tangential field at the boundary of a provided efield is set to zero to ensure a PEC boundary (perfect electric conductor).
- tolfloat, default: 1e-6
Convergence tolerance.
Iterations stop as soon as the norm of the residual has decreased by this factor, relative to the residual norm obtained for a zero electric field.
- maxitint, default: 50
Maximum number of multigrid iterations.
If
sslsolver
is used, this applies to thesslsolver
.In the case that multigrid is used as a pre-conditioner for the
sslsolver
, the maximum iteration for multigrid is defined by the maximum length of thelinerelaxation
andsemicoarsening
-cycles.- nu_initint, default: 0
Number of initial smoothing steps, before multigrid cycle.
- nu_preint, default: 2
Number of pre-smoothing steps.
- nu_coarseint, default: 1
Number of smoothing steps on coarsest grid.
- nu_postint, default: 2
Number of post-smoothing steps.
- clevelint, default: -1
The maximum coarsening level can be different for each dimension and is, by default, automatically determined (
clevel=-1
). The parameterclevel
restricts the maximum coarsening level by its value.- return_infobool, default: False
If True, a dictionary is returned with runtime info (final norm, number of iterations of multigrid and the sslsolver, log, exit message, etc).
- logint, default: 1
Only relevant if
return_info=True
.-1
: LOG ONLY: Only store info in log, do not print on screen.0
: SCREEN only: Only print info to screen, do not store in log.1
: BOTH: Store info in log and print on screen.
- plainbool, default: False
Plain multigrid method. This is a shortcut for
sslsolver=False, semicoarsening=False, linerelaxation=False
. The three parameters remain unchanged if they are set to anything else thanTrue
.
- Returns
- efieldField, returned if efield=None
Resulting electric field. It is not returned but stored in-place if an initial efield was provided.
- info_dictdict, returned if return_info=True
Dictionary with solver info. Keys:
exit
: Exit status, 0=Success, 1=Failure;exit_message
: Exit message, check this ifexit=1
;abs_error
: Absolute error;rel_error
: Relative error;ref_error
: Reference error [norm(sfield)];tol
: Tolerance (abs_error<ref_error*tol);it_mg
: Number of multigrid iterations;it_ssl
: Number of SSL iterations;time
: Runtime (s).runtime_at_cycle
: Runtime after each cycle (s).error_at_cycle
: Absolute error after each cycle.log
: Stored log.
Examples
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) ...: :: emg3d START :: 08:24:57 :: v1.2.0 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_ \/\/ [08:25:09] 2.284e-02 after 1 F-cycles [1.275e-06, 0.023] 0 0 [08:25:09] 1.565e-03 after 2 F-cycles [8.739e-08, 0.069] 0 0 [08:25:09] 1.295e-04 after 3 F-cycles [7.232e-09, 0.083] 0 0 [08:25:09] 1.197e-05 after 4 F-cycles [6.685e-10, 0.092] 0 0 [08:25:09] 1.233e-06 after 5 F-cycles [6.886e-11, 0.103] 0 0 [08:25:09] 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 :: 08:25:09 :: runtime = 0:00:12