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 messagesduring timestepping
- Options governing graphical visualization
latex: Use \(LaTeX\) formatting forgraph 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 set option values?¶
For each configuration option, meep_adjoint consults
the following fixed sequence of
- 1. Package-level default settings
Each option is assigned a (non-
None):2. Default Driver script
The python script you write to drive your
meep_adjointstudy may optionally override custom defaults override the package-level option defaults
- 3. User-level defaults
Global configuration files:
- 4. Project-level defaults
Local configuration files:
- 5. Session-level settings
Environment variables:
- 6. Run-level settings
Command-line arguments:
- 7. Function-level settings
The optional
optionsparameter in API routines
API routines for querying current values of configuration options¶
Implementation¶
Options¶
General overview¶
Internally, the module maintains two separate databases of option
settings: one for options that specifically affect the appearance of
visualization plots, and a second for all other options. [This is
done both (1) to facilitate a possible future refactoring of the adjoint
and visualization modules into separate standalone packages, and
(2) because the visualization module handles option settings in a
slightly more complicated way than does the adjoint module, as
discussed below.] Both databases are instances of the simple
class OptionAlmanac, which combines the functionality
of the configparser_ and argparse_ modules in the python standard
library.
The hierarchy of sources for option settings¶
As noted above, the module consults multiple sources—in a specific order—for user-specified option settings; any conflicts are adjudicated in favor of the later-encountered source, i.e. new option settings always overwrite existing settings 1.
- 1
An exception is the case in which the type of an option setting
is incompatible with the type of the existing option value; in this case the new setting is ignored with a warning and the previous option value retained.
More specifically, the value stored in the internal database for a given configuration option is initialized and then updated according to the following sequence:
The original default value hard-coded in the
meep_adjointsource distribution.The updated default value specified by a call to
meep_adjoint::set_adjoint_option_defaults()from a user script.The value specified in the global configuration file, if any.
The value specified in the local configuration file, if any.
The value of the option as an environment variable, if set.
The value of the option as a command-line argument, if specified.
Global and local configuration files¶
The configuration files parsed for adjoint and visualization options are as follows.
Global:
~/.meep_adjoint.rc,~/.meep_visualization.rcLocal:
./meep_adjoint.rc,./meep_visualization.rc
Note that global files lie in the user’s home directory and are “dotfiles”, i.e. have filenames that begin with a period. Local files lie in the current working directory and have the same filename as their global counterparts, minus the leading period.