###################################################################### Configuration and customization ###################################################################### ::mod:`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 :mod:`meep_adjoint` source code, but for starters here are some of the more useful options, categorized by the sector of :mod:`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 set option values? ====================================================================== For each configuration option, :mod:`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 :mod:`meep_adjoint` study 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 ``options`` parameter 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 :class:`OptionAlmanac`, which combines the functionality of the `configparser_` and `argparse_` modules in the python standard library. .. _argparse: https://docs.python.org/3/library/argparse.html#module-argparse .. _configparser: https://docs.python.org/3/library/configparser.html?highlight=configparser#module-configparser 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: 1. The original default value hard-coded in the `meep_adjoint` source distribution. 2. The updated default value specified by a call to `meep_adjoint::set_adjoint_option_defaults()` from a user script. 3. The value specified in the `global configuration file`_, if any. 4. The value specified in the `local configuration file`_, if any. 5. The value of the option as an environment variable, if set. 6. The value of the option as a command-line argument, if specified. .. _`global configuration file`: `local configuration file`_ .. _`local configuration file`: Global and local configuration files -------------------------------------------------- The configuration files parsed for adjoint and visualization options are as follows. * **Global**: :file:`~/.meep_adjoint.rc`, :file:`~/.meep_visualization.rc` * **Local**: :file:`./meep_adjoint.rc`, :file:`./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. Configuration-related API routines ============================================== ******************** Adjoint options ******************** -------------------------------------------------- Options affecting :codename:meep geometries -------------------------------------------------- ************************************************** Trying csv tables... ************************************************** .. csv-table:: Frozen Delights! :header: "Treat", "Quantity", "Description" :widths: 15, 10, 30 "Albatross", 2.99, "On a stick!" "Popcorn", 1.99, "Straight from the oven" .. warning:: This is really a very painful process.