minor updates and fixes to docs (NanoComp#1446)

* minor updates and fixes to docs

* warning for plot2D using meep.am_master()

* Update simulation.py

Co-authored-by: Steven G. Johnson <stevenj@mit.edu>

doc/docs/Python_Tutorials/Basics.md

@@ -431,7 +431,7 @@ We turn to a similar but slightly different example for which there exists an an
 
 A 1d cell must be used since a higher-dimensional cell will introduce [artificial modes due to band folding](../FAQ.md#why-are-there-strange-peaks-in-my-reflectancetransmittance-spectrum-when-modeling-planar-or-periodic-structures). We will use a Gaussian source spanning visible wavelengths of 0.4 to 0.8 μm. Unlike a [continuous-wave](../Python_User_Interface.md#continuoussource) (CW) source, a pulsed source turns off. This enables a termination condition of when there are no fields remaining in the cell (due to absorption by the PMLs) via the [run function](../Python_User_Interface.md#run-functions) `stop_when_fields_decayed`, similar to the previous example.
 
-Creating an oblique planewave source typically requires specifying two parameters: (1) for periodic structures, the Bloch-periodic wavevector $\vec{k}$ via [`k_point`](../FAQ.md#how-does-k_point-define-the-phase-relation-between-adjacent-unit-cells), and (2) the source amplitude function `amp_func` for setting the $e^{i\vec{k} \cdot \vec{r}}$ spatial dependence ($\vec{r}$ is the position vector). Since we have a 1d cell and the source is at a single point, it is not necessary to specify the source amplitude (see this [2d example](https://github.com/NanoComp/meep/blob/master/python/examples/pw-source.py) for how this is done). The magnitude of the Bloch-periodic wavevector is specified according to the dispersion relation formula for a planewave in homogeneous media with index $n$: $\omega=c|\vec{k}|/n$. As the source in this example is incident from air, $|\vec{k}|$ is simply equal to the frequency $\omega$. Note that specifying $\vec{k}$ involves a *single* frequency. Any broadband source is therefore incident at a specified angle for only a *single* frequency. This is described in more detail in Section 4.5 ("Efficient Frequency-Angle Coverage") in [Chapter 4](https://arxiv.org/abs/1301.5366) ("Electromagnetic Wave Source Conditions") of the book [Advances in FDTD Computational Electrodynamics: Photonics and Nanotechnology](https://www.amazon.com/Advances-FDTD-Computational-Electrodynamics-Nanotechnology/dp/1608071707). In this example, $\omega$ is set to the minimum frequency of the pulse to produce propagating fields at all pulse frequencies. In general, any pulse frequencies which are *less* than any non-zero component of $\vec{k}$ will result in *evanescent* fields (which carry zero power to the far field, and computationally will yield exponentially small power).
+Creating an oblique planewave source typically requires specifying two parameters: (1) for periodic structures, the Bloch-periodic wavevector $\vec{k}$ via [`k_point`](../FAQ.md#how-does-k_point-define-the-phase-relation-between-adjacent-unit-cells), and (2) the source amplitude function `amp_func` for setting the $e^{i\vec{k} \cdot \vec{r}}$ spatial dependence ($\vec{r}$ is the position vector). Since we have a 1d cell and the source is at a single point, it is not necessary to specify the source amplitude (see this [2d example](https://github.com/NanoComp/meep/blob/master/python/examples/pw-source.py) for how this is done). The magnitude of the Bloch-periodic wavevector is specified according to the dispersion relation formula for a planewave in homogeneous media with index $n$: $\omega=c|\vec{k}|/n$. As the source in this example is incident from air, $|\vec{k}|$ is simply equal to the frequency $\omega$. Note that specifying $\vec{k}$ corresponds to a single frequency. Any broadband source is therefore incident at a specified angle for only a *single* frequency. This is described in more detail in Section 4.5 ("Efficient Frequency-Angle Coverage") in [Chapter 4](https://arxiv.org/abs/1301.5366) ("Electromagnetic Wave Source Conditions") of the book [Advances in FDTD Computational Electrodynamics: Photonics and Nanotechnology](https://www.amazon.com/Advances-FDTD-Computational-Electrodynamics-Nanotechnology/dp/1608071707). In this example, $\omega$ is set to the minimum frequency of the pulse to produce propagating fields at all pulse frequencies. In general, any pulse frequencies which are *less* than any non-zero component of $\vec{k}$ will result in *evanescent* fields (which carry zero power to the far field, and computationally will yield exponentially small power).
 
 In this example, the plane of incidence which contains $\vec{k}$ and the surface normal vector is chosen to be $xz$. The source angle $\theta$ is defined in degrees in the counterclockwise (CCW) direction around the $y$ axis with 0 degrees along the $+z$ axis. In Meep, a 1d cell is defined along the $z$ direction. When $\vec{k}$ is not set, only the $E_x$ and $H_y$ field components are permitted. A non-zero $\vec{k}$ results in a 3d simulation where all field components are included and are complex valued (note that the fields are real, by default). A current source with $E_x$ polarization lies within the plane of incidence and corresponds to the convention of $\mathcal{P}$-polarization. In order to model the $\mathcal{S}$-polarization, we must use an $E_y$ source. This example involves just the $\mathcal{P}$-polarization.
 

doc/docs/Python_Tutorials/GDSII_Import.md

@@ -315,8 +315,9 @@ def find_modes(filename,wvl=1.55,bw=0.05):
             until_after_sources=100)
 
     plt.figure()
-    sim.plot2D(fields=mp.Hz)
-    plt.savefig('ring_resonator_Hz.png')
+    sim.plot2D(fields=mp.Hz,
+               eps_parameters={'contour':True})
+    plt.savefig('ring_resonator_Hz.png',bbox_inches='tight',dpi=150)
 
     wvl = np.array([1/m.freq for m in h.modes])
     Q = np.array([m.Q for m in h.modes])

doc/docs/Python_User_Interface.md

@@ -77,14 +77,6 @@ class Simulation(object):
 The `Simulation` [class](#classes) contains all the attributes that you can set to
 control various parameters of the Meep computation.
 
-#### Output File Names
-
-The output filenames used by Meep, e.g. for HDF5 files, are automatically prefixed by
-the `filename_prefix` parameter. If `filename_prefix` is `None` (the default),
-however, then Meep constructs a default prefix based on the current Python filename
-with `".py"` replaced by `"-"`: e.g. `test.py` implies a prefix of `"test-"`. You can
-get this prefix by calling `get_filename_prefix`.
-
 </div>
 
 
@@ -168,9 +160,8 @@ Python. `Vector3` is a `meep` class.
   optimized. See `dimensions` below. **Note:** because Maxwell's equations are
   scale invariant, you can use any units of distance you want to specify the cell
   size: nanometers, microns, centimeters, etc. However, it is usually convenient
-  to pick some characteristic lengthscale of your problem and set that length to
-  1. See also [Units](Introduction.md#units-in-meep). Required argument (no
-  default).
+  to pick some characteristic lengthscale of your problem and set that length to 1.
+  See also [Units](Introduction.md#units-in-meep). Required argument (no default).
 
 + **`default_material` [`Medium` class ]** — Holds the default material that is
   used for points not in any object of the geometry list. Defaults to `air` (ε=1).
@@ -283,10 +274,10 @@ Python. `Vector3` is a `meep` class.
   simulate all fields, even those that remain zero throughout the simulation, by
   setting `force_all_components` to `True`.
 
-+ **`filename_prefix` [`string`]** — A string prepended to all output filenames.
-  If empty (the default), then Meep uses the name of the current Python file, with
-  ".py" replaced by "-" (e.g. `foo.py` uses a `"foo-"` prefix). See also [Output
-  File Names](Python_User_Interface.md#output-file-names).
++ **`filename_prefix` [`string`]** — A string prepended to all output filenames
+  (e.g., for HDF5 files). If `None` (the default), then Meep constructs a default
+  prefix based on the current Python filename ".py" replaced by "-" (e.g. `foo.py`
+  uses a `"foo-"` prefix). You can get this prefix by calling `get_filename_prefix`.
 
 + **`Courant` [`number`]** — Specify the
   [Courant factor](https://en.wikipedia.org/wiki/Courant%E2%80%93Friedrichs%E2%80%93Lewy_condition)
@@ -2466,6 +2457,9 @@ plt.show()
 plt.savefig('sim_domain.png')
 ```
 
+Warning: When running a [parallel simulation](Parallel_Meep.md), do *not* call `plot2D` from within an
+`if meep.am_master():` statement since this will cause one of the MPI processes to deadlock.
+
 **Parameters:**
 
 * `ax`: a `matplotlib` axis object. `plot2D()` will add plot objects, like lines,
@@ -3464,7 +3458,7 @@ def get_array_metadata(self,
 
 This routine provides geometric information useful for interpreting the arrays
 returned by `get_array` or `get_dft_array` for the spatial region defined by `vol`
-or `center/size`. In both cases, the return value is a tuple `(x,y,z,w)`, where:
+or `center`/`size`. In both cases, the return value is a tuple `(x,y,z,w)`, where:
 
 + `x,y,z` are 1d NumPy arrays storing the $x,y,z$ coordinates of the points in the
   grid slice
@@ -5310,7 +5304,7 @@ def __init__(self, **kwargs):
 
 <div class="method_docstring" markdown="1">
 
-Construct an `Ellipsiod`.
+Construct an `Ellipsoid`.
 
 </div>
 

doc/docs/Scheme_Tutorials/Basics.md

@@ -409,7 +409,7 @@ We turn to a similar but slightly different example for which there exists an an
 
 A 1d cell must be used since a higher-dimensional cell will introduce [artificial modes due to band folding](../FAQ.md#why-are-there-strange-peaks-in-my-reflectancetransmittance-spectrum-when-modeling-planar-or-periodic-structures). We will use a Gaussian source spanning visible wavelengths of 0.4 to 0.8 μm. Unlike a [continuous-wave](../Scheme_User_Interface.md#source) (CW) source, a pulsed source turns off. This enables a termination condition of when there are no fields remaining in the cell (due to absorption by the PMLs) via the [run function](../Scheme_User_Interface.md#run-functions) `stop-when-fields-decayed`, similar to the previous example.
 
-Creating an oblique planewave source typically requires specifying two parameters: (1) for periodic structures, the Bloch-periodic wavevector $\vec{k}$ via [`k_point`](../FAQ.md#how-does-k_point-define-the-phase-relation-between-adjacent-unit-cells), and (2) the source amplitude function `amp_func` for setting the $e^{i\vec{k} \cdot \vec{r}}$ spatial dependence ($\vec{r}$ is the position vector). Since we have a 1d cell and the source is at a single point, it is not necessary to specify the source amplitude (see this [2d example](https://github.com/NanoComp/meep/blob/master/python/examples/pw-source.py) for how this is done). The magnitude of the Bloch-periodic wavevector is specified according to the dispersion relation formula for a planewave in homogeneous media with index $n$: $\omega=c|\vec{k}|/n$. As the source in this example is incident from air, $|\vec{k}|=\sqrt{k_x^2+k_z^2}$ is simply equal to the frequency $\omega$. Note that specifying $\vec{k}$ involves a *single* frequency. Any broadband source is therefore incident at a specified angle for only a *single* frequency. This is described in more detail in Section 4.5 ("Efficient Frequency-Angle Coverage") in [Chapter 4](https://arxiv.org/abs/1301.5366) ("Electromagnetic Wave Source Conditions") of the book [Advances in FDTD Computational Electrodynamics: Photonics and Nanotechnology](https://www.amazon.com/Advances-FDTD-Computational-Electrodynamics-Nanotechnology/dp/1608071707). In this example, $\omega$ is set to the minimum frequency of the pulse to produce propagating fields at all pulse frequencies. In general, any pulse frequencies which are *less* than any non-zero component of $|\vec{k}|$ will result in *evanescent* fields (which are essentially irrelevant in most practical applications).
+Creating an oblique planewave source typically requires specifying two parameters: (1) for periodic structures, the Bloch-periodic wavevector $\vec{k}$ via [`k_point`](../FAQ.md#how-does-k_point-define-the-phase-relation-between-adjacent-unit-cells), and (2) the source amplitude function `amp_func` for setting the $e^{i\vec{k} \cdot \vec{r}}$ spatial dependence ($\vec{r}$ is the position vector). Since we have a 1d cell and the source is at a single point, it is not necessary to specify the source amplitude (see this [2d example](https://github.com/NanoComp/meep/blob/master/python/examples/pw-source.py) for how this is done). The magnitude of the Bloch-periodic wavevector is specified according to the dispersion relation formula for a planewave in homogeneous media with index $n$: $\omega=c|\vec{k}|/n$. As the source in this example is incident from air, $|\vec{k}|=\sqrt{k_x^2+k_z^2}$ is simply equal to the frequency $\omega$. Note that specifying $\vec{k}$ corresponds to a single frequency. Any broadband source is therefore incident at a specified angle for only a *single* frequency. This is described in more detail in Section 4.5 ("Efficient Frequency-Angle Coverage") in [Chapter 4](https://arxiv.org/abs/1301.5366) ("Electromagnetic Wave Source Conditions") of the book [Advances in FDTD Computational Electrodynamics: Photonics and Nanotechnology](https://www.amazon.com/Advances-FDTD-Computational-Electrodynamics-Nanotechnology/dp/1608071707). In this example, $\omega$ is set to the minimum frequency of the pulse to produce propagating fields at all pulse frequencies. In general, any pulse frequencies which are *less* than any non-zero component of $|\vec{k}|$ will result in *evanescent* fields (which are essentially irrelevant in most practical applications).
 
 In this example, the plane of incidence which contains $\vec{k}$ and the surface normal vector is chosen to be $xz$. The source angle $\theta$ is defined in degrees in the counterclockwise (CCW) direction around the $y$ axis with 0 degrees along the $+z$ axis. In Meep, a 1d cell is defined along the $z$ direction. When $\vec{k}$ is not set, only the $E_x$ and $H_y$ field components are permitted. A non-zero $\vec{k}$ results in a 3d simulation where all field components are included and are complex valued (note that the fields are real, by default). A current source with $E_x$ polarization lies within the plane of incidence and corresponds to the convention of $\mathcal{P}$-polarization. In order to model the $\mathcal{S}$-polarization, we must use an $E_y$ source. This example involves just the $\mathcal{P}$-polarization.
 

python/examples/ring_gds.py

@@ -93,8 +93,9 @@ def find_modes(filename,wvl=1.55,bw=0.05):
             until_after_sources=100)
 
     plt.figure()
-    sim.plot2D(fields=mp.Hz)
-    plt.savefig('ring_resonator_Hz.png')
+    sim.plot2D(fields=mp.Hz,
+               eps_parameters={'contour':True})
+    plt.savefig('ring_fields.png',bbox_inches='tight',dpi=150)
 
     wvl = np.array([1/m.freq for m in h.modes])
     Q = np.array([m.Q for m in h.modes])

python/geom.py

@@ -1077,7 +1077,7 @@ class Ellipsoid(Block):
     """
     def __init__(self, **kwargs):
         """
-        Construct an `Ellipsiod`.
+        Construct an `Ellipsoid`.
         """
         super(Ellipsoid, self).__init__(**kwargs)
 

python/simulation.py

@@ -930,14 +930,6 @@ class Simulation(object):
     """
     The `Simulation` [class](#classes) contains all the attributes that you can set to
     control various parameters of the Meep computation.
-
-    #### Output File Names
-
-    The output filenames used by Meep, e.g. for HDF5 files, are automatically prefixed by
-    the `filename_prefix` parameter. If `filename_prefix` is `None` (the default),
-    however, then Meep constructs a default prefix based on the current Python filename
-    with `".py"` replaced by `"-"`: e.g. `test.py` implies a prefix of `"test-"`. You can
-    get this prefix by calling `get_filename_prefix`.
     """
     def __init__(self,
                  cell_size,
@@ -1010,9 +1002,8 @@ def __init__(self,
           optimized. See `dimensions` below. **Note:** because Maxwell's equations are
           scale invariant, you can use any units of distance you want to specify the cell
           size: nanometers, microns, centimeters, etc. However, it is usually convenient
-          to pick some characteristic lengthscale of your problem and set that length to
-          1. See also [Units](Introduction.md#units-in-meep). Required argument (no
-          default).
+          to pick some characteristic lengthscale of your problem and set that length to 1.
+          See also [Units](Introduction.md#units-in-meep). Required argument (no default).
 
         + **`default_material` [`Medium` class ]** — Holds the default material that is
           used for points not in any object of the geometry list. Defaults to `air` (ε=1).
@@ -1125,10 +1116,10 @@ def __init__(self,
           simulate all fields, even those that remain zero throughout the simulation, by
           setting `force_all_components` to `True`.
 
-        + **`filename_prefix` [`string`]** — A string prepended to all output filenames.
-          If empty (the default), then Meep uses the name of the current Python file, with
-          ".py" replaced by "-" (e.g. `foo.py` uses a `"foo-"` prefix). See also [Output
-          File Names](Python_User_Interface.md#output-file-names).
+        + **`filename_prefix` [`string`]** — A string prepended to all output filenames
+          (e.g., for HDF5 files). If `None` (the default), then Meep constructs a default
+          prefix based on the current Python filename ".py" replaced by "-" (e.g. `foo.py`
+          uses a `"foo-"` prefix). You can get this prefix by calling `get_filename_prefix`.
 
         + **`Courant` [`number`]** — Specify the
           [Courant factor](https://en.wikipedia.org/wiki/Courant%E2%80%93Friedrichs%E2%80%93Lewy_condition)
@@ -3858,6 +3849,9 @@ def plot2D(self, ax=None, output_plane=None, fields=None, labels=False,
         plt.savefig('sim_domain.png')
         ```
 
+        Note: When running a [parallel simulation](Parallel_Meep.md), the `plot2D` function expects to be called
+        on all processes, but only generates a plot on the master process.
+
         **Parameters:**
 
         * `ax`: a `matplotlib` axis object. `plot2D()` will add plot objects, like lines,

python/visualization.py

@@ -516,11 +516,11 @@ def plot_fields(sim,ax=None,fields=None,output_plane=None,field_parameters=None)
     return ax
 
 def plot2D(sim,ax=None, output_plane=None, fields=None, labels=False,
-            eps_parameters=None,boundary_parameters=None,
-            source_parameters=None,monitor_parameters=None,
-            field_parameters=None, frequency=None,
-            plot_eps_flag=True, plot_sources_flag=True,
-            plot_monitors_flag=True, plot_boundaries_flag=True):
+           eps_parameters=None,boundary_parameters=None,
+           source_parameters=None,monitor_parameters=None,
+           field_parameters=None, frequency=None,
+           plot_eps_flag=True, plot_sources_flag=True,
+           plot_monitors_flag=True, plot_boundaries_flag=True):
 
     # Initialize the simulation
     if sim.structure is None: