###################################################################### 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 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.') .. admonition:: Visualization options and adjoint options Internally, the package distinguishes two categories of configuration options: + options that control the behavior of the :ref:`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. .. comment:: 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. ====================================================================== How does `meep_adjoint` determine settings for configuration options? ====================================================================== :mod:`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 :file:`~/.meep_adjoint.rc`, :file:`~/.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 :ref:`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 :file:`meep_adjoint.rc`, :file:`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: .. _argparse: https://docs.python.org/3/library/argparse.html#module-argparse .. _configparser: https://docs.python.org/3/library/configparser.html?highlight=configparser#module-configparser .. _`global configuration file`: .. _`local configuration file`: .. _adjoint options: ==================================================================================== Adjoint options ==================================================================================== .. include:: adj_opt_docs.rst .. _visualization options: ==================================================================================== Visualization options ==================================================================================== ++++++++++++++++++++++++++++++++++++++++++++++++++ Sectioned visualization options ++++++++++++++++++++++++++++++++++++++++++++++++++ .. include:: sec_vis_opt_docs.rst ++++++++++++++++++++++++++++++++++++++++++++++++++ Other visualization options ++++++++++++++++++++++++++++++++++++++++++++++++++ .. include:: oth_vis_opt_docs.rst