combine_solutions module

Take the best compensation settings among several runs.

Basic usage: ./combine_solutions.py -d /path/to/sim1/ /path/to/sim2/ /path/to/sim3

This is useful when different strategies are best on different fault scenarios.

The compensation settings are sorted against a column in the evaluations.csv files.

Reminder on the directory structure and conventions:

simulation_1 <- project folder

000000_ref <- simulation folder (holds a fault scenario) | 0_Envelope1D | 1_TraceWin

000001 | 0_Envelope1D | 1_TraceWin

…

evaluations.csv

simulation_2

000000_ref

000001

…

combine_bests(paths, criterion_to_minimize='Lost power over whole linac in W.', out_folder='', copy=False)

Compare several solutions, and concatenate the best one.

To determine the best solution for every fault scenario, we open each simulation’s evaluations.csv, look at the value of the column criterion_to_minimize and keep the simulation with the lowest.

Parameters:

• paths (Sequence[Path | str]) – Project folders (where evaluations.csv and every simulation is).

• criterion_to_minimize (str, default: 'Lost power over whole linac in W.') – The evaluations.csv column against which simulations are compared. The default is "Lost power over whole linac in W." (we keep simulations with the lowest lost power).

• out_folder (Path | str, default: '') – Where every best simulation folder will be gathered. If not provided, we create a combined/ folder in the last common ancestor of all provided paths.

• copy (bool, default: False) – To create hard-copies of the original simulation folders instead of creating a symlink.

Return type:

None

_infer_an_output_folder(paths, output_folder_name='combined')

Return output folder in the last common parent of paths.

Parameters:

• paths (Sequence[Path])

• output_folder_name (str, default: 'combined')

Return type:

Path

_select_best_simulations(paths, criterion_to_minimize)

Give the name of the best solution according to criterion_to_minimize

Parameters:

• paths (Sequence[Path]) – Path to project folders to be compared.

• criterion_to_minimize (str) – The quantity that we want to minimize. It must be a column name in evaluations.csv.

Return type:

tuple[Series, DataFrame]

Returns:

• best_simulation_folders – For each fault scenario, holds the path to the best simulation folder.

• combined – A evaluations.csv where each row holds the values for the best simulation. You must ensure that all evaluations.csv have the same columns.

_reconstruct_folder_names(n_simulations)

Reconstruct the name of the simulation folders.

Parameters:

n_simulations (int)

Return type:

Series

_concat_evaluations_files(evaluations, best_solutions)

Concatenate the evaluations, taking only the best.

Parameters:

• evaluations (dict[str, DataFrame]) – Keys are user-defined names for every simulation. Values are corresponding evaluations.csv files; their columns must be the same. They must have the same indexes.

• best_solutions (Sequence[Path]) – For every calculation, defines the evaluation we want to keep. The lenght must be the same as the length of every object in evaluations. Contained strings must all be keys of evaluations.

Return type:

DataFrame

Returns:

Same columns as evaluations. Every row contains the evaluations.csv row of the best solution.

_gather_best_simulations_in_same_place(best_simulation_folders, out_folder, create_symlinks_instead_of_hard_copies, dirs_exist_ok=True)

Concatenate the best simulation folders in a single place.

Parameters:

• best_simulation_folders (Collection[Path])

• out_folder (Path)

• create_symlinks_instead_of_hard_copies (bool)

• dirs_exist_ok (bool, default: True)

Return type:

None

_copy_or_create_symlink(src, dst, create_symlinks_instead_of_hard_copies, dirs_exist_ok)

Copy src to dst or create symlinks.

Parameters:

• src (Path)

• dst (Path)

• create_symlinks_instead_of_hard_copies (bool)

• dirs_exist_ok (bool)

Return type:

None

_load_evaluation(evaluation_folder, evaluation_namecol=None, new_name=None)

Load the file and rename column header.

Parameters:

• evaluation_folder (Path) – Folder where the evaluations.csv file is.

• evaluation_namecol (Sequence[str] | None, default: None) – Name of the column in the evaluations.csv for the sorting; if not provided, we keep all the columns.

• new_name (Sequence[str] | None, default: None) – If provided, the loaded columns will be renamed with this. The length of new_name must match evaluation_namecol.

Return type:

DataFrame

Returns:

Holds all the values of evaluation_namecol in evaluation_path.

main()