nextnano_optimizers.metric module#

Metric says how the output datafiles of a simulation become numbers to optimize. It wraps a single user-supplied extraction function that receives the array of nextnanopy.DataFile objects produced by run_simulation() and returns a flat vector of objective values.

The two shapes it carries are what make the contract checkable. input_shape is the shape of the datafile array coming in — (k,) for k target outputs, or (k, n1, n2, ...) when the IO has a sweep, so sweep point s of target t is dfiles[t, s]. output_shape is the shape of the vector going out: (1,) for a single-objective problem, (p,) for p objectives.

The module ships a few ready-made extractors for the common cases; write your own when the objective needs more than the first value of each file.

`Metric`([input_length, output_length, ...])	Defines how simulation output datafiles are converted into a numeric metric array for optimization.
`Metric.extract`(input_datafiles, args, *kwargs)	Computes the metric array from the input datafiles.
`default_value_getter`(dfile)	Get first value of the first variable in the datafile.
`default_extractor`(dfiles)	Default extractor function for the metric.
`default_multiobj_extractor`(dfiles)	Extractor function example for multi-objective optimization.
`sum_expand_vector_with_zeros_extractor`(dfiles)	Dummy extractor function for the multi-objective optimization.

Usage#

Single objective, one target file, using the default extractor:

from nextnano_optimizers.metric import Metric

metric = Metric(input_length=1, output_length=1)

A custom extraction function — the gap between the first two eigenenergies:

import numpy

def transition_energy(dfiles):
    energies = dfiles[0].variables["Energy"].value
    return numpy.array([energies[1] - energies[0]])

metric = Metric(
    input_length=1,
    output_length=1,
    extraction_function=transition_energy,
)

With a sweep of size 3 the same target file arrives as a (1, 3) array, so the extractor is written against both axes:

def spread_over_bias(dfiles):
    values = [dfiles[0, s].variables["Energy"].value[0] for s in range(3)]
    return numpy.array([max(values) - min(values)])

metric = Metric(
    input_shape=(1, 3),
    output_shape=(1,),
    extraction_function=spread_over_bias,
)

Reference#

class nextnano_optimizers.metric.Metric(input_length=None, output_length=None, extraction_function: Callable | None = None, input_shape=None, output_shape=None)#

Bases: object

Defines how simulation output datafiles are converted into a numeric metric array for optimization.

Wraps a user-supplied extraction function that maps an ndarray of nextnano output DataFile objects to a flat numpy array of objective values. Supports single-objective (output_shape=(1,)) and multi-objective optimization.

The extraction function receives an ndarray of shape input_shape (object dtype, elements are nextnanopy.DataFile instances):

Without sweep: input_shape = (k,) — k target output files.
With sweep of shape (n1, n2, ...): input_shape = (k, n1, n2, ...) — k targets × all sweep combinations. Access sweep point s of target t as dfiles[t, s].

Parameters:

input_shapetuple of int, optional: Full shape of the DataFile array passed to the extraction function, i.e. (k,) without sweep or (k, n1, n2, ...) with sweep. Mutually exclusive with input_length.
input_lengthint, optional: Shorthand for input_shape=(input_length,) (no sweep). Mutually exclusive with input_shape.
output_shapetuple of int, optional: Shape of the array returned by the extraction function. Must be 1-D, e.g. (1,) for a scalar objective or (p,) for p objectives. Mutually exclusive with output_length.
output_lengthint, optional: Shorthand for output_shape=(output_length,). Mutually exclusive with output_shape.
extraction_functioncallable, optional: Function f(dfiles) -> numpy.ndarray that converts the DataFile array into a flat objective vector. Defaults to default_extractor.

Attributes:

input_shapetuple of int: Full shape of the DataFile ndarray expected by the extraction function.
output_shapetuple of int: Shape of the objective vector produced by the extraction function.
extraction_functioncallable: The extraction function used to compute the metric.

Methods

`extract`(input_datafiles, args, *kwargs)	Computes the metric array from the input datafiles.
`validate_metric`()	Validates the metric definition.

extract(input_datafiles, *args, **kwargs)#

Computes the metric array from the input datafiles.

Parameters:

input_datafilesnumpy.ndarray or list: ndarray of shape input_shape (object dtype, elements are DataFiles), or a plain list for backward-compatible 1-D-input callers.

property input_length: int#: First dimension of input_shape (= number of target output files k).

property output_length: int#: Product of output_shape dims; equals p for 1-D output_shape (p,).

validate_metric()#

Validates the metric definition.

Raises:

ValueError: If input_shape is empty or its first dim < 1, if output_shape is not 1-D, or if output_shape[0] < 1.

Extraction functions#

nextnano_optimizers.metric.default_value_getter(dfile)#: Get first value of the first variable in the datafile. Use for default extraction function.

nextnano_optimizers.metric.default_extractor(dfiles)#

Default extractor function for the metric. No-sweep variant only.

Expects dfiles to be a 1-D iterable of k DataFile objects (no sweep dimensions). Sums the first value of the first variable across all datafiles and returns a length-1 array.

nextnano_optimizers.metric.default_multiobj_extractor(dfiles)#

Extractor function example for multi-objective optimization. No-sweep variant only.

Expects dfiles to be a 1-D iterable of k DataFile objects (no sweep dimensions). Returns a length-k array with the first value of the first variable from each datafile, one objective per datafile.

nextnano_optimizers.metric.sum_expand_vector_with_zeros_extractor(dfiles)#: Dummy extractor function for the multi-objective optimization. Returns a vector of the length of dfiles. The first element is the sum of the first values of the first variable in each datafile, and the rest are zeros.