addressing #252, and also adding ScalFMM build script back, accidenta…

doc/content/bib/ferret.bib

@@ -1,6 +1,13 @@
 @PREAMBLE{
- "\providecommand{\noopsort}[1]{}" 
- # "\providecommand{\singleletter}[1]{#1}%" 
+ "\providecommand{\noopsort}[1]{}"
+ # "\providecommand{\singleletter}[1]{#1}%"
+}
+
+@book{NyeBook,
+	Author = {Nye, J. F.},
+	Publisher = {Oxford University Press Inc.},
+	Title = {Physical Properties of Crystals},
+	Year = {1985}
 }
 
 @BOOK{StohrBook,
@@ -18,6 +25,17 @@ @BOOK{RabeBook2007
    publisher    = {Springer-Verlag Berlin Heidelberg}
 }
 
+@article{Bernasconi1995,
+  title={Temperature dependence and dispersion of electro-optic and elasto-optic effect
+  in perovskite crystals},
+  author={Bernasconi, P. and Zgonik, M. and G\"{u}nter, P.},
+  journal={Journal of Applied Physics},
+  volume={78},
+  number={2651},
+  year={1995},
+  publisher={AIP}
+}
+
 @article{Weingart2012,
   title={Noncollinear magnetism and single-ion anisotropy in multiferroic perovskites},
   author={Weingart, Carlo and Spaldin, Nicola and Bousquet, Eric},
@@ -205,15 +223,15 @@ @article{Heron2014
   year={2014},
   journal={Nature}
   }
-  
+
 @article{Fiebig2016,
   title={Advances in magnetoelectric multiferroics},
   author={Fiebig, M. and Lottermoser, T. and Meier, D. and Trassin, M.},
   volume={1},
   number={16046},
   year={2016},
   journal={Nature Reviews Materials}
-  } 
+  }
 
 @article{Chauleau2019,
   title={Electric and antiferromagnetic chiral textures at multiferroic domain walls},
@@ -223,7 +241,7 @@ @article{Chauleau2019
   year={2019},
   journal={Nature Materials}
   }
-  
+
 @article{Gross2017,
   title={Real-space imaging of non-collinear antiferromagnetic order with a single-spin magnetometer},
   author={Gross, I. and Akhtar, W. and Garcia, V. and Mart\'{i}nez, L. J. and Chouaieb, S. and Garcia, K. and Carr\'{e}t\'{e}ro, C. and Barth\'{e}l\'{e}my, A. and Appel, P. and Maletinsky, P. and Kim, J.-V. and Chauleau, J. -Y. and Jaouen, N. and Viret, M. and Bibes, M. and Fusil, S. and Jacques, V.},
@@ -241,8 +259,8 @@ @article{Hlinka2006
   year={2006},
   journal={Physical Review B}
   }
-  
-  
+
+
  @article{Sosnowska2002,
   title={Crystal structure and spiral magnetic ordering of $\mathrm{BiFeO}_3$ doped with manganese},
   author={Sosnowska, I. and Sch\"{a}fer, W. and Kockelmann, W. and Andersen, K. H. and Troyanchu, I. O.},
@@ -254,7 +272,7 @@ @article{Sosnowska2002
   %ISSN 1432-0630
 
 
-  
+
 @article{Chen2008,
   title={Phase-Field Method of Phase Transitions/Domain Structures in Ferroelectric Thin Films: A Review},
   author={Chen, L.-Q.},
@@ -276,14 +294,14 @@ @article{Dieguez2013
   }
 
   %V. Bhide and M. Multani, Solid State Communications 3, 271 (1965), ISSN 0038-1098
- 
+
   @article{Mangeri2023,
   title={A coupled polar-magnetic continuum model for multiferroic $\mathrm{BiFeO}_3$},
   author={Mangeri, J. and Graf, M. and Biswas, S. and Rodrigues, D. and Heinonen, O. and Iniguez, J.},
   year={2023},
   journal={to appear on arXiv}
   }
-  
+
  @article{Jiang2016,
   title={An O(N) and parallel approach to integral problems by a kernel-independent fast multipole method: Application to polarization and magnetization of interacting particles},
   author={Jiang, X. and Li, J. and Zhao, X. and Qin, J. and Karpeev, D. and Hernandez-Ortiz, J. and de Pablo, J. J. and Heinonen, O.},
@@ -301,7 +319,7 @@ @article{Marton2017
   year={2017},
   journal={Physical Review B}
   }
-  
+
 
  @article{Xue2021,
   title={Theory and phase-field simulations of electrical control of spin cycloids in a multiferroic},
@@ -375,5 +393,3 @@ @article{slaughter2021continuous
 doi       = {10.1080/00295450.2020.1826804},
 url       = {https://doi.org/10.1080/00295450.2020.1826804}
 }
-
-

doc/content/theory/intro_optical.md

@@ -1,56 +1,76 @@
 # Optical properties in FERRET
 
 !alert construction title=Documentation in-progress
-This section requires some work before it will be online. Please contact the developers if you need assistance with this aspect of the module.
-
-In this section a description of the physics governing light interactions with matter are discussed.  First, an explanation of electromagnetic theory in crystals is developed based on primarily on Maxwell's equations.  This is followed by a discussion on the phenomenological description of wave propagation in crystals, mainly by connecting refractive indices to the optical indicatrix.  Lastly, a description of the photoelastic and electro-optic effects, which involve changes to the optical properties of crystals under applied external stresses and electric fields.
-
-We start by considering Maxwell's equations, in an isotropic medium for simplicity sake, presented in tensor form,
-\begin{align}
-    \frac{\partial D_i}{\partial r_i} &= \rho \\
-    \frac{\partial B_i}{\partial r_i} &= 0 \\
-    \epsilon_{ijk} \frac{\partial E_k}{r_j} &= - \frac{\partial B_i}{dt}\\
-    \epsilon_{ijk} \frac{\partial H_k}{r_j} &= j_i + \frac{\partial D_i}{\partial t}
-\end{align}
-where $\epsilon_{ijk}$ is the Levi-Civita symbol, $\rho$ is charge density, $j_i$ is current density, $E_i$ and $B_i$ are electric and magnetic field strength, and $D_i$ and $M_i$ are the electric displacement vector and magnetization respectively.  By assuming a medium with no free charges or currents, and replacing $D_i$ and $B_i$ with the relations $D_i = \kappa_o \kappa_r E_i$ and $B_i = \mu_o \mu_r H_i$,\footnote{It should be noted here that $\kappa_r$ and $\mu_r$ are the relative permittivity and permeability respectively.  It is important to remember that they are actually $\kappa = \kappa_r/\kappa_o$ and $\mu = \mu_r/\mu_o$, where the naught subscript is representative of the free space (vacuum) values. } we arrive at the simplified equations
-\begin{align}
-    \epsilon_{ijk} \frac{\partial E_k}{r_j} &= - \mu_o \mu_r \frac{\partial H_i}{dt} \\
-    \epsilon_{ijk} \frac{\partial H_k}{r_j} &= \kappa_o \kappa_r \frac{\partial E_i}{\partial t}
-\end{align}
-where $\kappa_o$ and $\mu_o$ are the permittivity and permeability of vacuum and $\kappa_r$ and $\mu_r$ are the relative permittivity and permeability of the medium.  By combining these equations to eliminate $H_i$, and utilizing a useful vector identity, the final result is
+This section requires some work before it will be finalized online. Please contact the developers if you need assistance with this aspect of the module.
+
+In this section, we describe the postprocessing capability of FERRET to compute refractive indices for an arbitrary anisotropic medium. The medium can have internal structure (in the case of ferroelectrics) or can be nominally isotropic but under the influence of elastic or electric fields (i.e. elastoptics, electrooptics, or piezooptics).
+
+The refractive index is defined by the quantity known as the indicatrix
+
 \begin{equation}
-    \frac{\partial^2 E_i}{\partial r_i^2} = \mu \kappa \frac{\partial^2 E_i}{dt^2}
-\end{equation}
-which has the same form as the wave equation and has a solution of the form
-\begin{equation}\label{wave_prop}
-    E_i (r_k, t) = E_i^0 e^{i(kr_k - \omega t)}
+    B_{ij} x_{i} x_{j} = 1,
 \end{equation}
-where $k$ is the wave vector, $r_k$ is the direction of propagation, and $\omega$ is the angular frequency of the wave.  The phase velocity of the wave is given by
-\begin{equation}\label{wave_velocity}
-    \frac{1}{v^2} = \mu \kappa
-\end{equation}
-from which the speed of light in free space can be determined by setting $\kappa_r = \mu_r = 1$ to find that $c = 2.998 \times 10^8$ m/s.\footnote{The standard values of $\kappa_o = 8.854 \times 10^{-12}$ C/Vm and $\mu_o = 1.256 \times 10^{-6}$ N/A$^2$ were used to calculate this.}. From Eq.~\ref{wave_velocity} it is clear that the velocity of a wave in a medium is $v = c/ \sqrt{\kappa_r \mu_r}$ and therefore we can define that the index of refraction is
+
+in which $B_{ij} = \kappa_0 \partial E_i / \partial D_j$ with $\kappa_0$ the permittivity of vacuum. In an isotropic medium, $B_{11} = B_{22} = B_{33}$ and therefore the indicatrix can be considered to be a perfect sphere in coordinate $x_1, x_2, x_3$ space. The quantities $B_{ij}$ are reciprocal to the relative dielectric permeability or $B_{ij} = 1/\kappa_{ij}$ and $B_{ij} = 1/n_{ij}^2$ where $n_{ij}$ is the refective index tensor. Usually the off-diagonal elements are very small or zero. We can see an example of the cubic medium in Fig. \ref{fig_indicatrix}.
+
+!media media/indicatrix.png style=display:block;margin:auto;width:50%; caption=Left; Isotropic (cubic) medium. Right; Lower symmetry indicatrix characterized by a change of $n_z$ with respect to $n_x = n_y$.  id=fig_indicatrix
+
+If the crystal symmetry is broken, then the indicatrix will also be modified thus losing the $n_x = n_y = n_z$ relationship as shown in the right panel of Fig. \ref{fig_indicatrix}. This can be due to a phase transition or an applied external field (i.e. electric or mechanical). Since there are many possible ways to change a crystal structure, we will only describe a few that make sense in the context of FERRET simulations. There are two assumptions to the phenomological theory prescribed to the topical properties of crystals and they are:
+
+\begin{itemize}
+    \item In a homogeneously deformed solid the effect of deformation is only to alter the parameters of the optical indicatrix.
+    \item When strain is within elastic limits, the changes of an optical parameter (polarization constant) due to deformation can be expressed as a homogeneous linear function of the nine strain or stress components.
+    \item The electromagnetic (EM) field is weak and does not induce secondary changes to the refractive index.
+\end{itemize}
+
+Typically, this last assumption is usually what is applicable to experiments involving transmission or scattering. To lowest order, the relative change in the indicatrix components due to electric and mechanical fields are given by [!cite](NyeBook),
+
 \begin{equation}
-    n = \frac{c}{v}
+    \Delta B_{ij} = r_{ijk} E_k + \pi_{ijkl} \sigma_{kl}
 \end{equation}
-or more simply $n = \sqrt{\kappa}$ at optical frequencies (setting $\mu = 1$).  With this definition in place, as well the formula that defines the light wave propagation (Eq.~\ref{wave_prop}, we can carry on to developing the phenomenological description of optical properties in crystals.
 
+where $r_{ijk}$ and $\pi_{ijkl}$ is the electrooptic and photoelastic tensors. Typical orders of magnitude of $r_{ijk}$ and $\pi_{ijkl}$ are $10^{-12}$ m/V and m/N respectively. The quantity $\sigma_{kl}$ is the stress tensor components but the change of the indicatrix can also be expressed in terms of strain $\varepsilon_{rs}$,
+
+\begin{equation}
+    \Delta B_{ij} = r_{ijk} E_k + \pi_{ijkl} C_{klrs} \varepsilon_{rs}
+\end{equation}
 
+with $C_{klrs}$ is the elastic stiffness tensor. As an example, we can consider an applied uniaxial stress $\sigma_{xx}^0$ on a cubic crystal (\mathbf{E} = 0). Before the deformation,
 
-First developed by Pockels, there are two assumptions to the phenomological theory prescribed to the topical properties of crystals and they are:
-\begin{enumerate}
-    \item In a homogeneously deformed solid the effect of deformation is only to alter the optical parameters of the optical indicatrix.
-    \item When strain is within elastic limits, the changes of an optical parameter (polarization constant) due to deformation can be expressed as a homogeneous linear function of the nine strain components.
-\end{enumerate}. The optical properties of crystals can be defined in terms of the refractive index ellipsoid, pictured above/below, and expressed as
 \begin{equation}
-     \frac{x^2}{n_x^2} +  \frac{y^2}{n_y^2} +  \frac{z^2}{n_z^2} = 1
+    B_{0} \left(x^2_1 + x^2_2 + x^2_3\right) = 1
 \end{equation}
-where x, y, and z are the principle axes, and $n_x$,$n_y$, and $n_z$ are the associated principal refractive indices.  The refractive index unfortunately does not transform like a tensor, however, the dielectric tensor $\kappa_{ij}$ does.  For an anistropic medium, the previous derivation is expanded by considering the tensorial properties of the medium; specifically the permittivity becomes $\kappa_{ij}$ with a directional dependence.  Since this second-rank tensor is symmetric (the \textit{i} and \textit{j} suffixes are interchangeable) it is possible to multiply it by the product of two coordinate vectors to create a quadric.\footnote{A quadric is a representation surface that can be used to describe any second-rank tensor, and hence any crystal property that is given by such a tensor.}. By using the relation between permittivity and index of refraction, a full tensorial description of the optical properties of a crystal can be defined.  Using all we know now, we can can define the optical indicatrix equation as
+
+with $B_{0} = 1/n_0^2$. After deformation, by using the above expressions for $\Delta B_{ij}$ and a cubic symmetry for $\pi_{ijkl}$, we find (in Voight notation),
+
 \begin{equation}
-    B_{11}x^2 + B_{22}y^2 +B_{33}z^2 = 1,
+\begin{aligned}
+    \Delta n_1 &= - \frac{1}{2} n_0^3 \pi_{11} \sigma_{xx}^0 \\
+    \Delta n_2 &= - \frac{1}{2} n_0^3 \pi_{13} \sigma_{xx}^0 \\
+    \Delta n_3 &= - \frac{1}{2} n_0^3 \pi_{12} \sigma_{xx}^0
+\end{aligned}
 \end{equation}
-or more generally as
-\begin{equation}\label{polarization_indicatrix}
-    \sum_{i,j} B_{ij} r_i r_j = 1
+
+Note that if the crystal symmetry before deformation is cubic symmetry of $\bar{4}3m, 432$, or $m3m$, then $\pi_{12} = \pi_{13}$ and the resulting indicatrix relationship is $n_x = n_y \neq n_z$ as in Fig. \ref{fig_indicatrix}. However, if the cubic symmetry is $23$ or $m3$, then $\pi_{12} \neq \pi_{13}$ resulting in $n_x \neq n_y \neq n_z$ which has much consequence on an observed birefringence.
+
+In principle any symmetry crystal is allowed in FERRET simulations and that these expressions also work for inhomogeneously applied fields breaking the symmetry locally leading to spatially varying refractive indices.
+
+Another example of possible postprocessing ability in FERRET is to compute the relative changes in the refractive index due to the ferroelectric phase transition.
+
+
+Similarly to a stress which breaks the symmetry, the onset of the electric polarization moment arising from a structural distortion of the ionic lattice also breaks the symmetry. In the case of canonical perovskite ferroelectric (FE) $\mathrm{BaTiO}_3$, the symmetry initially goes from cubic $(m3m)$ to tetragonal $(4mm)$ as the temperature is lowered below the Curie temperature $T_C$. We consult the work of [!cite](Bernasconi1995) for a description.
+
+The spontaneous polarization $P_S$ entires into the relative changes to the indicatrix coefficients via,
+
+\begin{equation}
+\begin{aligned}
+    \Delta B_1 = \Delta B_2 &= g_{1122} P_S^2 + \left(p_{1111} + p_{1122}\right)\varepsilon_{xx} + p_{1122} \varepsilon_{zz} \\
+    \Delta B_3 &= g_{1111} P_S^2 + 2 p_{1122} \varepsilon_{xx} + p_{1111} \varepsilon_{zz}
+\end{aligned}
 \end{equation}
-where $B_{ij} = 1/{n_{ij}^2 = 1 /\kappa_{ij}}$, and $r_i$ are the principle axes.  Also known as polarization constants, these parameters can be conveniently utilized to describe induced changes of the crystal optical properties.
+
+where $\varepsilon_{ij}$ is the spontaneous strain arising from the phase transition. One can appreciate here that both the polarization and the elastic field adjust the refractive indices leading to a birefringence $(n_1 = n_2 \neq n_3)$. The parameters $(g_{ijkl})$ are known as the polar-optic coefficients in units of $10^{-2}$ $\mathrm{m}^4$ $\mathrm{C}^{-2}$. These materials constants have been shown to be strongly temperature dependent (as is for $P_S$) as well as dependent on the wavelength of light $\lambda_0$. Using room temperature values of $P_S$ and $\lambda_0 = 633$ nm, we have $n_3^{-2} - n_1^{-2} \approx 10^{-1}$ due to the FE phase transition.
+
+For low frequency electric fields, the ionic structure of the polarization should respond which would introduce additional higher order modulations to the relative refractive index changes. Note that this means that this postprocessing feature is very limited in terms of the situations that it can be applied to. For weak EM fields however, and at frequencies of the visible spectrum, the polarization is fixed in space time. We should also mention that the values of $g_{ijkl}$ are not known for many ferroelectric materials but they should be able to be computed from first-principles methodology or measured carefully as in the case of $\mathrm{BaTiO}_3$ in the cited work.
+
+As the birefringence is one way to observe and measure the domain topology, we provide this feature in FERRET for users. By first using the phase field method to calculate the ground state structure (in arbitrary 3D geometries), the local refractive indices can then be computed with this approach. We provide an example in our tutorials listed on this website and we aim to expand this capability in the future to handle lower symmetries and other FE materials such as those displaying magnetic order (multiferroics).

doc/content/tutorials/ferroelectric_domain_wall.md

@@ -2,4 +2,22 @@
 
 # Tutorial 2: Ferroelectric domain wall
 
-This tutorial gives an example to compute the 180 degree domain wall profile of BaTiO3 at room temperature in FERRET.
+This tutorial gives an example on how to compute the $180^\circ$ domain wall (DW) profile of $\mathrm{BaTiO}_3$ (BTO) at room temperature ($T = 298$ K) in FERRET. In this problem, the polarization $\mathbf{P}$ is coupled to the elastic strain field $\varepsilon_{kl} = \frac{1}{2} \left( \frac{\partial u_k}{\partial x_l} + \frac{\partial u_l}{\partial x_k} \right)$ via electrostrictive coupling appropriate for BTO.
+
+The expected DW plane configuration is (100) or equivalent directions so we choose a computational geometry as follows,
+
+
+
+where $n_x, n_y,$ and $n_z$ are chosen accordingly such that the mesh spacing $\Delta$ is approximately 0.25 nm.
+
+
+We utilize the GlobalStrain system in MOOSE to ensure periodicity of the strain tensor components along the long direction of the box.
+
+
+In principle, this type of calculation can be generalized to any ferroic material (i.e. ferromagnets) to study the DW textures of magnetization in the presence of additional couplings (for example magnetoelasticity).
+
+
+
+run time 1864 secs on 8 processors
+
+TEST: