# Optimization

[`optimize`](#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 (EMode<sub>3D</sub> only). The parameters are named with the keys of [`sweep`](solver-analysis.md#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`](eme.md#monitor_coupling) beam (`'beam, <name>'`).

Every evaluation starts from the simulation as declared when [`optimize`](#optimize) is called. It sets each parameter, solves what the objectives need (a mode solve for a mode quantity, [`EME`](eme.md#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`](../interface.md#get), [`plot`](solver-analysis.md#plot) and [`EME`](eme.md#EME) read it.

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

```python
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`](#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`](#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`](solver-analysis.md#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`](eme.md#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`](eme.md#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*](#Objective)) – a parameter key, or an `Objective` whose quantity is limited
  * **op** (*str*) – ‘<=’, ‘>=’ or ‘==’
  * **value** (*float*) – the limit

### *class* OptimizationResult

What [`optimize`](#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`](#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`](#optimize)
  * **results** (*str* *or* *list*) – the quantities to return, any [`get`](../interface.md#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`](eme.md#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`](#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`](#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`](eme.md#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 EMode<sub>3D</sub> 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`.
