Python User Interface#

All Simulation attributes are described in further detail below. In brackets after each variable is the type of value that it should hold. The classes, complex datatypes like GeometricObject, are described in a later subsection. The basic datatypes, like integer, boolean, complex, and string are defined by Python. Vector3 is a meep class.

• geometry [ list of GeometricObject class ] — Specifies the geometric objects making up the structure being simulated. When objects overlap, later objects in the list take precedence. Defaults to no objects (empty list).

• geometry_center [ Vector3 class ] — Specifies the coordinates of the center of the cell. Defaults to (0, 0, 0), but changing this allows you to shift the coordinate system used in Meep (for example, to put the origin at the corner). Passing geometry_center=c is equivalent to adding the c vector to the coordinates of every other object in the simulation, i.e. c becomes the new origin that other objects are defined with respect to.

• sources [ list of Source class ] — Specifies the current sources to be present in the simulation. Defaults to none (empty list).

• symmetries [ list of Symmetry class ] — Specifies the spatial symmetries (mirror or rotation) to exploit in the simulation. Defaults to none (empty list). The symmetries must be obeyed by both the structure and the sources. See also Exploiting Symmetry.

• boundary_layers [ list of PML class ] — Specifies the PML absorbing boundary layers to use. Defaults to none (empty list).

• cell_size [ Vector3 ] — Specifies the size of the cell which is centered on the origin of the coordinate system. Any sizes of 0 imply a reduced-dimensionality calculation. Strictly speaking, the dielectric function is taken to be uniform along that dimension. A 2d calculation is especially 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. 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). This can also be a NumPy array that defines a dielectric function much like epsilon_input_file below (see below). If you want to use a material function as the default material, use the material_function keyword argument (below).

• material_function [ function ] — A Python function that takes a Vector3 and returns a Medium. See also Material Function. Defaults to None.

• epsilon_func [ function ] — A Python function that takes a Vector3 and returns the dielectric constant at that point. See also Material Function. Defaults to None.

• epsilon_input_file [string] — If this string is not empty (the default), then it should be the name of an HDF5 file whose first/only dataset defines a scalar, real-valued, frequency-independent dielectric function over some discrete grid. Alternatively, the dataset name can be specified explicitly if the string is in the form "filename:dataset". This dielectric function is then used in place of the ε property of default_material (i.e. where there are no geometry objects). The grid of the epsilon file dataset need not match the computational grid; it is scaled and/or linearly interpolated as needed to map the file onto the cell. The structure is warped if the proportions of the grids do not match. Note: the file contents only override the ε property of the default_material, whereas other properties (μ, susceptibilities, nonlinearities, etc.) of default_material are still used.

• dimensions [integer] — Explicitly specifies the dimensionality of the simulation, if the value is less than 3. If the value is 3 (the default), then the dimensions are automatically reduced to 2 if possible when cell_size in the $z$ direction is 0. If dimensions is the special value of CYLINDRICAL, then cylindrical coordinates are used and the $x$ and $z$ dimensions are interpreted as $r$ and $z$, respectively. If dimensions is 1, then the cell must be along the $z$ direction and only $E_x$ and $H_y$ field components are permitted. If dimensions is 2, then the cell must be in the $xy$ plane.

• m [number] — For CYLINDRICAL simulations, specifies that the angular $\phi$ dependence of the fields is of the form $e^{im\phi}$ (default is m=0). If the simulation cell includes the origin $r=0$, then m must be an integer.

• accurate_fields_near_cylorigin [boolean] — For CYLINDRICAL simulations with |m| > 1, compute more accurate fields near the origin $r=0$ at the expense of requiring a smaller Courant factor. Empirically, when this option is set to True, a Courant factor of roughly $\min[0.5, 1 / (|m| + 0.5)]$ or smaller seems to be needed. Default is False, in which case the $D_r$, $D_z$, and $B_r$ fields within |m| pixels of the origin are forced to zero, which usually ensures stability with the default Courant factor of 0.5, at the expense of slowing convergence of the fields near $r=0$.

• resolution [number] — Specifies the computational grid resolution in pixels per distance unit. Required argument. No default.

• k_point [False or Vector3] — 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, equivalent to taking MPB's k_points through its function reciprocal->cartesian.

• kz_2d ["complex", "real/imag", or "3d"] — 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. See 2d Cell with Out-of-Plane Wavevector.

• ensure_periodicity [boolean] — If True (the default) and if the boundary conditions are periodic (k_point is not False), then the geometric objects are automatically repeated periodically according to the lattice vectors which define the size of the cell.

• eps_averaging [boolean] — If True (the default), then subpixel averaging is used when initializing the dielectric function. For simulations involving a material function, eps_averaging is False (the default) and must be enabled in which case the input variables subpixel_maxeval (default 10⁴) and subpixel_tol (default 10^-4) specify the maximum number of function evaluations and the integration tolerance for the adaptive numerical integration. Increasing/decreasing these, respectively, will cause a more accurate but slower computation of the average ε with diminishing returns for the actual FDTD error. Disabling subpixel averaging will lead to staircasing effects and irregular convergence.

• force_complex_fields [boolean] — By default, Meep runs its simulations with purely real fields whenever possible. It uses complex fields which require twice the memory and computation if the k_point is non-zero or if m is non-zero. However, by setting force_complex_fields to True, Meep will always use complex fields.

• force_all_components [boolean] — By default, in a 2d simulation Meep uses only the field components that might excited by your current sources: either the in-plane $(E_x,E_y,H_z)$ or out-of-plane $(H_x,H_y,E_z)$ polarization, depending on the source. (Both polarizations are excited if you use multiple source polarizations, or if an anisotropic medium is present that couples the two polarizations.) In rare cases (primarily for combining results of multiple simulations with differing polarizations), you might want to force it to 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 (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 $S$ which relates the time step size to the spatial discretization: $cΔ t = SΔ x$. Default is 0.5. For numerical stability, the Courant factor must be at most $n_\textrm{min}/\sqrt{\textrm{# dimensions}}$, where $n_\textrm{min}$ is the minimum refractive index (usually 1), and in practice $S$ should be slightly smaller.

• loop_tile_base_db, loop_tile_base_eh [number] — To improve the memory locality of the field updates, Meep has an experimental feature to "tile" the loops over the Yee grid voxels. The splitting of the update loops for step-curl and update-eh into tiles or subdomains involves a recursive-bisection method in which the base case for the number of voxels is specified using these two parameters, respectively. The default value is 0 or no tiling; a typical nonzero value to try would be 10000.

• output_volume [Volume class ] — Specifies the default region of space that is output by the HDF5 output functions (below); see also the Volume class which manages meep::volume* objects. Default is None, which means that the whole cell is output. Normally, you should use the in_volume(...) function to modify the output volume instead of setting output_volume directly.

• output_single_precision [boolean] — Meep performs its computations in double-precision floating point, and by default its output HDF5 files are in the same format. However, by setting this variable to True (default is False) you can instead output in single precision which saves a factor of two in space.

• progress_interval [number] — Time interval (seconds) after which Meep prints a progress message. Default is 4 seconds.

• extra_materials [ list of Medium class ] — By default, Meep turns off support for material dispersion (susceptibilities or conductivity) or nonlinearities if none of the objects in geometry have materials with these properties — since they are not needed, it is faster to omit their calculation. This doesn't work, however, if you use a material_function: materials via a user-specified function of position instead of just geometric objects. If your material function only returns a nonlinear material, for example, Meep won't notice this unless you tell it explicitly via extra_materials. extra_materials is a list of materials that Meep should look for in the cell in addition to any materials that are specified by geometric objects. You should list any materials other than scalar dielectrics that are returned by material_function here.

• chunk_layout [string or Simulation instance or BinaryPartition class] — This will cause the Simulation to use the chunk layout described by either (1) an .h5 file (created using Simulation.dump_chunk_layout), (2) another Simulation instance, or (3) a BinaryPartition class object. For more information, see Load and Dump Structure and Parallel Meep/User-Specified Cell Partition.

The following require a bit more understanding of the inner workings of Meep to use. See also SWIG Wrappers.

• structure [meep::structure*] — Pointer to the current structure being simulated; initialized by _init_structure which is called automatically by init_sim() which is called automatically by any of the run functions. The structure initialization is handled by the Simulation class, and most users will not need to call _init_structure.

• fields [meep::fields*] — Pointer to the current fields being simulated; initialized by init_sim() which is called automatically by any of the run functions.

• num_chunks [integer] — Minimum number of "chunks" (subregions) to divide the structure/fields into. Overrides the default value determined by the number of processors, PML layers, etcetera. Mainly useful for debugging.

• split_chunks_evenly [boolean] — When True (the default), the work per chunk is not taken into account when splitting chunks up for multiple processors. The cell is simply split up into equal chunks (with the exception of PML regions, which must be on their own chunk). When False, Meep attempts to allocate an equal amount of work to each processor, which can increase the performance of parallel simulations.

run(step_functions..., until=condition/time)

Run the simulation until a certain time or condition, calling the given step functions (if any) at each timestep. The keyword argument until is either a number, in which case it is an additional time (in Meep units) to run for, or it is a function (of no arguments) which returns True when the simulation should stop. until can also be a list of stopping conditions which may include a number of additional functions.

run(step_functions..., until_after_sources=condition/time)

Run the simulation until all sources have turned off, calling the given step functions (if any) at each timestep. The keyword argument until_after_sources is either a number, in which case it is an additional time (in Meep units) to run for after the sources are off, or it is a function (of no arguments). In the latter case, the simulation runs until the sources are off and condition returns True. Like until above, until_after_sources can take a list of stopping conditions.

Return the current prefix string that is prepended, by default, to all file names.

If you don't want to use any prefix, then you should set filename_prefix to the empty string ''.

In addition to the filename prefix, you can also specify that all the output files be written into a newly-created directory (if it does not yet exist). This is done by calling Simulation.use_output_directory([dirname])

Output all files into a subdirectory, which is created if necessary. If the optional argument dname is specified, that is the name of the directory. If dname is omitted and filename_prefix is None, the directory name is the current Python filename with ".py" replaced by "-out": e.g. test.py implies a directory of "test-out". If dname is omitted and filename_prefix has been set, the directory name is set to filename_prefix + "-out" and filename_prefix is then reset to None.

Return the current simulation time in simulation time units (e.g. during a run function). This is not the wall-clock time.

Occasionally, e.g. for termination conditions of the form $time < T?$, it is desirable to round the time to single precision in order to avoid small differences in roundoff error from making your results different by one timestep from machine to machine (a difference much bigger than roundoff error); in this case you can call Simulation.round_time() instead, which returns the time rounded to single precision.

Return the number of elapsed timesteps.

Call after running a simulation to print the times spent on various types of work. Example output:

Field time usage:
        connecting chunks: 0.0156826 s +/- 0.002525 s
            time stepping: 0.996411 s +/- 0.232147 s
       copying boundaries: 0.148588 s +/- 0.0390397 s
    all-all communication: 1.39423 s +/- 0.581098 s
        1-1 communication: 0.136174 s +/- 0.0107685 s
     Fourier transforming: 0.0321625 s +/- 0.0614168 s
          MPB mode solver: 0.348019 s +/- 0.370068 s
          everything else: 0.207387 s +/- 0.0164821 s

Return a list of times spent by each process for a type of work time_sink which is the same as for mean_time_spent_on.

Return the mean time spent by all processes for a type of work time_sink which can be one of the following integer constants: 0: "time stepping", 1: "connecting chunks", 2: "copying boundaries", 3: "all-all communication", 4: "1-1 communication", 5: "outputting fields", 6: "Fourier transforming", 7: "MPB mode solver", 8: "near-to-far-field transform", 9: "updating B field", 10: "updating H field", 11: "updating D field", 12: "updating E field", 13: "boundary stepping B", 14: "boundary stepping WH", 15: "boundary stepping PH", 16: "boundary stepping H", 17: "boundary stepping D", 18: "boundary stepping WE", 19: "boundary stepping PE", 20: "boundary stepping E", 21: "everything else".

Call after running a simulation to output to a file with filename fname the times spent on various types of work as CSV (comma separated values) with headers for each column and one row per process.

Sets the condition of the boundary on the specified side in the specified direction. See the Constants (Enumerated Types) section for valid side, direction, and boundary_condition values.

newstructure should be the structure field of another Simulation object with the same cell size and resolution. Over the next time period phasetime (in the current simulation's time units), the current structure ($\varepsilon$, $\mu$, and conductivity $\sigma_D$) will be gradually changed to newstructure. In particular, at each timestep it linearly interpolates between the old structure and the new structure. After phasetime has elapsed, the structure will remain equal to newstructure. This is demonstrated in the following image for two Cylinder objects (the simulation script is in examples/phase_in_material.py).

Given a component or derived_component constant c and a Vector3 pt, returns the value of that component at that point.

Given a frequency frequency and a Vector3 pt, returns the average eigenvalue of the permittivity tensor at that location and frequency. If frequency is non-zero, the result is complex valued; otherwise it is the real, frequency-independent part of $\varepsilon$ (the $\omega\to\infty$ limit).

Given a frequency frequency and a Vector3 pt, returns the average eigenvalue of the permeability tensor at that location and frequency. If frequency is non-zero, the result is complex valued; otherwise it is the real, frequency-independent part of $\mu$ (the $\omega\to\infty$ limit).

Given three 1d NumPy arrays (xtics,ytics,ztics) which define the coordinates of a Cartesian grid anywhere within the cell volume, compute the trace of the $\varepsilon(f)$ tensor at frequency $f$ (in Meep units) from the geometry exactly at each grid point. frequency defaults to 0 which is the instantaneous $\varepsilon$. (For MaterialGrids, the $\varepsilon$ at each grid point is computed using bilinear interpolation from the nearest MaterialGrid points and possibly also projected to form a level set.) Note that this is different from get_epsilon_point which computes $\varepsilon$ by bilinearly interpolating from the nearest Yee grid points. This function is useful for sampling the material geometry to any arbitrary resolution. The return value is a NumPy array with shape equivalent to numpy.meshgrid(xtics,ytics,ztics). Empty dimensions are collapsed.

Initialize the component c fields using the function func which has a single argument, a Vector3 giving a position and returns a complex number for the value of the field at that point.

Given a list of field components cs, compute the Fourier transform of these fields for nfreq equally spaced frequencies covering the frequency range fcen-df/2 to fcen+df/2 or an array/list freq for arbitrarily spaced frequencies over the Volume specified by where (default to the entire cell). The volume can also be specified via the center and size arguments. The default routine interpolates the Fourier-transformed fields at the center of each voxel within the specified volume. Alternatively, the exact Fourier-transformed fields evaluated at each corresponding Yee grid point is available by setting yee_grid to True. To reduce the memory-bandwidth burden of accumulating DFT fields, an integer decimation_factor can be specified for updating the DFT fields at every decimation_factor timesteps. If decimation_factor is 0 (the default), this value is automatically determined from the Nyquist rate of the bandwidth-limited sources and this DFT monitor. It can be turned off by setting it to 1. Use this feature with care, as the decimated timeseries may be corrupted by aliasing of high frequencies.

Given a direction constant, and a mp.Volume, returns the flux (the integral of $\Re [\mathbf{E}^* \times \mathbf{H}]$) in that volume. Most commonly, you specify a volume that is a plane or a line, and a direction perpendicular to it, e.g.

flux_in_box(d=mp.X,mp.Volume(center=mp.Vector3(0,0,0),size=mp.Vector3(0,1,1)))

If the center and size arguments are provided instead of box, Meep will construct the appropriate volume for you.

Given a mp.Volume, returns the integral of the electric-field energy $\mathbf{E}^* \cdot \mathbf{D}/2$ in the given volume. If the volume has zero size along a dimension, a lower-dimensional integral is used. If the center and size arguments are provided instead of box, Meep will construct the appropriate volume for you. Note: in cylindrical coordinates $(r,\phi,z)$, the integrand is multiplied by the circumference $2\pi r$, or equivalently the integral is over an annular volume.

Given a mp.Volume, returns the integral of the magnetic-field energy $\mathbf{H}^* \cdot \mathbf{B}/2$ in the given volume. If the volume has zero size along a dimension, a lower-dimensional integral is used. If the center and size arguments are provided instead of box, Meep will construct the appropriate volume for you. Note: in cylindrical coordinates $(r,\phi,z)$, the integrand is multiplied by the circumference $2\pi r$, or equivalently the integral is over an annular volume.

Given a mp.Volume, returns the integral of the electric- and magnetic-field energy $\mathbf{E}^* \cdot \mathbf{D}/2 + \mathbf{H}^* \cdot \mathbf{B}/2$ in the given volume. If the volume has zero size along a dimension, a lower-dimensional integral is used. If the center and size arguments are provided instead of box, Meep will construct the appropriate volume for you. Note: in cylindrical coordinates $(r,\phi,z)$, the integrand is multiplied by the circumference $2\pi r$, or equivalently the integral is over an annular volume.

Given a mp.Volume, returns the instantaneous modal volume according to the Purcell-effect definition: $\left(\int\varepsilon|\mathbf{E}|^2\right)/\left(\max{\varepsilon|\mathbf{E}|^2}\right)$. If no volume argument is provided, the entire cell is used by default. If the center and size arguments are provided instead of box, Meep will construct the appropriate volume for you.

Note that if you are at a fixed frequency and you use complex fields (via Bloch-periodic boundary conditions or fields_complex=True), then one half of the flux or energy integrals above corresponds to the time average of the flux or energy for a simulation with real fields.

Often, you want the integration box to be the entire cell. A useful function to return this box, which you can then use for the box arguments above, is Simulation.total_volume().

One versatile feature is that you can supply an arbitrary function $f(\mathbf{x},c_1,c_2,\ldots)$ of position $\mathbf{x}$ and various field components $c_1,\ldots$ and ask Meep to integrate it over a given volume, find its maximum, or output it (via output_field_function, described later). This is done via the functions:

Returns the integral of the complex-valued function func over the Volume specified by where (defaults to entire cell) for the meep::fields contained in the Simulation instance that calls this method. func is a function of position (a Vector3, its first argument) and zero or more field components specified by cs: a list of component constants. func can be real- or complex-valued. The volume can optionally be specified via the center and size arguments.

If any dimension of where is zero, that dimension is not integrated over. In this way you can specify 1d, 2d, or 3d integrals.

Note: in cylindrical coordinates $(r,\phi,z)$, the integrand is multiplied by the circumference $2\pi r$, or equivalently the integral is over an annular volume.

As integrate_field_function, but returns the maximum absolute value of func in the volume where instead of its integral.

The integration is performed by summing over the grid points with a simple trapezoidal rule, and the maximum is similarly over the grid points. See Field Functions for examples of how to call integrate_field_function and max_abs_field_function. See Synchronizing the Magnetic and Electric Fields if you want to do computations combining the electric and magnetic fields. The volume can optionally be specified via the center and size arguments.

Occasionally, one wants to compute an integral that combines fields from two separate simulations (e.g. for nonlinear coupled-mode calculations). This functionality is supported in Meep, as long as the two simulations have the same cell, the same resolution, the same boundary conditions and symmetries (if any), and the same PML layers (if any).

Similar to integrate_field_function, but takes additional parameters fields2 and cs2. fields2 is a meep::fields* object similar to the global fields variable (see below) specifying the fields from another simulation. cs1 is a list of components to integrate with from the meep::fields instance in Simulation.fields, as for integrate_field_function, while cs2 is a list of components to integrate from fields2. Similar to integrate_field_function, func is a function that returns an number given arguments consisting of: the position vector, followed by the values of the components specified by cs1 (in order), followed by the values of the components specified by cs2 (in order). The volume can optionally be specified via the center and size arguments.

To get two fields in memory at once for integrate2_field_function, the easiest way is to run one simulation within a given Python file, then save the results in another fields variable, then run a second simulation. This would look something like:

...set up and run first simulation...
fields2 = sim.fields # save the fields in a variable
sim.fields = None    # prevent the fields from getting deallocated by reset-meep
sim.reset_meep()
...set up and run second simulation...

It is also possible to timestep both fields simultaneously (e.g. doing one timestep of one simulation then one timestep of another simulation, and so on, but this requires you to call much lower-level functions like fields_step().

Reset all of Meep's parameters, deleting the fields, structures, etcetera, from memory as if you had not run any computations. If the num_chunks or chunk_layout attributes have been modified internally, they are reset to their original values passed in at instantiation.

Restart the fields at time zero, with zero fields. Does not reset the Fourier transforms of the flux planes, which continue to be accumulated.

Change the k_point (the Bloch periodicity).

Change the list of sources in Simulation.sources to new_sources, and changes the sources used for the current simulation. new_sources must be a list of Source objects.

This can be called in a step function, and is useful for changing the geometry or default material as a function of time.

Add a bunch of FluxRegions to the current simulation (initializing the fields if they have not yet been initialized), telling Meep to accumulate the appropriate field Fourier transforms for nfreq equally spaced frequencies covering the frequency range fcen-df/2 to fcen+df/2 or an array/list freq for arbitrarily spaced frequencies. Return a flux object, which you can pass to the functions below to get the flux spectrum, etcetera. To reduce the memory-bandwidth burden of accumulating DFT fields, an integer decimation_factor can be specified for updating the DFT fields at every decimation_factor timesteps. If decimation_factor is 0 (the default), this value is automatically determined from the Nyquist rate of the bandwidth-limited sources and this DFT monitor. It can be turned off by setting it to 1. Use this feature with care, as the decimated timeseries may be corrupted by aliasing of high frequencies. The choice of decimation factor should take into account the properties of all sources in the simulation as well as the frequency range of the DFT field monitor.

Given a number of flux objects, this displays a comma-separated table of frequencies and flux spectra, prefixed by "flux1:" or similar (where the number is incremented after each run). All of the fluxes should be for the same fcen/df/nfreq or freq. The first column are the frequencies, and subsequent columns are the flux spectra.

Save the Fourier-transformed fields corresponding to the given flux object in an HDF5 file of the given filename without the .h5 suffix (the current filename-prefix is prepended automatically).

Load the Fourier-transformed fields into the given flux object (replacing any values currently there) from an HDF5 file of the given filename without the .h5 suffix (the current filename-prefix is prepended automatically). You must load from a file that was saved by save_flux in a simulation of the same dimensions (for both the cell and the flux regions) with the same number of processors and chunk layout.

As load_flux, but negates the Fourier-transformed fields after they are loaded. This means that they will be subtracted from any future field Fourier transforms that are accumulated.

Get the Fourier-transformed fields corresponding to the given flux object as a FluxData, which is just a named tuple of NumPy arrays. Note that this object is only useful for passing to load_flux_data below and should be considered opaque.

Load the Fourier-transformed fields into the given flux object (replacing any values currently there) from the FluxData object fdata. You must load from an object that was created by get_flux_data in a simulation of the same dimensions (for both the cell and the flux regions) with the same number of processors and chunk layout.

As load_flux_data, but negates the Fourier-transformed fields after they are loaded. This means that they will be subtracted from any future field Fourier transforms that are accumulated.

Given a flux object and either a list of indices bands (starts at one) or a DiffractedPlanewave object, return a namedtuple with the following fields:

• alpha: the complex eigenmode coefficients as a 3d NumPy array of size (len(bands), flux.nfreqs, 2). The last/third dimension refers to modes propagating in the forward (+) or backward (-) directions defined relative to the sign of the propagation constant β of the mode (the wavevector component in the direction perpendicular to the mode-monitor plane).
• vgrp: the group velocity as a NumPy array.
• kpoints: a list of mp.Vector3s of the kpoint used in the mode calculation.
• kdom: a list of mp.Vector3s of the mode's dominant wavevector.
• cscale: a NumPy array of each mode's scaling coefficient. Useful for adjoint calculations.

Similar to add_flux, but for use with get_eigenmode_coefficients.

The parameters of this routine are the same as that of get_eigenmode_coefficients or EigenModeSource, but this function returns an object that can be used to inspect the computed mode. In particular, it returns an EigenmodeData instance with the following fields:

• band_num: same as a single element of the bands parameter
• freq: the computed frequency, same as the frequency input parameter if match_frequency=True
• group_velocity: the group velocity of the mode in direction
• k: the Bloch wavevector of the mode in direction
• kdom: the dominant planewave of mode band_num
• amplitude(point, component): the (complex) value of the given $\mathbf{E}$ or $\mathbf{H}$ field component (Ex, Hy, etcetera) at a particular point (a Vector3) in space (interpreted with Bloch-periodic boundary conditions if you give a point outside the original eig_vol).

If match_frequency=False or kpoint is not zero in the given direction, the frequency input parameter is ignored.

Construct a DiffractedPlanewave.

• g [ list of 3 integers ] — The diffraction order $(m_x,m_y,m_z)$ corresponding to the wavevector $(k_x+2\pi m_x/\Lambda_x,k_y+2\pi m_y/\Lambda_y,k_z+2\pi m_z/\Lambda_z)$. $(k_x,k_y,k_z)$ is the k_point (wavevector specifying the Bloch-periodic boundaries) of the Simulation class object. The diffraction order $m_{x,y,z}$ should be non-zero only in the $d$-1 periodic directions of a $d$ dimensional cell of size $(\Lambda_x,\Lambda_y,\Lambda_z)$ (e.g., a plane in 3d) in which the mode monitor or source extends the entire length of the cell.

• axis [ Vector3 ] — The plane of incidence for each planewave (used to define the $\mathcal{S}$ and $\mathcal{P}$ polarizations below) is defined to be the plane that contains the axis vector and the planewave's wavevector. If None, axis defaults to the first direction that lies in the plane of the monitor or source (e.g., $y$ direction for a $yz$ plane in 3d, either $x$ or $y$ in 2d).

• s [ complex ] — The complex amplitude of the $\mathcal{S}$ polarziation (i.e., electric field perpendicular to the plane of incidence).

• p [ complex ] — The complex amplitude of the $\mathcal{P}$ polarziation (i.e., electric field parallel to the plane of incidence).

Add a bunch of EnergyRegions to the current simulation (initializing the fields if they have not yet been initialized), telling Meep to accumulate the appropriate field Fourier transforms for nfreq equally spaced frequencies covering the frequency range fcen-df/2 to fcen+df/2 or an array/list freq for arbitrarily spaced frequencies. Return an energy object, which you can pass to the functions below to get the energy spectrum, etcetera. To reduce the memory-bandwidth burden of accumulating DFT fields, an integer decimation_factor can be specified for updating the DFT fields at every decimation_factor timesteps. If decimation_factor is 0 (the default), this value is automatically determined from the Nyquist rate of the bandwidth-limited sources and this DFT monitor. It can be turned off by setting it to 1. Use this feature with care, as the decimated timeseries may be corrupted by aliasing of high frequencies.

Given a number of energy objects, this displays a comma-separated table of frequencies and energy density spectra for the electric fields prefixed by "electric_energy1:" or similar (where the number is incremented after each run). All of the energy should be for the same fcen/df/nfreq or freq. The first column are the frequencies, and subsequent columns are the energy density spectra.

Given a number of energy objects, this displays a comma-separated table of frequencies and energy density spectra for the magnetic fields prefixed by "magnetic_energy1:" or similar (where the number is incremented after each run). All of the energy should be for the same fcen/df/nfreq or freq. The first column are the frequencies, and subsequent columns are the energy density spectra.

Given a number of energy objects, this displays a comma-separated table of frequencies and energy density spectra for the total fields "total_energy1:" or similar (where the number is incremented after each run). All of the energy should be for the same fcen/df/nfreq or freq. The first column are the frequencies, and subsequent columns are the energy density spectra.

Save the Fourier-transformed fields corresponding to the given energy object in an HDF5 file of the given filename without the .h5 suffix (the current filename-prefix is prepended automatically).

Load the Fourier-transformed fields into the given energy object (replacing any values currently there) from an HDF5 file of the given filename without the .h5 suffix (the current filename-prefix is prepended automatically). You must load from a file that was saved by save_energy in a simulation of the same dimensions for both the cell and the energy regions with the same number of processors and chunk layout.

As load_energy, but negates the Fourier-transformed fields after they are loaded. This means that they will be subtracted from any future field Fourier transforms that are accumulated.

Add a bunch of ForceRegions to the current simulation (initializing the fields if they have not yet been initialized), telling Meep to accumulate the appropriate field Fourier transforms for nfreq equally spaced frequencies covering the frequency range fcen-df/2 to fcen+df/2 or an array/list freq for arbitrarily spaced frequencies. Return a forceobject, which you can pass to the functions below to get the force spectrum, etcetera. To reduce the memory-bandwidth burden of accumulating DFT fields, an integer decimation_factor can be specified for updating the DFT fields at every decimation_factor timesteps. If decimation_factor is 0 (the default), this value is automatically determined from the Nyquist rate of the bandwidth-limited sources and this DFT monitor. It can be turned off by setting it to 1. Use this feature with care, as the decimated timeseries may be corrupted by aliasing of high frequencies.

Given a number of force objects, this displays a comma-separated table of frequencies and force spectra, prefixed by "force1:" or similar (where the number is incremented after each run). All of the forces should be for the same fcen/df/nfreq or freq. The first column are the frequencies, and subsequent columns are the force spectra.

Save the Fourier-transformed fields corresponding to the given force object in an HDF5 file of the given filename without the .h5 suffix (the current filename-prefix is prepended automatically).

Load the Fourier-transformed fields into the given force object (replacing any values currently there) from an HDF5 file of the given filename without the .h5 suffix (the current filename-prefix is prepended automatically). You must load from a file that was saved by save_force in a simulation of the same dimensions for both the cell and the force regions with the same number of processors and chunk layout.

As load_force, but negates the Fourier-transformed fields after they are loaded. This means that they will be subtracted from any future field Fourier transforms that are accumulated.

Get the Fourier-transformed fields corresponding to the given force object as a ForceData, which is just a named tuple of NumPy arrays. Note that this object is only useful for passing to load_force_data below and should be considered opaque.

Load the Fourier-transformed fields into the given force object (replacing any values currently there) from the ForceData object fdata. You must load from an object that was created by get_force_data in a simulation of the same dimensions (for both the cell and the flux regions) with the same number of processors and chunk layout.

As load_force_data, but negates the Fourier-transformed fields after they are loaded. This means that they will be subtracted from any future field Fourier transforms that are accumulated.

Add a bunch of Near2FarRegions to the current simulation (initializing the fields if they have not yet been initialized), telling Meep to accumulate the appropriate field Fourier transforms for nfreq equally spaced frequencies covering the frequency range fcen-df/2 to fcen+df/2 or an array/list freq for arbitrarily spaced frequencies. Return a near2far object, which you can pass to the functions below to get the far fields. To reduce the memory-bandwidth burden of accumulating DFT fields, an integer decimation_factor can be specified for updating the DFT fields at every decimation_factor timesteps. If decimation_factor is 0 (the default), this value is automatically determined from the Nyquist rate of the bandwidth-limited sources and this DFT monitor. It can be turned off by setting it to 1. Use this feature with care, as the decimated timeseries may be corrupted by aliasing of high frequencies.

Given a Vector3 point x which can lie anywhere outside the near-field surface, including outside the cell and a near2far object, returns the computed (Fourier-transformed) "far" fields at x as list of length 6nfreq, consisting of fields $(E_x^1,E_y^1,E_z^1,H_x^1,H_y^1,H_z^1,E_x^2,E_y^2,E_z^2,H_x^2,H_y^2,H_z^2,...)$ in Cartesian coordinates and $(E_r^1,E_\phi^1,E_z^1,H_r^1,H_\phi^1,H_z^1,E_r^2,E_\phi^2,E_z^2,H_r^2,H_\phi^2,H_z^2,...)$ in cylindrical coordinates for the frequencies 1,2,...,nfreq.

Given an HDF5 file name fname (does not include the .h5 suffix), a Volume given by where (may be 0d, 1d, 2d, or 3d), and a resolution (in grid points / distance unit), outputs the far fields in where (which may lie outside the cell) in a grid with the given resolution (which may differ from the FDTD grid resolution) to the HDF5 file as a set of twelve array datasets ex.r, ex.i, ..., hz.r, hz.i, giving the real and imaginary parts of the Fourier-transformed $\mathbf{E}$ and $\mathbf{H}$ fields on this grid. Each dataset is an $n_x \times n_y \times n_z \times nfreq$ 4d array of $space \times frequency$ although dimensions that are equal to one are omitted. The volume can optionally be specified via center and size.

Like output_farfields but returns a dictionary of NumPy arrays instead of writing to a file. The dictionary keys are Ex, Ey, Ez, Hx, Hy, Hz. Each array has the same shape as described in output_farfields.

Note that far fields have the same units and scaling as the Fourier transforms of the fields, and hence cannot be directly compared to time-domain fields. In practice, it is easiest to use the far fields in computations where overall scaling (units) cancel out or are irrelevant, e.g. to compute the fraction of the far fields in one region vs. another region.

Save the Fourier-transformed fields corresponding to the given near2far object in an HDF5 file of the given filename (without the .h5 suffix). The current filename-prefix is prepended automatically.

Load the Fourier-transformed fields into the given near2far object (replacing any values currently there) from an HDF5 file of the given filename without the .h5 suffix (the current filename-prefix is prepended automatically). You must load from a file that was saved by save_near2far in a simulation of the same dimensions for both the cell and the near2far regions with the same number of processors and chunk layout.

As load_near2far, but negates the Fourier-transformed fields after they are loaded. This means that they will be subtracted from any future field Fourier transforms that are accumulated.

Get the Fourier-transformed fields corresponding to the given near2far object as a NearToFarData, which is just a named tuple of NumPy arrays. Note that this object is only useful for passing to load_near2far_data below and should be considered opaque.

Load the Fourier-transformed fields into the near2far object (replacing any values currently there) from the NearToFarData object n2fdata. You must load from an object that was created by get_near2far_data in a simulation of the same dimensions (for both the cell and the flux regions) with the same number of processors and chunk layout.

As load_near2far_data, but negates the Fourier-transformed fields after they are loaded. This means that they will be subtracted from any future field Fourier transforms that are accumulated.

Given a Volume where (may be 0d, 1d, 2d, or 3d) and a resolution (in grid points / distance unit), compute the far fields in where (which may lie outside the cell) in a grid with the given resolution (which may differ from the FDTD solution) and return its Poynting flux in direction as a list. The dataset is a 1d array of nfreq dimensions.

Dumps the structure to the file fname.

Loads a structure from the file fname.

Dumps the chunk layout to file fname.

Dumps the fields to the file fname.

Loads a fields from the file fname.

Dumps simulation state.

Loads simulation state.

This should called right after the Simulation object has been created but before 'init_sim' is called.

Plots a 2D cross section of the simulation domain using matplotlib. The plot includes the geometry, boundary layers, sources, and monitors. Fields can also be superimposed on a 2D slice. Requires matplotlib. Calling this function would look something like:

sim = mp.Simulation(...)
sim.run(...)
field_func = lambda x: 20*np.log10(np.abs(x))
import matplotlib.pyplot as plt
sim.plot2D(fields=mp.Ez,
           field_parameters={'alpha':0.8, 'cmap':'RdBu', 'interpolation':'none', 'post_process':field_func},
           boundary_parameters={'hatch':'o', 'linewidth':1.5, 'facecolor':'y', 'edgecolor':'b', 'alpha':0.3})
plt.show()
plt.savefig('sim_domain.png')

If you just want to quickly visualize the simulation domain without the fields (i.e., when setting up your simulation), there is no need to invoke the run function prior to calling plot2D. Just define the Simulation object followed by any DFT monitors and then invoke plot2D.

Note: When running a parallel simulation, 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, patches, and scatter plots, to this object. If no ax is supplied, then the routine will create a new figure and grab its axis.
• output_plane: a Volume object that specifies the plane over which to plot. Must be 2D and a subset of the grid volume (i.e., it should not extend beyond the cell).
• fields: the field component (mp.Ex, mp.Ey, mp.Ez, mp.Hx, mp.Hy, mp.Hz) to superimpose over the simulation geometry. Default is None, where no fields are superimposed.
• labels: if True, then labels will appear over each of the simulation elements. Defaults to False.
• eps_parameters: a dict of optional plotting parameters that override the default parameters for the geometry.
  • interpolation='spline36': interpolation algorithm used to upsample the pixels.
  • cmap='binary': the color map of the geometry
  • alpha=1.0: transparency of geometry
  • contour=False: if True, plot a contour of the geometry rather than its image
  • contour_linewidth=1: line width of the contour lines if contour=True
  • frequency=None: for materials with a frequency-dependent permittivity $\varepsilon(f)$, specifies the frequency $f$ (in Meep units) of the real part of the permittivity to use in the plot. Defaults to the frequency parameter of the Source object.
  • resolution=None: the resolution of the $\varepsilon$ grid. Defaults to the resolution of the Simulation object.
  • colorbar=False: whether to add a colorbar to the plot's parent Figure based on epsilon values.
• boundary_parameters: a dict of optional plotting parameters that override the default parameters for the boundary layers.
  • alpha=1.0: transparency of boundary layers
  • facecolor='g': color of polygon face
  • edgecolor='g': color of outline stroke
  • linewidth=1: line width of outline stroke
  • hatch='\': hatching pattern
• source_parameters: a dict of optional plotting parameters that override the default parameters for the sources.
  • color='r': color of line and pt sources
  • alpha=1.0: transparency of source
  • facecolor='none': color of polygon face for planar sources
  • edgecolor='r': color of outline stroke for planar sources
  • linewidth=1: line width of outline stroke
  • hatch='\': hatching pattern
  • label_color='r': color of source labels
  • label_alpha=0.3: transparency of source label box
  • offset=20: distance from source center and label box
• monitor_parameters: a dict of optional plotting parameters that override the default parameters for the monitors.
  • color='g': color of line and point monitors
  • alpha=1.0: transparency of monitors
  • facecolor='none': color of polygon face for planar monitors
  • edgecolor='r': color of outline stroke for planar monitors
  • linewidth=1: line width of outline stroke
  • hatch='\': hatching pattern
  • label_color='g': color of source labels
  • label_alpha=0.3: transparency of monitor label box
  • offset=20: distance from monitor center and label box
• field_parameters: a dict of optional plotting parameters that override the default parameters for the fields.
  • interpolation='spline36': interpolation function used to upsample field pixels
  • cmap='RdBu': color map for field pixels
  • alpha=0.6: transparency of fields
  • post_process=np.real: post processing function to apply to fields (must be a function object)
  • colorbar=False: whether to add a colorbar to the plot's parent Figure based on field values.
• colorbar_parameters: a dict of optional plotting parameters that override the default parameters for the colorbar.
  • label=None: an optional label for the colorbar, defaults to '$\epsilon_r$' for epsilon and 'field values' for fields.
  • orientation='vertical': the orientation of the colorbar gradient
  • extend=None: make pointed end(s) for out-of-range values. Allowed values are: ['neither', 'both', 'min', 'max']
  • format=None: formatter for tick labels. Can be an fstring (i.e. "{x:.2e}") or a matplotlib.ticker.ScalarFormatter.
  • position='right': position of the colorbar with respect to the Axes
  • size='5%': size of the colorbar in the dimension perpendicular to its orientation
  • pad='2%': fraction of original axes between colorbar and image axes
• nb: set this to True if plotting in a Jupyter notebook to use ipympl for plotting. Note: this requires ipympl to be installed.

Uses vispy to render a 3D scene of the simulation object. The simulation object must be 3D. Can also be embedded in Jupyter notebooks.

Args: save_to_image: if True, saves the image to a file image_name: the name of the image file to save to

kwargs: Camera settings. scale_factor: float, camera zoom factor azimuth: float, azimuthal angle in degrees elevation: float, elevation angle in degrees

Displays an interactive image of how the cell is divided into chunks. Each rectangular region is a chunk, and each color represents a different processor. Requires matplotlib.

run(step_functions..., until=condition/time)

Run the simulation until a certain time or condition, calling the given step functions (if any) at each timestep. The keyword argument until is either a number, in which case it is an additional time (in Meep units) to run for, or it is a function (of no arguments) which returns True when the simulation should stop. until can also be a list of stopping conditions which may include a number of additional functions.

run(step_functions..., until_after_sources=condition/time)

Run the simulation until all sources have turned off, calling the given step functions (if any) at each timestep. The keyword argument until_after_sources is either a number, in which case it is an additional time (in Meep units) to run for after the sources are off, or it is a function (of no arguments). In the latter case, the simulation runs until the sources are off and condition returns True. Like until above, until_after_sources can take a list of stopping conditions.

Given a list of Vector3, k_points of k vectors, runs a simulation for each k point (i.e. specifying Bloch-periodic boundary conditions) and extracts the eigen-frequencies, and returns a list of the complex frequencies. In particular, you should have specified one or more Gaussian sources. It will run the simulation until the sources are turned off plus an additional $t$ time units. It will run Harminv at the same point/component as the first Gaussian source and look for modes in the union of the frequency ranges for all sources. Returns a list of lists of frequencies (one list of frequencies for each k). Also prints out a comma-delimited list of frequencies, prefixed by freqs:, and their imaginary parts, prefixed by freqs-im:. See Tutorial/Resonant Modes and Transmission in a Waveguide Cavity.

Lower level function called by run_k_points that runs a simulation for a single k point k_point and returns a Harminv instance. Useful when you need to access more Harminv data than just the frequencies.

Output the Fourier-transformed fields in dft_fields (created by add_dft_fields) to an HDF5 file with name fname (does not include the .h5 suffix).

Output the field function func to an HDF5 file in the datasets named name*.r and name*.i for the real and imaginary parts. Similar to integrate_field_function, func is a function of position (a Vector3) and the field components corresponding to cs: a list of component constants. If real_only is True, only outputs the real part of func.

Returns a slice of the materials or time-domain fields over a subregion of the cell at the current simulation time as a NumPy array. The materials/fields are centered on the Yee-grid voxels using a bilinear interpolation of the nearest Yee-grid points.

• component [ component constant ] — The field or material component (e.g., meep.Ex, meep.Hy, meep.Sz, meep.Dielectric, etc) of the array data. No default.

• vol [ Volume ] — The rectilinear subregion/slice of the cell volume. The return value of get_array has the same dimensions as the Volume's size attribute. If None (default), then a size and center must be specified.

• center, size [ Vector3 ] — If both are specified, the method will construct an appropriate Volume. This is a convenience feature and alternative to supplying a Volume.

• cmplx [ boolean ] — If True, return complex-valued data otherwise return real-valued data (default).

• arr [ numpy.ndarray ] — Optional parameter to pass a pre-allocated NumPy array of the correct size and type (either numpy.float32 or numpy.float64 depending on the floating-point precision of the fields and materials) which will be overwritten with the field/material data instead of allocating a new array. Normally, this will be the array returned from a previous call to get_array for a similar slice, allowing one to re-use arr (e.g., when fetching the same slice repeatedly at different times).

• frequency [ number ] — The frequency at which the average eigenvalue of the $\varepsilon$ and $\mu$ tensors are evaluated. Defaults to 0 which is the instantaneous $\varepsilon$.

• snap [ boolean ] — Empty dimensions of the grid slice are "collapsed" into a single element. However, if snap is set to True, this interpolation behavior is disabled and the grid slice is instead "snapped" everywhere to the nearest grid point. (Empty slice dimensions are still of size one.) This feature is mainly useful for comparing results with the output_ routines (e.g., output_epsilon, output_efield_z, etc.).

For convenience, the following wrappers for get_array over the entire cell are available: get_epsilon(), get_mu(), get_hpwr(), get_dpwr(), get_tot_pwr(), get_Xfield(), get_Xfield_x(), get_Xfield_y(), get_Xfield_z(), get_Xfield_r(), get_Xfield_p() where X is one of h, b, e, d, or s. The routines get_Xfield_* all return an array type consistent with the fields (real or complex). The routines get_epsilon() and get_mu() accept the optional argument frequency (defaults to 0) and all routines accept snap (defaults to False).

Note on array-slice dimensions: The routines get_epsilon, get_Xfield_z, etc. use as default size=meep.Simulation.fields.total_volume() which for simulations involving Bloch-periodic boundaries (via k_point) will result in arrays that have slightly different dimensions than e.g. get_array(center=meep.Vector3(), size=cell_size, component=meep.Dielectric, etc. (i.e., the slice spans the entire cell volume cell_size). Neither of these approaches is "wrong", they are just slightly different methods of fetching the boundaries. The key point is that if you pass the same value for the size parameter, or use the default, the slicing routines always give you the same-size array for all components. You should not try to predict the exact size of these arrays; rather, you should simply rely on Meep's output.

Returns the Fourier-transformed fields as a NumPy array. The type is either numpy.complex64 or numpy.complex128 depending on the floating-point precision of the fields. The DFT fields are centered on the Yee-grid voxels using bilinear interpolation of the nearest Yee-grid points.

• dft_obj [ DftObj class ] — A dft_flux, dft_force, dft_fields, or dft_near2far object obtained from calling the appropriate add function (e.g., mp.add_flux).

• component [ component constant ]— The field component (e.g., meep.Ez).

• num_freq [ int ] — The index of the frequency. An integer in the range 0...nfreq-1, where nfreq is the number of frequencies stored in dft_obj as set by the nfreq parameter to add_dft_fields, add_flux, etc.

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:

• x,y,z are 1d NumPy arrays storing the $x,y,z$ coordinates of the points in the grid slice
• w is a NumPy array of the same dimensions as the array returned by get_array/get_dft_array, whose entries are the weights in a cubature rule for integrating over the spatial region (with the points in the cubature rule being just the grid points contained in the region). Thus, if $Q(\mathbf{x})$ is some spatially-varying quantity whose value at the $n$th grid point is $Q_n$, the integral of $Q$ over the region may be approximated by the sum:

$$\int_{\mathcal V} Q(\mathbf{x})d\mathbf{x} \approx \sum_{n} w_n Q_n.$$

This is a 1-, 2-, or 3-dimensional integral depending on the number of dimensions in which $\mathcal{V}$ has zero extent. If the $Q_n$ samples are stored in an array Q of the same dimensions as w, then evaluating the sum on the RHS is just one line: np.sum(w*Q).

A convenience parameter dft_cell is provided as an alternative to vol or center/size. Set dft_cell to a dft_flux or dft_fields object to define the region covered by the array. If the dft_cell argument is provided then all other arguments related to the spatial region (vol, center, and size) are ignored. If no arguments are provided, then the entire cell is used.

For empty dimensions of the grid slice get_array_metadata will collapse the two elements corresponding to the nearest Yee grid points into a single element using linear interpolation.

If return_pw=True, the return value is a 2-tuple (p,w) where p (points) is a list of mp.Vector3s with the same dimensions as w (weights). Otherwise, by default the return value is a 4-tuple (x,y,z,w).

Return an array of complex values of the source amplitude for component over the given vol or center/size. The array has the same dimensions as that returned by get_array. Not supported for cylindrical coordinates.

Creates a Medium object.

• epsilon [number] The frequency-independent isotropic relative permittivity or dielectric constant. Default is 1. You can also use index=n as a synonym for epsilon=n*n; note that this is not really the refractive index if you also specify μ, since the true index is $\sqrt{\mu\varepsilon}$. Using epsilon=ep is actually a synonym for epsilon_diag=mp.Vector3(ep, ep, ep).

• epsilon_diag and epsilon_offdiag [Vector3] — These properties allow you to specify ε as an arbitrary real-symmetric tensor by giving the diagonal and offdiagonal parts. Specifying epsilon_diag=Vector3(a, b, c) and/or epsilon_offdiag=Vector3(u, v, w) corresponds to a relative permittivity ε tensor $$\begin{pmatrix} a & u & v \\ u & b & w \\ v & w & c \end{pmatrix}$$ Default is the identity matrix ($a = b = c = 1$ and $u = v = w = 0$).

• mu [number] — The frequency-independent isotropic relative permeability μ. Default is 1. Using mu=pm is actually a synonym for mu_diag=mp.Vector3(pm, pm, pm).

• mu_diag and mu_offdiag [Vector3] — These properties allow you to specify μ as an arbitrary real-symmetric tensor by giving the diagonal and offdiagonal parts exactly as for ε above. Default is the identity matrix.

• D_conductivity [number] — The frequency-independent electric conductivity $\sigma_D$. Default is 0. You can also specify a diagonal anisotropic conductivity tensor by using the property D_conductivity_diag which takes a Vector3 to give the $\sigma_D$ tensor diagonal. See also Conductivity.

• B_conductivity [number] — The frequency-independent magnetic conductivity $\sigma_B$. Default is 0. You can also specify a diagonal anisotropic conductivity tensor by using the property B_conductivity_diag which takes a Vector3 to give the $\sigma_B$ tensor diagonal. See also Conductivity.

• chi2 [number] — The nonlinear electric Pockels susceptibility $\chi^{(2)}$ (quadratic nonlinearity). Default is 0. See also Nonlinearity. This is equivalent to setting E_chi2; alternatively, an analogous magnetic nonlinearity can be specified using H_chi2. These are isotropic nonlinearities, but diagonal anisotropic polarizations of the form $\chi_i^{(2)} E_i^2$ can be specified with E_chi2_diag (which defaults to [E_chi2,E_chi2,E_chi2]).

• chi3 [number] — The nonlinear electric Kerr susceptibility $\chi^{(3)}$ (cubic nonlinearity). Default is 0. See also Nonlinearity. This is equivalent to setting E_chi3; alternatively, an analogous magnetic nonlinearity can be specified using H_chi3. These are isotropic nonlinearities, but diagonal anisotropic polarizations of the form $\chi_i^{(3)} |E|^2 E_i$ can be specified with E_chi3_diag (which defaults to [E_chi3,E_chi3,E_chi3]).

• E_susceptibilities [ list of Susceptibility class ] — List of dispersive susceptibilities (see below) added to the dielectric constant ε in order to model material dispersion. Defaults to none (empty list). See also Material Dispersion.

• H_susceptibilities [ list of Susceptibility class ] — List of dispersive susceptibilities (see below) added to the permeability μ in order to model material dispersion. Defaults to none (empty list). See also Material Dispersion.

Return repr(self).

Returns the medium's permittivity tensor as a 3x3 Numpy array at the specified frequency freq 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.

Returns the medium's permeability tensor as a 3x3 Numpy array at the specified frequency freq 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.

Transforms epsilon, mu, and sigma of any susceptibilities by the 3×3 matrix m. If m is a 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 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.

Creates a MaterialGrid object.

The input are two materials medium1 and medium2 along with a weight function $u(x)$ which is defined on a rectilinear grid by the NumPy array weights of size grid_size (a 3-tuple or Vector3 of integers $N_x$,$N_y$,$N_z$). The resolution of the grid may be nonuniform depending on the size property of the Block object as shown in the following example for a 2d MaterialGrid with $N_x=5$ and $N_y=4$. $N_z=0$ implies that the MaterialGrid is extruded in the $z$ direction. The grid points are defined at the corners of the voxels.

Elements of the weights array must be in the range [0,1] where 0 is medium1 and 1 is medium2. An array of boolean values False and True will be converted to 0 and 1, respectively. The weights array is used to define a linear interpolation from medium1 to medium2. Two material types are supported: (1) frequency-independent isotropic $\varepsilon$ (epsilon_diag and epsilon_offdiag are interpolated) and (2) LorentzianSusceptibility (sigma and sigma_offdiag are interpolated). medium1 and medium2 must both be the same type. The materials are bilinearly interpolated from the rectilinear grid to Meep's Yee grid.

For improving accuracy, subpixel smoothing can be enabled by specifying do_averaging=True. If you want to use a material grid to define a (nearly) discontinuous, piecewise-constant material that is either medium1 or medium2 almost everywhere, you can optionally enable a (smoothed) projection feature by setting the parameter beta to a positive value. The default is no projection (beta=0). When the projection feature is enabled, the weights $u(x)$ can be thought of as a level-set function defining an interface at $u(x)=\eta$ with a smoothing factor $\beta$ where $\beta=+\infty$ gives an unsmoothed, discontinuous interface. The projection operator is $(\tanh(\beta\times\eta) +\tanh(\beta\times(u-\eta)))/(\tanh(\beta\times\eta)+\tanh(\beta\times(1-\eta)))$ involving the parameters beta ($\beta$: bias or "smoothness" of the turn on) and eta ($\eta$: offset for erosion/dilation). The level set provides a general approach for defining a discontinuous function from otherwise continuously varying (via the bilinear interpolation) grid values. Subpixel smoothing is fast and accurate because it exploits an analytic formulation for level-set functions. Note that when subpixel smoothing is enabled via do_averaging=True, projecting the weights is done internally using the beta parameter. It is therefore not necessary to manually project the weights outside of MaterialGrid. However, visualizing the weights used to define the structure does require manually projecting the weights yourself. (Alternatively, you can output the actual structure using plot2D or output_epsilon.)

A nonzero damping term creates an artificial conductivity $\sigma = u(1-u)*$ damping, which acts as dissipation loss that penalizes intermediate pixel values of non-binarized structures. The value of damping should be proportional to $2\pi$ times the typical frequency of the problem.

It is possible to overlap any number of different MaterialGrids. This can be useful for defining grids which are symmetric (e.g., mirror, rotation). One way to set this up is by overlapping a given MaterialGrid object with a symmetrized copy of itself. In the case of spatially overlapping MaterialGrid objects (with no intervening objects), any overlapping points are computed using the method grid_type which is one of "U_MIN" (minimum of the overlapping grid values), "U_PROD" (product), "U_MEAN" (mean), "U_DEFAULT" (topmost material grid). In general, these "U_*" options allow you to combine any material grids that overlap in space with no intervening objects.

Reset the weights to x.

• sigma [number] — The scale factor $\sigma$.

You can also specify an anisotropic $\sigma$ tensor by using the property sigma_diag which takes three numbers or a Vector3 to give the $\sigma_n$ tensor diagonal, and sigma_offdiag which specifies the offdiagonal elements (defaults to 0). That is, sigma_diag=mp.Vector3(a, b, c) and sigma_offdiag=mp.Vector3(u, v, w) corresponds to a $\sigma$ tensor

$$\begin{pmatrix} a & u & v \\ u & b & w \\ v & w & c \end{pmatrix}$$

• frequency [number] — The resonance frequency $f_n = \omega_n / 2\pi$.

• gamma [number] — The resonance loss rate $\gamma_n / 2\pi$.

Note: multiple objects with identical values for the frequency and gamma but different sigma will appear as a single Lorentzian susceptibility term in the preliminary simulation info output.

• frequency [number] — The frequency scale factor $f_n = \omega_n / 2\pi$ which multiplies $\sigma$ (not a resonance frequency).

• gamma [number] — The loss rate $\gamma_n / 2\pi$.

• sigma [number] — The scale factor $\sigma$.

You can also specify an anisotropic $\sigma$ tensor by using the property sigma_diag which takes three numbers or a Vector3 to give the $\sigma_n$ tensor diagonal, and sigma_offdiag which specifies the offdiagonal elements (defaults to 0). That is, sigma_diag=mp.Vector3(a, b, c) and sigma_offdiag=mp.Vector3(u, v, w) corresponds to a $\sigma$ tensor

$$\begin{pmatrix} a & u & v \\ u & b & w \\ v & w & c \end{pmatrix}$$

Construct a Transition.

• frequency [number] — The radiative transition frequency $f = \omega / 2\pi$.

• gamma [number] — The loss rate $\gamma = \gamma / 2\pi$.

• sigma_diag [Vector3] — The per-polarization coupling strength $\sigma$.

• from_level [number] — The atomic level from which the transition occurs.

• to_level [number] — The atomic level to which the transition occurs.

• transition_rate [number] — The non-radiative transition rate $f = \omega / 2\pi$. Default is 0.

• pumping_rate [number] — The pumping rate $f = \omega / 2\pi$. Default is 0.

• noise_amp [number] — The noise has root-mean square amplitude σ $\times$ noise_amp.

This is a somewhat unusual polarizable medium, a Lorentzian susceptibility with a random noise term added into the damped-oscillator equation at each point. This can be used to directly model thermal radiation in both the far field and the near field. Note, however that it is more efficient to compute far-field thermal radiation using Kirchhoff's law of radiation, which states that emissivity equals absorptivity. Near-field thermal radiation can usually be computed more efficiently using frequency-domain methods, e.g. via SCUFF-EM, as described e.g. here or here.

• noise_amp [number] — The noise has root-mean square amplitude σ $\times$ noise_amp.

This is a somewhat unusual polarizable medium, a Lorentzian susceptibility with a random noise term added into the damped-oscillator equation at each point. This can be used to directly model thermal radiation in both the far field and the near field. Note, however that it is more efficient to compute far-field thermal radiation using Kirchhoff's law of radiation, which states that emissivity equals absorptivity. Near-field thermal radiation can usually be computed more efficiently using frequency-domain methods, e.g. via SCUFF-EM, as described e.g. here or here.

• bias [Vector3] — The gyrotropy vector. Its direction determines the orientation of the gyrotropic response, and the magnitude is the precession frequency $|\mathbf{b}_n|/2\pi$.

• bias [Vector3] — The gyrotropy vector. Its direction determines the orientation of the gyrotropic response, and the magnitude is the precession frequency $|\mathbf{b}_n|/2\pi$.

• sigma [number] — The coupling factor $\sigma_n / 2\pi$ between the polarization and the driving field. In magnetic ferrites, this is the Larmor precession frequency at the saturation field.

• frequency [number] — The Larmor precession frequency, $f_n = \omega_n / 2\pi$.

• gamma [number] — The loss rate $\gamma_n / 2\pi$ in the off-diagonal response.

• alpha [number] — The loss factor $\alpha_n$ in the diagonal response. Note that this parameter is dimensionless and contains no 2π factor.

• bias [Vector3] — Vector specifying the orientation of the gyrotropic response. Unlike the similarly-named bias parameter for the gyrotropic Lorentzian/Drude susceptibilities, the magnitude is ignored; instead, the relevant precession frequencies are determined by the sigma and frequency parameters.

Return the sum of the two vectors.

v3 = v1 + v2

Returns whether or not the two vectors are numerically equal. Beware of using this function after operations that may have some error due to the finite precision of floating-point numbers; use close instead.

v1 == v2

Create a new Vector3 with the given components. All three components default to zero. This can also be represented simply as (x,y,z) or [x,y,z].

If other is a Vector3, returns the dot product of v1 and other. If other is a number, then v1 is scaled by the number.

c = v1 * other

Returns whether or not the two vectors are numerically unequal. Beware of using this function after operations that may have some error due to the finite precision of floating-point numbers; use close instead.

v1 != v2

Return repr(self).

If other is a Vector3, returns the dot product of v1 and other. If other is a number, then v1 is scaled by the number.

c = other * v1

Return the difference of the two vectors.

v3 = v1 - v2

Returns the conjugated dot product: conj(self) dot v.

Returns whether or not the corresponding components of the self and v vectors are within tol of each other. Defaults to 1e-7.

v1.close(v2, [tol])

Return the cross product of self and v.

v3 = v1.cross(v2)

Returns the dot product of self and v.

v3 = v1.dot(v2)

Returns the length math.sqrt(abs(self.dot(self))) of the given vector.

v2 = v1.norm()

Returns the vector rotated by an angle theta (in radians) in the right-hand direction around the axis vector (whose length is ignored). You may find the python functions math.degrees and math.radians useful to convert angles between degrees and radians.

v2 = v1.rotate(axis, theta)

Returns a unit vector in the direction of the vector.

v2 = v1.unit()

Construct a GeometricObject.

• material [Medium class or function ] — The material that the object is made of (usually some sort of dielectric). Uses default Medium. If a function is supplied, it must take one argument and return a Python Medium.

• epsilon_func [ function ] — A function that takes one argument (a Vector3) and returns the dielectric constant at that point. Can be used instead of material. Default is None.

• center [Vector3] — Center point of the object. Defaults to (0,0,0).

One normally does not create objects of type GeometricObject directly, however; instead, you use one of the following subclasses. Recall that subclasses inherit the properties of their superclass, so these subclasses automatically have the material and center properties and can be specified in a subclass's constructor via keyword arguments.

Displays all properties and current values of a GeometricObject, indented by indent_by spaces (default is 0).

Shifts the object's center by vec (Vector3), returning a new object. This can also be accomplished via the + operator:

geometric_obj + Vector3(10,10,10)

Using += will shift the object in place.

Constructs a Sphere

Constructs a Cylinder.

Constructs a Wedge.

Construct a Cone.

radius2 [number] — Radius of the tip of the cone (i.e. the end of the cone pointed to by the axis vector). Defaults to zero (a "sharp" cone).

Construct a Block.

• size [Vector3] — The lengths of the block edges along each of its three axes. Not really a 3-vector, but it has three components, each of which should be nonzero. No default value.

• e1, e2, e3 [Vector3] — The directions of the axes of the block; the lengths of these vectors are ignored. Must be linearly independent. They default to the three lattice directions.

Construct an Ellipsoid.

Construct a Prism.

• vertices [list of Vector3] — The vertices that make up the prism. They must lie in a plane that's perpendicular to the axis. Note that infinite lengths are not supported. To simulate infinite geometry, just extend the edge of the prism beyond the cell.

• height [number] — The prism thickness, extruded in the direction of axis. mp.inf can be used for infinite height. No default value.

• axis [Vector3] — The axis perpendicular to the prism. Defaults to Vector3(0,0,1).

• center [Vector3] — If center is not specified, then the coordinates of the vertices define the bottom of the prism with the top of the prism being at the same coordinates shifted by height*axis. If center is specified, then center is the coordinates of the centroid of all the vertices (top and bottom) of the resulting 3d prism so that the coordinates of the vertices are shifted accordingly.

• sidewall_angle [number] — The sidewall angle of the prism in units of radians. Default is 0.

Constructs a Matrix.

Return repr(self).

Construct a Symmetry.

• direction [direction constant ] — The direction of the symmetry (the normal to a mirror plane or the axis for a rotational symmetry). e.g. X, Y, or Z (only Cartesian/grid directions are allowed). No default value.

• phase [complex] — An additional phase to multiply the fields by when operating the symmetry on them. Default is +1, e.g. a phase of -1 for a mirror plane corresponds to an odd mirror. Technically, you are essentially specifying the representation of the symmetry group that your fields and sources transform under.

• thickness [number] — The spatial thickness of the PML layer which extends from the boundary towards the inside of the cell. The thinner it is, the more numerical reflections become a problem. No default value.

• direction [direction constant ] — Specify the direction of the boundaries to put the PML layers next to. e.g. if X, then specifies PML on the $\pm x$ boundaries (depending on the value of side, below). Default is the special value ALL, which puts PML layers on the boundaries in all directions.

• side [side constant ] — Specify which side, Low or High of the boundary or boundaries to put PML on. e.g. if side is Low and direction is meep.X, then a PML layer is added to the $-x$ boundary. Default is the special value meep.ALL, which puts PML layers on both sides.

• R_asymptotic [number] — The asymptotic reflection in the limit of infinite resolution or infinite PML thickness, for reflections from air (an upper bound for other media with index > 1). For a finite resolution or thickness, the reflection will be much larger, due to the discretization of Maxwell's equation. Default value is 10⁻¹⁵, which should suffice for most purposes. You want to set this to be small enough so that waves propagating within the PML are attenuated sufficiently, but making R_asymptotic too small will increase the numerical reflection due to discretization.

• pml_profile [function] — By default, Meep turns on the PML conductivity quadratically within the PML layer — one doesn't want to turn it on suddenly, because that exacerbates reflections due to the discretization. More generally, with pml_profile one can specify an arbitrary PML "profile" function $f(u)$ that determines the shape of the PML absorption profile up to an overall constant factor. u goes from 0 to 1 at the start and end of the PML, and the default is $f(u) = u^2$. In some cases where a very thick PML is required, such as in a periodic medium (where there is technically no such thing as a true PML, only a pseudo-PML), it can be advantageous to turn on the PML absorption more smoothly. See Optics Express, Vol. 16, pp. 11376-92 (2008). For example, one can use a cubic profile $f(u) = u^3$ by specifying pml_profile=lambda u: u*u*u.

Construct a Source.

• src [SourceTime class ] — Specify the time-dependence of the source (see below). No default.

• component [component constant ] — Specify the direction and type of the current component: e.g. mp.Ex, mp.Ey, etcetera for an electric-charge current, and mp.Hx, mp.Hy, etcetera for a magnetic-charge current. Note that currents pointing in an arbitrary direction are specified simply as multiple current sources with the appropriate amplitudes for each component. No default.

• center [Vector3] — The location of the center of the current source in the cell. No default.

• size [Vector3] — The size of the current distribution along each direction of the cell. Default is (0,0,0): a point-dipole source.

• volume [Volume] — A meep.Volume can be used to specify the source region instead of a center and a size.

• amplitude [complex] — An overall complex amplitude multiplying the current source. Default is 1.0. Note that specifying a complex amplitude imparts a phase shift to the real part of the overall current and thus does not require using complex fields for the entire simulation (via force_complex_fields=True).

• amp_func [function] — A Python function of a single argument, that takes a Vector3 giving a position and returns a complex current amplitude for that point. The position argument is relative to the center of the current source, so that you can move your current around without changing your function. Default is None, meaning that a constant amplitude of 1.0 is used. Note that your amplitude function (if any) is multiplied by the amplitude property, so both properties can be used simultaneously.

• amp_func_file [string] — String of the form path_to_h5_file.h5:dataset. The .h5 extension is optional. Meep will read the HDF5 file and create an amplitude function that interpolates into the grid specified by the file. Meep expects the data to be split into real and imaginary parts, so in the above example it will look for dataset.re and dataset.im in the file path_to_h5_file.h5. Defaults to the empty string.

• amp_data [numpy.ndarray with dtype=numpy.complex128] — Like amp_func_file above, but instead of interpolating into an HDF5 file, interpolates into a complex NumPy array. The array should be three dimensions. For a 2d simulation, just pass 1 for the third dimension, e.g., arr = np.zeros((N, M, 1), dtype=np.complex128). Defaults to None.

As described in Section 4.2 ("Incident Fields and Equivalent Currents") in Chapter 4 ("Electromagnetic Wave Source Conditions") of the book Advances in FDTD Computational Electrodynamics: Photonics and Nanotechnology, it is also possible to supply a source that is designed to couple exclusively into a single waveguide mode (or other mode of some cross section or periodic region) at a single frequency, and which couples primarily into that mode as long as the bandwidth is not too broad. This is possible if you have MPB installed: Meep will call MPB to compute the field profile of the desired mode, and use the field profile to produce an equivalent current source. The mode-launcher feature does not work in cylindrical coordinates. To use the mode launcher, instead of a source you should use an EigenModeSource.

Construct an EigenModeSource.

• eig_band [integer or DiffractedPlanewave class] — Either the index $n$ (1,2,3,...) of the desired band $\omega_n(\mathbf{k})$ to compute in MPB where 1 denotes the lowest-frequency band at a given $\mathbf{k}$ point, and so on, or alternatively a diffracted planewave in homogeneous media.

• direction [mp.X, mp.Y, or mp.Z; default mp.AUTOMATIC], eig_match_freq [boolean; default True], eig_kpoint [Vector3] — By default (if eig_match_freq is True), Meep tries to find a mode with the same frequency $\omega_n(\mathbf{k})$ as the src property (above), by scanning $\mathbf{k}$ vectors in the given direction using MPB's find_k functionality. Alternatively, if eig_kpoint is supplied, it is used as an initial guess for $\mathbf{k}$. By default, direction is the direction normal to the source region, assuming size is $d$–1 dimensional in a $d$-dimensional simulation (e.g. a plane in 3d). If direction is set to mp.NO_DIRECTION, then eig_kpoint is not only the initial guess and the search direction of the $\mathbf{k}$ vectors, but is also taken to be the direction of the waveguide, allowing you to launch modes in oblique ridge waveguides (not perpendicular to the source plane). If eig_match_freq is False, then the $\mathbf{k}$ vector of the desired mode is specified with eig_kpoint (in Meep units of 2π/(unit length)). Also, the eigenmode frequency computed by MPB overwrites the frequency parameter of the src property for a GaussianSource and ContinuousSource but not CustomSource (the width or any other parameter of src is unchanged). By default, the $\mathbf{k}$ components in the plane of the source region are zero. However, if the source region spans the entire cell in some directions, and the cell has Bloch-periodic boundary conditions via the k_point parameter, then the mode's $\mathbf{k}$ components in those directions will match k_point so that the mode satisfies the Meep boundary conditions, regardless of eig_kpoint. Note that once $\mathbf{k}$ is either found by MPB, or specified by eig_kpoint, the field profile used to create the current sources corresponds to the Bloch mode, $\mathbf{u}_{n,\mathbf{k}}(\mathbf{r})$, multiplied by the appropriate exponential factor, $e^{i \mathbf{k} \cdot \mathbf{r}}$.

• eig_parity [mp.NO_PARITY (default), mp.EVEN_Z, mp.ODD_Z, mp.EVEN_Y, mp.ODD_Y] — The parity (= polarization in 2d) of the mode to calculate, assuming the structure has $z$ and/or $y$ mirror symmetry in the source region, with respect to the center of the source region. (In particular, it does not matter if your simulation as a whole has that symmetry, only the cross section where you are introducing the source.) If the structure has both $y$ and $z$ mirror symmetry, you can combine more than one of these, e.g. EVEN_Z + ODD_Y. Default is NO_PARITY, in which case MPB computes all of the bands which will still be even or odd if the structure has mirror symmetry, of course. This is especially useful in 2d simulations to restrict yourself to a desired polarization.

• eig_resolution [integer, defaults to 2*resolution ] — The spatial resolution to use in MPB for the eigenmode calculations. This defaults to twice the Meep resolution in which case the structure is linearly interpolated from the Meep pixels.

• eig_tolerance [number, defaults to 10^–12 ] — The tolerance to use in the MPB eigensolver. MPB terminates when the eigenvalues stop changing to less than this fractional tolerance.

• component [as above, but defaults to ALL_COMPONENTS] — Once the MPB modes are computed, equivalent electric and magnetic sources are created within Meep. By default, these sources include magnetic and electric currents in all transverse directions within the source region, corresponding to the mode fields as described in Section 4.2 ("Incident Fields and Equivalent Currents") in Chapter 4 ("Electromagnetic Wave Source Conditions") of the book Advances in FDTD Computational Electrodynamics: Photonics and Nanotechnology. If you specify a component property, however, you can include only one component of these currents if you wish. Most users won't need this feature.

• eig_lattice_size [Vector3], eig_lattice_center [Vector3] — Normally, the MPB computational unit cell is the same as the source volume given by the size and center parameters. However, occasionally you want the unit cell to be larger than the source volume. For example, to create an eigenmode source in a periodic medium, you need to pass MPB the entire unit cell of the periodic medium, but once the mode is computed then the actual current sources need only lie on a cross section of that medium. To accomplish this, you can specify the optional eig_lattice_size and eig_lattice_center, which define a volume (which must enclose size and center) that is used for the unit cell in MPB with the dielectric function ε taken from the corresponding region in the Meep simulation.

Returns the total power of the fields from the eigenmode source at frequency freq.

Construct a GaussianBeamSource.

• beam_x0 [Vector3] — The location of the beam focus relative to the center of the source. The beam focus does not need to lie within the source region (i.e., the beam focus can be anywhere, inside or outside the cell, independent of the position of the source).

• beam_kdir [Vector3] — The propagation direction of the beam. The length is ignored. The wavelength of the beam is determined by the center frequency of the Source.src object and the refractive index (real part only) at the center of the source region.

• beam_w0 [number] — The beam waist radius.

• beam_E0 [Vector3] — The polarization vector of the beam. Elements can be complex valued (i.e., for circular polarization). The polarization vector must be parallel to the source region in order to generate a transverse mode.

Construct a ContinuousSource.

• frequency [number] — The frequency f in units of $c$/distance or ω in units of 2π$c$/distance. See Units. No default value. You can instead specify wavelength=x or period=x, which are both a synonym for frequency=1/x; i.e. 1/ω in these units is the vacuum wavelength or the temporal period.

• start_time [number] — The starting time for the source. Default is 0 (turn on at $t=0$).

• end_time [number] — The end time for the source. Default is 10²⁰ (never turn off).

• width [number] — Roughly, the temporal width of the smoothing (technically, the inverse of the exponential rate at which the current turns off and on). Default is 0 (no smoothing). You can instead specify fwidth=x, which is a synonym for width=1/x (i.e. the frequency width is proportional to the inverse of the temporal width).

• slowness [number] — Controls how far into the exponential tail of the tanh function the source turns on. Default is 3.0. A larger value means that the source turns on more gradually at the beginning. For a detailed explanation of the effects of width and slowness on the time profile of the source, see here.

• is_integrated [boolean] — If True, the source is the integral of the current (the dipole moment) which oscillates but does not increase for a sinusoidal current. In practice, there is little difference between integrated and non-integrated sources except for planewaves extending into PML. Default is False.

Construct a GaussianSource.

• frequency [number] — The center frequency $f$ in units of $c$/distance (or $\omega$ in units of $2\pi c$/distance). See Units. No default value. You can instead specify wavelength=x or period=x, which are both a synonym for frequency=1/x; i.e. $1/\omega$ in these units is the vacuum wavelength or the temporal period.

• width [number] — The width $w$ used in the Gaussian. No default value. You can instead specify fwidth=x, which is a synonym for width=1/x (i.e. the frequency width is proportional to the inverse of the temporal width).

• start_time [number] — The starting time for the source; default is 0 (turn on at $t=0$). This is not the time of the peak. See below.

• cutoff [number] — How many widths the current decays for before it is cut off and set to zero — this applies for both turn-on and turn-off of the pulse. Default is 5.0. A larger value of cutoff will reduce the amount of high-frequency components that are introduced by the start/stop of the source, but will of course lead to longer simulation times. The peak of the Gaussian is reached at the time $t_0$=start_time + cutoff*width.

• is_integrated [boolean] — If True, the source is the integral of the current (the dipole moment) which is guaranteed to be zero after the current turns off. In practice, there is little difference between integrated and non-integrated sources except for planewaves extending into PML. Default is False.

• fourier_transform(f) — Returns the Fourier transform of the current evaluated at frequency $f$ ($\omega=2\pi f$) given by: $$\widetilde G(\omega) \equiv \frac{1}{\sqrt{2\pi}} \int e^{i\omega t}G(t)\,dt \equiv \frac{1}{\Delta f} e^{i\omega t_0 -\frac{(\omega-\omega_0)^2}{2\Delta f^2}}$$ where $G(t)$ is the current (not the dipole moment). In this formula, $\Delta f$ is the fwidth of the source, $\omega_0$ is $2\pi$ times its frequency, and $t_0$ is the peak time discussed above. Note that this does not include any amplitude or amp_func factor that you specified for the source.

Construct a CustomSource.

• src_func [function] — The function $f(t)$ specifying the time-dependence of the source. It should take one argument (the time in Meep units) and return a complex number.

• start_time [number] — The starting time for the source. Default is -10²⁰: turn on at $t=-\infty$. Note, however, that the simulation normally starts at $t=0$ with zero fields as the initial condition, so there is implicitly a sharp turn-on at $t=0$ whether you specify it or not.

• end_time [number] — The end time for the source. Default is 10²⁰ (never turn off).

• is_integrated [boolean] — If True, the source is the integral of the current (the dipole moment) which is guaranteed to be zero after the current turns off. In practice, there is little difference between integrated and non-integrated sources except for planewaves extending into PML. Default is False.

• center_frequency [number] — Optional center frequency so that the CustomSource can be used within an EigenModeSource. Defaults to 0.

• fwidth [number] — Optional bandwidth in frequency units. Default is 0. For bandwidth-limited sources, this parameter is used to automatically determine the decimation factor of the time-series updates of the DFT fields monitors (if any).

Construct a FluxRegion object.

• center [Vector3] — The center of the flux region (no default).

• size [Vector3] — The size of the flux region along each of the coordinate axes. Default is (0,0,0); a single point.

• direction [direction constant ] — The direction in which to compute the flux (e.g. mp.X, mp.Y, etcetera). Default is AUTOMATIC, in which the direction is determined by taking the normal direction if the flux region is a plane (or a line, in 2d). If the normal direction is ambiguous (e.g. for a point or volume), then you must specify the direction explicitly (not doing so will lead to an error).

• weight [complex] — A weight factor to multiply the flux by when it is computed. Default is 1.0.

• volume [Volume] — A meep.Volume can be used to specify the flux region instead of a center and a size.

Construct a Volume.

Call self as a function.

Construct an Animate2D object.

• sim — Optional Simulation object (this has no effect, and is included for backwards compatibility).

• fields — Optional field component to record at each time instant.

• f — Optional matplotlib figure object that the routine will update on each call. If not supplied, then a new one will be created upon initialization.

• realtime — Whether or not to update a figure window in realtime as the simulation progresses. Disabled by default.

• normalize — Records fields at each time step in memory in a NumPy array and then normalizes the result by dividing by the maximum field value at a single point in the cell over all the time snapshots.

• plot_modifiers — A list of functions that can modify the figure's axis object. Each function modifier accepts a single argument, an axis object, and must return that same axis object. The following modifier changes the xlabel:

  def mod1(ax):
      ax.set_xlabel('Testing')
      return ax

  plot_modifiers = [mod1]

• update_epsilon — Redraw epsilon on each call. (Useful for topology optimization)

• nb — For the animation work in a Jupyter notebook, set to True and use the cell magic: %matplotlib ipympl

• **customization_args — Customization keyword arguments passed to plot2D() (i.e. labels, eps_parameters, boundary_parameters, etc.)

Generates and outputs a GIF file of the animation with the filename, filename, and the frame rate, fps. Note that GIFs are significantly larger than mp4 videos since they don't use any compression. Artifacts are also common because the GIF format only supports 256 colors from a predefined color palette. Requires ffmpeg.

Outputs an interactable JSHTML animation object that is embeddable in Jupyter notebooks. The object is packaged with controls to manipulate the video's playback. User must specify a frame rate fps in frames per second.

Generates and outputs an mp4 video file of the animation with the filename, filename, and the frame rate, fps. Default encoding is h264 with yuv420p format. Requires ffmpeg.

Allows a Haminv instance to be used as a step function.

Construct a Harminv object.

A Harminv is a step function that collects data from the field component c (e.g. $E_x$, etc.) at the given point pt (a Vector3). Then, at the end of the run, it uses Harminv to look for modes in the given frequency range (center fcen and width df), printing the results to standard output (prefixed by harminv:) as comma-delimited text, and also storing them to the variable Harminv.modes. The optional argument mxbands is the maximum number of modes to search for. Defaults to 100.

Allows a PadeDFT instance to be used as a step function.

Construct a Padé DFT object.

A PadeDFT is a step function that collects data from the field component c (e.g. meep.Ex, etc.) at the given point pt (a Vector3). Then, at the end of the run, it uses the scipy Padé algorithm to approximate the analytic frequency response at the specified point.

• c [ component constant ] — The field component to use for extrapolation. No default.
• vol [ Volume class ] — The volume over which to accumulate the fields (may be 0d, 1d, 2d, or 3d). No default.
• center [ Vector3 class ] — Alternative method for specifying volume, using a center point
• size [ Vector3 class ] — Alternative method for specifying volume, using a size vector
• m [ int ] — The order of the numerator $P$. If not specified, defaults to the length of aggregated field data times m_frac.
• n [ int ] — The order of the denominator $Q$. Defaults to length of field data - m - 1.
• m_frac [ float ] — Method for specifying m as a fraction of field samples to use as the order for numerator. Default is 0.5.
• n_frac [ float ] — Fraction of field samples to use as order for denominator. No default.
• sampling_interval [ int ] — The interval at which to sample the field data. Defaults to 1.
• start_time [ int ] — The time (in increments of $\Delta t$) at which to start sampling the field data. Default is 0 (beginning of simulation).
• stop_time [ int ] — The time (in increments of $\Delta t$) at which to stop sampling the field data. Default is None (end of simulation).

See add_verbosity_var()

Convenience for setting the verbosity level. This lets you set the global level by calling the instance like a function. For example, if verbosity is an instance of this class, then its value can be changed like this:

verbosity(0)

Add a new verbosity flag to be managed. cvar should be some object that has a verbosity attribute, such as meep.cvar or mpb.cvar.

Returns the current global verbosity level.

Validates the range, and sets the global verbosity level. Returns the former value.

The constructor accepts three separate groups of arguments: (1) data: a list of lists where each list entry is either (a) a node defined as [ (split_dir,split_pos), left, right ] for which split_dir and split_pos define the splitting direction (i.e., mp.X, mp.Y, mp.Z) and position (e.g., 3.5, -4.2, etc.) and left and right are the two branches (themselves BinaryPartition objects) or (b) a leaf with integer value for the process ID proc_id in the range between 0 and number of processes - 1 (inclusive), (2) a node defined using split_dir, split_pos, left, and right, or (3) a leaf with proc_id. Note that the same process ID can be assigned to as many chunks as you want, which means that one process timesteps multiple chunks. If you use fewer MPI processes, then the process ID is taken modulo the number of processes.

Pretty-prints the tree structure of the BinaryPartition object.