Coverage for src / sparkle / platform / settings_objects.py: 96%

1"""Classes and Enums to control settings.""" 

2 

3from __future__ import annotations 

4from typing import TYPE_CHECKING 

5 

6 

7import argparse 

8import configparser 

9from enum import Enum 

10from pathlib import Path 

11from typing import Any, NamedTuple, Optional 

12 

13from runrunner import Runner 

14 

15from sparkle.platform.cli_types import VerbosityLevel 

16from sparkle.types import SparkleObjective, resolve_objective 

17 

18 

19if TYPE_CHECKING: 

20 from sparkle.configurator.configurator import Configurator 

21 

22 

23class Option(NamedTuple): 

24 """Class to define an option in the Settings.""" 

25 

26 name: str 

27 section: str 

28 type: Any 

29 default_value: Any 

30 alternatives: tuple[str, ...] 

31 help: str = "" 

32 cli_kwargs: dict[str, Any] = {} 

33 

34 def __str__(self: Option) -> str: 

35 """Return the option name.""" 

36 return self.name 

37 

38 def __eq__(self: Option, other: Any) -> bool: 

39 """Check if two options are equal.""" 

40 if isinstance(other, Option): 

41 return ( 

42 self.name == other.name 

43 and self.section == other.section 

44 and self.type == other.type 

45 and self.default_value == other.default_value 

46 and self.alternatives == other.alternatives 

47 ) 

48 if isinstance(other, str): 

49 return self.name == other or other in self.alternatives 

50 return False 

51 

52 @property 

53 def args(self: Option) -> list[str]: 

54 """Return the option names as a command line arguments.""" 

55 return [ 

56 f"--{name.replace('_', '-')}" 

57 for name in [self.name] + list(self.alternatives) 

58 ] 

59 

60 @property 

61 def kwargs(self: Option) -> dict[str, Any]: 

62 """Return the option attributes as kwargs.""" 

63 kw = {"help": self.help, **self.cli_kwargs} 

64 

65 # If this option uses a boolean flag action, argparse must NOT receive 'type' 

66 action = kw.get("action") 

67 if action in ("store_true", "store_false"): 

68 return kw 

69 

70 # Otherwise include the base 'type' 

71 return {"type": self.type, **kw} 

72 

73 

74class Settings: 

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

76 

77 # CWD Prefix 

78 cwd_prefix = Path() # Empty for now 

79 

80 # Library prefix 

81 lib_prefix = Path(__file__).parent.parent.resolve() 

82 

83 # Default directory names 

84 rawdata_dir = Path("Raw_Data") 

85 analysis_dir = Path("Analysis") 

86 DEFAULT_settings_dir = Path("Settings") 

87 __settings_file = Path("sparkle_settings.ini") 

88 __latest_settings_file = Path("latest.ini") 

89 

90 # Default settings path 

91 DEFAULT_settings_path = Path(cwd_prefix / DEFAULT_settings_dir / __settings_file) 

92 DEFAULT_previous_settings_path = Path( 

93 cwd_prefix / DEFAULT_settings_dir / __latest_settings_file 

94 ) 

95 DEFAULT_reference_dir = DEFAULT_settings_dir / "Reference_Lists" 

96 

97 # Default library pathing 

98 DEFAULT_components = lib_prefix / "Components" 

99 

100 # Report Component: Bilbiography 

101 bibliography_path = DEFAULT_components / "latex_source" / "report.bib" 

102 

103 # Example settings path 

104 DEFAULT_example_settings_path = Path(DEFAULT_components / "sparkle_settings.ini") 

105 

106 # Wrapper templates pathing 

107 DEFAULT_solver_wrapper_template = DEFAULT_components / "sparkle_solver_wrapper.sh" 

108 

109 # Runsolver component 

110 DEFAULT_runsolver_dir = DEFAULT_components / "runsolver" / "src" 

111 DEFAULT_runsolver_exec = DEFAULT_runsolver_dir / "runsolver" 

112 

113 # Ablation component 

114 DEFAULT_ablation_dir = DEFAULT_components / "ablationAnalysis-0.9.4" 

115 DEFAULT_ablation_exec = DEFAULT_ablation_dir / "ablationAnalysis" 

116 DEFAULT_ablation_validation_exec = DEFAULT_ablation_dir / "ablationValidation" 

117 

118 # Default input directory pathing 

119 DEFAULT_solver_dir = cwd_prefix / "Solvers" 

120 DEFAULT_instance_dir = cwd_prefix / "Instances" 

121 DEFAULT_extractor_dir = cwd_prefix / "Extractors" 

122 DEFAULT_snapshot_dir = cwd_prefix / "Snapshots" 

123 

124 # Default output directory pathing 

125 DEFAULT_tmp_output = cwd_prefix / "Tmp" 

126 DEFAULT_output = cwd_prefix / "Output" 

127 DEFAULT_configuration_output = DEFAULT_output / "Configuration" 

128 DEFAULT_selection_output = DEFAULT_output / "Selection" 

129 DEFAULT_parallel_portfolio_output = DEFAULT_output / "Parallel_Portfolio" 

130 DEFAULT_ablation_output = DEFAULT_output / "Ablation" 

131 DEFAULT_log_output = DEFAULT_output / "Log" 

132 

133 # Default output subdirs 

134 DEFAULT_output_analysis = DEFAULT_output / analysis_dir 

135 

136 # Old default output dirs which should be part of something else 

137 DEFAULT_feature_data = DEFAULT_output / "Feature_Data" 

138 DEFAULT_performance_data = DEFAULT_output / "Performance_Data" 

139 

140 # Collection of all working dirs for platform 

141 DEFAULT_working_dirs = [ 

142 DEFAULT_solver_dir, 

143 DEFAULT_instance_dir, 

144 DEFAULT_extractor_dir, 

145 DEFAULT_output, 

146 DEFAULT_configuration_output, 

147 DEFAULT_selection_output, 

148 DEFAULT_output_analysis, 

149 DEFAULT_tmp_output, 

150 DEFAULT_log_output, 

151 DEFAULT_feature_data, 

152 DEFAULT_performance_data, 

153 DEFAULT_settings_dir, 

154 DEFAULT_reference_dir, 

155 ] 

156 

157 # Old default file paths from GV which should be turned into variables 

158 DEFAULT_feature_data_path = DEFAULT_feature_data / "feature_data.csv" 

159 DEFAULT_performance_data_path = DEFAULT_performance_data / "performance_data.csv" 

160 

161 # Define sections and options 

162 # GENERAL Options 

163 SECTION_general: str = "general" 

164 OPTION_objectives = Option( 

165 "objectives", 

166 SECTION_general, 

167 str, 

168 None, 

169 ("sparkle_objectives",), 

170 "A list of Sparkle objectives.", 

171 cli_kwargs={"nargs": "+"}, 

172 ) 

173 OPTION_configurator = Option( 

174 "configurator", 

175 SECTION_general, 

176 str, 

177 None, 

178 tuple(), 

179 "Name of the configurator to use.", 

180 ) 

181 OPTION_solver_cutoff_time = Option( 

182 "solver_cutoff_time", 

183 SECTION_general, 

184 int, 

185 None, 

186 ("target_cutoff_time", "cutoff_time_each_solver_call"), 

187 "Solver cutoff time in seconds.", 

188 ) 

189 OPTION_extractor_cutoff_time = Option( 

190 "extractor_cutoff_time", 

191 SECTION_general, 

192 int, 

193 None, 

194 tuple("cutoff_time_each_feature_computation"), 

195 "Extractor cutoff time in seconds.", 

196 ) 

197 OPTION_run_on = Option( 

198 "run_on", 

199 SECTION_general, 

200 Runner, 

201 None, 

202 tuple(), 

203 "On which compute resource to execute.", 

204 cli_kwargs={"choices": [Runner.LOCAL, Runner.SLURM]}, 

205 ) 

206 OPTION_verbosity = Option( 

207 "verbosity", 

208 SECTION_general, 

209 VerbosityLevel, 

210 VerbosityLevel.STANDARD, 

211 ("verbosity_level",), 

212 "Verbosity level.", 

213 ) 

214 OPTION_seed = Option( 

215 "seed", 

216 SECTION_general, 

217 int, 

218 None, 

219 tuple(), 

220 "Seed to use for pseudo-random number generators.", 

221 ) 

222 OPTION_appendices = Option( 

223 "appendices", 

224 SECTION_general, 

225 bool, 

226 False, 

227 tuple(), 

228 "Include the appendix section in the generated report.", 

229 cli_kwargs={ 

230 "action": "store_true", 

231 "default": None, 

232 }, 

233 ) 

234 

235 # CONFIGURATION Options 

236 SECTION_configuration = "configuration" 

237 OPTION_configurator_number_of_runs = Option( 

238 "number_of_runs", 

239 SECTION_configuration, 

240 int, 

241 None, 

242 tuple(), 

243 "The number of independent configurator jobs/runs.", 

244 ) 

245 OPTION_configurator_solver_call_budget = Option( 

246 "solver_calls", 

247 SECTION_configuration, 

248 int, 

249 None, 

250 tuple(), 

251 "The maximum number of calls (evaluations) a configurator can do in a single " 

252 "run of the solver.", 

253 ) 

254 OPTION_configurator_max_iterations = Option( 

255 "max_iterations", 

256 SECTION_configuration, 

257 int, 

258 None, 

259 ("maximum_iterations",), 

260 "The maximum number of iterations a configurator can do in a single job.", 

261 ) 

262 

263 # ABLATION Options 

264 SECTION_ablation = "ablation" 

265 OPTION_ablation_racing = Option( 

266 "racing", 

267 SECTION_ablation, 

268 bool, 

269 False, 

270 ("ablation_racing",), 

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

272 ) 

273 OPTION_ablation_clis_per_node = Option( 

274 "clis_per_node", 

275 SECTION_ablation, 

276 int, 

277 None, 

278 ( 

279 "max_parallel_runs_per_node", 

280 "maximum_parallel_runs_per_node", 

281 ), 

282 "The maximum number of ablation analysis jobs to run in parallel on a single " 

283 "node.", 

284 ) 

285 

286 # SELECTION Options 

287 SECTION_selection = "selection" 

288 OPTION_selection_class = Option( 

289 "selector_class", 

290 SECTION_selection, 

291 str, 

292 None, 

293 ("class",), 

294 "Can contain any of the class names as defined in asf.selectors.", 

295 ) 

296 OPTION_selection_model = Option( 

297 "selector_model", 

298 SECTION_selection, 

299 str, 

300 None, 

301 ("model",), 

302 "Can be any of the sklearn.ensemble models.", 

303 ) 

304 OPTION_minimum_marginal_contribution = Option( 

305 "minimum_marginal_contribution", 

306 SECTION_selection, 

307 float, 

308 0.01, 

309 ( 

310 "minimum_marginal_contribution", 

311 "minimum_contribution", 

312 "contribution_threshold", 

313 ), 

314 "The minimum marginal contribution a solver (configuration) must have to be used for the selector.", 

315 ) 

316 

317 # SMAC2 Options 

318 SECTION_smac2 = "smac2" 

319 OPTION_smac2_wallclock_time_budget = Option( 

320 "wallclock_time_budget", 

321 SECTION_smac2, 

322 int, 

323 None, 

324 ("wallclock_time",), 

325 "The wallclock time budget in seconds for each SMAC2 run.", 

326 ) 

327 OPTION_smac2_cpu_time_budget = Option( 

328 "cpu_time_budget", 

329 SECTION_smac2, 

330 int, 

331 None, 

332 ("cpu_time",), 

333 "The cpu time budget in seconds for each SMAC2 run.", 

334 ) 

335 OPTION_smac2_target_cutoff_length = Option( 

336 "target_cutoff_length", 

337 SECTION_smac2, 

338 str, 

339 None, 

340 ("cutoff_length", "solver_cutoff_length"), 

341 "The target cutoff length for SMAC2 solver call.", 

342 ) 

343 OPTION_smac2_count_tuner_time = Option( 

344 "use_cpu_time_in_tunertime", 

345 SECTION_smac2, 

346 bool, 

347 None, 

348 ("countSMACTimeAsTunerTime",), 

349 "Whether to count and deducted SMAC2 CPU time from the CPU time budget.", 

350 ) 

351 OPTION_smac2_cli_cores = Option( 

352 "cli_cores", 

353 SECTION_smac2, 

354 int, 

355 None, 

356 tuple(), 

357 "Number of cores to use to execute SMAC2 runs.", 

358 ) 

359 OPTION_smac2_max_iterations = Option( 

360 "max_iterations", 

361 SECTION_smac2, 

362 int, 

363 None, 

364 ( 

365 "iteration_limit", 

366 "numIterations", 

367 "numberOfIterations", 

368 ), 

369 "The maximum number of iterations SMAC2 configurator can do in a single job.", 

370 ) 

371 

372 # SMAC3 Options 

373 SECTION_smac3 = "smac3" 

374 OPTION_smac3_number_of_trials = Option( 

375 "n_trials", 

376 SECTION_smac3, 

377 int, 

378 None, 

379 ("n_trials", "number_of_trials", "solver_calls"), 

380 "Maximum calls SMAC3 is allowed to make to the Solver in a single run/job.", 

381 ) 

382 OPTION_smac3_facade = Option( 

383 "facade", 

384 SECTION_smac3, 

385 str, 

386 "AlgorithmConfigurationFacade", 

387 ("facade", "smac_facade", "smac3_facade"), 

388 "The SMAC3 Facade to use. See the SMAC3 documentation for more options.", 

389 ) 

390 OPTION_smac3_facade_max_ratio = Option( 

391 "facade_max_ratio", 

392 SECTION_smac3, 

393 float, 

394 None, 

395 ("facade_max_ratio", "smac3_facade_max_ratio", "smac3_facade_max_ratio"), 

396 "The SMAC3 Facade max ratio. See the SMAC3 documentation for more options.", 

397 ) 

398 OPTION_smac3_crash_cost = Option( 

399 "crash_cost", 

400 SECTION_smac3, 

401 float, 

402 None, 

403 tuple(), 

404 "Defines the cost for a failed trial, defaults in SMAC3 to np.inf.", 

405 ) 

406 OPTION_smac3_termination_cost_threshold = Option( 

407 "termination_cost_threshold", 

408 SECTION_smac3, 

409 float, 

410 None, 

411 tuple(), 

412 "Defines a cost threshold when the SMAC3 optimization should stop.", 

413 ) 

414 OPTION_smac3_wallclock_time_budget = Option( 

415 "walltime_limit", 

416 SECTION_smac3, 

417 float, 

418 None, 

419 ("wallclock_time", "wallclock_budget", "wallclock_time_budget"), 

420 "The maximum time in seconds that SMAC3 is allowed to run per job.", 

421 ) 

422 OPTION_smac3_cpu_time_budget = Option( 

423 "cputime_limit", 

424 SECTION_smac3, 

425 float, 

426 None, 

427 ("cpu_time", "cpu_budget", "cpu_time_budget"), 

428 "The maximum CPU time in seconds that SMAC3 is allowed to run per job.", 

429 ) 

430 OPTION_smac3_use_default_config = Option( 

431 "use_default_config", 

432 SECTION_smac3, 

433 bool, 

434 None, 

435 tuple(), 

436 "If True, the configspace's default configuration is evaluated in the initial " 

437 "design. For historic benchmark reasons, this is False by default. Notice, that " 

438 "this will result in n_configs + 1 for the initial design. Respecting n_trials, " 

439 "this will result in one fewer evaluated configuration in the optimization.", 

440 ) 

441 OPTION_smac3_min_budget = Option( 

442 "min_budget", 

443 SECTION_smac3, 

444 float, 

445 None, 

446 ("minimum_budget",), 

447 "The minimum budget (epochs, subset size, number of instances, ...) that is used" 

448 " for the optimization. Use this argument if you use multi-fidelity or instance " 

449 "optimization.", 

450 ) 

451 OPTION_smac3_max_budget = Option( 

452 "max_budget", 

453 SECTION_smac3, 

454 float, 

455 None, 

456 ("maximum_budget",), 

457 "The maximum budget (epochs, subset size, number of instances, ...) that is used" 

458 " for the optimization. Use this argument if you use multi-fidelity or instance " 

459 "optimization.", 

460 ) 

461 

462 # IRACE Options 

463 SECTION_irace = "irace" 

464 OPTION_irace_max_time = Option( 

465 "max_time", 

466 SECTION_irace, 

467 int, 

468 0, 

469 ("maximum_time",), 

470 "The maximum time in seconds for each IRACE run/job.", 

471 ) 

472 OPTION_irace_max_experiments = Option( 

473 "max_experiments", 

474 SECTION_irace, 

475 int, 

476 0, 

477 ("maximum_experiments",), 

478 "The maximum number of experiments for each IRACE run/job.", 

479 ) 

480 OPTION_irace_first_test = Option( 

481 "first_test", 

482 SECTION_irace, 

483 int, 

484 None, 

485 tuple(), 

486 "Specifies how many instances are evaluated before the first elimination test. " 

487 "IRACE Default: 5.", 

488 ) 

489 OPTION_irace_mu = Option( 

490 "mu", 

491 SECTION_irace, 

492 int, 

493 None, 

494 tuple(), 

495 "Parameter used to define the number of configurations sampled and evaluated at " 

496 "each iteration. IRACE Default: 5.", 

497 ) 

498 OPTION_irace_max_iterations = Option( 

499 "max_iterations", 

500 SECTION_irace, 

501 int, 

502 None, 

503 ("nb_iterations", "iterations", "max_iterations"), 

504 "Maximum number of iterations to be executed. Each iteration involves the " 

505 "generation of new configurations and the use of racing to select the best " 

506 "configurations. By default (with 0), irace calculates a minimum number of " 

507 "iterations as N^iter = ⌊2 + log2 N param⌋, where N^param is the number of " 

508 "non-fixed parameters to be tuned. Setting this parameter may make irace stop " 

509 "sooner than it should without using all the available budget. IRACE recommends" 

510 " to use the default value (Empty).", 

511 ) 

512 

513 # ParamILS Options 

514 SECTION_paramils = "paramils" 

515 OPTION_paramils_min_runs = Option( 

516 "min_runs", 

517 SECTION_paramils, 

518 int, 

519 None, 

520 ("minimum_runs",), 

521 "Set the minimum number of runs for ParamILS for each run/job.", 

522 ) 

523 OPTION_paramils_max_runs = Option( 

524 "max_runs", 

525 SECTION_paramils, 

526 int, 

527 None, 

528 ("maximum_runs",), 

529 "Set the maximum number of runs for ParamILS for each run/job.", 

530 ) 

531 OPTION_paramils_cpu_time_budget = Option( 

532 "cputime_budget", 

533 SECTION_paramils, 

534 int, 

535 None, 

536 ( 

537 "cputime_limit", 

538 "cputime_limit", 

539 "tunertime_limit", 

540 "tuner_timeout", 

541 "tunerTimeout", 

542 ), 

543 "The maximum CPU time for each ParamILS run/job.", 

544 ) 

545 OPTION_paramils_random_restart = Option( 

546 "random_restart", 

547 SECTION_paramils, 

548 float, 

549 None, 

550 tuple(), 

551 "Set the random restart chance for ParamILS.", 

552 ) 

553 OPTION_paramils_focused = Option( 

554 "focused_approach", 

555 SECTION_paramils, 

556 bool, 

557 False, 

558 ("focused",), 

559 "Set the focused approach for ParamILS.", 

560 ) 

561 OPTION_paramils_count_tuner_time = Option( 

562 "use_cpu_time_in_tunertime", 

563 SECTION_paramils, 

564 bool, 

565 None, 

566 tuple(), 

567 "Whether to count and deducted ParamILS CPU time from the CPU time budget.", 

568 ) 

569 OPTION_paramils_cli_cores = Option( 

570 "cli_cores", 

571 SECTION_paramils, 

572 int, 

573 None, 

574 tuple(), 

575 "Number of cores to use for ParamILS runs.", 

576 ) 

577 OPTION_paramils_max_iterations = Option( 

578 "max_iterations", 

579 SECTION_paramils, 

580 int, 

581 None, 

582 ( 

583 "iteration_limit", 

584 "numIterations", 

585 "numberOfIterations", 

586 "maximum_iterations", 

587 ), 

588 "The maximum number of ParamILS iterations per run/job.", 

589 ) 

590 OPTION_paramils_number_initial_configurations = Option( 

591 "initial_configurations", 

592 SECTION_paramils, 

593 int, 

594 None, 

595 "The number of initial configurations ParamILS should evaluate.", 

596 ) 

597 

598 SECTION_parallel_portfolio = "parallel_portfolio" 

599 OPTION_parallel_portfolio_check_interval = Option( 

600 "check_interval", 

601 SECTION_parallel_portfolio, 

602 int, 

603 None, 

604 tuple(), 

605 "The interval time in seconds when Solvers are checked for their status.", 

606 ) 

607 OPTION_parallel_portfolio_number_of_seeds_per_solver = Option( 

608 "num_seeds_per_solver", 

609 SECTION_parallel_portfolio, 

610 int, 

611 None, 

612 ("solver_seeds",), 

613 "The number of seeds per solver.", 

614 ) 

615 

616 SECTION_slurm = "slurm" 

617 OPTION_slurm_parallel_jobs = Option( 

618 "number_of_jobs_in_parallel", 

619 SECTION_slurm, 

620 int, 

621 None, 

622 ("num_job_in_parallel",), 

623 "The number of jobs to run in parallel.", 

624 ) 

625 OPTION_slurm_prepend_script = Option( 

626 "prepend_script", 

627 SECTION_slurm, 

628 str, 

629 None, 

630 ("job_prepend", "prepend"), 

631 "Slurm script to prepend to the sbatch.", 

632 ) 

633 

634 sections_options: dict[str, list[Option]] = { 

635 SECTION_general: [ 

636 OPTION_objectives, 

637 OPTION_configurator, 

638 OPTION_solver_cutoff_time, 

639 OPTION_extractor_cutoff_time, 

640 OPTION_run_on, 

641 OPTION_appendices, 

642 OPTION_verbosity, 

643 OPTION_seed, 

644 ], 

645 SECTION_configuration: [ 

646 OPTION_configurator_number_of_runs, 

647 OPTION_configurator_solver_call_budget, 

648 OPTION_configurator_max_iterations, 

649 ], 

650 SECTION_ablation: [ 

651 OPTION_ablation_racing, 

652 OPTION_ablation_clis_per_node, 

653 ], 

654 SECTION_selection: [ 

655 OPTION_selection_class, 

656 OPTION_selection_model, 

657 OPTION_minimum_marginal_contribution, 

658 ], 

659 SECTION_smac2: [ 

660 OPTION_smac2_wallclock_time_budget, 

661 OPTION_smac2_cpu_time_budget, 

662 OPTION_smac2_target_cutoff_length, 

663 OPTION_smac2_count_tuner_time, 

664 OPTION_smac2_cli_cores, 

665 OPTION_smac2_max_iterations, 

666 ], 

667 SECTION_smac3: [ 

668 OPTION_smac3_number_of_trials, 

669 OPTION_smac3_facade, 

670 OPTION_smac3_facade_max_ratio, 

671 OPTION_smac3_crash_cost, 

672 OPTION_smac3_termination_cost_threshold, 

673 OPTION_smac3_wallclock_time_budget, 

674 OPTION_smac3_cpu_time_budget, 

675 OPTION_smac3_use_default_config, 

676 OPTION_smac3_min_budget, 

677 OPTION_smac3_max_budget, 

678 ], 

679 SECTION_irace: [ 

680 OPTION_irace_max_time, 

681 OPTION_irace_max_experiments, 

682 OPTION_irace_first_test, 

683 OPTION_irace_mu, 

684 OPTION_irace_max_iterations, 

685 ], 

686 SECTION_paramils: [ 

687 OPTION_paramils_min_runs, 

688 OPTION_paramils_max_runs, 

689 OPTION_paramils_cpu_time_budget, 

690 OPTION_paramils_random_restart, 

691 OPTION_paramils_focused, 

692 OPTION_paramils_count_tuner_time, 

693 OPTION_paramils_cli_cores, 

694 OPTION_paramils_max_iterations, 

695 OPTION_paramils_number_initial_configurations, 

696 ], 

697 SECTION_parallel_portfolio: [ 

698 OPTION_parallel_portfolio_check_interval, 

699 OPTION_parallel_portfolio_number_of_seeds_per_solver, 

700 ], 

701 SECTION_slurm: [OPTION_slurm_parallel_jobs, OPTION_slurm_prepend_script], 

702 } 

703 

704 def __init__( 

705 self: Settings, file_path: Path, argsv: argparse.Namespace = None 

706 ) -> None: 

707 """Initialise a settings object. 

708 

709 Args: 

710 file_path (Path): Path to the settings file. 

711 argsv: The CLI arguments to process. 

712 """ 

713 # Settings 'dictionary' in configparser format 

714 self.__settings = configparser.ConfigParser() 

715 for section in self.sections_options.keys(): 

716 self.__settings.add_section(section) 

717 self.__settings[section] = {} 

718 

719 # General attributes 

720 self.__sparkle_objectives: list[SparkleObjective] = None 

721 self.__general_sparkle_configurator: Configurator = None 

722 self.__solver_cutoff_time: int = None 

723 self.__extractor_cutoff_time: int = None 

724 self.__run_on: Runner = None 

725 self.__appendices: bool = False 

726 self.__verbosity_level: VerbosityLevel = None 

727 self.__seed: Optional[int] = None 

728 

729 # Configuration attributes 

730 self.__configurator_solver_call_budget: int = None 

731 self.__configurator_number_of_runs: int = None 

732 self.__configurator_max_iterations: int = None 

733 

734 # Ablation attributes 

735 self.__ablation_racing_flag: bool = None 

736 self.__ablation_max_parallel_runs_per_node: int = None 

737 

738 # Selection attributes 

739 self.__selection_model: str = None 

740 self.__selection_class: str = None 

741 self.__minimum_marginal_contribution: float = None 

742 

743 # SMAC2 attributes 

744 self.__smac2_wallclock_time_budget: int = None 

745 self.__smac2_cpu_time_budget: int = None 

746 self.__smac2_target_cutoff_length: str = None 

747 self.__smac2_use_tunertime_in_cpu_time_budget: bool = None 

748 self.__smac2_cli_cores: int = None 

749 self.__smac2_max_iterations: int = None 

750 

751 # SMAC3 attributes 

752 self.__smac3_number_of_trials: int = None 

753 self.__smac3_facade: str = None 

754 self.__smac3_facade_max_ratio: float = None 

755 self.__smac3_crash_cost: float = None 

756 self.__smac3_termination_cost_threshold: float = None 

757 self.__smac3_wallclock_time_limit: int = None 

758 self.__smac3_cputime_limit: int = None 

759 self.__smac3_use_default_config: bool = None 

760 self.__smac3_min_budget: float = None 

761 self.__smac3_max_budget: float = None 

762 

763 # IRACE attributes 

764 self.__irace_max_time: int = None 

765 self.__irace_max_experiments: int = None 

766 self.__irace_first_test: int = None 

767 self.__irace_mu: int = None 

768 self.__irace_max_iterations: int = None 

769 

770 # ParamILS attributes 

771 self.__paramils_cpu_time_budget: int = None 

772 self.__paramils_min_runs: int = None 

773 self.__paramils_max_runs: int = None 

774 self.__paramils_random_restart: float = None 

775 self.__paramils_focused_approach: bool = None 

776 self.__paramils_use_cpu_time_in_tunertime: bool = None 

777 self.__paramils_cli_cores: int = None 

778 self.__paramils_max_iterations: int = None 

779 self.__paramils_number_initial_configurations: int = None 

780 

781 # Parallel portfolio attributes 

782 self.__parallel_portfolio_check_interval: int = None 

783 self.__parallel_portfolio_num_seeds_per_solver: int = None 

784 

785 # Slurm attributes 

786 self.__slurm_jobs_in_parallel: int = None 

787 self.__slurm_job_prepend: str = None 

788 

789 # The seed that has been used to set the random state 

790 self.random_state: Optional[int] = None 

791 

792 if file_path and file_path.exists(): 

793 self.read_settings_ini(file_path) 

794 

795 if argsv: 

796 self.apply_arguments(argsv) 

797 

798 def read_settings_ini(self: Settings, file_path: Path) -> None: 

799 """Read the settings from an INI file.""" 

800 if not file_path.exists(): 

801 raise ValueError(f"Settings file {file_path} does not exist.") 

802 # Read file 

803 file_settings = configparser.ConfigParser() 

804 file_settings.read(file_path) 

805 

806 # Set internal settings based on data read from FILE if they were read 

807 # successfully 

808 if file_settings.sections() == []: 

809 # Print error if unable to read the settings 

810 print( 

811 f"ERROR: Failed to read settings from {file_path} The file may " 

812 "have been empty or be in another format than INI." 

813 ) 

814 return 

815 

816 for section in file_settings.sections(): 

817 if section not in self.__settings.sections(): 

818 print(f'Unrecognised section: "{section}" in file {file_path} ignored') 

819 continue 

820 for option_name in file_settings.options(section): 

821 if option_name not in self.sections_options[section]: 

822 if section == Settings.SECTION_slurm: # Flexible section 

823 self.__settings.set( 

824 section, 

825 option_name, 

826 file_settings.get(section, option_name), 

827 ) 

828 else: 

829 print( 

830 f'Unrecognised section - option combination: "{section} ' 

831 f'{option_name}" in file {file_path} ignored' 

832 ) 

833 continue 

834 option_index = self.sections_options[section].index(option_name) 

835 option = self.sections_options[section][option_index] 

836 self.__settings.set( 

837 section, option.name, file_settings.get(section, option_name) 

838 ) 

839 del file_settings 

840 

841 def write_settings_ini(self: Settings, file_path: Path) -> None: 

842 """Write the settings to an INI file.""" 

843 # Create needed directories if they don't exist 

844 file_path.parent.mkdir(parents=True, exist_ok=True) 

845 # We don't write empty sections 

846 for s in self.__settings.sections(): 

847 if not self.__settings[s]: 

848 self.__settings.remove_section(s) 

849 with file_path.open("w") as fout: 

850 self.__settings.write(fout) 

851 for s in self.sections_options.keys(): 

852 if s not in self.__settings.sections(): 

853 self.__settings.add_section(s) 

854 

855 def write_used_settings(self: Settings) -> None: 

856 """Write the used settings to the default locations.""" 

857 # Write to latest settings file 

858 self.write_settings_ini(self.DEFAULT_previous_settings_path) 

859 

860 def apply_arguments(self: Settings, argsv: argparse.Namespace) -> None: 

861 """Apply the arguments to the settings.""" 

862 # Read a possible second file, that overwrites the first, where applicable 

863 # e.g. settings are not deleted, but overwritten where applicable 

864 if hasattr(argsv, "settings_file") and argsv.settings_file: 

865 self.read_settings_ini(argsv.settings_file) 

866 # Match all possible arguments to the settings 

867 for argument in argsv.__dict__.keys(): 

868 value = argsv.__dict__[argument] 

869 if value is None: 

870 continue # Skip None 

871 if isinstance(value, Enum): 

872 value = value.name 

873 elif isinstance(value, list): 

874 value = ",".join([str(s) for s in value]) 

875 else: 

876 value = str(value) 

877 for section in self.sections_options.keys(): 

878 if argument in self.sections_options[section]: 

879 index = self.sections_options[section].index(argument) 

880 option = self.sections_options[section][index] 

881 self.__settings.set(option.section, option.name, value) 

882 break 

883 

884 def _abstract_getter(self: Settings, option: Option) -> Any: 

885 """Abstract getter method.""" 

886 if self.__settings.has_option(option.section, option.name): 

887 if option.type is bool: 

888 return self.__settings.getboolean(option.section, option.name) 

889 value = self.__settings.get(option.section, option.name) 

890 if not isinstance(value, option.type): 

891 if issubclass(option.type, Enum): 

892 return option.type[value.upper()] 

893 return option.type(value) # Attempt to resolve str to type 

894 return value 

895 return option.default_value 

896 

897 # General settings ### 

898 @property 

899 def objectives(self: Settings) -> list[SparkleObjective]: 

900 """Get the objectives for Sparkle.""" 

901 if self.__sparkle_objectives is None and self.__settings.has_option( 

902 Settings.SECTION_general, "objectives" 

903 ): 

904 objectives = self.__settings[Settings.SECTION_general]["objectives"] 

905 if "status:metric" not in objectives: 

906 objectives += ",status:metric" 

907 if "cpu_time:metric" not in objectives: 

908 objectives += ",cpu_time:metric" 

909 if "wall_time:metric" not in objectives: 

910 objectives += ",wall_time:metric" 

911 if "memory:metric" not in objectives: 

912 objectives += ",memory:metric" 

913 self.__sparkle_objectives = [ 

914 resolve_objective(obj) for obj in objectives.split(",") 

915 ] 

916 return self.__sparkle_objectives 

917 

918 @property 

919 def configurator(self: Settings) -> Configurator: 

920 """Get the configurator class (instance).""" 

921 if self.__general_sparkle_configurator is None and self.__settings.has_option( 

922 Settings.OPTION_configurator.section, Settings.OPTION_configurator.name 

923 ): 

924 # NOTE: Import here for speed up if not using configurator 

925 from sparkle.configurator.implementations import resolve_configurator 

926 

927 self.__general_sparkle_configurator = resolve_configurator( 

928 self.__settings.get( 

929 Settings.OPTION_configurator.section, 

930 Settings.OPTION_configurator.name, 

931 ) 

932 )() 

933 return self.__general_sparkle_configurator 

934 

935 @property 

936 def solver_cutoff_time(self: Settings) -> int: 

937 """Solver cutoff time in seconds.""" 

938 if self.__solver_cutoff_time is None: 

939 self.__solver_cutoff_time = self._abstract_getter( 

940 Settings.OPTION_solver_cutoff_time 

941 ) 

942 return self.__solver_cutoff_time 

943 

944 @property 

945 def extractor_cutoff_time(self: Settings) -> int: 

946 """Extractor cutoff time in seconds.""" 

947 if self.__extractor_cutoff_time is None: 

948 self.__extractor_cutoff_time = self._abstract_getter( 

949 Settings.OPTION_extractor_cutoff_time 

950 ) 

951 return self.__extractor_cutoff_time 

952 

953 @property 

954 def run_on(self: Settings) -> Runner: