nextnanoevo.io module

Defines the nextnanoevo.IO (input-output) class for interfacing with nextnano simulations.

class nextnanoevo.io.IO(input_file_path: str, variable_names: list, target_output_paths: list, sweep: dict | None = None)

Bases: object

A class to represent a nextnano simulation problem. Interface between the input file, variables under optimization and output datafiles used for metric.

Accepts both single-individual (1D values) and population (2D values) inputs to run_simulation. Output shape adapts to the input shape: - 1D input -> output_datafiles is ndarray shape (k,) or (k, n1, ...) with sweep - 2D input -> output_datafiles is list[ndarray | None] of length N

Parameters:

input_file_pathstr

The path to nextnano input file.

variable_nameslist of str

A list of variable names to be used in the simulation.

target_output_pathslist of list or tuple

A nested list or tuple containing paths to the target output files.

Example one output: [('bias_00000', 'potential.dat')]
Example 2 outputs: [('bias_00000', 'potential.dat'), ('Structure', 'AlloyConcentration.dat')]

sweepdict, optional

Fixed variable values to sweep over, independent of the optimized variables. Each key must be a variable name present in the input file and must not appear in variable_names. Each value is a list of numbers. For every individual, one simulation is run per sweep combination (Cartesian product across all sweep keys), so evaluating N individuals with sweep size S runs N*S simulations in total. Example: {"source_bias": [-0.5, 0.0, 0.5]} runs 3 simulations per individual. Default None (no sweep).

Attributes:

input_file_pathstr: The input file for the nextnano simulation.
input_variable_nameslist of str: A list of variable names to be used in the simulation.
target_outputlist of list or tuple: Paths to the target output files.
sweepdict or None: The sweep specification passed at construction, or None.
number_of_output_targetsint: Number of target output paths (k).
number_of_input_variablesint: Number of input variable names (m).
sweep_shapetuple of int: Per-key lengths of the sweep, in the sweep dict’s insertion order.
sweep_sizeint: Total number of sweep combinations (1 when there is no sweep).

Methods

`get_datafiles_from_datafolder`(datafolder)	Retrieves the data files from the specified datafolder.
`get_target`()	Retrieves the target datafiles from the simulation output.
`run_simulation`(input_variable_values[, ...])	Runs the nextnano simulation(s) for the given input variable values.

Raises:

ValueError: If input variables are invalid.

property execution_codes: list

get_datafiles_from_datafolder(datafolder: DataFolder) → list: Retrieves the data files from the specified datafolder.

get_target(): Retrieves the target datafiles from the simulation output.

property number_of_input_variables: int

property number_of_output_targets: int

property output_datafiles

Retrieves the data files from the target output paths.

Shape depends on the most recent run_simulation call:

1D input, no sweep: ndarray (object dtype) shape (k,).
1D input, sweep (n1, n2, ...): ndarray shape (k, n1, n2, ...).
2D input, no sweep: list[ndarray(k,) | None] length N.
2D input, sweep: list[ndarray(k, n1, ...) | None] length N.

Element type is always nextnanopy.DataFile.

Raises:

RuntimeError: If the input file has not been executed yet, or (1D-input only) if the single simulation failed.

property output_folders: list

run_simulation(input_variable_values, parallel_limit: int = 1, input_dir_path: str | None = None, clean_input_file: bool = False) → None

Runs the nextnano simulation(s) for the given input variable values.

Parameters:

input_variable_values1D or 2D iterable: 1D (m,) runs one simulation. 2D (N, m) runs N simulations, each row a separate set of variable values. With a sweep of size S, each individual is expanded to S simulations (one per sweep combination), so N individuals produce N*S total simulations.
parallel_limitint: Maximum number of parallel simulations. Default 1 (serial).
input_dir_pathstr, optional: Where to save generated input files. If None, saves next to the original.
clean_input_filebool: Whether to remove generated input files after execution. Default False. Note: when running across multiple run_simulation calls in the same input_dir_path (e.g. successive evolution generations), keep this False so nextnanopy auto-increments input filenames and produces unique output folders. Setting True causes filename — and therefore output folder — collisions.

Raises:

ValueError: If the shape of input_variable_values is incompatible with input_variable_names.

property sweep_shape: tuple: Per-key lengths of the sweep, in the sweep dict’s insertion order. Empty tuple when there is no sweep.

property sweep_size: int: Total number of sweep combinations (1 when there is no sweep).