add Python tutorials for material dispersion and third-harmonic generation examples to documentation and other minor fixes

doc/docs/Acknowledgements.md

@@ -5,26 +5,28 @@
 Authors
 ---------------
 
-Meep originated as part of graduate research at MIT with initial contributions by Steven G. Johnson, Ardavan Oskooi, [David Roundy](http://physics.oregonstate.edu/~roundyd/), Mihai Ibanescu, and [Peter Bermel](http://web.ics.purdue.edu/~pbermel/). Currently, the Meep project is maintained by [Simpetus](http://www.simpetus.com) and the open-source community on [GitHub](https://github.com/stevengj/meep).
+Meep originated as part of graduate research at MIT with initial contributions by [Steven G. Johnson](http://math.mit.edu/~stevenj/), [Ardavan Oskooi](http://ab-initio.mit.edu/~oskooi/), [David Roundy](http://physics.oregonstate.edu/~roundyd/), [Mihai Ibanescu](https://www.linkedin.com/in/mihai-ibanescu-2b147825/), and [Peter Bermel](http://web.ics.purdue.edu/~pbermel/). Currently, the Meep project is maintained by [Simpetus](http://www.simpetus.com) and the open-source community on [GitHub](https://github.com/stevengj/meep).
 
 Referencing
 -----------
 
-We kindly request that you use the following reference in any publication for which you use Meep:
+We kindly request that you cite the following reference in any publication for which you use Meep:
 
 - A.F. Oskooi, D. Roundy, M. Ibanescu, P. Bermel, J.D. Joannopoulos, and S.G. Johnson, [MEEP: A flexible free-software package for electromagnetic simulations by the FDTD method](http://dx.doi.org/doi:10.1016/j.cpc.2009.11.008), Computer Physics Communications, vol. 181, pp. 687-702 (2010). ([pdf](http://math.mit.edu/~stevenj/papers/OskooiRo10.pdf))
 
 If you want a one-sentence description of the algorithm for inclusion in a publication, we recommend something like:
 
 - Simulations were performed with the finite-difference time-domain (FDTD) method [ref FDTD], using a freely available software package [ref Meep].
 
-As a general reference on the FDTD method you might use, for example:
+General references on the FDTD method include, for example:
 
-- A. Taflove and S.C. Hagness, Computational Electrodynamics: The Finite-Difference Time-Domain Method, Artech: Norwood, MA, (2005).
+- A. Taflove and S.C. Hagness, [Computational Electrodynamics: The Finite-Difference Time-Domain Method](http://us.artechhouse.com/Computational-Electrodynamics-The-Finite-Difference-Time-Domain-Method-Third-Edition-P1634.aspx), Artech: Norwood, MA, (2005).
+
+- A. Taflove, A. Oskooi, and S.G. Johnson, [Advances in FDTD Computational Electrodynamics: Photonics and Nanotechnology](http://us.artechhouse.com/Advances-in-FDTD-Computational-Electrodynamics-P1567.aspx), Artech: Norwood, MA, (2013).
 
 Financial Support
 -----------------
 
 Meep's continued development has been supported by a Small Business Innovation Research (SBIR) Phase 1 award from the National Science Foundation (NSF) under award number [1647206](https://www.nsf.gov/awardsearch/showAward?AWD_ID=1647206). Initial development was supported in part by the Materials Research Science and Engineering Center program of the NSF under award numbers DMR-9400334 and DMR-0819762, by the Army Research Office through the Institute for Soldier Nanotechnologies under DAAD-19-02-D0002, and DARPA under N00014-05-1-0700 administered by the Office of Naval Research.
 
-We are also grateful to the authors of earlier Fortran FDTD programs that were used in our research group at MIT, which were invaluable as benchmarks in testing our new code. This includes a 2d FDTD code by Jerry Chen, with later improvements by Shanhui Fan, Steven G. Johnson, and others. There was also a 3d code initially written by Shanhui Fan, with later improvements by Daniel Abrams, Doug Allan, SGJ, Chiyan Luo, and Elefterios Lidorikis.
+We are also grateful to the authors of earlier Fortran FDTD programs that were used in our research group at MIT, which were invaluable as benchmarks in testing our new code. This includes a 2d FDTD code by Jerry Chen, with later improvements by Shanhui Fan, Steven G. Johnson, and others. There was also a 3d code initially written by Shanhui Fan, with later improvements by Daniel Abrams, Doug Allan, Steven G. Johnson, Chiyan Luo, and Elefterios Lidorikis.

doc/docs/C++_Tutorial.md

@@ -2,7 +2,7 @@
 # C++ Tutorial
 ---
 
-Instead of using the Scheme interface described in the [Scheme Tutorial](Scheme_Tutorial.md), Meep is also callable as a C++ library by writing a C++ program that links to it. The C++ interface provides the most flexibility in setting up simulations. There are numerous examples in the `tests/` directory of the Meep codebase which cover a wide range of Meep's functionality. These are a good additional reference. Finally, we should also note that, while Meep is nominally in C++, it is perhaps better described as "C+". That is, most of the coding style is C-like with a few C++ features.
+Instead of using the [Scheme interface](Scheme_User_Interface/), Meep is also callable as a C++ library by writing a C++ program that links to it. The C++ interface provides the most flexibility in setting up simulations. There are numerous examples in the `tests/` directory of the Meep codebase which cover a wide range of Meep's functionality. These are a good additional reference. Finally, we should also note that, while Meep is nominally in C++, it is perhaps better described as "C+". That is, most of the coding style is C-like with a few C++ features.
 
 Differences from libctl
 -----------------------
@@ -14,7 +14,7 @@ The most notable difference is that, while the libctl interface puts the origin
 Overview
 --------
 
-We begin with a brief outline of a Meep C++ program, with minimal explanations, leaving more details for the examples below and the [C++ User Interface](C++_User_Interface.md). The C++ program should begin with:
+We begin with a brief outline of a Meep C++ program, with minimal explanations, leaving more details for the examples below and the [C++ interface](C++_User_Interface.md). The C++ program should begin with:
 
 ```c++
 #include <meep.hpp>
@@ -48,7 +48,7 @@ int main(int argc, char **argv) {
 }
 ```
 
-This example doesn't do much — it just runs a Gaussian source and outputs the $\mathbf{H}_z$ field at the end. The dielectric structure is determined by the user-defined function `eps`, which has the form:
+This example doesn't do much &mdash; it just runs a Gaussian source and outputs the $\mathbf{H}_z$ field at the end. The dielectric structure is determined by the user-defined function `eps`, which has the form:
 
 ```c++
 double eps(const vec &p) {
@@ -198,26 +198,26 @@ In order to compile your code and link against the Meep library, you must link i
 
 (1) After compiling the Meep package following the instructions elsewhere, place foo.cpp in the `tests/` subdirectory, cd to the same directory, and invoke:
 
-```
+```sh
 make foo.dac
 ```
 
 Run the resulting executable via:
 
-```
+```sh
 ./foo.dac
 ```
 
 (2) Use the [pkg-config](https://en.wikipedia.org/wiki/pkg-config) program which is installed by default on most Linux systems:
 
-```
+```sh
 ` g++ `pkg-config --cflags meep` foo.cpp -o foo `pkg-config --libs meep` `
 ```
 
 Naturally, replace `g++` with the name of your C++ compiler if you are not using the GNU compilers.
 
 (3) Compile with g++, this time invoking each library separately:
 
-```
+```sh
 g++ -malign-double foo.cpp -o foo -lmeep -lhdf5 -lz -lgsl -lharminv -llapack -lcblas -latlas -lfftw3 -lm
 ```

doc/docs/Download.md

@@ -24,14 +24,14 @@ The current stable version of Meep preinstalled on [Ubuntu](https://en.wikipedia
 Precompiled Meep packages for Ubuntu
 ------------------------------------
 
-Precompiled packages of Meep are available for [Ubuntu](https://en.wikipedia.org/wiki/Ubuntu) as **meep**. The Ubuntu 16.10 package is available in the [science](https://packages.ubuntu.com/yakkety/meep) repository. We highly recommend using Ubuntu as the Meep software and all of its dependencies can be installed using just one line:
+Precompiled packages of Meep are available for [Ubuntu](https://en.wikipedia.org/wiki/Ubuntu) as **meep** via this [list](https://packages.ubuntu.com/search?keywords=meep). We highly recommend using Ubuntu as Meep and all of its dependencies can be installed using just one line:
 
-```
+```sh
 sudo apt-get install meep h5utils
 ```
 
 You can also install the [parallel version of Meep](http://packages.debian.org/testing/science/meep-mpi-default) which is based on [Open MPI](https://www.open-mpi.org/) using:
 
-```
+```sh
 sudo apt-get install meep-mpi-default
 ```

doc/docs/Exploiting_Symmetry.md

@@ -20,10 +20,10 @@ Meep supports exploiting several kinds of symmetries:
 ### Rotations and Reflections
 
 -   Mirror planes through the origin, and normal to the $x$/$y$/$z$ axes.
--   180° rotational symmetry about the origin, around the $x$/$y$/$z$ axes. This is also known as a $C_2$ symmetry, in group theory. (This is different from a mirror plane: e.g. the letter "S" has $C_2$ but not mirror symmetry.)
+-   180° rotational symmetry about the origin, around the $x$/$y$/$z$ axes. This is also known as a $C_2$ symmetry, in group theory. This is different from a mirror plane: e.g. the letter "S" has $C_2$ but not mirror symmetry.
 -   90° (fourfold) rotational symmetry about the origin, around the $x$/$y$/$z$ axes. This is also known as a $C_4$ symmetry.
 
-The first two kinds of symmetry each reduce the computational cell (internally) by a factor of two, and the third by a factor of four. If your structure has multiple symmetries, you can combine them arbitrarily. For example, your cell may have two orthogonal mirror planes (e.g. one even and one odd), or it may have four-fold rotational symmetry about the $z$ axis and a mirror plane through $z=0$. Thus, in 3d you might be able to reduce your computational cell by at most a factor of eight, or a factor of four in 2d. (This is why the ctl interface lets you specify a *list* `symmetries` of `symmetry` objects.)
+The first two kinds of symmetry each reduce the computational cell (internally) by a factor of two, and the third by a factor of four. If your structure has multiple symmetries, you can combine them arbitrarily. For example, your cell may have two orthogonal mirror planes (e.g. one even and one odd), or it may have four-fold rotational symmetry about the $z$ axis and a mirror plane through $z=0$. Thus, in 3d you might be able to reduce your computational cell by at most a factor of eight, or a factor of four in 2d. This is why the interface lets you specify a *list* `symmetries` of `symmetry` objects.
 
 There are also two other kinds of symmetry you can exploit.
 
@@ -45,7 +45,7 @@ In a cylindrical simulation, fields can be written in the form of a function of
 
 If the structure has discrete or continuous translational symmetry in some direction, then this is handled in Meep by specifying periodic boundary conditions in that direction. Here, the fields/sources take the form of $\exp(i\mathbf{k}\cdot\mathbf{x})$ multiplied by a periodic envelope, so one specifies **Bloch-periodic** boundary conditions with a given Bloch wavevector $\mathbf{k}$.
 
-For example, to simulate the modes of a uniform waveguide (continuous translational symmetry) in the $x$ direction, one would specify a structure with `no-size` in the $x$ direction and a given $k_x$ corresponding to the wavenumber of the desired mode. For discrete periodicity, see this [band diagram example](Scheme_Tutorials/Resonant_Modes_and_Transmission_in_a_Waveguide_Cavity.md#band-diagram).
+For example, to simulate the modes of a uniform waveguide (continuous translational symmetry) in the $x$ direction, one would specify a structure with `no-size` in the $x$ direction and a given $k_x$ corresponding to the wavenumber of the desired mode. For discrete periodicity, see [Tutorials/Resonant Modes and Transmission in a Waveguide Cavity/Band Diagram](Scheme_Tutorials/Resonant_Modes_and_Transmission_in_a_Waveguide_Cavity.md#band-diagram).
 
 Symmetry Phase Factors
 ----------------------

doc/docs/FAQ.md

@@ -4,6 +4,8 @@
 
 The following are frequently asked questions about Meep.
 
+[TOC]
+
 General
 -------
 
@@ -20,9 +22,9 @@ Installation
 
 ### Where can I install Meep?
 
-Meep runs on any Unix-like operating system, such as Linux and macOS, from notebooks to desktops to high-performance computing (HPC) clusters. Precompiled packages are available for Ubuntu. Meep can also be installed on Windows using the free [Cygwin](https://en.wikipedia.org/wiki/Cygwin) Unix-compatibility environment.
+Meep runs on any Unix-like operating system, such as Linux and MacOS, from notebooks to desktops to high-performance computing (HPC) clusters. Precompiled packages are available for Ubuntu. Meep can also be installed on Windows using the free [Cygwin](https://en.wikipedia.org/wiki/Cygwin) Unix-compatibility environment.
 
-Installing Meep from source code requires some understanding of Unix, especially to install the various prerequisites. Step-by-step instructions are available for [Ubuntu 16.04](https://www.mail-archive.com/[email protected]/msg05819.html) and [macOS Sierra](https://www.mail-archive.com/[email protected]/msg05811.html).
+Installing Meep from source code requires some understanding of Unix, especially to install the various prerequisites. Step-by-step instructions are available for [Ubuntu 16.04](https://www.mail-archive.com/[email protected]/msg05819.html) and [MacOS Sierra](https://www.mail-archive.com/[email protected]/msg05811.html).
 
 Meep is also available preinstalled on Ubuntu on Amazon Web Services (AWS) Elastic Compute Cloud (EC2) as a free [Amazon Machine Image (AMI)](https://aws.amazon.com/marketplace/pp/B01KHWH0AS). To access this AMI, follow these [instructions](http://www.simpetus.com/launchsims.html).
 
@@ -37,13 +39,13 @@ Physics
 
 There is no simple formula relating the input current amplitude (**J** in Maxwell's equations) to the resulting fields (**E**) etcetera, even at the same point as the current. The exact same current will produce a different field and radiate a different total power depending upon the surrounding materials/geometry, and depending on the frequency. This is a physical consequence of the geometry's effect on the local density of states; it can also be thought of as feedback from reflections on the source. As a simple example, if you put a current source inside a perfect electric conductor, the resulting field will be zero. As another example, the frequency-dependence of the radiated power in vacuum is part of the reason why the sky is blue.
 
-See also our online book chapter on [Wave Source Conditions](http://arxiv.org/abs/arXiv:1301.5366).
+See also this online book chapter on [Wave Source Conditions](http://arxiv.org/abs/arXiv:1301.5366).
 
 If you are worried about this, then you are probably setting up your calculation in the wrong way. Especially in linear materials, the absolute magnitude of the field is useless; the only meaningful quantities are dimensionless ratios like the fractional transmission: the transmitted power relative to the transmitted power in some reference calculation. Almost always, you want to perform two calculations, one of which is a reference, and compute the ratio of a result in one calculation to the result in the reference. For nonlinear calculations, see [Units and Nonlinearity](Units_and_Nonlinearity.md).
 
 ### How do I set the imaginary part of ε?
 
-If you only care about the imaginary part of ε in a narrow bandwidth around some frequency ω, you should set it by using the electric conductivity as described in [Conductivity](Materialsmd#Conductivity). If you care about the imaginary part of ε over a broad bandwidth, then for any physical material the imaginary part will be frequency-dependent and you will have to fit it to Meep's dispersive-ε support. See [Material Dispersion](Materials.md#material-dispersion).
+If you only care about the imaginary part of ε in a narrow bandwidth around some frequency ω, you should set it by using the electric conductivity as described in [Materials](Materials/#conductivity-and-complex). If you care about the imaginary part of ε over a broad bandwidth, then for any physical material the imaginary part will be frequency-dependent and you will have to fit it to Meep's dispersive-ε support. See [Materials](Materials#material-dispersion).
 
 Meep doesn't implement a frequency-independent complex ε. Not only is this not physical, but it also leads to both exponentially decaying and exponentially growing solutions in Maxwell's equations from positive- and negative-frequency Fourier components, respectively. Thus, it cannot be simulated in the time domain.
 
@@ -55,7 +57,7 @@ If you solve Maxwell's equations in a homogeneous-epsilon material at some real
 
 If you do a simulation of any kind in the time domain (not just FDTD), you pretty much can't avoid exciting both the decaying and the growing solutions. This is *not* a numerical instability, it is a real solution of the underlying equations for an unphysical material.
 
-See [Materials](Materials.md) for how to include dispersive materials which can have negative ε and loss.
+See [Materials](Materials/#material-dispersion) for how to include dispersive materials which can have negative $\varepsilon$ and loss.
 
 If you have negative ε *and* negative μ *everywhere*, the case of a negative-index material, then the simulation is fine. However at the boundary between negative- and positive-index materials, you will encounter instabilities: because of the way Maxwell's equations are discretized in FDTD, the ε and μ are discretized on different spatial grids, so you will get a half-pixel or so of εμ < 0 at the boundary between negative and positive indices, which will cause the simulation to diverge. But of course, any physical negative-index metamaterial also involves dispersion.
 
@@ -70,7 +72,7 @@ An official Python interface is currently under development and will likely be r
 
 ### Why doesn't turning off subpixel averaging work?
 
-By default, when Meep assigns a dielectric constant ε or μ to each pixel, it uses a carefully designed average of the ε values within that pixel. This subpixel averaging generally improves the accuracy of the simulation—perhaps counter-intuitively, for geometries with discontinous ε it is *more* accurate (i.e. closer to the exact Maxwell result for the *discontinuous* case) to do the simulation with the subpixel-averaged (*smoothed*) ε, as long as the averaging is done properly. For details, see the [reference publication](License_and_Copyright.md#referencing).
+By default, when Meep assigns a dielectric constant ε or μ to each pixel, it uses a carefully designed average of the ε values within that pixel. This subpixel averaging generally improves the accuracy of the simulation—perhaps counter-intuitively, for geometries with discontinous ε it is *more* accurate (i.e. closer to the exact Maxwell result for the *discontinuous* case) to do the simulation with the subpixel-averaged (*smoothed*) $\varepsilon$, as long as the averaging is done properly. For details, see the [reference publication](Acknowledgements/#referencing).
 
 Still, there are times when, for whatever reason, you might not want this feature. For example, if your accuracy is limited by other issues, or if you want to skip the wait at the beginning of the simulation for it do to the averaging. In this case, you can disable the subpixel averaging by doing `(set! eps-averaging? false)` in your control file. See the [User Interface](Scheme_User_Interface.md).