add 2 FAQs and update docs (#880)

* add 1 FAQ and update docs

* updates

* add FAQ on chirped pulse (including 1 figure) and --with-openmp to build instructions

* Scheme version of linear-chirped pulse example

* tweaks

* Update FAQ.md

doc/docs/Build_From_Source.md

@@ -246,8 +246,7 @@ By default, Meep's configure script tries to guess the gcc `-march` flag for the
 
 **`--with-openmp`**
 —
-This flag enables some experimental support for [OpenMP](https://en.wikipedia.org/wiki/OpenMP) multithreading parallelism on multi-core machines (*instead* of MPI, or in addition to MPI if you have multiple processor cores per MPI process).  Currently, only multi-frequency `near2far` calculations are sped up this way, but in the future we [hope to add](https://github.com/NanoComp/meep/issues/228) additional OpenMP parallelism.   (When you run Meep, you can first set the `OMP_NUM_THREADS` environment variable to the number of threads you want OpenMP to use.)
-
+This flag enables some experimental support for [OpenMP](https://en.wikipedia.org/wiki/OpenMP) multithreading parallelism on multi-core machines (*instead* of MPI, or in addition to MPI if you have multiple processor cores per MPI process). Currently, only multi-frequency `near2far` calculations are sped up this way, but in the future we [hope to add](https://github.com/NanoComp/meep/issues/228) additional OpenMP parallelism. When you run Meep, you can first set the `OMP_NUM_THREADS` environment variable to the number of threads you want OpenMP to use.
 
 ### Building From Source
 
@@ -334,8 +333,7 @@ pip3 install --user --no-binary=h5py h5py
 cd ~/install
 git clone https://github.com/NanoComp/meep.git
 cd meep/
-sh autogen.sh --enable-shared --with-mpi PYTHON=python3 \
-    LDFLAGS="${MY_LDFLAGS}" CPPFLAGS="${MY_CPPFLAGS}"
+sh autogen.sh --enable-shared --with-mpi --with-openmp PYTHON=python3 LDFLAGS="${MY_LDFLAGS}" CPPFLAGS="${MY_CPPFLAGS}"
 make && sudo make install
 ```
 
@@ -496,7 +494,7 @@ sudo /usr/local/bin/python3 setup.py install
 cd ~/install
 git clone https://github.com/NanoComp/meep.git
 cd meep/
-sh autogen.sh --enable-shared --with-mpi PYTHON=python3 MPICC=/usr/local/bin/mpicc MPICXX=/usr/local/bin/mpic++ LDFLAGS="${MY_LDFLAGS}" CPPFLAGS="${MY_CPPFLAGS}"
+sh autogen.sh --enable-shared --with-mpi --with-openmp PYTHON=python3 MPICC=/usr/local/bin/mpicc MPICXX=/usr/local/bin/mpic++ LDFLAGS="${MY_LDFLAGS}" CPPFLAGS="${MY_CPPFLAGS}"
 make -j
 sudo make install
 ```

doc/docs/Installation.md

@@ -7,9 +7,9 @@
 Building from Source
 --------------------
 
-Building Meep directly from the source code can be challenging for users unfamiliar with building Unix software, mainly because of the many prerequisites that must be installed combined with the need to tell Meep's build scripts where to find these prerequisites.
+Building Meep directly from the source code can be challenging for users unfamiliar with building Unix software. This is mainly because of the numerous prerequisites that must be installed as well as the need to specify in the build scripts where these packages are to be found.
 
-Meep's build systems uses the standard [GNU Autotools](https://en.wikipedia.org/wiki/GNU_Build_System) `./configure && make && make install` machinery, but requires a number of prerequisites in order to obtain a full-featured Meep installation: [MPB](http://mpb.readthedocs.io/en/latest/), [Libctl](https://github.com/NanoComp/libctl), [Harminv](https://github.com/NanoComp/harminv), [libGDSII](https://github.com/HomerReid/libGDSII), [MPI](https://en.wikipedia.org/wiki/Message_Passing_Interface), [HDF5](https://support.hdfgroup.org/HDF5/), [Python](https://www.python.org/), and [Guile](https://www.gnu.org/software/guile/). MPB and Harminv, in turn, require [LAPACK and BLAS](http://www.netlib.org/lapack/lug/node11.html) and [FFTW](http://fftw.org/) to be installed.
+Meep's build systems uses the standard [GNU Autotools](https://en.wikipedia.org/wiki/GNU_Build_System) `./configure && make && make install` machinery, but requires a number of prerequisites in order to obtain a full-featured Meep installation: [MPB](http://mpb.readthedocs.io/en/latest/), [Libctl](https://github.com/NanoComp/libctl), [Harminv](https://github.com/NanoComp/harminv), [libGDSII](https://github.com/HomerReid/libGDSII), [MPI](https://en.wikipedia.org/wiki/Message_Passing_Interface), [OpenMP](https://en.wikipedia.org/wiki/OpenMP), [HDF5](https://support.hdfgroup.org/HDF5/), [Python](https://www.python.org/), and [Guile](https://www.gnu.org/software/guile/). MPB and Harminv, in turn, require [LAPACK and BLAS](http://www.netlib.org/lapack/lug/node11.html) and [FFTW](http://fftw.org/) to be installed.
 
 Gzipped tarballs of stable versions of the source are available on the [releases page](https://github.com/NanoComp/meep/releases), and you can also do a `git clone` of the master branch of the [Meep repository on Github](https://github.com/NanoComp/meep) if you have Autotools installed. For more information, see [Build From Source](Build_From_Source.md).
 

doc/docs/Perfectly_Matched_Layer.md

@@ -11,7 +11,7 @@ For a more detailed discussion of PMLs in Meep, see Chapter 5 ("Rigorous PML Val
 -   [Notes on Perfectly Matched Layers](http://math.mit.edu/~stevenj/18.369/pml.pdf) by S. G. Johnson: a general introduction to PML concepts
 -   [J. Computational Physics, Vol. 230, pp. 2369-77, 2011](http://math.mit.edu/~stevenj/papers/OskooiJo11.pdf): a description of the precise PML formulation that is used in Meep, which is slightly different from many PML formulations described elsewhere in order to properly handle arbitrary anisotropy. This paper also describes a general strategy to validate PML.
 
-As shown in the figure below, there are two important cases involving *inhomogeneous* media where the fundamental coordinate stretching idea behind PML breaks down giving rise to reflection artifacts. The workaround is to replace the PML with an adiabatic [absorber](Python_User_Interface.md#absorber). Additionally, if you operate near a low-group velocity band edge in a periodic media, you may need to make the PML/absorber very thick (overlapping many periods) to be effective. For a more details on why PML breaks down in these cases, see [Optics Express, Vol. 16, pp. 11376-92, 2008](http://www.opticsinfobase.org/abstract.cfm?URI=oe-16-15-11376). Also, [Physical Review E, Vol. 79, 065601, 2011](http://math.mit.edu/~stevenj/papers/LohOs09.pdf) describes a separate case where PML fails involving backward-wave modes which may occur at metal-dielectric interfaces (i.e., [surface-plasmon polaritons](https://en.wikipedia.org/wiki/Surface_plasmon_polariton)).
+As shown in the figure below, there are two important cases involving *inhomogeneous* media where the fundamental coordinate stretching idea behind PML breaks down giving rise to reflection artifacts. The workaround is to replace the PML with an adiabatic [absorber](Python_User_Interface.md#absorber). Additionally, if you operate near a low-group velocity band edge in a periodic media, you may need to make the PML/absorber very thick (overlapping many periods) to be effective. For more details on why PML breaks down in these cases, see [Optics Express, Vol. 16, pp. 11376-92, 2008](http://www.opticsinfobase.org/abstract.cfm?URI=oe-16-15-11376). Also, [Physical Review E, Vol. 79, 065601, 2011](http://math.mit.edu/~stevenj/papers/LohOs09.pdf) describes a separate case where PML fails involving backward-wave modes which may occur at metal-dielectric interfaces (i.e., [surface-plasmon polaritons](https://en.wikipedia.org/wiki/Surface_plasmon_polariton)).
 
 <center>
 ![](images/PML_failure.png)

doc/docs/Python_User_Interface.md

@@ -300,13 +300,13 @@ List of dispersive susceptibilities (see below) added to the permeability μ in
 —
 Transforms `epsilon`, `mu`, and `sigma` of any [susceptibilities](#susceptibility) by the 3×3 matrix `M`. If `M` is a [rotation matrix](https://en.wikipedia.org/wiki/Rotation_matrix), then the principal axes of the susceptibilities are rotated by `M`.  More generally, the susceptibilities χ are transformed to MχMᵀ/|det M|, which corresponds to [transformation optics](http://math.mit.edu/~stevenj/18.369/coordinate-transform.pdf) for an arbitrary curvilinear coordinate transformation with Jacobian matrix M. The absolute value of the determinant is to prevent inadvertent construction of left-handed materials, which are [problematic in nondispersive media](FAQ.md#why-does-my-simulation-diverge-if-0).
 
-**`epsilon(freq` [ scalar, list, or `numpy` array, ]`)`**
+**`epsilon(f)`**
 —
-Calculates the medium's permittivity tensor as a 3x3 `numpy` array at the specified frequency, `freq`. Either a scalar, list, or `numpy` array of frequencies may be supplied. In the case `N` frequency points, a `numpy` array size Nx3x3 is returned.
+Returns the medium's permittivity tensor as a 3x3 Numpy array at the specified frequency `f` which can be either a scalar, list, or Numpy array. In the case of a list/array of N frequency points, a Numpy array of size Nx3x3 is returned.
 
-**`mu(freq` [ scalar, list, or `numpy` array, ]`)`**
+**`mu(f)`**
 —
-Calculates the medium's permeability tensor as a 3x3 `numpy` array at the specified frequency, `freq`. Either a scalar, list, or `numpy` array of frequencies may be supplied. In the case `N` frequency points, a `numpy` array size Nx3x3 is returned.
+Returns the medium's permeability tensor as a 3x3 Numpy array at the specified frequency `f` which can be either a scalar, list, or Numpy array. In the case of a list/array of N frequency points, a Numpy array of size Nx3x3 is returned.
 
 **material functions**
 
@@ -880,7 +880,7 @@ where $G(t)$ is the current (not the dipole moment). In this formula, $\Delta f$
 
 ### CustomSource
 
-A user-specified source function $f(t)$. You can also specify start/end times at which point your current is set to zero whether or not your function is actually zero. These are optional, but you must specify an `end_time` explicitly if you want `run` functions like `until_after_sources` to work, since they need to know when your source turns off.
+A user-specified source function $f(t)$. You can also specify start/end times at which point your current is set to zero whether or not your function is actually zero. These are optional, but you must specify an `end_time` explicitly if you want `run` functions like `until_after_sources` to work, since they need to know when your source turns off. For a demonstration of a [linear-chirped pulse](FAQ.md#how-do-i-create-a-chirped-pulse), see [`examples/chirped_pulse.py`](https://github.com/NanoComp/meep/blob/master/python/examples/chirped_pulse.py).
 
 **`src_func` [`function`]**
 —

doc/docs/Scheme_User_Interface.md

@@ -701,7 +701,7 @@ How many `width`s the current decays for before we cut it off and set it to zero
 
 ### custom-src
 
-A user-specified source function $f(t)$. You can also specify start/end times at which point your current is set to zero whether or not your function is actually zero. These are optional, but you must specify an `end-time` explicitly if you want functions like `run-sources` to work, since they need to know when your source turns off.
+A user-specified source function $f(t)$. You can also specify start/end times at which point your current is set to zero whether or not your function is actually zero. These are optional, but you must specify an `end-time` explicitly if you want functions like `run-sources` to work, since they need to know when your source turns off. For a demonstration of a [linear-chirped pulse](FAQ.md#how-do-i-create-a-chirped-pulse), see [`examples/chirped-pulse.ctl`](https://github.com/NanoComp/meep/blob/master/scheme/examples/chirped-pulse.ctl).
 
 **`src-func` [`function`]**
 —

python/examples/chirped_pulse.py

@@ -0,0 +1,36 @@
+## linear-chirped pulse planewave with higher frequencies at the front (down-chirp)
+
+import meep as mp
+import numpy as np
+
+resolution = 40
+
+dpml = 2
+pml_layers = [mp.PML(thickness=dpml,direction=mp.X)]
+
+sx = 40
+sy = 6
+cell_size = mp.Vector3(sx+2*dpml,sy)
+
+v0 = 1.0  # pulse center frequency
+a = 0.2   # Gaussian envelope half-width
+b = -0.5  # linear chirp rate (positive: up-chirp, negative: down-chirp)
+t0 = 15   # peak time
+
+chirp = lambda t: np.exp(1j*2*np.pi*v0*(t-t0)) * np.exp(-a*(t-t0)**2+1j*b*(t-t0)**2)
+
+sources = [mp.Source(src=mp.CustomSource(src_func=chirp),
+                     center=mp.Vector3(-0.5*sx),
+                     size=mp.Vector3(y=sy),
+                     component=mp.Ez)]
+
+sim = mp.Simulation(cell_size=cell_size,
+                    boundary_layers=pml_layers,
+                    resolution=resolution,
+                    k_point=mp.Vector3(),
+                    sources=sources,
+                    symmetries=[mp.Mirror(mp.Y)])
+
+sim.run(mp.in_volume(mp.Volume(center=mp.Vector3(), size=mp.Vector3(sx,sy)),
+                     mp.at_every(2.7, mp.output_efield_z)),
+        until=t0+50)

python/materials.py

@@ -259,7 +259,7 @@
 Ag_gam4 = 0.916*eV_um_scale
 Ag_sig4 = Ag_f4*Ag_plasma_frq**2/Ag_frq4**2
 Ag_f5 = 5.646
-Ag_frq5 = 20.29*eV_um_scale      
+Ag_frq5 = 20.29*eV_um_scale      # 0.061 um
 Ag_gam5 = 2.419*eV_um_scale
 Ag_sig5 = Ag_f5*Ag_plasma_frq**2/Ag_frq5**2
 
@@ -299,7 +299,7 @@
 Au_gam4 = 2.494*eV_um_scale
 Au_sig4 = Au_f4*Au_plasma_frq**2/Au_frq4**2
 Au_f5 = 4.384
-Au_frq5 = 13.32*eV_um_scale
+Au_frq5 = 13.32*eV_um_scale      # 0.093 um
 Au_gam5 = 2.214*eV_um_scale
 Au_sig5 = Au_f5*Au_plasma_frq**2/Au_frq5**2
 

scheme/examples/chirped-pulse.ctl

@@ -0,0 +1,28 @@
+;; linear-chirped pulse planewave with higher frequencies at the front (down-chirp)
+
+(set-param! resolution 40)
+
+(define-param dpml 2)
+(set! pml-layers (list (make pml (thickness dpml) (direction X))))
+
+(define-param sx 40)
+(define-param sy 6)
+
+(set! geometry-lattice (make lattice (size (+ sx (* 2 dpml)) sy no-size)))
+
+(define-param v0 1.0) ; pulse center frequency
+(define-param a 0.2)  ; Gaussian envelope half-width
+(define-param b -0.5) ; linear chirp rate (positive: up-chirp, negative: down-chirp)
+(define-param t0 15)  ; peak time
+
+(define chirp (lambda (t) (* (exp (* 0+1i 2 pi v0 (- t t0))) (exp (+ (* (- a) (sqr (- t t0))) (* 0+1i b (sqr (- t t0))))))))
+
+(set! sources (list (make source
+                      (src (make custom-src (src-func chirp)))
+                      (center (* -0.5 sx) 0 0)
+                      (size 0 sy 0)
+                      (component Ez))))
+
+(set! k-point (vector3 0 0 0))
+
+(run-until (+ t0 50) (in-volume (volume (center 0 0 0) (size sx sy 0)) (at-every 2.7 output-efield-z)))

scheme/materials.scm

@@ -260,6 +260,11 @@
 (define Ag-gam4 (* 0.916 eV-um-scale))
 (define Ag-sig4 (/ (* Ag-f4 (sqr Ag-plasma-frq)) (sqr Ag-frq4)))
 
+(define Ag-f5 5.646)
+(define Ag-frq5 (* 20.29 eV-um-scale)) ; 0.061 um
+(define Ag-gam5 (* 2.419 eV-um-scale))
+(define Ag-sig5 (/ (* Ag-f5 (sqr Ag-plasma-frq)) (sqr Ag-frq5)))
+
 (define Ag (make medium (epsilon 1.0)
   (E-susceptibilities
      (make drude-susceptibility
@@ -271,7 +276,9 @@
      (make lorentzian-susceptibility
        (frequency Ag-frq3) (gamma Ag-gam3) (sigma Ag-sig3))
      (make lorentzian-susceptibility
-       (frequency Ag-frq4) (gamma Ag-gam4) (sigma Ag-sig4)))))
+       (frequency Ag-frq4) (gamma Ag-gam4) (sigma Ag-sig4))
+     (make lorentzian-susceptibility
+       (frequency Ag-frq5) (gamma Ag-gam5) (sigma Ag-sig5)))))
 
 ;------------------------------------------------------------------
 ; gold (Au)
@@ -303,6 +310,11 @@
 (define Au-gam4 (* 2.494 eV-um-scale))
 (define Au-sig4 (/ (* Au-f4 (sqr Au-plasma-frq)) (sqr Au-frq4)))
 
+(define Au-f5 4.384)
+(define Au-frq5 (* 13.32 eV-um-scale)) ; 0.093 um
+(define Au-gam5 (* 2.214 eV-um-scale))
+(define Au-sig5 (/ (* Au-f5 (sqr Au-plasma-frq)) (sqr Au-frq5)))
+
 (define Au (make medium (epsilon 1.0)
   (E-susceptibilities
      (make drude-susceptibility
@@ -314,7 +326,9 @@
      (make lorentzian-susceptibility
        (frequency Au-frq3) (gamma Au-gam3) (sigma Au-sig3))
      (make lorentzian-susceptibility
-       (frequency Au-frq4) (gamma Au-gam4) (sigma Au-sig4)))))
+       (frequency Au-frq4) (gamma Au-gam4) (sigma Au-sig4))
+     (make lorentzian-susceptibility
+       (frequency Au-frq5) (gamma Au-gam5) (sigma Au-sig5)))))
 
 ;------------------------------------------------------------------
 ; copper (Cu)