Configuration and customization¶

:meep_adjoint is highly customizable, offering a large number of user-configurable options and a convenient hierarchical framework for setting and updating their values.

What are the configurable options? How do they affect the behavior of the package?¶

At the bottom of this page you’ll find an exhaustive bleeding-edge list autogenerated from the most recent version of the meep_adjoint source code, but for starters here are some of the more useful options, categorized by the sector of meep_adjoint behavior they affect:

Options governing FDTD calculations and simulation geometries

res: Yee grid resolution

dpml: Width of PML layers

dft_reltol: Continue timestepping until frequency-domain fields have converged to within this relative error

Options governing design optimization

element_type: type (family and order) of finite-element basis function, as tabulated e.g. in the FENICS documentation or the periodic table of finite elements.

element_length: lengthscale of finite-element discretization

alpha: relaxation parameter for simple gradient-descent optimizer

Options governing console and file output

filebase: base name of output files

silence_meep: suppress :codename:meep console messages
during timestepping

Options governing graphical visualization

latex: Use math:LaTeX formatting for graph axes and titles

linecolor: Color of lines and curves (default)

src_region_linecolor: Color of lines and curves in plots of source regions

flux_region_linecolor: Color of lines and curves in plots of flux regions

flux_data_linecolor: Color of lines and curves in plots of flux data

How do I fetch current option settings from `meep_adjoint` driver scripts?¶

By calling meep_adjoint.get_adjoint_option or meep_adjoint.get_visualization_option:

from meep_adjoint import get_adjoint_option as adj_opt
from meep_adjoint import get_visualization_option as vis_opt

fcen = adj_opt('fcen')

src_lc = vis_opt('src_region_linecolor')

foo = adj_opt('bar')

if foo is None:
    print('Whoops! There is no option named --bar.')

Visualization options and adjoint options

Internally, the package distinguishes two categories of configuration options:

options that control the behavior of the visualization module, and

everything else.

We refer to these respectively as visualization options and adjoint options.

One reason for the distinction is that, for visualization options but not adjoint options, there is a further subdivision into sectioned vs. non-sectioned options, as discussed below.

How does `meep_adjoint` determine settings for configuration options?¶

meep_adjoint begins by setting each option to the hard-coded default value provided as part of the option’s definition (see below), then looks for updates in each of the following places, in the following sequence, with each update overriding the previous setting.

2. Script-level defaults

The python script you write to drive meep_adjoint may call meep_adjoint.set_option_defaults to specify problem-specific default values for certain options.

3. User-level defaults: Global configuration files

The global configuration files are ~/.meep_adjoint.rc, ~/.meep_visualization.rc. Typically this would be for options on which you have a personal preference that differs from the meep_adjoint default and which you want to configure once and for all and have it be generally active in all your meep_adjoint sessions, except where overruled by a setting from a higher-priority source like command-line. Example: If you love chartreuse and hate cyan, you will want to change the default colors used by the visualization module to draw Poynting-flux monitors, and you’ll want this change to be generally in effect in all your sessions unless specifically overridden.

4. Project-level defaults: Local configuration files

The local configuration files are meep_adjoint.rc, meep_visualization.rc in the current working directory. These are for updates that you want to be in effect for all work on a particular project.

5. Session-level settings: Environment variables

6. Run-level settings: Command-line arguments

7. Console-level / function-call level settings

Adjoint options¶

Options affecting FDTD geometries/computation¶
Option	Default	Description
`res`	20.0	Yee grid resolution
`fcen`	0.0	source center frequency
`df`	0.0	source frequency width
`source_component`	Ez	forward source component (str)
`source_mode`	1	forward source eigenmode index
`nfreq`	1	number of DFT frequencies
`dpml`	-1.0	PML width (-1 –> auto-select)
`dair`	-1.0	gap width between material bodies and PMLs (-1 –> auto-select)
`eps_design`	1.0	function of (x,y,z) giving initial design permittivity
`dft_reltol`	1e-06	convergence tolerance for terminating timestepping
`dft_timeout`	10.0	max runtime in units of last_source_time
`dft_interval`	0.25	meep time between DFT convergence checks in units of last_source_time
`complex_fields`	False	use complex fields in forward calculation
`reuse_simulation`	False	reuse (do not reallocate) simulation data structure

Options affecting basis-set expansions¶
Option	Default	Description
`beta_min`	0.0	lower bound on basis expansion coefficient
`beta_max`	inf	upper bound on basis expansion coefficient
`element_type`	CG 1	finite-element family and degree
`element_length`	0.0	finite-element discretization length

Options affecting gradient-duhscent optimizer¶
Option	Default	Description
`alpha`	1.0	initial value of alpha (update relaxation parameter)
`alpha_min`	0.001	minimum value of alpha
`alpha_max`	10.0	maximum value of alpha
`boldness`	1.25	sometimes you just gotta live a little (explain me)
`timidity`	0.75	can’t be too cautious in this dangerous world (explain me)
`max_iters`	100	max number of optimization iterations

Options affecting console/file/GUI output¶
Option	Default	Description
`filebase`		base name of output files
`silence_meep`	True	suppress MEEP console messages when timestepping
`loglevel`	info	[‘info’\|’debug’]
`visualization`	auto	[‘on’\|’off’\|’auto’] to enable/disable/automate graphical visualization
`termcolors`	True	output colorized terminal text
`dashboard`	auto	[‘on’\|’off’\|’auto’] to enable/disable/automate GUI dashboard
`dashboard_size`	0.5	GUI dashboard size relative to screen size
`dashboard_position`	top right	GUI dashboard position
`dashboard_font_family`	Fantasque Sans Mono	GUI dashboard font family
`dashboard_font_scale`	1.0	GUI dashboard font scale factor
`dashboard_on_top`	True	GUI dashboard stays on top of other windows
`dashboard_cpu_interval`	2000	GUI dashboard CPU usage update interval (ms)
`dashboard_host`	localhost	GUI dashboard server hostname
`dashboard_port`	37673	GUI dashboard server port
`dashboard_loglevel`	info	‘info’ \| ‘debug’

Visualization options¶

Sectioned visualization options¶

Sectioned visualization options¶
Option	Default	Description
`cmap`	plasma	default colormap
`alpha`	1.0	default transparency
`fontsize`	25	font size for labels and titles
`shading`	gouraud	shading style
`interp`	gaussian	interpolation method
`method`	contourf	contourf \| imshow \|pcolormesh
`contours`	100	number of contours
`linecolor`	#ff0000	default line color
`linewidth`	4.0	default line width
`linestyle`		default line style
`fillcolor`	#ffffff	default fill color
`cmin`	-inf	colormap minimum
`cmax`	inf	colormap maximum
`zmin`	0.6
`zmax`	0.8
`cb_pad`	0.04	colorbar padding
`cb_shrink`	0.6	colorbar shrink factor
`latex`	True	LaTeX text formatting
`show`	True	display plots on screen

Other visualization options¶

Other visualization options¶
Option	Default	Description
`backend`	wx	matplotlib backend