Sweep

class nextnanopy.Sweep(variables_to_sweep, fullpath=None, configpath=None)

Bases: object

A parameter sweep over the input variables of one input file.

One simulation is run for every combination of the swept values, combined as a Cartesian product: sweeping two variables with 3 and 4 values gives 12 simulations.

Building and running are separate steps. save() writes one input file per combination, and execute() runs those files and collects their output. Calling execute() on a sweep that was never saved does not raise: it warns that no input files were created and returns.

Parameters:

variables_to_sweepdict of {strlist}

Values to sweep for each input variable, keyed by variable name, as {'name1': values1, 'name2': values2}. Every name must already be a variable of the input file, and every value must be iterable. A single string counts as iterable and sweeps its characters, so wrap single values in a list.

fullpathstr or pathlib.Path, default=None

Path to the input file to sweep, as for InputFile. Without it there are no variables to sweep over, so only an empty variables_to_sweep is accepted.

configpathstr or pathlib.Path, default=None

Path to the config file, as for InputFile. It is handed to every input file the sweep generates, so they all run on the same configuration as the sweep itself.

Attributes:

input_fileInputFileTemplate

The prototype input file whose variables are swept, parsed once at construction.

var_sweepdict of {strlist}

The validated variables_to_sweep, keyed by variable name.

input_fileslist of InputFileTemplate

One input file per swept combination. Empty until save() has run, which replaces the list on every call.

sweep_output_directorystr

Directory holding the output of every simulation of the sweep. None until execute() has run.

sweep_infodictDictList of dict

Variable combination of each generated input file, keyed by that file’s path. Empty until save() has run.

sweep_output_infodictDictList of dict

The same combinations keyed by output folder instead. This is what is written to sweep_infodict.json in the sweep directory. Empty until execute() has run.

fullpathstr or pathlib.Path

Path of the input file being swept. Read-only.

filename_onlystr

File name of the input file without the extension. Read-only.

productstr

Detected nextnano product of the input file. Read-only.

configNNConfig

The configuration input_file runs on. Settable, but the assignment reaches only input_file: the files save() generates take their configuration from the configpath given at construction.

configpathstr or pathlib.Path

Path of the configuration file behind config. Read-only.

Raises:

ValueError

If a name in variables_to_sweep is not a variable of the input file.

TypeError

If a value in variables_to_sweep is not iterable.

property fullpath

property config

property configpath

property product

property filename_only

save_sweep(delete_old_files=True, round_decimal=8, integer_only_in_name=False, temp=False, variables_comb_screen_fn=None)

Write and save on disk one input file per swept combination.

save() is the preferred name for this method. save_sweep() is kept for compatibility and will be deprecated.

The files are written next to the input file being swept, with the swept values appended to the name (example__BIAS_1.5_.in), and are collected in input_files and sweep_infodict.

Parameters:

delete_old_filesbool, default=True

If True, delete the input files generated by an earlier save() on this sweep before writing the new ones. Files from other sweeps are never touched.

round_decimalint, default=8

Number of decimals the swept values are rounded to in the file names. Values that are strings are used as they are.

integer_only_in_namebool, default=False

If True, name the files after the input file with an index appended (example_0.in, example_1.in, …) instead of after the swept values.

tempbool, default=False

If True, write the files into a temporary folder that is removed when the process exits, instead of next to the input file.

variables_comb_screen_fncallable, default=None

Filter for the combinations to generate. It is called with one combination of values at a time, in the order of the swept variables, and the combination is kept when the call returns true. If omitted, every combination is generated.

Parameters:

variables_comb_screen_fn (Callable[[...], Any])

See also

save

Preferred name for this method.

save(*args, **kwargs)

Save the sweep input files. See save_sweep() for the parameters.

Notes

This is the preferred name. For now it simply forwards to save_sweep(). In a future patch the two will swap: save will hold the implementation and save_sweep will become the mirror, emitting a deprecation warning.

prepare_output(overwrite=False, output_directory=None)

create_input_files(input_file_path, round_decimal, integer_only_in_name=False, variables_comb_screen_fn=None)

Parameters:

variables_comb_screen_fn (Callable[[...], Any])

execute_sweep(delete_input_files=False, overwrite=False, show_log=True, convergenceCheck=False, convergence_check_mode='pause', parallel_limit=1, separate_sweep_dir=True, **kwargs)

Execute the input files written by save().

execute() is the preferred name for this method. execute_sweep() is kept for compatibility and will be deprecated.

Each input file is run in turn, or parallel_limit at a time. The output is collected under sweep_output_directory together with sweep_info.txt and sweep_infodict.json, and every simulation’s variable combination is recorded in sweep_output_infodict.

Parameters:

delete_input_filesbool, default=False

If True, delete the generated input files once they have been executed.

overwritebool, default=False

If True, the output overwrites the old output data. If False, execution creates a new output folder, adding an integer to the folder name. It applies to the sweep folder and to the folder of every simulation in it, so a sweep run with overwrite=False writes over no earlier output at either level. The per-file subfolder itself is always created: it is what keeps the sweep points apart.

show_logbool, default=True

If True, the simulation log is displayed in the console. If False, only the count of the current simulation is displayed. The log file is written to the output folder either way.

convergenceCheckbool, default=False

If True, check the log of every simulation for convergence once it has finished. What happens on a simulation that did not converge is decided by convergence_check_mode.

convergence_check_mode{‘pause’, ‘terminate’, ‘continue’}

What to do when a simulation did not converge. Only used when convergenceCheck is True.

• ‘pause’: ask the user how to proceed. If no interactive terminal is attached (e.g. CI, cluster jobs), behaves like ‘terminate’ instead of blocking on input.

• ‘terminate’: terminate the script.

• ‘continue’: notify the user but continue the script.

parallel_limitint, default=1

Number of simulations to run simultaneously. Especially useful for simple simulations, which may run more efficiently in parallel. Be aware that some nextnano solvers parallelize computations internally in threads (controlled by threads in the nextnanopy configuration): to avoid an undesirable slowdown, keep parallel_limit * threads at or below the number of physical cores of the machine.

separate_sweep_dirbool, default=True

If True, create one directory for the sweep and put every simulation’s output folder inside it. If False, the output folders are created directly in the output directory.

**kwargsdict

Forwarded to InputFile.execute() for every simulation. outputdirectory is the exception: it is taken as the parent of the sweep directory rather than passed on, and defaults to the outputdirectory of config.

Raises:

RuntimeError

If convergenceCheck is True and a simulation did not converge, unless convergence_check_mode is ‘continue’. The sweep stops at that simulation and the remaining input files are not executed.

Warns:

UserWarning

If no input files were created, i.e. save() has not been called. Nothing is executed, but the sweep directory has already been created.

See also

InputFile.execute

Meaning of the arguments passed on to each simulation.

execute

Preferred name for this method.

execute(*args, **kwargs)

Execute the sweep. See execute_sweep() for the parameters.

Notes

This is the preferred name. For now it simply forwards to execute_sweep(). In a future patch the two will swap: execute will hold the implementation and execute_sweep will become the mirror, emitting a deprecation warning.

create_infodict_files()

create_infodict_json()

mk_dir(overwrite=False, output_directory=None)

create_info()