LocalOptimizer#

class nextnano_optimizers.optimizer.LocalOptimizer(nextnanoio: IO, metric: Metric, output_dir: str | None = None)#

Bases: PlottingFacadeMixin

Minimize a scalar objective using local optimization algorithms.

Uses scipy.optimize.minimize to optimize the objective defined by metric, evaluating candidates through nextnano simulations. The optimization starts from an initial guess and searches for a local minimum.

Parameters:

nextnanoioIO: Defines the input file path, input variables under optimization and output files of the simulations.
metricMetric: Defines how the objective value is extracted from the simulation outputs.
output_dirstr, default=None: Directory where optimization results are saved. If None, defaults to the outputdirectory specified in nextnanopy config.

Attributes:

champion_xnumpy.ndarray or None: Input variables of the best candidate evaluated during optimization.
champion_ffloat or None: The objective value of the best candidate evaluated during optimization.

See also

IO: Configure simulation inputs and outputs.
Metric: Define how objective values are calculated.
scipy.optimize.minimize(): SciPy function used for local optimization.

Examples

Optimize the quantum well width to match the target transition energy.

import numpy as np
from nextnano_optimizers.io import IO
from nextnano_optimizers.metric import Metric
from nextnano_optimizers.optimizer import LocalOptimizer

io = IO(
    input_file_path="device.nnp",
    variable_names=["well_width"],
    target_output_paths=[("bias_00000", "Quantum", "energy_spectrum.dat")],
)

def extract_target(datafiles):
    energies = datafiles[0].variables["Energy"].value
    transition_energy = energies[1] - energies[0]
    return np.array([(transition_energy - 0.25) ** 2])

metric = Metric(
    input_shape=(1,),
    output_shape=(1,),
    extraction_function=extract_target,
)

optimizer = LocalOptimizer(nextnanoio=io, metric=metric)
result = optimizer.run(x0=[6.0], method="Nelder-Mead")

print(result.x)  # Optimized well width
print(result.fun)  # objective value at optimizerd well width

plot_all(save_dir=None, show=False, fig_format='png')#

Plot the optimization results.

Generates figures showing the optimization progress and available visualizations of the optimization results. The figures produced depend on the number of optimization variables and objectives:

Requires the optional matplotlib dependency (pip install nextnano_optimizers[plot]).

Optimization progress: Objective and parameter values as a function of optimization iterations.
Parameter space: Evaluated candidates in the design space. Plotted only for problems with multiple parameters.
Pareto front: The Pareto-set (the optimal set in the input space) and the Pareto front (the optimal set in the objective space). Plotted only for multi-objective problems.

Parameters:

save_dirstr or bool, default=None: Path to a directory where figures are saved. If None, figures are saved in the figures subdirectory of the optimization output directory. If False, figures are not saved. A directory is created if specified path it does not exist.
showbool, default=False: If True, display the figures.
fig_formatstr, default=”png”: File format for saving figures, such as "png", "pdf", or "svg". Ignored if save_dir=False.

Returns:

list of matplotlib.figure.Figure: Generated figures.

Raises:

RuntimeError: If called before run().
ValueError: If fig_format is not supported by matplotlib.

See also

setup_plotting: Customize the figures generated by this method. Should be called before plot_all.

Examples

Save the figures in the figures subdirectory of this run’s output directory:

>>> optimizer.run(x0=[10.0])
>>> figures = optimizer.plot_all()

Display the figures without saving them:

>>> optimizer.plot_all(save_dir=False, show=True)

Save them as PDFs in a custom directory:

>>> optimizer.plot_all(save_dir="my_figures", fig_format="pdf")

Label the axes before plotting:

>>> optimizer.setup_plotting(param_names=["well width (nm)"])
>>> optimizer.plot_all()

run(x0, *, live_progress: bool = False, **kwargs)#

Run the optimization.

Parameters:

x0float or array-like: Initial values of the optimization variables, in the same order as variable_names in nextnanoio. A scalar is acceptable when optimizing a single variable.
live_progressbool, default=False: If True, display a live plot of the optimization progress. The plot updates during optimization and closes when the run finishes. Requires the optional matplotlib dependency. For the progress plot customization, see setup_plotting().
**kwargs: Additional keyword arguments passed to scipy.optimize.minimize, such as method, bounds, options. See scipy.optimize.minimize() for the full list.

Returns:

scipy.optimize.OptimizeResult: The result returned by scipy.optimize.minimize().

Raises:

ValueError: If the metric is multi-objective, or if x0 does not have one entry per input variable.
RuntimeError: If nextnano simulation fails to run (syntax error, convergence failure etc).

Notes

champion_x hold the best candidate found during the run. That is normally the same point reported in OptimizeResult.x, but not always. The exact behavior depends on the optimization algorithm. For example, an algorithm may evaluate the best point found during the search, later move away from it, and eventually converge to a different local minimum.

setup_plotting(**plotter_kwargs) → None#

Configure the optimization plots.

The configuration applies to both the live progress plot displayed by run(live_progress=True) and the figures generated by plot_all().

Parameters:

**plotter_kwargs: Plotting options described below.
param_nameslist of str, optional: Labels for the optimization variables.
fitness_nameslist of str, optional: Labels for the objectives.
exclude_failedbool, optional: If True, exclude evaluations assigned the non_execution_penalty from the plots (i.e. failed evaluations).
fitness_limitslist or dict, optional: Plotting limits for each objective, specified as (min, max) pairs. If dictionary is used, the keys should match the fitness names, see examples below.
progress_seriesstr or sequence of str, optional: Curves to display in the optimization progress plot. Use "all" to display all available curves. The series applicable to all optimizations: (“best”, “candidates”). The series also applicable to evolution: (“min-max”, “min”, “max”, “median”, “mean”).
series_labelsdict, optional: Custom legend labels for progress_series curves, keyed by curve tag from the progress_series.
series_specsdict, optional: Custom plotting properties for individual curves, keyed by curve name. Each entry can specify kind and/or style. See examples below.
iteration_labelstr, optional: Label used for optimization iterations. Each optimizer defaults to its own word: "generation" for Evolution, "trial" for BayesianOptimization, and "evaluation" for LocalOptimizer.
progress_titlestr, optional: Title of the optimization progress plot.
population_labelstr, optional: Label used for candidates in the final iteration.

Raises:

TypeError

If an unrecognized plotting option is provided.

ValueError

In either of two cases:

progress_series contains an unknown curve.
The number of entries in param_names or fitness_names does not match the number of optimization variables or objectives.