parasolpy.tradeoff

Multi-objective tradeoff analysis: epsilon non-dominance, parallel plots, clustering.

Functions

append_Kmeans(df[, num_clusters, ...])	Cluster solutions with K-Means and append a 'Cluster' column in place.
build_radar_figure(normalized_solutions, ...)	Create a Plotly radar figure from normalized solution values.
df_to_pt(df, obj_names, obj_directions[, ...])	Converts a pandas DataFrame of solutions into a list of Platypus Solution objects.
label_eps_nd(df, label_col, obj_names, ...)	label_eps_nd: label epsilon non-dominated solutions
load_objective_names(output_folder[, ...])	Load objective names from an output folder configuration XML.
load_objectives_and_solutions(output_folder)	Load objective names and solutions DataFrame from an output folder.
log_eps_experiment(log_path, entry)	Write a single experiment record to a JSON file.
normalize_for_radar(solutions, objective_names)	Return normalized radar values and objective labels with closure for polygon plotting.
parallel_plot_hp(df[, obj_names, ...])	Generates an interactive parallel plot using HiPlot for visualizing solution tradeoffs.
resolve_solutions_csv(output_folder[, ...])	Resolve a solutions CSV path across canonical and user-renamed naming patterns.
run_eps_experiment(output_folder, ...)	Apply epsilon non-dominance labeling and write named output files.

parasolpy.tradeoff.df_to_pt(df, obj_names, obj_directions, num_vars=0, num_constrs=0)

Converts a pandas DataFrame of solutions into a list of Platypus Solution objects.

This function takes a DataFrame where each row represents a solution and columns represent objectives (and potentially decision variables or constraints). It creates Platypus Problem and Solution objects, mapping DataFrame rows to solutions and objective columns to Platypus objectives, handling minimization and maximization as specified.

Parameters:

• df (pd.DataFrame) – The input DataFrame where each row is a solution.

• obj_names (list of str) – A list of column names in df that represent the objective functions.

• obj_directions (list of str) – A list of strings (‘minimize’ or ‘maximize’) indicating the optimization direction for each objective. Must match the order of obj_names_param.

• num_vars (int, optional) – The number of decision variables in the problem. Defaults to 0.

• num_constrs (int, optional) – The number of constraints in the problem. Defaults to 0.

Returns:

A list of Platypus Solution objects, each representing a row from

the input DataFrame.

Return type:

list

Raises:

• TypeError – If df is not a pandas DataFrame, or if obj_names, obj_directions are not lists of strings.

• ValueError – If obj_names is empty, objective directions are invalid, lengths of obj_names and obj_directions do not match, or num_vars/num_constrs are not non-negative integers.

parasolpy.tradeoff.parallel_plot_hp(df, obj_names=None, obj_directions=None, plot_direction='bottom', color_column=None, hide_columns=None, forced_ranges_columns=None, force_min=None, force_max=None, colormap='interpolateViridis', invert_columns=None)

Generates an interactive parallel plot using HiPlot for visualizing solution tradeoffs.

This function takes a DataFrame of solutions and generates a parallel coordinates plot to visualize the relationships between different objective functions and other metrics. It supports customizing the plot’s direction (for highlighting ‘good’ solutions), coloring by a specific column, and hiding unnecessary columns.

Parameters:

• df (pd.DataFrame) – The input DataFrame where each row represents a solution and columns represent objectives or other attributes.

• obj_names (list of str) – Names of the objective columns in df.

• obj_directions (list of str) – Optimization direction (‘minimize’ or ‘maximize’) for each objective.

• plot_direction (str, optional) – Defines the direction for inverting objective axes to highlight optimal regions. Must be ‘bottom’ (good solutions at the bottom of the plot) or ‘top’ (good solutions at the top). Defaults to ‘bottom’.

• color_column (str, optional) – The name of the column in df to use for coloring the lines in the parallel plot. If None, no column will be used for coloring. Defaults to None.

• hide_columns (list of str, optional) – A list of column names in df to hide from the parallel plot. Defaults to None (no columns hidden).

• forced_ranges_columns (list of str, optional) – Columns for which a forced axis range should be applied in the parallel plot.

• force_min (list of number, optional) – Minimum values for each forced-range column.

• force_max (list of number, optional) – Maximum values for each forced-range column.

• colormap (str, optional) – D3 colormap name used when color_column is provided.

• invert_columns (list of str, optional) – Explicit columns to invert. If provided, this takes precedence over obj_names/obj_directions.

Returns:

An HiPlot experiment object configured with the parallel plot.

Return type:

hiplot.Experiment

Raises:

• TypeError – If any input is malformed (wrong types for list/string arguments).

• ValueError – If plot_direction is not ‘bottom’ or ‘top’, color_column is not present in df (when provided), any specified column is missing, or forced-range list lengths do not match.

parasolpy.tradeoff.label_eps_nd(df, label_col, obj_names, obj_directions, epsilons, num_vars=0, num_constrs=0)

label_eps_nd: label epsilon non-dominated solutions

This function takes a DataFrame of solutions and identifies which ones are epsilon non-dominated based on a given set of objectives, directions, and epsilon values. It adds a new boolean column to the DataFrame, marking True for epsilon non-dominated solutions and False otherwise.

### Positional Arguments: * df (pd.DataFrame): The input DataFrame containing solution data. * label_col (str): The name of the new column to be added to df to store the boolean labels. * obj_names (list of str): Names of the objective columns in df. * obj_directions (list of str): Optimization direction (‘minimize’ or ‘maximize’) for each objective. * epsilons (list of numbers): Epsilon values for each objective, defining the desired precision for performing the epsilon non-dominance calculation.

### Optional Keyword Arguments: * num_vars (int, optional): Number of decision variables. Defaults to 0. * num_constrs (int, optional): Number of constraints. Defaults to 0.

### How it works: 1. Input Validation: Checks if all input parameters are of the correct type and format. 2. Initialize Label Column: Creates a new column in the DataFrame (label_col) and sets all values to False. 3. Convert to Platypus Format: Uses the df_to_pt function to convert the DataFrame into a list of Platypus Solution objects. 4. Epsilon Non-dominated Sorting: Employs the EpsilonBoxArchive from Platypus to perform the epsilon non-dominated sort. 5. Label Solutions: Identifies the id (original DataFrame index) of the epsilon non-dominated solutions and updates the label_col in the input DataFrame to True for these solutions. 6. Return DataFrame: Returns the DataFrame with the new label_col populated.

parasolpy.tradeoff.append_Kmeans(df, num_clusters=3, cluster_columns=None)

Cluster solutions with K-Means and append a ‘Cluster’ column in place.

Parameters:

• df – DataFrame of solutions. Modified in place — a "Cluster" column containing integer cluster labels (0-indexed) is added.

• num_clusters – Number of K-Means clusters. Defaults to 3.

• cluster_columns – List of column names to use as features. When None, all columns in df are used.

Returns:

• The input df with the new "Cluster" column added.

• The fitted KMeans object (useful for inspecting centroids).

Return type:

tuple[pd.DataFrame, sklearn.cluster.KMeans]

parasolpy.tradeoff.load_objective_names(output_folder, config_filename=None, return_config_path=False, include_directions=False)

Load objective names from an output folder configuration XML.

Parameters:

• output_folder – Search output folder containing copied input files.

• config_filename – Optional relative path to a specific XML file. If None, auto-discovers legacy CopyOfConfiguration.xml or newer XML names.

• return_config_path – If True, also return the resolved config XML path.

• include_directions – If True, also return the list of objective directions.

parasolpy.tradeoff.resolve_solutions_csv(output_folder, solutions_filename=None)

Resolve a solutions CSV path across canonical and user-renamed naming patterns.

parasolpy.tradeoff.load_objectives_and_solutions(output_folder, config_filename=None, solutions_filename=None, return_paths=False, include_directions=False)

Load objective names and solutions DataFrame from an output folder.

Parameters:

• output_folder – Search output folder containing copied input files and result CSVs.

• config_filename – Optional relative config XML path; auto-discovered when None.

• solutions_filename – Optional relative solutions CSV path; auto-discovered when None.

• return_paths – If True, also return resolved config and CSV paths.

• include_directions – If True, also return the list of objective directions.

parasolpy.tradeoff.normalize_for_radar(solutions, objective_names)

Return normalized radar values and objective labels with closure for polygon plotting.

parasolpy.tradeoff.build_radar_figure(normalized_solutions, objectives_with_closure, showlegend=False)

Create a Plotly radar figure from normalized solution values.

parasolpy.tradeoff.run_eps_experiment(output_folder, objective_names, objective_directions, solutions_base, experiment_name, epsilons)

Apply epsilon non-dominance labeling and write named output files.

This is the core computation step for one epsilon experiment: it labels solutions, writes two CSVs and one HTML parallel-plot file, and returns a summary dict so callers can report results without coupling to the I/O.

Parameters:

• output_folder – Directory where output files are written.

• objective_names – List of objective column names.

• objective_directions – List of ‘minimize’/’maximize’ strings matching objective_names.

• solutions_base – DataFrame of candidate solutions (not mutated; a copy is made).

• experiment_name – Filesystem-safe string used as a suffix in all output filenames.

• epsilons – List of epsilon values, one per objective.

Returns:

‘n_total’ — total number of input solutions ‘n_retained’ — number of epsilon non-dominated solutions ‘labeled_path’ — Path written for all solutions with eps_nd label ‘eps_only_path’ — Path written for epsilon non-dominated solutions only ‘html_path’ — Path written for HiPlot parallel-plot HTML

Return type:

dict with keys

parasolpy.tradeoff.log_eps_experiment(log_path, entry)

Write a single experiment record to a JSON file.

One file is written per experiment. If the file already exists it is overwritten (e.g. when re-running an experiment with the same name). Path objects in the entry are automatically serialized to strings.

Parameters:

• log_path – Path-like destination for the JSON file.

• entry – dict describing the experiment. All values must be JSON-serializable or Path objects (which are converted to strings automatically).