Optimization

optimize finds the parameters of a simulation you have already set up that give the best value of a quantity you choose, within bounds and constraints (EMode3D only). The parameters are named with the keys of sweep: a setting ('wavelength'), one profile’s setting ('setting, <profile>, <name>'), a shape property ('shape, <name>, <property>'), a shape property of a labeled profile ('shape, <profile>, <name>, <property>'), a section property ('section, <name>, <property>'), or an argument of a monitor_coupling beam ('beam, <name>').

Every evaluation starts from the simulation as declared when optimize is called. It sets each parameter, solves what the objectives need (a mode solve for a mode quantity, EME for an S-matrix or a monitor coupling) and records the result, so an evaluation depends only on its parameters, whatever ran before it. A cross-section that an earlier evaluation solved is not solved again: optimizing a section length solves the modes once, and optimizing a beam’s angle on a solved chain solves nothing. At the end, the simulation is left solved at the best point, so get, plot and EME read it.

The objectives and constraints are declared as data with the classes below, imported from emodeconnection:

from emodeconnection import Parameter, Objective, Constraint

res = em.optimize(
    parameters=[Parameter('section, coupler, length', bounds=(5e3, 40e3), x0=15e3)],
    objective=Objective('S_power', out='coupler.out_right', into='coupler.in_left'),
    constraints=[Constraint('section, coupler, length', '<=', 30e3)],
)
print(res.parameters, res.objective, res.status)
optimize

Find the parameters that give the best objective, within bounds and constraints.

Parameters:
  • parameters – what to vary, a Parameter or a list of them

  • objective – what to improve, an Objective or a list of them, whose weighted sum is improved

  • constraints – limits on a parameter or on an objective’s quantity, a Constraint or a list of them, default: None

  • method (str) – ‘cobyqa’ (bounds and constraints, no derivatives), ‘nelder-mead’ or ‘powell’ (bounds, constraints by a penalty), ‘differential_evolution’ (a global search over finite bounds, constraints too), ‘l-bfgs-b’ (bounds, with a gradient) or ‘slsqp’ (bounds and constraints, with a gradient), default: ‘cobyqa’

  • gradient (str or None) – how ‘l-bfgs-b’ and ‘slsqp’ get a gradient. None and ‘adjoint’ take it from each evaluation: the pulsed adjoint for a poling design with pulse objectives, and the S-matrix gradients of evaluate for ‘S_power’ and ‘S_phase’ objectives (with ‘parameter’ ones) over section lengths, ‘wavelength’ and shape properties. None falls back to finite differences where neither covers every parameter and objective, and ‘adjoint’ raises an error there. ‘finite_difference’ evaluates the point and one step in each parameter. Default: None

  • check_gradient (bool) – with a gradient taken from the evaluations, compare the first evaluation’s gradient with forward differences of the objective (one more evaluation per parameter) and warn when they differ by more than 5 % of its size, default: False

  • max_evaluations (int) – the most evaluations to make, default: 100

  • max_time (float or None) – [s] the most time to run, default: None (no limit)

  • tolerance (float) – the convergence tolerance, relative to each parameter’s range, default: 1e-4

  • seed (int) – the random seed of ‘differential_evolution’, so a run can be repeated, default: 0

  • apply_best (bool) – leave the simulation solved at the best point, default: True

  • record (str or None) – a file to write each evaluation to as one line of JSON as it completes, so an interrupted run keeps its history, default: None

  • snapshot (str or None) – also write the starting point to this .eph file, which evaluate can evaluate from in another session, default: None

  • simulation_name (str) – simulation name, default: ‘emode’

Returns an OptimizationResult.

A constraint on a parameter ('<=' or '>=') narrows that parameter’s bounds, so it is met exactly. A constraint on an objective’s quantity is met to the method’s tolerance. Each method spends evaluations differently: ‘cobyqa’ needs a few evaluations per parameter per step, finite differences one more evaluation than there are parameters per gradient, and ‘differential_evolution’ fifteen per parameter per generation. The result of a mode solve reproduces to about 1e-9 on the same grid, so set tolerance above that for objectives read from a mode solve.

class Parameter(key, bounds=None, x0=None, shape=(), step=None)

A quantity to vary.

Parameters:
  • key (str) – the parameter, as a sweep key, 'beam, <name>' (one of ‘angle’, ‘mode_field_diameter’, ‘center’, ‘index’ and ‘polarization’), or 'poling, <section>, domain_lengths', the length [nm] of every domain of a section with a PulsedProcess ('poling, <section>, domain_lengths[k]' for domain k alone)

  • bounds – (min, max), either end None for no limit, default: None

  • x0 (float or None) – the starting value, default: None (the value the simulation holds now, or for a beam argument the value in the objective’s beam)

  • step (float or None) – the finite-difference step as a fraction of the bounded range (or of the value when unbounded), default: None (1e-6)

  • shape (tuple) – the shape of a list of values, such as (n,), for 'poling, <section>, domain_lengths', default: () (one value, or for the domain lengths the number of domains the section holds now)

A shape’s 'position' given one value moves the shape in x and keeps its height. bounds of a list of values is one (min, max) for every element, or a list of them, one per element.

Poling design. Every domain of a poled section can be a free variable. Parameter('poling, <section>, domain_lengths', bounds=(1500, 6000)) varies the length of each domain within a fabrication minimum and maximum, starting from the section’s declared poling as domains (Poling.to_domain_lengths). 'poling, <section>, total_length', the sum of the domain lengths, can be constrained (Constraint('poling, ppln, total_length', '<=', 5e6)), which costs no evaluation. Each evaluation propagates the pulse through the chain the last EME prepared, with new domain walls, and solves no mode. With ‘l-bfgs-b’ or ‘slsqp’ and 'band_energy' or 'band_average' objectives, the gradient with respect to every domain comes from one adjoint propagation, so one evaluation with its gradient costs one and a half to two and a half propagations, whatever the number of domains. With gradient='finite_difference' a gradient costs one propagation per domain, which suits tens of domains but not thousands.

class Objective(kind, goal='maximize', target=None, weight=1.0, ...)

A quantity to improve. kind and the arguments that select it:

  • 'S_power' and 'S_phase': \(|S|^2\) and the phase of one S-matrix element. out and into name the ports, by name (its mode 0), as '<port>_<mode>', or as a mode index of the whole matrix, and wavelength picks one wavelength of a multi-wavelength circuit.

  • 'monitor_coupling': monitor_coupling of the monitor monitor for the beam beam, a dict of that function’s arguments.

  • 'effective_index', 'group_index' and 'loss' (dB/m): of mode mode (default 0) of profile (default the default profile).

  • 'band_energy' (pJ) and 'band_average' (average power, W): of a pulse after pulsed propagation, between the wavelengths band = (min, max) in nm, for tracked mode mode (default all of them).

  • 'parameter': the value of the parameter key itself, to make a device as short or as narrow as its constraints allow.

Parameters:
  • goal (str) – ‘maximize’, ‘minimize’, or ‘target’, which minimizes the squared distance to target, default: ‘maximize’

  • target (float or None) – the value to reach with goal='target', default: None

  • weight (float) – the objective’s weight in a list of them, default: 1.0

value(results) returns the objective’s quantity from an evaluation’s results.

class Constraint(quantity, op, value)

A limit.

Parameters:
  • quantity (str or Objective) – a parameter key, or an Objective whose quantity is limited

  • op (str) – ‘<=’, ‘>=’ or ‘==’

  • value (float) – the limit

class OptimizationResult

What optimize returns. parameters is the best point by key and x the same as a list, objective and constraints its values, and goal says whether the objective was maximized or minimized. With several objectives that are not all maximized, objective is the minimized sum of each one’s value (minimized), negative value (maximized) or squared distance from its target, each times its weight. status is ‘converged’, ‘budget’ (max_evaluations ran out), ‘time’ (max_time ran out) or ‘failed’, and message says more. history lists every evaluation as an Evaluation with its index, parameters, objective, constraints, the results the objectives read, seconds, solves (the mode solves it made), cache_hits (the solves and junctions it reused) and cached (a point the run had already evaluated, which costs nothing). best is the best evaluation, evaluations the number actually solved and seconds the run’s time. to_json() gives the whole result as plain JSON-ready data.

evaluate

Evaluate the simulation at one point. It starts from the simulation’s snapshot, sets every parameter, solves what the results need and returns a record. The snapshot is taken by snapshot, or else by the first evaluation. A change of the declaration (a shape, a setting, a material, a labeled profile, a section, a port connection or a monitor) drops it, and the next evaluation takes a new one. So a section or profile declared after an evaluation is part of the next one, and the parameters an evaluation set are undone by the next one. The same parameters give the same results whatever ran before. An evaluation leaves the simulation at its point, so a change made right after one starts from that point. Available in every session.

Parameters:
  • parameters (dict) – {key: value} for every parameter, with the keys of optimize

  • results (str or list) – the quantities to return, any get key, ‘S_matrix’ or ‘monitor_coupling’, default: ‘effective_index’

  • snapshot (str or None) – a snapshot file to evaluate from instead of this simulation’s snapshot, default: None

  • monitor (str or None) – the monitor of a ‘monitor_coupling’ result, default: None

  • beam (dict or None) – the arguments of monitor_coupling for a ‘monitor_coupling’ result, default: None

  • profile (str or None) – the profile a mode result is read from, default: None (the default profile)

  • gradients (bool) – also return the derivative of the ‘S_matrix’ result with respect to every parameter, from the solved chain with no further mode solve. It needs ‘S_matrix’ in results and at least one parameter, and each parameter must be a number keyed 'section, <name>, length', 'wavelength' or 'shape, <name>, <property>' (the property one of ‘width’, ‘height’, ‘mask’, ‘mask_offset’, ‘etch_depth’, ‘sidewall_angle’, ‘position’ or ‘index’). Any other key raises an error. Default: False

  • simulation_name (str) – simulation name, default: ‘emode’

Returns a dict with parameters, results, seconds, solves, cache_hits and seeded. With gradients=True it also holds gradients, {'S_matrix': {key: dS/dp}} with each derivative the shape of the S-matrix, and gradient_method, {key: method}, which says how each derivative was taken:

  • 'exact': a section length, which moves only the propagation of that section’s slices.

  • 'first order': the wavelength or a shape property, to first order in the modes, through both the slices’ propagation and the junctions they meet.

  • 'junctions held': the wavelength or a shape property, where a cross-section’s modes have no first-order change (an FEM solve, for one). The slices’ propagation moves and the junctions are held fixed.

A shape key sets the default profile’s shape, so a gradient by it raises an error when a section is built on a labeled profile that holds its own copy of that shape. A nearly degenerate pair of modes makes the first-order change unreliable, and the solver warns.

snapshot

Take the snapshot evaluate starts from: the simulation as declared now (profiles, shapes, sections, ports and settings), without anything solved. A later change of the declaration replaces it with the simulation as declared at the next evaluation, but a file it wrote keeps the simulation as it was. Available in every session.

Parameters:
  • file_name (str or None) – also write the snapshot to this .eph file, which another session can evaluate from, default: None

  • simulation_name (str) – simulation name, default: ‘emode’

Returns the file’s path when file_name is given.

perturb

The first-order change of the solved modes with shape parameters, for tolerance analysis. From the one solve of the profile it gives the derivative of each mode’s effective index by each parameter (a width, a height, a sidewall angle, a material index), and with deltas the effective index to first order at each sample. A Monte Carlo tolerance pass of many samples then costs one solve. With 'S_matrix' in results it also gives the S-matrix of the simulation’s chain (it runs EME first) at each sample, with each section’s propagation moved to first order and the junctions as solved. Available in every session, and the S-matrix in EMode3D only.

The derivative is exact for the solver’s own grid: it agrees with a difference of two more mode solves on the same grid to about \(10^{-3}\) of its value. The first-order effective index is the tangent at the solved point, so its error grows as the square of the change: on a 490 x 220 nm Si strip at 20 nm it is \(2 \times 10^{-5}\) in the effective index at a 2 nm change of width, \(10^{-4}\) at 5 nm and \(10^{-3}\) at 20 nm. A face that lies on a grid line or on a line of cell centers puts a small step into the effective index as it moves off the line, and the derivative there is that of the side the solve lies on. validate solves the first samples again on the same grid and reports the first-order error. The FDM takes the derivative from its operator. The FEM, which meshes the shapes, and a bend solved by transformation optics take a difference of two more solves for each parameter instead.

Parameters:
  • parameters (str or list) – shape keys 'shape, <name>, <property>', the property one of ‘width’, ‘height’, ‘mask’, ‘mask_offset’, ‘etch_depth’, ‘sidewall_angle’, ‘position’ (along x) or ‘index’ (every principal index of the shape’s material, at the profile’s wavelength). ‘mask’ and ‘mask_offset’ move every entry by the same amount.

  • deltas (list or None) – the change of each parameter (nm, degrees for an angle), or one row of changes per sample, default: None

  • results (str or list) – ‘effective_index’ and, with deltas, ‘S_matrix’, default: ‘effective_index’

  • profile (str or None) – the profile whose modes are perturbed, default: None (the default profile)

  • validate (int) – solve this many of the samples again and report the first-order error, default: 0

  • simulation_name (str) – simulation name, default: ‘emode’

Returns a dict with parameters, effective_index (the solve’s), derivative (one row per parameter, one column per mode), method (per mode, ‘field’ from the one solve or ‘difference’ from two more), and with deltas effective_index_perturbed (one row per sample), S_matrix (one per sample) when asked, and validation with the first-order and re-solved effective indices and their difference error.