nextnanoevo.metric module

class nextnanoevo.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.

nextnanoevo.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.

nextnanoevo.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.

nextnanoevo.metric.default_value_getter(dfile)

Get first value of the first variable in the datafile. Use for default extraction function.

nextnanoevo.metric.len_of_output_object(obj: list | tuple | ndarray)

Gets length of the output object (list, tuple or ndarray)

nextnanoevo.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.