updates and tweaks to documentation (NanoComp#165)

README.md

@@ -7,7 +7,7 @@
 
 **Meep** is a free finite-difference time-domain (FDTD) simulation software package to model electromagnetic systems. Meep is an acronym which officially stands for *MIT Electromagnetic Equation Propagation*. Its features include:
 
--   **Free software** under the [GNU GPL](https://en.wikipedia.org/wiki/GNU_General_Public_License).
+-   **Free and open-source software** under the [GNU GPL](https://en.wikipedia.org/wiki/GNU_General_Public_License).
 -   Complete **scriptability** via [Python](http://meep.readthedocs.io/en/latest/Python_Tutorials/Basics/), [Scheme](http://meep.readthedocs.io/en/latest/Scheme_Tutorials/Basics), or [C++](C++).
 -   Simulation in **1d, 2d, 3d**, and **cylindrical** coordinates.
 -   Distributed memory **parallelism** on any system supporting the [MPI](https://en.wikipedia.org/wiki/MPI) standard. Portable to any Unix-like operating system such as [Linux](https://en.wikipedia.org/wiki/Linux) and [macOS](https://en.wikipedia.org/wiki/macOS).

doc/docs/Acknowledgements.md

@@ -10,7 +10,7 @@ Meep originated as part of graduate research at MIT with initial contributions b
 Referencing
 -----------
 
-We kindly request that you cite the following reference in any publication for which you use Meep:
+We kindly request that you cite the following reference publication in any work 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://ab-initio.mit.edu/~oskooi/papers/Oskooi10.pdf))
 

doc/docs/C++_Tutorial.md

@@ -2,7 +2,7 @@
 # C++ Tutorial
 ---
 
-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.
+Instead of using the [Python interface](Python_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.
 
 [TOC]
 

doc/docs/Exploiting_Symmetry.md

@@ -8,7 +8,7 @@ An important point to understand is that, when you specify a symmetry, it must b
 
 **Meep does not check whether the symmetry is obeyed**. If you specify a symmetry that does not preserve your structure/sources, then the results are undefined.
 
-For the Scheme syntax to specify a symmetry, see the [symmetry reference](Scheme_User_Interface.md#symmetry). There are also examples in [Tutorial/Basics](Python_Tutorials/Basics/#exploiting-symmetry).
+For the Python syntax to specify a symmetry, see the [symmetry reference](Python_User_Interface.md#symmetry). There are also examples in [Tutorial/Basics](Python_Tutorials/Basics/#exploiting-symmetry).
 
 [TOC]
 

doc/docs/FAQ.md

@@ -74,13 +74,13 @@ Usage
 
 ### Is there a Python interface?
 
-An official Python interface is currently under development and will likely be released by the end of 2017. An unofficial [Python interface](https://github.com/FilipDominec/python-meep-utils) has been independently developed by researchers at the Institute of Physics at the Czech Academy of Sciences and Ghent University. Unfortunately, this interface has a number of shortcomings including missing support for geometric objects, lack of high-level abstractions for low-level functionality, and limited documentation. These will all be addressed in the official interface.
+An official Python interface is currently under development and will be released in early 2018. An unofficial [Python interface](https://github.com/FilipDominec/python-meep-utils) has been developed independently by researchers at the Institute of Physics at the Czech Academy of Sciences and Ghent University. Unfortunately, this interface has a number of shortcomings including missing support for geometric objects, lack of high-level abstractions for low-level functionality, and limited documentation. These will all be addressed in the official interface.
 
 ### Why doesn't turning off subpixel averaging work?
 
 By default, when Meep assigns a dielectric constant $\varepsilon$ or $\mu$ to each pixel, it uses a carefully designed average of the $\varepsilon$ values within that pixel. This subpixel averaging generally improves the accuracy of the simulation — perhaps counter-intuitively, for geometries with discontinous $\varepsilon$ 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 setting `eps_averaging = False` via the `Simulation` instance (Python) or `(set! eps-averaging? false)` (Scheme) in your script file. See the [User Interface](Python_User_Interface.md).
+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 setting `eps_averaging = False` via the `Simulation` class (Python) or `(set! eps-averaging? false)` (Scheme) in your script file. See the [User Interface](Python_User_Interface.md).
 
 Even if you disable the subpixel averaging, however, when you output the dielectric function to a file and plot it, you may notice that there are some pixels with intermediate $\varepsilon$ values, right at the boundary between two materials. This has a completely different source. Internally, Meep's simulation is performed on a [Yee grid](Yee_Lattice.md), in which every field component is stored on a slightly different grid which are offset from one another by half-pixels, and the $\varepsilon$ values are also stored on this Yee grid. For output purposes, however, it is more user-friendly to output all fields etcetera on the same grid at the center of each pixel, so all quantities are interpolated onto this grid for output. Therefore, even though the internal $\varepsilon$ values are indeed discontinuous when you disable subpixel averaging, the *output* file will still contain some "averaged" values at interfaces due to the interpolation from the Yee grid to the center-pixel grid.
 

doc/docs/Field_Function_Examples.md

@@ -2,53 +2,88 @@
 # Field Function Examples
 ---
 
-As described in the [User Interface](Scheme_User_Interface.md), Meep provides several routines to integrate, analyze, and output arbitrary user-specified functions of the field components. See the functions whose names end with `-field-function`. This facility, while powerful, requires a bit more Scheme programming than most Meep usage, and is best illustrated by a few examples.
+As described in the [User Interface](Python_User_Interface.md), Meep provides several routines to integrate, analyze, and output arbitrary user-specified functions of the field components. See the functions whose names end with `_field_function`. This facility, while powerful, requires a bit more programming than most Meep usage, and is best illustrated by a few examples.
 
 Every field-function that can be passed to these routines is of the form *f*(**r**,components...), where **r** is a position vector and "components..." are zero or more field components that the function depends on. The set of desired components is user-specified. As an arbitrary example, suppose we are interested in the strange function:
 
 $$f(\mathbf{r}, E_x, H_z, \varepsilon) = x |\mathbf{r}| + E_x - \varepsilon H_z$$
 
-We would define this function, in Scheme, by:
+We would define this function by:
 
+
+*Python*
+```py
+def f(r, ex, hz, eps):
+    return (r.x * r.norm() + ex) - (eps * hz)
+```
+
+*Scheme*
 ```scm
 (define (f r ex hz eps)
    (- (+ (* (vector3-x r) (vector3-norm r)) ex) (* eps hz)))
 ```
 
-Note that the `r` argument is a `vector3`, and can be manipulated by the functions defined in the [Libctl User Reference](https://libctl.readthedocs.io/en/latest/Libctl_User_Reference/).
+Note that the `r` argument is a `Vector3` (Python) or `vector3` (Scheme), and can be manipulated by the functions defined in the [Libctl User Reference](https://libctl.readthedocs.io/en/latest/Libctl_User_Reference/).
 
-Now, suppose we want to compute the integral of this function, over the whole computational cell. We can do this by calling the function `integrate-field-function`, as follows:
+Now, suppose we want to compute the integral of this function, over the whole computational cell. We can do this by calling the function `integrate_field_function` (Python) or `integrate-field-function` (Scheme), as follows:
 
+*Python*
+```py
+print("The integral of our weird function is: {}"
+	   .format(meep.Simulation.integrate_field_function([meep.Ex, meep.Hz, meep.Dielectric], f)))
+```
+
+*Scheme*
 ```scm
-(print "The integral of our weird function is: "
-       (integrate-field-function (list Ex Hz Dielectric) f) "\n")
+(print "The integral of our weird function is: "
+       (integrate-field-function (list Ex Hz Dielectric) f) "\n")
 ```
 
-Note that the first argument to `integrate-field-function` is a `list` (a standard Scheme type) of `component` constants, specifying in order the list of field components our function `f` expects to be passed. Meep will then call `f` for every point in the computational cell in parallel on a parallel machine, and return the integral approximated by a [trapezoidal rule](https://en.wikipedia.org/wiki/trapezoidal_rule).
+Note that the first argument to `integrate_field_function` (Python) or `integrate-field-function` (Scheme) is a list (a standard Python/Scheme type) of `component` constants, specifying in order the list of field components our function `f` expects to be passed. Meep will then call `f` for every point in the computational cell in parallel on a parallel machine, and return the integral approximated by a [trapezoidal rule](https://en.wikipedia.org/wiki/trapezoidal_rule).
 
-You can also specify an optional third argument to `integrate-field-function`, specifying an integration volume in case you don't want the integral over the whole computational cell. For example, the following code computes the integral of `f` along a line from (-1,0,0) to (1,0,0):
+You can also specify an optional third argument to `integrate_field_function` or `integrate-field-function`, specifying an integration volume in case you don't want the integral over the whole computational cell. For example, the following code computes the integral of `f` along a line from (-1,0,0) to (1,0,0):
 
+*Python*
+```py
+print("The integral of our weird function from (-1,0,0) to (1,0,0) is: {}"
+	   .format(meep.Simulation.integrate_field_function([meep.Ex, meep.Hz, meep.Dielectric], f, meep.Volume(size=meep.Vector3(1), center=meep.Vector3()))))
+```
+
+*Scheme*
 ```scm
 (print "The integral of our weird function from (-1,0,0) to (1,0,0) is: "
        (integrate-field-function (list Ex Hz Dielectric) f (volume (size 1 0 0) (center 0 0 0))) "\n")
 ```
 
 Instead of computing the integral, Meep also provides a function to compute the maximum absolute value of our given function:
 
+*Python*
+```py
+print("The maximum absolute value of our weird function from (-1,0,0) to (1,0,0) is: {}"
+	   .format(meep.Simulation.max_abs_field_function([meep.Ex, meep.Hz, meep.Dielectric], f, meep.Volume(size=meep.Vector3(1), center=meep.Vector3()))))
+```
+
+*Scheme*
 ```scm
 (print "The maximum absolute value of our weird function from (-1,0,0) to (1,0,0) is: "
        (max-abs-field-function (list Ex Hz Dielectric) f (volume (size 1 0 0) (center 0 0 0))) "\n")
 ```
 
 Finally, we can also output our function to an HDF5 file, similar to the built-in functions to output selected field components, and so on. The following outputs an HDF5 file consisting of our function `f` evaluated at every point in the computational cell:
 
+*Python*
+```py
+meep.Simulation.output_field_function("weird-function", [meep.Ex, meep.Hz, meep.Dielectric], f)
+```
+
+*Scheme*
 ```scm
 (output-field-function "weird-function" (list Ex Hz Dielectric) f)
 ```
 
-Here, the first argument is used for the name of the dataset within the HDF5, and is also used for the name of the HDF5 file itself plus a `.h5` suffix and a time stamp, unless you have specified the output file via `to-appended` or other means.
+Here, the first argument is used for the name of the dataset within the HDF5, and is also used for the name of the HDF5 file itself plus a `.h5` suffix and a time stamp, unless you have specified the output file via `to_appended` or `to-appended` or other means.
 
-The above example calls the integration, maximum, and output routines only once, at the current time. Often, you will want to pass them to `run-until` instead, using `at-every` to print or output at periodic time intervals. A common mistake is to do something like the following:
+The above example calls the integration, maximum, and output routines only once, at the current time. Often, you will want to pass them to `meep.Simulation.run(..., until=...)` (Python) or `run-until` (Scheme) instead, using `at_every` or `at-every` to print or output at periodic time intervals. In Scheme, a common mistake is to do something like the following:
 
 ```scm
 (run-until 200 (at-every 1 (output-field-function "weird-function" (list Ex Hz Dielectric) f)))
@@ -69,4 +104,4 @@ As described in [Synchronizing the Magnetic and Electric Fields](Synchronizing_t
 (run-until 200 (synchronized-magnetic (at-every 1 my-weird-output)))
 ```
 
-See also the section [writing your own step functions](Scheme_User_Interface.md#writing-your-own-step-functions).
+See also the section "Writing Your Own Step Functions" in the [Python](Python_User_Interface.md#writing-your-own-step-functions) or [Scheme](Scheme_User_Interface.md#writing-your-own-step-functions) interface.

doc/docs/License_and_Copyright.md

@@ -2,7 +2,7 @@
 # License and Copyright
 ---
 
-Meep is copyright © 2005–2017, Massachusetts Institute of Technology.
+Meep is copyright © 2005–2018, Massachusetts Institute of Technology.
 
 Meep is free software. You can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or at your option any later version.
 

doc/docs/Materials.md

@@ -8,7 +8,7 @@ However, $\varepsilon$ is not only a function of position. In general, it also d
 
 Similarly for the relative permeability $\mu$(**r**), for which dispersion, nonlinearity, and anisotropy are all supported as well.
 
-In this section, we describe the form of the equations and material properties that Meep can simulate. The actual user interface where these properties are specified is described in the [User Interface](Scheme_User_Interface.md). 
+In this section, we describe the form of the equations and material properties that Meep can simulate. The actual user interface where these properties are specified is described in the [User Interface](Python_User_Interface.md). 
 
 [TOC]
 
@@ -80,7 +80,7 @@ Often, you only care about the absorption loss in a narrow bandwidth, where you
 
 One approach to this problem would be allowing you to specify a constant, frequency-independent, imaginary part of $\varepsilon$, but this has the disadvantage of requiring the simulation to employ complex fields which double the memory and time requirements, and also tends to be numerically unstable. Instead, the approach in Meep is for you to set the conductivity $\sigma_D$ (or $\sigma_B$ for an imaginary part of $\mu$), chosen so that $\mathrm{Im}\, \varepsilon = \varepsilon_\infty \sigma_D / \omega$ is the correct value at your frequency $\omega$ of interest. Note that, in Meep, you specify $f = \omega/2\pi$ instead of $\mu$ for the frequency, however, so you need to include the factor of 2$\pi$ when computing the corresponding imaginary part of $\varepsilon$. Conductivities can be implemented with purely real fields, so they are not nearly as expensive as implementing a frequency-independent complex $\varepsilon$ or $\mu$.
 
-For example, suppose you want to simulate a medium with $\varepsilon = 3.4 + 0.101i$ at a frequency 0.42 (in your Meep units), and you only care about the material in a narrow bandwidth around this frequency (i.e. you don't need to simulate the full experimental frequency-dependent permittivity). Then, in Meep, you could use `(make medium (epsilon 3.4) (D-conductivity (/ (* 2 pi 0.42 0.101) 3.4))`; i.e. $\varepsilon_\infty = \mathrm{Re}\,\varepsilon = 3.4$ and $\sigma_D = \omega \mathrm{Im} \varepsilon / \varepsilon_\infty = (2\pi 0.42) 0.101 / 3.4$.
+For example, suppose you want to simulate a medium with $\varepsilon = 3.4 + 0.101i$ at a frequency 0.42 (in your Meep units), and you only care about the material in a narrow bandwidth around this frequency (i.e. you don't need to simulate the full experimental frequency-dependent permittivity). Then, in Meep, you could use `meep.Medium(epsilon=3.4, D_conductivity=2*math.pi*0.42*0.101/3.4)`; i.e. $\varepsilon_\infty = \mathrm{Re}\,\varepsilon = 3.4$ and $\sigma_D = \omega \mathrm{Im} \varepsilon / \varepsilon_\infty = (2\pi 0.42) 0.101 / 3.4$.
 
 **Note**: the "conductivity" in Meep is slightly different from the conductivity you might find in a textbook, because for computational convenience it appears as $\sigma_D \mathbf{D}$ in our Maxwell equations rather than the more-conventional $\sigma \mathbf{E}$; this just means that our definition is different from the usual electric conductivity by a factor of $\varepsilon$. Also, just as Meep uses the dimensionless relative permittivity for $\varepsilon$, it uses nondimensionalized units of 1/*a* (where *a* is your unit of distance) for the conductivities $\sigma_{D,B}$. If you have the electric conductivity $\sigma$ in SI units and want to convert to $\sigma_D$ in Meep units, you can simply use the formula: $\sigma_D = (a/c) \sigma / \varepsilon_r \varepsilon_0$ where *a* is your unit of distance in meters, *c* is the vacuum speed of light in m/s, $\varepsilon_0$ is the SI vacuum permittivity, and $\varepsilon_r$ is the real relative permittivity.