High-level (public) API: Exported classes and functions

The “high-level” API consists of classes, functions, and other python objects intended specifically to be invoked by meep_adjoint users in driver scripts and interactive sessions.

In principle, a high-level API offers access to a package’s full range of capabilities via maximally streamlined and convenient interfaces that do not require users to know anything about under-the-hood implementation details. I think the high-level API to meep_adjoint is quite succcessful by this standard: it should be entirely possible for device engineers to assemble a productive meep_adjoint-based design-optimization workflow using only the public class methods and package-level functions documented on this page.

On the other hand, some users may be interested in delving into the innards of the adjoint-sensitivity implementation in meep_adjoint—perhaps to extend the capabilities of the package, or to improve its performance, or to borrow pieces of the computation for other projects, or perhaps just to trace through the details of how it all works. Users interested in how the sausage is made are referred to the low-level API reference on the following page, as well as the discussion of the class hierarchy in the implementation notes.

OptimizationProblem: Driver class for meep_adjoint sessions

class OptimizationProblem(cell_size=None, background_geometry=[], foreground_geometry=[], sources=None, source_region=[], objective_regions=[], basis=None, design_region=None, extra_regions=[], objective_function=None, extra_quantities=[])

Bases: object

Top-level class in the MEEP adjoint module.

Intended to be instantiated from user scripts with mandatory constructor input arguments specifying the data required to define an adjoint-based optimization.

The class knows how to do one basic thing: Given an input vector of design variables, compute the objective function value (forward calculation) and optionally its gradient (adjoint calculation). This is done by the __call__ method. The actual computations are delegated to a hierarchy of lower-level classes, of which the uppermost is TimeStepper.

cell_sizearray_like

Dimensions of computational cell

background_geometry, foreground_geometrylist of meep.GeometricObject

Size of computational cell and lists of GeometricObjects that {precede,follow} the design object in the overall geometry.

source_regionmeep.Subregion

source region bounding box (to be used in lieu of sources)

sourceslist of meep.Source

(either sources or source_region should be non-None) Specification of forward source distribution, i.e. the source excitation(s) that produce the fields from which the objective function is computed.

In general, sources will be an arbitrary caller-created list of Source objects, in which case source_region, source_component are ignored.

As an alternative convenience convention, the caller may omit sources and instead specify source_region; in this case, a source distribution over the given region is automatically created based on the values of the module-wide configuration options fcen, df, source_component, source_mode.

objective regionslist of Subregion

subregions of the computational cell over which frequency-domain fields are tabulated and used to compute objective quantities

design_regionmeep_adjoint.Subregion

design region bounding box (to be used in lieu of basis)

basismeep_adjoint.Basis

(either basis or design_region should be non-None) Specification of function space for the design permittivity.

In general, basis will be a caller-created instance of some subclass of meep.adjoint.Basis. Then the spatial extent of the design region is determined by basis and the design_region argument is ignored.

As an alternative convenience convention, the caller may omit basis and set design_region; in this case, an appropriate basis for the given design_region is automatically created based on the values of various module-wide adj_opt such as ‘element_type’ and ‘element_length’. This convenience convention is only available for box-shaped (hyperrectangular) design regions.

extra_regionslist of Subregion

Optional list of additional subregions over which to tabulate frequency-domain fields.

objective_functionstr

definition of the quantity to be maximized. This should be a mathematical expression in which the names of one or more objective quantities appear, and which should evaluate to a real number when numerical values are substituted for the names of all objective quantities.

extra_quantitieslist of str

Optional list of additional objective quantities to be computed and reported together with the objective function.

get_fdf_funcs()

construct callable functions for objective function value and gradient

Returns

f_func(beta) = objective function value for design variables beta df_func(beta) = objective function gradient for design variables beta

Return type

2-tuple (f_func, df_func) of standalone (non-class-method) callables, where

update_design(beta_vector=None, design=None)

Update the design permittivity function.

Precisely one of (beta_vector, design) should be specified.

If beta_vector is specified, it simply replaces the old beta_vector wholesale.

If design is specified, the function it describes is projected onto the basis set to yield the new beta_vector.

In either case, before accepting the new coefficient vector we apply a componentwise clipping operation to ensure that all coefficients lie in the range [beta_min, beta_max] (where beta_{min,max} are configurable options). For finite-element bases this simple constraint form suffices to ensure physicality of the permittivity, but for other basis sets the physicality constraint will be more complicated to implement, and we should probably introduce a mechanism for building the constraints into the Basis class and subclasses.

Parameters

• beta_vector (np.array) – basis expansion coefficients for new permittivity function

• design (function-like) – new permittivity function

visualize(fig_id=None, options={})

Produce a graphical visualization of the geometry and/or fields, as appropriately autodetermined based on the current state of progress.

Package-level functions for accessing configuration options

Adjoint-solver options

get_adjoint_option(option, overrides={})

Return currently configured value of option.

Parameters

• option (str) – name of option

• overrides (dict) – {option:value} records to override current settings

Returns

Value of option if found in database, or None otherwise

set_adjoint_option_defaults(custom_defaults={}, search_env=True)

Routine intended to be called by meep_adjoint API scripts to set problem-specific option defaults. :param custom_defaults: dict of {option:new_default_value} records :param search_env: True/False to enable/disable scanning environment variables

for option settings

Visualization options

get_visualization_option(option, section='default', overrides={})

Singleton version of the above routine that also allows an alternative calling convention for convenience: the section label may be prepended to the name of the option instead of specified separately. Thus, the following two sets of parameter values are equivalent:

option=’linewidth’, section=’pml’ option=’pml_linewidth’ section=’default’ (or section left unspecified)

get_visualization_options(opts, section='default', overrides={})

Return currently configured values of options.

Parameters

• opts (list of str) – names of options for which we want values

• section (str) – name of section

• overrides (dict) – {option:value} records to override current settings

Returns

List of option values.

set_visualization_option_defaults(custom_defaults={}, search_env=True)

Parameters

• custom_defaults – dict of {option:new_default_value} records

• search_env – True/False to enable/disable scanning environment variables for option settings

set_option_defaults(custom_defaults={}, search_env=True)