Merge pull request #1224 from cmorency1/devel

added a reference to EM paper Morency gji 2020

doc/USER_MANUAL/04_running_the_solver.tex

@@ -373,9 +373,9 @@ \section{How to run poroelastic wave simulations}
 Check the following new inputs in \texttt{Par\_file}:
 %
 \begin{description}[style=nextline, labelindent=1em, font=\normalfont]
-\item[In section \textbf{"\# geometry of model and mesh description"}:]
-\texttt{TURN\_VISCATTENUATION\_ON}, \texttt{Q0}, and \texttt{FREQ0} deal with viscous damping in a poroelastic medium.
-\texttt{Q0} is the quality factor set at the central frequency \texttt{FREQ0}. For more details
+\item[In section \textbf{"\# Attenuation"}:]
+\texttt{ATTENUATION\_PORO\_FLUID\_PART}, \texttt{Q0\_poroelastic}, and \texttt{freq0\_poroelastic} deal with viscous damping in a poroelastic medium.
+\texttt{Q0\_poroelastic} is the quality factor set at the central frequency \texttt{freq0\_poroelastic}. For more details
 see \cite{MoTr08}.
 
 \item[In section \textbf{"\# time step parameters"}:]
@@ -412,7 +412,7 @@ \section{How to run poroelastic wave simulations}
 \texttt{SAVE\_FORWARD} determines if the last frame of a forward simulation is saved (\texttt{.true.}) or not (\texttt{.false})
 
 \item[In section \textbf{"\# define models...."}:]
-There are three possible types of models:
+There are three possible types of models for seismic wave propagation:
   \begin{enumerate}[label=\ttfamily \Roman*:]
     \item (\texttt{model\_number 1 rho Vp Vs 0 0 QKappa Qmu 0 0 0 0 0 0}) or
     \item (\texttt{model\_number 2 rho c11 c13 c15 c33 c35 c55 c12 c23 c25 0 0 0}) or
@@ -454,6 +454,71 @@ \section{How to run poroelastic wave simulations}
 several sources with different frequencies and if you consider anistropic
 permeability.
 
+%------------------------------------------------------------------------------------------------%
+\section{How to run electromagnetic wave simulations}
+%------------------------------------------------------------------------------------------------%
+
+For more details on the electromagetic (EM) wave propagation in SPECFEM, please refer to \cite{Morency20}.
+Check the following new inputs in \texttt{Par\_file}:
+%
+\begin{description}[style=nextline, labelindent=1em, font=\normalfont]
+\item[In section \textbf{"\# Attenuation"}:]
+\texttt{ATTENUATION\_PERMITTIVITY}, \texttt{ATTENUATION\_CONDUCTIVITY}, and \texttt{f0\_electromagnetic} deal with dispersive and attenuating EM media.
+For more details see section  2.2 in \cite{Morency20}.
+
+\item[In section \textbf{"\# time step parameters"}:]
+\texttt{SIMULATION\_TYPE} defines the type of simulation
+  \begin{enumerate}[label=(\arabic*)]
+    \item forward simulation
+    \item UNUSED (purposely, for compatibility with the numbering convention used in our 3D codes)
+    \item adjoint method and kernels calculation -- {\bf TO DO}
+  \end{enumerate}
+
+\item[In section \textbf{"\# define models...."}:]
+There are three possible types of models for seismic wave propagation and one for EM wave propagation:
+  \begin{enumerate}[label=\ttfamily \Roman*:]
+    \item (\texttt{model\_number 1 rho Vp Vs 0 0 QKappa Qmu 0 0 0 0 0 0}) or
+    \item (\texttt{model\_number 2 rho c11 c13 c15 c33 c35 c55 c12 c23 c25 0 0 0}) or
+    \item (\texttt{model\_number 3 rhos rhof phi c kxx kxz kzz Ks Kf Kfr etaf mufr Qmu}) or
+    \item (\texttt{model\_number 4 mu0 e0 e11 e33 sig11 sig33 Qe11 Qe33 Qs11 Qs33 0 0 0}).
+  \end{enumerate}
+
+
+
+For isotropic EM material use \texttt{IV}, where
+
+\begin{description}
+\item[{\texttt{mu\_0}}] = magnetic permeability
+\item[{\texttt{e\_0}}] = vacuum dielectric permittivity
+\item[{\texttt{e\_11}}] = xx component of relative dielectric permittivity
+\item[{\texttt{e\_33}}] = zz component of relative dielectric permittivity
+\item[{\texttt{sig\_11}}] = xx component of conductivity
+\item[{\texttt{sig\_33}}] = zz component of conductivity 
+\item[{\texttt{Qe\_11}}] = quality factor of xx component of permittivity
+\item[{\texttt{Qe\_33}}] = quality factor of zz component of permittivity
+\item[{\texttt{Qs\_11}}] = quality factor of xx component of conductivity
+\item[{\texttt{Qs\_33}}] = quality factor of zz component of conductivity
+\end{description}
+
+\end{description}
+
+\texttt{get\_electromagnetic\_velocities.f90} allows to compute the anisotropic EM wavespeeds as a function of
+the source dominant frequency. Notice that for this calculation we use the dominant frequency of the first source, f0(1). Caution if you use
+several sources with different frequencies.
+
+Finally, 2-D transverse electric (TE) mode, more suitable for crosshole and vertical radar profiling applications, and transverse magnetic (TM) mode, suitable for surface based reflection ground penetration radar type of applications, can be handled using the P-SV/SH flag in \texttt{Par\_file}: 
+\begin{description}
+\item[P-SV (EM TE):]
+To run a EM waves calculation propagating in the $x$-$z$ plane,
+set \texttt{p\_sv = .true.}
+
+\item[SH (EM TM):]
+To run EM waves calculation travelling in the $x$-$z$ plane with a
+$y$-component of electric field, set \texttt{p\_sv = .false.}
+\end{description}
+
+
+
 %------------------------------------------------------------------------------------------------%
 \section{Coupled simulations}
 %------------------------------------------------------------------------------------------------%

doc/USER_MANUAL/bibliography.bib

@@ -14025,6 +14025,15 @@ @Article{MoTr08
   Volume                   = {175}
 }
 
+@Article{Morency20,
+  Title                    = {Electromagnetic wave propagation based upon spectral-element methodology in dispersive and attenuating media},
+  Author                   = {C. Morency},
+  Journal                  = gji,
+  Year                     = {2020},
+  Pages                    = {951-966},
+  Volume                   = {220}
+} 
+
 @Article{Morita96,
   Title                    = {The characteristics of {J}-array seismograms},
   Author                   = {Y. Morita},

doc/USER_MANUAL/features.tex

@@ -24,6 +24,7 @@ \chapter*{Simulation features supported in SPECFEM2D}
                 & Acoustic                  & X  & X \\
                 & Elastic                   & X  & X \\
                 & Poroelastic               & X  & - \\
+                & Electromagnetic       & X  & - \\
                 & Anisotropy                & X  & X \\
                 & Attenuation               & X  & X \\
 \hline