utils

Central script containing objects for surrogate optimization and helper functions.

class qnetsur.utils.Simulation(sim_wrapper, sim, rng, values, variables)

Bases: object

Object to run quantum network simulations. It allows for the specification of both fixed and variable simulation parameters, supports the generation of random parameter sets, and facilitates the running of simulations through a user-defined simulation function.

Parameters:

• sim_wrapper (function) – The wrapper function that preprocesses simulation parameters before execution and adapts outputs according to needs of use case.

• sim (function) – The actual simulation function to be executed.

• rng (class) – Random number generator object to be used.

• values (dict) – Fixed parameters for the simulation.

• variables (dict, optional) – Variable parameters for the simulation, allowing for dynamic adjustments.

run_sim(x, vals=None)

Executes a single simulation run with the given parameters.

run_exhaustive(x, N=10, seed=42)

Executes N simulations in parallel.

get_random_x(n)

Generates n sets of random parameters based on the specified variable parameters.

get_random_x(n: int) → dict

Generates random parameters for the simulation.

run_exhaustive(x: dict, N=10, seed=42) → list

Runs the quantum network simulation with the provided parameters N times in parallel.

run_sim(x: dict) → list

Runs the quantum network simulation with the provided parameters.

Parameters:

x (dict) – Parameters for the simulation.

Returns:

Results of the simulation.

Return type:

list

class qnetsur.utils.Surrogate(sim_wrapper, sim, rng, values, variables, initial_training_size, ntop, degree=4, max_data_size=100000)

Bases: Simulation

Initializes the Surrogate model with a simulation wrapper, the actual simulation function, and a set of fixed and variable parameters. It sets up the environment for running surrogate model-based optimizations, including the multiprocessing setup for parallel simulations.

Parameters:

• sim_wrapper (function) – A function that wraps around the actual simulation to perform pre-processing of simulation parameters.

• sim (function) – The actual simulation function to be optimized.

• initial_training_size (int) – The number of configurations to use for the initial surrogate model training.

• ntop (int) – The number of configurations to use in acquisition process

• degree (int, optional) – Exponent in acquisition transition function (exploitation degree).

X

Training set parameters.

Type:

dict

X_df

DataFrame version of X for easier manipulation and model training.

Type:

pandas.DataFrame

y

Simulation results corresponding to each set of parameters in X.

Type:

list

y_std

Standard deviation of simulation results, providing insight into result variability.

Type:

list

model

Regression model used for surrogate modeling. Default is SVR (Support Vector Regression) from scikit-learn.

Type:

class

mmodel

Multi-output wrapper for the regression model, allowing it to output multiple predictions.

Type:

class

mmodel_std

Separate multi-output model for predicting the standard deviation of simulation results.

Type:

class

build_time

Time taken to build or update the surrogate model.

Type:

list

sim_time

Time taken for simulation runs.

Type:

list

optimize_time

Time taken for optimization processes.

Type:

list

procs

Number of processes to use for parallel simulations, based on CPU count.

Type:

int

get_neighbour(max_time, current_time, x)

Generates a neighbouring set of parameters based on current optimization state.

acquisition(max_T, current_t)

Selects new parameters for evaluation by balancing exploration and exploitation.

update()

Updates the surrogate model with new data points collected from simulation runs.

optimize(max_T)

Conducts the optimization process to find optimal simulation parameters.

acquisition() → None

Computes n new data points according to estimated improvement and degree of exploration and adds the data to the training sample.

gen_initial_set() → None

Generates the initial training set.

get_neighbour(x: dict) → dict

Generates most promising parameters in limited neighbouring region according to current knowledge of surrogate model and depending on the time left.

optimize(limit, isscore=False, issequential=False, verbose=False) → None

Conducts the optimization process to find optimal simulation parameters.

optimize_with_iteration() → None

Optimization until a set maximum number of iterations.

optimize_with_timer() → None

Optimization until a set maximum number of seconds.

run_multiple_and_add_target_values(X) → None

train_models() → None

Trains the machine lerning models on current data set and chooses the one with smaller error to use for prediction.

update(counter) → None

Updates the model with new data. Executes simulation on most promising points found and adds simulation results to training dataset.

simulatedannealing

qnetsur.simulatedannealing.get_neighbour(sim, x: dict, rng) → dict

Generates random parameters for the simulation from neighborhood of x.

Parameters:

n (int) – Number of random parameter sets to generate.

Returns:

Randomly generated parameters.

Return type:

dict

qnetsur.simulatedannealing.get_random_x(self, n, rng) → dict

Generates random parameters for the simulation.

Parameters:

n (int) – Number of random parameter sets to generate.

Returns:

Randomly generated parameters.

Return type:

dict

qnetsur.simulatedannealing.objective(sim, x: dict) → float

Evaluate the objective function at given parameter settings.

Parameters:

• sim (Simulation) – The simulation environment.

• x (dict) – The parameter settings at which to evaluate.

Returns:

The negative sum of evaluations (to be minimized).

Return type:

float

qnetsur.simulatedannealing.simulated_annealing(sim, limit, temp: int = 10, beta_schedule: int = 5) → list

Global optimizing method Simulated Annealing (Kirkpatrick et al., 1983)

Parameters:

• sim (Simulation) – An instance of the Simulation class that provides methods and properties necessary for the simulation environment.

• limit (float) – The maximum time allowed for the optimization process in seconds.

• temp (int, optional) – The initial temperature for the annealing process. Default is 10.

• beta_schedule (int, optional) – The number of iterations for each temperature level. Default is 5.

• seed (int, optional) – The seed for the random number generator to ensure reproducibility. Default is 42.

Returns:

A list of dictionaries, where each dictionary represents the state of the system at each step

of the optimization. Each dictionary contains keys for the parameter values, their corresponding utility, and the computational time taken for that step.

Return type:

list

datacollector

class qnetsur.datacollector.SurrogateCollector(sim)

Bases: object

Collector designed for gathering and organizing data from surrogate-based optimization results.

This class provides methods to retrieve various sets of data including model outputs, timing metrics, and machine learning performance scores, all structured into pandas DataFrames.

sim

An instance of the Simulation class that provides methods and properties necessary for the simulation environment.

Type:

Simulation

get_machine_learning_scores()

Retrieves the performance scores of the machine learning models used in the simulation.

The scores are extracted from the simulation model and formatted into a DataFrame to provide a clear view of each model’s performance.

Returns:

A DataFrame containing performance scores for each machine learning model.

Return type:

pd.DataFrame

get_model_df()

Constructs a DataFrame containing all relevant outputs from the simulation model.

The DataFrame includes objective values, raw outputs, standardized outputs, and the inputs to the model, providing a comprehensive view of the model’s performance.

Returns:

A DataFrame combining input data with simulation outputs including

objective values, raw and standardized outputs.

Return type:

pd.DataFrame

get_timing()

Retrieves and formats the timing information for the simulation.

The method extracts timing data for the simulation setup, model building, and acquisition phases, and formats it into a readable DataFrame.

Returns:

A DataFrame containing detailed timing information for different

phases of the simulation, suffixed with ‘ [s]’ to denote seconds.

Return type:

pd.DataFrame

get_total()

Compiles all collected data into a single comprehensive DataFrame.

This method aggregates model outputs, timing data, and machine learning scores into one DataFrame, facilitating an integrated view of all results and metrics from the simulation.

Returns:

A merged DataFrame containing all collected data, allowing for easy analysis and visualization.

Return type:

pd.DataFrame

qnetsur.datacollector.get_parameters(variables)

Extracts and formats parameters from a dictionary for use in the Ax-platform optimization tool.

Parameters:

variables (dict) – A dictionary where keys correspond to parameter types (e.g., ‘range’, ‘ordinal’, ‘choice’) and values provide the definitions of these parameters.

Returns:

A list of parameter definitions formatted for use in optimization routines, with each parameter represented as a dictionary detailing its name, type, and constraints or choices.

Return type:

list