minor fixes to documentation (#1803)

* minor fixes to documentation

* clarify dispersive epsilon

doc/docs/Mode_Decomposition.md

@@ -1,6 +1,6 @@
 # Mode Decomposition
 
-Meep contains a feature to decompose arbitrary fields into a superposition of the harmonic modes of a given structure via its integration with the eigenmode solver [MPB](https://mpb.readthedocs.io). This section provides an overview of the theory and implementation of this feature. For examples, see [Tutorial/Mode Decomposition](Python_Tutorials/Mode_Decomposition.md).
+Meep contains a feature to decompose arbitrary fields into a superposition of the harmonic modes of a given structure via its integration with the eigenmode solver [MPB](https://mpb.readthedocs.io). Only dielectric structures with lossless, wavelength-independent, anisotropic $\varepsilon$ are supported by MPB. If dispersive materials are defined in Meep, only the real part of $\varepsilon$ is used. This section provides an overview of the theory and implementation of this feature. For examples, see [Tutorial/Mode Decomposition](Python_Tutorials/Mode_Decomposition.md).
 
 [TOC]
 

doc/docs/Python_User_Interface.md

@@ -1344,7 +1344,8 @@ following fields:
 
 + `alpha`: the complex eigenmode coefficients as a 3d NumPy array of size
   (`len(bands)`, `flux.nfreqs`, `2`). The last/third dimension refers to modes
-  propagating in the forward (+) or backward (-) directions.
+  propagating in the forward (+) or backward (-) directions defined relative to
+  the mode's dominant wavevector.
 + `vgrp`: the group velocity as a NumPy array.
 + `kpoints`: a list of `mp.Vector3`s of the `kpoint` used in the mode calculation.
 + `kdom`: a list of `mp.Vector3`s of the mode's dominant wavevector.
@@ -1361,6 +1362,8 @@ Technically, MPB computes $\omega_n(\mathbf{k})$ and then inverts it with Newton
 
 **Note:** for planewaves in homogeneous media, the `kpoints` may *not* necessarily be equivalent to the actual wavevector of the mode. This quantity is given by `kdom`.
 
+Note that Meep's MPB interface only supports dispersionless non-magnetic materials but it does support anisotropic $\\varepsilon$. Any nonlinearities, magnetic responses $\\mu$ conductivities $\\sigma$, or dispersive polarizations in your materials will be *ignored* when computing the mode decomposition. PML will also be ignored.
+
 
 <a id="Simulation.add_mode_monitor"></a>
 
@@ -2062,7 +2065,9 @@ Given a `Vector3` point `x` which can lie anywhere outside the near-field surfac
 including outside the cell and a `near2far` object, returns the computed
 (Fourier-transformed) "far" fields at `x` as list of length 6`nfreq`, consisting
 of fields $(E_x^1,E_y^1,E_z^1,H_x^1,H_y^1,H_z^1,E_x^2,E_y^2,E_z^2,H_x^2,H_y^2,H_z^2,...)$
-for the frequencies 1,2,…,`nfreq`.
+in Cartesian coordinates and
+$(E_r^1,E_\phi^1,E_z^1,H_r^1,H_\phi^1,H_z^1,E_r^2,E_\phi^2,E_z^2,H_r^2,H_\phi^2,H_z^2,...)$
+in cylindrical coordinates for the frequencies 1,2,…,`nfreq`.
 
 </div>
 
@@ -2837,7 +2842,7 @@ def stop_when_dft_decayed(tol=1e-11,
 <div class="function_docstring" markdown="1">
 
 Return a `condition` function, suitable for passing to `Simulation.run` as the `until`
-or `until_after_sources` parameter, that checks the `Simulation`'s dft objects every $t$
+or `until_after_sources` parameter, that checks the `Simulation`'s DFT objects every $t$
 timesteps, and stops the simulation once all the field components and frequencies of *every*
 DFT object have decayed by at least some tolerance `tol` (default is 1e-11). The time interval
 $t$ is determined automatically based on the frequency content in the DFT monitors.
@@ -5984,8 +5989,8 @@ def __init__(self,
 
 + **`side` [`side` constant ]** — Specify which side, `Low` or `High` of the
   boundary or boundaries to put PML on. e.g. if side is `Low` and direction is
-  `X`, then a PML layer is added to the $-x$ boundary. Default is the special
-  value `ALL`, which puts PML layers on both sides.
+  `meep.X`, then a PML layer is added to the $-x$ boundary. Default is the special
+  value `meep.ALL`, which puts PML layers on both sides.
 
 + **`R_asymptotic` [`number`]** — The asymptotic reflection in the limit of
   infinite resolution or infinite PML thickness, for reflections from air (an

doc/docs/Python_User_Interface.md.in

@@ -181,6 +181,8 @@ Technically, MPB computes $\omega_n(\mathbf{k})$ and then inverts it with Newton
 
 **Note:** for planewaves in homogeneous media, the `kpoints` may *not* necessarily be equivalent to the actual wavevector of the mode. This quantity is given by `kdom`.
 
+Note that Meep's MPB interface only supports dispersionless non-magnetic materials but it does support anisotropic $\\varepsilon$. Any nonlinearities, magnetic responses $\\mu$ conductivities $\\sigma$, or dispersive polarizations in your materials will be *ignored* when computing the mode decomposition. PML will also be ignored.
+
 @@ Simulation.add_mode_monitor @@
 
 `add_mode_monitor` works properly with arbitrary symmetries, but may be suboptimal because the Fourier-transformed region does not exploit the symmetry.  As an optimization, if you have a mirror plane that bisects the mode monitor, you can instead use `add_flux` to gain a factor of two, but in that case you *must* also pass the corresponding `eig_parity` to `get_eigenmode_coefficients` in order to only compute eigenmodes with the corresponding mirror symmetry.

python/simulation.py

@@ -197,8 +197,8 @@ def __init__(self, thickness,
 
         + **`side` [`side` constant ]** — Specify which side, `Low` or `High` of the
           boundary or boundaries to put PML on. e.g. if side is `Low` and direction is
-          `X`, then a PML layer is added to the $-x$ boundary. Default is the special
-          value `ALL`, which puts PML layers on both sides.
+          `meep.X`, then a PML layer is added to the $-x$ boundary. Default is the special
+          value `meep.ALL`, which puts PML layers on both sides.
 
         + **`R_asymptotic` [`number`]** — The asymptotic reflection in the limit of
           infinite resolution or infinite PML thickness, for reflections from air (an
@@ -546,7 +546,7 @@ def __init__(self, where=None, center=None, size=None):
 
 
 class DftObj(object):
-    """Wrapper around dft objects that allows delayed initialization of the structure.
+    """Wrapper around DFT objects that allows delayed initialization of the structure.
 
     When splitting the structure into chunks for parallel simulations, we want to know all
     of the details of the simulation in order to ensure that each processor gets a similar
@@ -2754,7 +2754,9 @@ def get_farfield(self, near2far, x):
         including outside the cell and a `near2far` object, returns the computed
         (Fourier-transformed) "far" fields at `x` as list of length 6`nfreq`, consisting
         of fields $(E_x^1,E_y^1,E_z^1,H_x^1,H_y^1,H_z^1,E_x^2,E_y^2,E_z^2,H_x^2,H_y^2,H_z^2,...)$
-        for the frequencies 1,2,…,`nfreq`.
+        in Cartesian coordinates and
+        $(E_r^1,E_\phi^1,E_z^1,H_r^1,H_\phi^1,H_z^1,E_r^2,E_\phi^2,E_z^2,H_r^2,H_\phi^2,H_z^2,...)$
+        in cylindrical coordinates for the frequencies 1,2,…,`nfreq`.
         """
         return mp._get_farfield(near2far.swigobj, py_v3_to_vec(self.dimensions, x, is_cylindrical=self.is_cylindrical))
 
@@ -3549,7 +3551,8 @@ def get_eigenmode_coefficients(self, flux, bands, eig_parity=mp.NO_PARITY, eig_v
 
         + `alpha`: the complex eigenmode coefficients as a 3d NumPy array of size
           (`len(bands)`, `flux.nfreqs`, `2`). The last/third dimension refers to modes
-          propagating in the forward (+) or backward (-) directions.
+          propagating in the forward (+) or backward (-) directions defined relative to
+          the mode's dominant wavevector.
         + `vgrp`: the group velocity as a NumPy array.
         + `kpoints`: a list of `mp.Vector3`s of the `kpoint` used in the mode calculation.
         + `kdom`: a list of `mp.Vector3`s of the mode's dominant wavevector.
@@ -4523,7 +4526,7 @@ def _stop(sim):
 def stop_when_dft_decayed(tol=1e-11, minimum_run_time=0, maximum_run_time=None):
     """
     Return a `condition` function, suitable for passing to `Simulation.run` as the `until`
-    or `until_after_sources` parameter, that checks the `Simulation`'s dft objects every $t$
+    or `until_after_sources` parameter, that checks the `Simulation`'s DFT objects every $t$
     timesteps, and stops the simulation once all the field components and frequencies of *every*
     DFT object have decayed by at least some tolerance `tol` (default is 1e-11). The time interval
     $t$ is determined automatically based on the frequency content in the DFT monitors.