about

Helper module for information about Sparkle.

configurator

This package provides configurator support for Sparkle.

instance

This package provides instance set support for Sparkle.

class sparkle.instance.FileInstanceSet(target: Path)

Object representation of a set of single-file instances.

property name: str

Get instance set name.

class sparkle.instance.InstanceSet(target: Path | list[str, Path])

Base object representation of a set of instances.

property all_paths: list[Path]

Returns all file paths in the instance set as a flat list.

get_path_by_name(name: str) → Path | list[Path]

Retrieves an instance paths by its name. Returns None upon failure.

property instance_names: list[str]

Get processed instance names for multi-file instances.

property instance_paths: list[Path]

Get processed instance paths.

property name: str

Get instance set name.

property size: int

Returns the number of instances in the set.

class sparkle.instance.IterableFileInstanceSet(target: Path)

Object representation of files containing multiple instances.

property size: int

Returns the number of instances in the set.

class sparkle.instance.MultiFileInstanceSet(target: Path | list[str, Path])

Object representation of a set of multi-file instances.

property all_paths: list[Path]

Returns all file paths in the instance set as a flat list.

platform

This package provides platform support for Sparkle.

class sparkle.platform.CommandName(value)

Enum of all command names.

class sparkle.platform.SettingState(value)

Enum of possible setting states.

class sparkle.platform.Settings(file_path: PurePath | None = None)

Class to read, write, set, and get settings.

add_slurm_extra_option(name: str, value: str, origin: SettingState = SettingState.DEFAULT) → None

Add additional Slurm options.

static check_settings_changes(cur_settings: Settings, prev_settings: Settings) → bool

Check if there are changes between the previous and the current settings.

Prints any section changes, printing None if no setting was found.

Args:

cur_settings: The current settings prev_settings: The previous settings

Returns:

True iff there are no changes.

get_ablation_racing_flag() → bool

Return a bool indicating whether the racing flag is set for ablation.

get_configurator_max_iterations() → int | None

Get the maximum number of configurator iterations.

get_configurator_number_of_runs() → int

Return the number of configuration runs.

get_configurator_settings(configurator_name: str) → dict[str, any]

Return the configurator settings.

get_configurator_solver_calls() → int | None

Return the maximum number of solver calls the configurator can do.

get_general_check_interval() → int

Return the general check interval.

get_general_extractor_cutoff_time() → int

Return the cutoff time in seconds for feature extraction.

get_general_solution_verifier() → object

Return the solution verifier to use.

get_general_sparkle_configurator() → Configurator

Return the configurator init method.

get_general_sparkle_objectives() → list[SparkleObjective]

Return the performance measure.

get_general_sparkle_selector() → Selector

Return the selector init method.

get_general_target_cutoff_time() → int

Return the cutoff time in seconds for target algorithms.

get_general_verbosity() → VerbosityLevel

Return the general verbosity.

get_irace_first_test() → int | None

Return the first test for IRACE.

Specifies how many instances are evaluated before the first elimination test. IRACE Default: 5. [firstTest]

get_irace_max_experiments() → int

Return the max number of experiments for IRACE.

get_irace_max_iterations() → int

Return the number of iterations for IRACE.

get_irace_max_time() → int

Return the max time in seconds for IRACE.

get_irace_mu() → int | None

Return the mu for IRACE.

Parameter used to define the number of configurations sampled and evaluated at each iteration. IRACE Default: 5. [mu]

get_number_of_jobs_in_parallel() → int

Return the number of runs Sparkle can do in parallel.

get_parallel_portfolio_check_interval() → int

Return the parallel portfolio check interval.

get_parallel_portfolio_number_of_seeds_per_solver() → int

Return the parallel portfolio seeds per solver to start.

get_run_on() → Runner

Return the compute on which to run.

get_slurm_extra_options(as_args: bool = False) → dict | list

Return a dict with additional Slurm options.

get_slurm_max_parallel_runs_per_node() → int

Return the number of algorithms Slurm can run in parallel per node.

get_smac2_cpu_time() → int | None

Return the budget per configuration run in seconds (cpu).

get_smac2_max_iterations() → int | None

Get the maximum number of SMAC2 iterations.

get_smac2_target_cutoff_length() → str

Return the target algorithm cutoff length.

‘A domain specific measure of when the algorithm should consider itself done.’

Returns:

The target algorithm cutoff length.

get_smac2_use_cpu_time_in_tunertime() → bool

Return whether to use CPU time in tunertime.

get_smac2_wallclock_time() → int | None

Return the budget per configuration run in seconds (wallclock).

read_settings_ini(file_path: PurePath = PurePosixPath('Settings/sparkle_settings.ini'), state: SettingState = SettingState.FILE) → None

Read the settings from an INI file.

set_ablation_racing_flag(value: bool = False, origin: SettingState = SettingState.DEFAULT) → None

Set a flag indicating whether racing should be used for ablation.

set_configurator_max_iterations(value: int | None = None, origin: SettingState = SettingState.DEFAULT) → None

Set the number of configuration runs.

set_configurator_number_of_runs(value: int = 25, origin: SettingState = SettingState.DEFAULT) → None

Set the number of configuration runs.

set_configurator_solver_calls(value: int = 100, origin: SettingState = SettingState.DEFAULT) → None

Set the number of solver calls.

set_general_check_interval(value: int = 10, origin: SettingState = SettingState.DEFAULT) → None

Set the general check interval.

set_general_extractor_cutoff_time(value: int = 60, origin: SettingState = SettingState.DEFAULT) → None

Set the cutoff time in seconds for feature extraction.

set_general_solution_verifier(value: str = 'None', origin: SettingState = SettingState.DEFAULT) → None

Set the solution verifier to use.

set_general_sparkle_configurator(value: str = 'SMAC2', origin: SettingState = SettingState.DEFAULT) → None

Set the Sparkle configurator.

set_general_sparkle_objectives(value: list[~sparkle.types.objective.SparkleObjective] = [<sparkle.types.objective.PAR object>], origin: ~sparkle.platform.settings_objects.SettingState = SettingState.DEFAULT) → None

Set the sparkle objective.

set_general_sparkle_selector(value: Path = PosixPath('/home/runner/work/Sparkle/Sparkle/sparkle/Components/AutoFolio/scripts/autofolio'), origin: SettingState = SettingState.DEFAULT) → None

Set the Sparkle selector.

set_general_target_cutoff_time(value: int = 60, origin: SettingState = SettingState.DEFAULT) → None

Set the cutoff time in seconds for target algorithms.

set_general_verbosity(value: VerbosityLevel = VerbosityLevel.STANDARD, origin: SettingState = SettingState.DEFAULT) → None

Set the general verbosity to use.

set_irace_first_test(value: int | None = None, origin: SettingState = SettingState.DEFAULT) → None

Set the first test for IRACE.

set_irace_max_experiments(value: int = 0, origin: SettingState = SettingState.DEFAULT) → None

Set the max number of experiments for IRACE.

set_irace_max_iterations(value: int | None = None, origin: SettingState = SettingState.DEFAULT) → None

Set the number of iterations for IRACE.

Maximum number of iterations to be executed. Each iteration involves the generation of new configurations and the use of racing to select the best configurations. By default (with 0), irace calculates a minimum number of iterations as N^iter = ⌊2 + log2 N param⌋, where N^param is the number of non-fixed parameters to be tuned. Setting this parameter may make irace stop sooner than it should without using all the available budget. IRACE recommends to use the default value (Empty).

set_irace_max_time(value: int = 0, origin: SettingState = SettingState.DEFAULT) → None

Set the max time in seconds for IRACE.

set_irace_mu(value: int | None = None, origin: SettingState = SettingState.DEFAULT) → None

Set the mu for IRACE.

set_number_of_jobs_in_parallel(value: int = 25, origin: SettingState = SettingState.DEFAULT) → None

Set the number of runs Sparkle can do in parallel.

set_parallel_portfolio_check_interval(value: int = 4, origin: SettingState = SettingState.DEFAULT) → None

Set the parallel portfolio check interval.

set_parallel_portfolio_number_of_seeds_per_solver(value: int = 1, origin: SettingState = SettingState.DEFAULT) → None

Set the parallel portfolio seeds per solver to start.

set_run_on(value: Runner = 'local', origin: SettingState = SettingState.DEFAULT) → None

Set the compute on which to run.

set_slurm_max_parallel_runs_per_node(value: int = 8, origin: SettingState = SettingState.DEFAULT) → None

Set the number of algorithms Slurm can run in parallel per node.

set_smac2_cpu_time(value: int | None = None, origin: SettingState = SettingState.DEFAULT) → None

Set the budget per configuration run in seconds (cpu).

set_smac2_max_iterations(value: int | None = None, origin: SettingState = SettingState.DEFAULT) → None

Set the maximum number of SMAC2 iterations.

set_smac2_target_cutoff_length(value: str = 'max', origin: SettingState = SettingState.DEFAULT) → None

Set the target algorithm cutoff length.

set_smac2_use_cpu_time_in_tunertime(value: bool | None = None, origin: SettingState = SettingState.DEFAULT) → None

Set whether to use CPU time in tunertime.

set_smac2_wallclock_time(value: int | None = None, origin: SettingState = SettingState.DEFAULT) → None

Set the budget per configuration run in seconds (wallclock).

write_settings_ini(file_path: Path) → None

Write the settings to an INI file.

write_used_settings() → None

Write the used settings to the default locations.

solver

This package provides solver support for Sparkle.

class sparkle.solver.Extractor(directory: Path, runsolver_exec: Path | None = None, raw_output_directory: Path | None = None)

Extractor base class for extracting features from instances.

build_cmd(instance: Path | list[Path], feature_group: str | None = None, output_file: Path | None = None, cutoff_time: int | None = None, log_dir: Path | None = None) → list[str]

Builds a command line string seperated by space.

Args:

instance: The instance to run on feature_group: The optional feature group to run the extractor for. outputfile: Optional file to write the output to. runsolver_args: The arguments for runsolver. If not present,

will run the extractor without runsolver.

Returns:

The command seperated per item in the list.

property feature_groups: list[str]

Returns the various feature groups the Extractor has.

property features: list[tuple[str, str]]

Determines the features of the extractor.

get_feature_vector(result: Path, runsolver_values: Path | None = None) → list[str]

Extracts feature vector from an output file.

Args:

result: The raw output of the extractor runsolver_values: The output of runsolver.

Returns:

A list of features. Vector of missing values upon failure.

property groupwise_computation: bool

Determines if you can call the extractor per group for parallelisation.

property output_dimension: int

The size of the output vector of the extractor.

run(instance: Path | list[Path], feature_group: str | None = None, output_file: Path | None = None, cutoff_time: int | None = None, log_dir: Path | None = None) → list | None

Runs an extractor job with Runrunner.

Args:

extractor_path: Path to the executable instance: Path to the instance to run on feature_group: The feature group to compute. Must be supported by the

extractor to use.

output_file: Target output. If None, piped to the RunRunner job. cutoff_time: CPU cutoff time in seconds log_dir: Directory to write logs. Defaults to self.raw_output_directory.

Returns:

The features or None if an output file is used, or features can not be found.

class sparkle.solver.SATVerifier

Class to handle the SAT verifier.

static sat_get_verify_string(sat_output: str) → SolverStatus

Return the status of the SAT verifier.

Four statuses are possible: “SAT”, “UNSAT”, “WRONG”, “UNKNOWN”

static sat_judge_correctness_raw_result(instance: Path, raw_result: Path) → SolverStatus

Run a SAT verifier to determine correctness of a result.

Args:

instance: path to the instance raw_result: path to the result to verify

Returns:

The status of the solver on the instance

verify(instance: Path, raw_result: Path) → SolverStatus

Run a SAT verifier and return its status.

class sparkle.solver.Selector(executable_path: Path, raw_output_directory: Path)

The Selector class for handling Algorithm Selection.

build_cmd(selector_path: Path, feature_vector: list | str) → list[str | Path]

Builds the commandline call string for running the Selector.

build_construction_cmd(target_file: Path, performance_data: Path, feature_data: Path, objective: SparkleObjective, runtime_cutoff: int | float | str | None = None, wallclock_limit: int | float | str | None = None) → list[str | Path]

Builds the commandline call string for constructing the Selector.

Args:

target_file: Path to the file to save the Selector to. performance_data: Path to the performance data csv. feature_data: Path to the feature data csv. objective: The objective to optimize for selection. runtime_cutoff: Cutoff for the runtime in seconds. Defaults to None wallclock_limit: Cutoff for total wallclock in seconds. Defaults to None

Returns:

The command list for constructing the Selector.

construct(target_file: Path | str, performance_data: PerformanceDataFrame, feature_data: FeatureDataFrame, objective: SparkleObjective, runtime_cutoff: int | float | str | None = None, wallclock_limit: int | float | str | None = None, run_on: Runner = Runner.SLURM, sbatch_options: list[str] | None = None, base_dir: Path = PosixPath('.')) → Run

Construct the Selector.

Args:

target_file: Path to the file to save the Selector to. performance_data: Path to the performance data csv. feature_data: Path to the feature data csv. objective: The objective to optimize for selection. runtime_cutoff: Cutoff for the runtime in seconds. wallclock_limit: Cutoff for the wallclock time in seconds. run_on: Which runner to use. Defaults to slurm. sbatch_options: Additional options to pass to sbatch. base_dir: The base directory to run the Selector in.

Returns:

Path to the constructed Selector.

static process_predict_schedule_output(output: str) → list

Return the predicted algorithm schedule as a list.

run(selector_path: Path, feature_vector: list | str) → list

Run the Selector, returning the prediction schedule upon success.

class sparkle.solver.SolutionVerifier

Solution verifier base class.

verifiy() → SolverStatus

Verify the solution.

class sparkle.solver.Solver(directory: Path, raw_output_directory: Path | None = None, runsolver_exec: Path | None = None, deterministic: bool | None = None, verifier: SolutionVerifier | None = None)

Class to handle a solver and its directories.

build_cmd(instance: str | list[str], objectives: list[SparkleObjective], seed: int, cutoff_time: int | None = None, configuration: dict | None = None, log_dir: Path | None = None) → list[str]

Build the solver call on an instance with a configuration.

Args:

instance: Path to the instance. seed: Seed of the solver. cutoff_time: Cutoff time for the solver. configuration: Configuration of the solver.

Returns:

List of commands and arguments to execute the solver.

static config_str_to_dict(config_str: str) → dict[str, str]

Parse a configuration string to a dictionary.

get_forbidden(port_type: PCSConvention) → Path

Get the path to the file containing forbidden parameter combinations.

get_pcs() → dict[str, tuple[str, str, str]]

Get the parameter content of the PCS file.

get_pcs_file(port_type: str | None = None) → Path

Get path of the parameter file.

Returns:

Path to the parameter file. None if it can not be resolved.

static parse_solver_output(solver_output: str, runsolver_configuration: list[str | Path] | None = None) → dict[str, Any]

Parse the output of the solver.

Args:

solver_output: The output of the solver run which needs to be parsed runsolver_configuration: The runsolver configuration to wrap the solver

with. If runsolver was not used this should be None.

Returns:

Dictionary representing the parsed solver output

port_pcs(port_type: PCSConvention) → None

Port the parameter file to the given port type.

read_pcs_file() → bool

Checks if the pcs file can be read.

run(instance: str | list[str] | InstanceSet, objectives: list[SparkleObjective], seed: int, cutoff_time: int | None = None, configuration: dict | None = None, run_on: Runner = Runner.LOCAL, commandname: str = 'run_solver', sbatch_options: list[str] | None = None, log_dir: Path | None = None) → SlurmRun | list[dict[str, Any]] | dict[str, Any]

Run the solver on an instance with a certain configuration.

Args:

instance: The instance(s) to run the solver on, list in case of multi-file.

In case of an instance set, will run on all instances in the set.

seed: Seed to run the solver with. Fill with abitrary int in case of

determnistic solver.

cutoff_time: The cutoff time for the solver, measured through RunSolver.

If None, will be executed without RunSolver.

configuration: The solver configuration to use. Can be empty. log_dir: Path where to place output files. Defaults to

self.raw_output_directory.

Returns:

Solver output dict possibly with runsolver values.

class sparkle.solver.Validator(out_dir: Path = PosixPath('.'), tmp_out_dir: Path = PosixPath('.'))

Class to handle the validation of solvers on instance sets.

append_entry_to_csv(solver: str, config_str: str, instance_set: InstanceSet, instance: str, solver_output: dict, subdir: Path | None = None) → None

Append a validation result as a row to a CSV file.

get_validation_results(solver: Solver, instance_set: InstanceSet, source_dir: Path | None = None, subdir: Path | None = None, config: str | None = None) → list[list[str]]

Query the results of the validation of solver on instance_set.

Args:

solver: Solver object instance_set: Instance set source_dir: Path where to look for any unprocessed output.

By default, look in the solver’s tmp dir.

subdir: Path where to place the .csv file subdir. By default will be

‘self.outputdir/solver.name_instanceset.name/validation.csv’

config: Path to the configuration if the solver was configured, None

otherwise

Returns

A list of row lists with string values

retrieve_raw_results(solver: Solver, instance_sets: InstanceSet | list[InstanceSet], subdir: Path | None = None, log_dir: Path | None = None) → None

Checks the raw results of a given solver for a specific instance_set.

Writes the raw results to a unified CSV file for the resolve/instance_set combination.

Args:

solver: The solver for which to check the raw result path instance_sets: The set of instances for which to retrieve the results subdir: Subdir where the CSV is to be placed, passed to the append method. log_dir: The directory to search for log files. If none, defaults to

the log directory of the Solver.

validate(solvers: list[Path] | list[Solver] | Solver | Path, configurations: list[dict] | dict | Path, instance_sets: list[InstanceSet], objectives: list[SparkleObjective], cut_off: int, subdir: Path | None = None, dependency: list[Run] | Run | None = None, sbatch_options: list[str] = [], run_on: Runner = Runner.SLURM) → Run

Validate a list of solvers (with configurations) on a set of instances.

Args:

solvers: list of solvers to validate configurations: list of configurations for each solver we validate.

If a path is supplied, will use each line as a configuration.

instance_sets: set of instance sets on which we want to validate each solver objectives: list of objectives to validate cut_off: maximum run time for the solver per instance subdir: The subdir where to place the output in the outputdir. If None,

a semi-unique combination of solver_instanceset is created.

dependency: Jobs to wait for before executing the validation. sbatch_options: list of slurm batch options run_on: whether to run on SLURM or local

structures

This package provides Sparkle’s wrappers for Pandas DataFrames.

class sparkle.structures.FeatureDataFrame(csv_filepath: Path, instances: list[str] = [], extractor_data: dict[str, list[tuple[str, str]]] = {})

Class to manage feature data CSV files and common operations on them.

add_extractor(extractor: str, extractor_features: list[tuple[str, str]], values: list[list[float]] | None = None) → None

Add an extractor and its feature names to the dataframe.

Arguments:

extractor: Name of the extractor extractor_features: Tuples of [FeatureGroup, FeatureName] values: Initial values of the Extractor per instance in the dataframe.

Defaults to FeatureDataFrame.missing_value.

add_instances(instance: str | list[str], values: list[float] | None = None) → None

Add one or more instances to the dataframe.

property extractors: list[str]

Returns all unique extractors in the DataFrame.

get_feature_groups(extractor: str | list[str] | None = None) → list[str]

Retrieve the feature groups in the dataframe.

Args:

extractor: Optional. If extractor(s) are given,

yields only feature groups of that extractor.

Returns:

A list of feature groups.

get_instance(instance: str) → list[float]

Return the feature vector of an instance.

get_value(instance: str, extractor: str, feature_group: str, feature_name: str) → None

Return a value in the dataframe.

has_missing_value() → bool

Return whether there are missing values in the feature data.

has_missing_vectors() → bool

Returns True if there are any Extractors still to be run on any instance.

impute_missing_values() → None

Imputes all NaN values by taking the average feature value.

property instances: list[str]

Return the instances in the dataframe.

remaining_jobs() → list[tuple[str, str, str]]

Determines needed feature computations per instance/extractor/group.

Returns:

list: A list of tuples representing (Extractor, Instance, Feature Group).

that needs to be computed.

remove_extractor(extractor: str) → None

Remove an extractor from the dataframe.

remove_instances(instances: str | list[str]) → None

Remove an instance from the dataframe.

reset_dataframe() → bool

Resets all values to FeatureDataFrame.missing_value.

save_csv(csv_filepath: Path | None = None) → None

Write a CSV to the given path.

Args:

csv_filepath: String path to the csv file. Defaults to self.csv_filepath.

set_value(instance: str, extractor: str, feature_group: str, feature_name: str, value: float) → None

Set a value in the dataframe.

sort() → None

Sorts the DataFrame by Multi-Index for readability.

to_autofolio(target: Path | None = None) → Path

Port the data to a format acceptable for AutoFolio.

class sparkle.structures.PerformanceDataFrame(csv_filepath: Path, solvers: list[str] = [], objectives: list[str | SparkleObjective] | None = None, instances: list[str] = [], n_runs: int = 1, init_df: bool = True)

Class to manage performance data and common operations on them.

add_instance(instance_name: str, initial_value: float | list[float] | None = None) → None

Add and instance to the DataFrame.

add_solver(solver_name: str, initial_value: float | list[float] | None = None) → None

Add a new solver to the dataframe. Initializes value to None by default.

Args:

solver_name: The name of the solver to be added. initial_value: The value assigned for each index of the new solver.

If not None, must match the index dimension (n_obj * n_inst * n_runs).

best_instance_performance(objective: str | SparkleObjective | None = None, run_id: int | None = None, exclude_solvers: list[str] | None = None) → Series

Return the best performance for each instance in the portfolio.

Args:

objective: The objective for which we calculate the best performance run_id: The run for which we calculate the best performance. If None,

we consider all runs.

exclude_solvers: List of solvers to exclude in the calculation.

Returns:

The best performance for each instance in the portfolio.

best_performance(exclude_solvers: list[str] = [], objective: str | SparkleObjective | None = None) → float

Return the overall best performance of the portfolio.

Args:

exclude_solvers: List of solvers to exclude in the calculation.

Defaults to none.

objective: The objective for which we calculate the best performance

Returns:

The aggregated best performance of the portfolio over all instances.

clean_csv() → None

Set all values in Performance Data to None.

copy(csv_filepath: Path | None = None) → PerformanceDataFrame

Create a copy of this object.

Args:

csv_filepath: The new filepath to use for saving the object to.

Warning: If the original path is used, it could lead to dataloss!

get_job_list(rerun: bool = False) → list[tuple[str, str]]

Return a list of performance computation jobs there are to be done.

Get a list of tuple[instance, solver] to run from the performance data csv file. If rerun is False (default), get only the tuples that don’t have a value in the table, else (True) get all the tuples.

Args:

rerun: Boolean indicating if we want to rerun all jobs

get_solver_ranking(objective: str | SparkleObjective | None = None) → list[tuple[str, float]]

Return a list with solvers ranked by average performance.

get_value(solver: str, instance: str, objective: str | None = None, run: int | None = None) → float

Index a value of the DataFrame and return it.

get_values(solver: str, instance: str | None = None, objective: str | None = None, run: int | None = None) → list[float]

Return a list of solver values.

property has_missing_values: bool

Returns True if there are any missing values in the dataframe.

property instances: list[str]

Return the instances as a Pandas Index object.

marginal_contribution(objective: str | SparkleObjective | None = None, sort: bool = False) → list[float]

Return the marginal contribution of the solvers on the instances.

Args:

objective: The objective for which we calculate the marginal contribution. sort: Whether to sort the results afterwards

Returns:

The marginal contribution of each solver.

mean(objective: str | None = None, solver: str | None = None, instance: str | None = None) → float

Return the mean value of a slice of the dataframe.

property multi_objective: bool

Return whether the dataframe represent MO or not.

property num_instances: int

Return the number of instances.

property num_objectives: int

Retrieve the number of objectives in the DataFrame.

property num_runs: int

Return the number of runs.

property num_solvers: int

Return the number of solvers.

property objective_names: list[str]

Return the objective names as a list of strings.

remaining_jobs() → dict[str, list[str]]

Return a dictionary for empty values per instance and solver combination.

remove_instance(instance_name: str) → None

Drop an instance from the Dataframe.

remove_solver(solver_name: str | list[str]) → None

Drop one or more solvers from the Dataframe.

reset_value(solver: str, instance: str, objective: str | None = None, run: int | None = None) → None

Reset a value in the dataframe.

save_csv(csv_filepath: Path | None = None) → None

Write a CSV to the given path.

Args:

csv_filepath: String path to the csv file. Defaults to self.csv_filepath.

schedule_performance(schedule: dict[slice(<class 'str'>, list[tuple[str, float | None]], None)], target_solver: str | None = None, objective: str | ~sparkle.types.objective.SparkleObjective | None = None) → float

Return the performance of a selection schedule on the portfolio.

Args:

schedule: Compute the best performance according to a selection schedule.

A dictionary with instances as keys and a list of tuple consisting of (solver, max_runtime) or solvers if no runtime prediction should be used.

target_solver: If not None, store the values in this solver of the DF. objective: The objective for which we calculate the best performance

Returns:

The performance of the schedule over the instances in the dictionary.

set_value(value: float, solver: str, instance: str, objective: str | None = None, run: int | None = None) → None

Setter method to assign a value to the Dataframe.

Args:

value: Float value to be assigned. solver: The solver that produced the value. instance: The instance that the value was produced on. objective: The objective for which the result was produced.

Optional in case of using single objective.

run: The run index for which the result was produced.

Optional in case of doing single run results.

property solvers: list[str]

Return the solver present as a list of strings.

to_autofolio(objective: SparkleObjective | None = None, target: Path | None = None) → Path

Port the data to a format acceptable for AutoFolio.

verify_indexing(objective: str, run_id: int) → tuple[str, int]

Method to check whether data indexing is correct.

Users are allowed to use the Performance Dataframe without the second and fourth dimension (Objective and Run respectively) in the case they only have one objective or only do one run. This method adjusts the indexing for those cases accordingly.

Args:

objective: The given objective name run_id: The given run index

Returns:

A tuple representing the (possibly adjusted) Objective and Run index.

verify_objective(objective: str) → str

Method to check whether the specified objective is valid.

Users are allowed to index the dataframe without specifying all dimensions. However, when dealing with multiple objectives this is not allowed and this is verified here. If we have only one objective this is returned. Otherwise, if an objective is specified by the user this is returned.

Args:

objective: The objective given by the user

verify_run_id(run_id: int) → int

Method to check whether run id is valid.

Similar to verify_objective but here we check the dimensionality of runs.

Args:

run_id: the run as specified by the user.

tools

Init for the tools module.

class sparkle.tools.PCSParser(inherit: PCSParser | None = None)

Base interface object for the parser.

It loads the pcs files into the generic pcs object. Once a parameter file is loaded, it can be exported to another file

check_validity() → bool

Check the validity of the pcs.

export(destination: Path, convention: str = 'smac') → None

Main export function.

load(filepath: Path, convention: str = 'smac') → None

Main import function.

class sparkle.tools.SlurmBatch(srcfile: Path)

Class to parse a Slurm batch file and get structured information.

Attributes

sbatch_options: list[str]

The SBATCH options. Ex.: [”–array=-22%250”, “–mem-per-cpu=3000”]

cmd_params: list[str]

The parameters to pass to the command

cmd: str

The command to execute

srun_options: list[str]

A list of arguments to pass to srun. Ex.: [“-n1”, “–nodes=1”]

file: Path

The loaded file Path

sparkle.tools.get_solver_call_params(args_dict: dict) → list[str]

Gather the additional parameters for the solver call.

Args:

args_dict: Dictionary mapping argument names to their currently held values

Returns:

A list of parameters for the solver call

sparkle.tools.get_time_pid_random_string() → str

Return a combination of time, Process ID, and random int as string.

Returns:

A random string composed of time, PID and a random positive integer value.

types

This package provides types for Sparkle applications.

class sparkle.types.FeatureGroup(value)

Various feature groups.

class sparkle.types.FeatureSubgroup(value)

Various feature subgroups. Only used for embedding in with feature names.

class sparkle.types.FeatureType(value)

Various feature types.

static with_subgroup(subgroup: FeatureSubgroup, feature: FeatureType) → str

Return a standardised string with a subgroup embedded.

class sparkle.types.SolverStatus(value)

Possible return states for solver runs.

class sparkle.types.SparkleCallable(directory: Path, runsolver_exec: Path | None = None, raw_output_directory: Path | None = None)

Sparkle Callable class.

build_cmd() → list[str | Path]

A method that builds the commandline call string.

run() → None

A method that runs the callable.

class sparkle.types.SparkleObjective(name: str, run_aggregator: ~typing.Callable = <function mean>, instance_aggregator: ~typing.Callable = <function mean>, solver_aggregator: ~typing.Callable | None = None, minimise: bool = True, post_process: ~typing.Callable | None = None, use_time: ~sparkle.types.objective.UseTime = UseTime.NO)

Objective for Sparkle specified by user.

property time: bool

Return whether the objective is time based.

class sparkle.types.UseTime(value)

Enum describing what type of time to use.

sparkle.types._check_class(candidate: Callable) → bool

Verify whether a loaded class is a valid objective class.

sparkle.types.resolve_objective(objective_name: str) → SparkleObjective

Try to resolve the objective class by (case-sensitive) name.

convention: objective_name(variable-k)?(:[min|max])?

Order of resolving:

class_name of user defined SparkleObjectives class_name of sparkle defined SparkleObjectives default SparkleObjective with minimization unless specified as max

Args:

name: The name of the objective class. Can include parameter value k.

Returns:

Instance of the Objective class or None if not found.