documentation for kz_2d for Python interface (NanoComp#1047)

* documentation for kz_2d for Python interface

* Update Python_User_Interface.md

doc/docs/Python_User_Interface.md

@@ -29,7 +29,7 @@ class Simulation(object):
                  default_material=mp.Medium(),
                  m=0,
                  k_point=False,
-                 special_kz=False,
+                 kz_2d="complex",
                  extra_materials=[],
                  material_function=None,
                  epsilon_func=None,
@@ -113,9 +113,10 @@ Specifies the computational grid resolution in pixels per distance unit. Require
 —
 If `False` (the default), then the boundaries are perfect metallic (zero electric field). If a `Vector3`, then the boundaries are Bloch-periodic: the fields at one side are $\exp(i\mathbf{k}\cdot\mathbf{R})$ times the fields at the other side, separated by the lattice vector $\mathbf{R}$. A non-zero `Vector3` will produce complex fields. The `k_point` vector is specified in Cartesian coordinates in units of 2π/distance. Note: this is *different* from [MPB](https://mpb.readthedocs.io), equivalent to taking MPB's `k_points` through its function `reciprocal->cartesian`.
 
-**`special_kz` [`boolean`]**
+**`kz_2d` [`"complex"`, `"real/imag"`, or `"3d"`]**
 —
-By default, a 2d cell (i.e., `dimensions=2`) combined with a `k_point` that has a *non-zero* component in $z$ results in a 3d simulation with complex fields. However, by setting `special_kz` to `True`, Meep will use a 2d cell and real fields (if the $x$ and $y$ components of `k_point` are zero) which improves performance.
+A 2d cell (i.e., `dimensions=2`) combined with a `k_point` that has a *non-zero* component in $z$ would normally result in a 3d simulation with complex fields. However, by default (`kz_2d="complex"`), Meep will use a 2d computational cell in which $k_z$ is incorporated as an additional term in Maxwell's equations, which still results in complex fields but greatly improved performance.
+Setting `kz_2d="3d"` will instead use a 3d cell that is one pixel thick (with Bloch-periodic boundary conditions), which is considerably more expensive. The third possibility, `kz_2d="real/imag"`, saves an additional factor of two by storing some field components as purely real and some as purely imaginary in a "real" field, but this option requires some care to use and will be explained elsewhere in the future.
 
 **`ensure_periodicity` [`boolean`]**
 —