Additional documentation for simulation in cylindrical coordinates (#2471)

* additional documentation for simulation in cylindrical coordinates

* add figures

* Update doc/docs/Exploiting_Symmetry.md

* add details on quasi PML in r direction

* swap rz coordinate axes in figure showing Yee grid for consistency with plot2D

---------

Co-authored-by: Steven G. Johnson <[email protected]>

Author: oskooi

README.md

@@ -12,7 +12,7 @@
 
 -   **Free and open-source software** under the [GNU GPL](https://en.wikipedia.org/wiki/GNU_General_Public_License).
 -   Complete **scriptability** via [Python](https://meep.readthedocs.io/en/latest/Python_Tutorials/Basics/), [Scheme](https://meep.readthedocs.io/en/latest/Scheme_Tutorials/Basics), or [C++](https://meep.readthedocs.io/en/master/C++_Tutorial/) APIs.
--   Simulation in **1d, 2d, 3d**, and **cylindrical** coordinates.
+-   Simulation in **1d, 2d, 3d**, and **[cylindrical](https://meep.readthedocs.io/en/latest/Exploiting_Symmetry/#cylindrical-symmetry)** coordinates.
 -   Distributed memory [parallelism](https://meep.readthedocs.io/en/latest/Parallel_Meep) on any system supporting [MPI](https://en.wikipedia.org/wiki/MPI).
 -   Portable to any Unix-like operating system such as [Linux](https://en.wikipedia.org/wiki/Linux), [macOS](https://en.wikipedia.org/wiki/macOS), and [FreeBSD](https://en.wikipedia.org/wiki/FreeBSD).
 -   **Precompiled binary packages** of official releases via [Conda](https://meep.readthedocs.io/en/latest/Installation/#conda-packages).

doc/docs/Exploiting_Symmetry.md

@@ -41,11 +41,27 @@ To exploit $E_z$ or $H_z$ symmetry, you don't have to do anything special: if yo
 
 ### Cylindrical Symmetry
 
-If your structure has cylindrical symmetry (also known as the $C_{\infty\mathrm{v}}$ group), i.e. continuous rotational symmetry around the $z$ axis, then Meep can exploit this by running the simulation in cylindrical/polar coordinates.
+If your structure has cylindrical symmetry (also known as the $C_{\infty\mathrm{v}}$ group), i.e. continuous rotational symmetry around the $z$ axis, then Meep can exploit this by running the simulation in [cylindrical/polar coordinates](https://en.wikipedia.org/wiki/Cylindrical_coordinate_system).
 
-To do this, you must set `dimensions = mp.CYLINDRICAL` in the Python script, and then the vectors are interpreted as $(r,\phi,z)$ triplets instead of $(x,y,z)$.
+To do this, you must set `dimensions = mp.CYLINDRICAL` in the Python script, and then the vectors are interpreted as $(r,\phi,z)$ triplets instead of $(x,y,z)$. The 2d cell consists of the $rz$ plane ($\phi = 0$). The $\phi$ component of the vectors is ignored.
 
-In a cylindrical simulation, fields can be written in the form of a function of $(r,z)$ multiplied by a function $\exp(im\phi)$ for the $\phi$ dependence, where $m$ is a user-specified parameter (related to the angular momentum of the field). If the cell includes the $r=0$ origin, then $m$ must be an integer to be single-valued at the origin. Otherwise, $m$ can be arbitrary (this is useful e.g. for bend simulations).
+In a cylindrical simulation, the fields can be written in the form of a function of $(r,z)$ multiplied by a function $\exp(im\phi)$ for the $\phi$ dependence, where $m$ is a user-specified parameter (related to the angular momentum of the field). For reference, Maxwell's equations in cylindrical coordinates and a schematic of the Yee grid are shown below.
+
+![](images/Maxwell_equations_cylindrical.png#center)
+
+![](images/Yee_grid_cylindrical.png#center)
+
+The ($E_\phi$, $E_z$, $H_r$) fields at $r = 0$ must obey certain symmetries determined by the value of $m$:
+
+* $m = 0$: fields are rotation-invariant. At $r = 0$, this means that $E_z$ can be nonzero, but $E_\phi$ and $H_r$ must be zero since they are otherwise not rotation-invariant.
+* $m = \pm 1$: fields flip sign when rotated by $\phi = \pi$ radians. At $r = 0$, this means that $E_\phi$ and $ H_r$ can be nonzero but $E_z$ must be zero.
+* $|m| > 1$: all fields go to zero at $r = 0$.
+
+Integrals in cylindrical coordinates involve a $2 \pi r \, dr$ factor, which is automatically included by Meep when computing integrated quantities (Poynting flux, energy, etcetera).
+
+A zero-thickness source in the $r$ direction is treated by Meep as a Dirac $\delta(r)$ function. In some contexts you might prefer $\delta(r)/r$ or $\delta(r)/2\pi r$ so that the radial integral is 1; these additional factors can be included by scaling the source amplitude or by scaling the resulting fields/powers in postprocessing.
+
+The [perfectly matched layer (PML)](Perfectly_Matched_Layer.md) in the $r$ direction is a *quasi* PML rather than a true PML. At the same thickness, reflections from the quasi PML will generally tend to be larger than a true PML. The thickness of the quasi PML may therefore need to be increased to compensate for these larger reflections. The quasi PML approaches a true PML as the outer radius of the computational cell increases. (This is because the implicit curvature of the PML region decreases with radius and approaches the Cartesian case of the quasi PML.) For additional information, see Section 4.2 of [Computer Physics Communications, Vol. 181, pp. 687-702 (2010)](http://ab-initio.mit.edu/~oskooi/papers/Oskooi10.pdf).
 
 For examples, see [Tutorial/Cylindrical Coordinates](Python_Tutorials/Cylindrical_Coordinates.md).
 

doc/docs/Python_Tutorials/Local_Density_of_States.md

@@ -327,7 +327,7 @@ A more efficient approach to computing the total emitted power from the dipole i
 
 To demonstrate this feature of the LDOS, we will compute the extraction efficiency of an LED-like structure consisting of a point dipole embedded within a dielectric layer ($n$=2.4 and thickness 0.7 $\lambda/n$) surrounded by vacuum and positioned above an infinite ground plane of a lossless metal. We will compute the extraction efficiency (at a wavelength $\lambda$ = 1.0 μm for a dipole with polarization parallel to the ground plane) as a function of the height of the dipole source above the ground plane using two different coordinate systems — 3D Cartesian and cylindrical — and demonstrate that the results are equivalent (apart from discretization error). The key difference is that simulation using cylindrical (2D) coordinates is significantly faster and more memory efficient than 3D.
 
-The simulation setup is shown in the figures below for 3D Cartesian (cross section in $xz$) and cylindrical coordinates. (Note that this single-dipole calculation differs from the somewhat related flux calculation in [Tutorials/Custom Source/Stochastic Dipole Emission in Light Emitting Diodes](Custom_Source.md#stochastic-dipole-emission-in-light-emitting-diodes) which involved modeling a *collection* of dipoles.) In this example, the point-dipole source is positioned at $r=0$ which involves a single simulation. Nonaxisymmetric dipoles positioned at $r>0$, however, are more challenging because they involve multiple simulations. For a demonstration, see [Cylindrical Coordinates/Nonaxisymmetric Dipole Sources](Cylindrical_Cordinates.md#nonaxisymmetric-dipole-sources).
+The simulation setup is shown in the figures below for 3D Cartesian (cross section in $xz$) and cylindrical coordinates. (Note that this single-dipole calculation differs from the somewhat related flux calculation in [Tutorials/Custom Source/Stochastic Dipole Emission in Light Emitting Diodes](Custom_Source.md#stochastic-dipole-emission-in-light-emitting-diodes) which involved modeling a *collection* of dipoles.) In this example, the point-dipole source is positioned at $r=0$ which involves a single simulation. Nonaxisymmetric dipoles positioned at $r>0$, however, are more challenging because they involve multiple simulations. For a demonstration, see [Cylindrical Coordinates/Nonaxisymmetric Dipole Sources](Cylindrical_Coordinates.md#nonaxisymmetric-dipole-sources).
 
 ![](../images/dipole_extraction_eff_3D.png#center)
 

doc/docs/images/Maxwell_equations_cylindrical.png

@@ -8,7 +8,7 @@
 
 -   **Free and open-source software** under the [GNU GPL](https://en.wikipedia.org/wiki/GNU_General_Public_License).
 -   Complete **scriptability** via [Python](Python_Tutorials/Basics), [Scheme](Scheme_Tutorials/Basics), or [C++](C++_Tutorial) APIs.
--   Simulation in **1d, 2d, 3d**, and **cylindrical** coordinates.
+-   Simulation in **1d, 2d, 3d**, and **[cylindrical](Exploiting_Symmetry.md#cylindrical-symmetry)** coordinates.
 -   Distributed memory [parallelism](Parallel_Meep) on any system supporting [MPI](https://en.wikipedia.org/wiki/MPI).
 -   Portable to any Unix-like operating system such as [Linux](https://en.wikipedia.org/wiki/Linux), [macOS](https://en.wikipedia.org/wiki/macOS), and [FreeBSD](https://en.wikipedia.org/wiki/FreeBSD).
 -   **Precompiled binary packages** of official releases via [Conda](Installation.md#conda-packages).