Time-to-Solution (TTS) Statistics

Header: fiction/technology/sidb/simulation/analysis/time_to_solution.hpp

struct time_to_solution_params

Parameters for measuring heuristic accuracy and time-to-solution.

Public Members

sidb::simulation::exact_engine engine = exact_engine::QUICKEXACT

Exhaustive simulation algorithm used to simulate the ground state as reference.

uint64_t repetitions = 100

Number of iterations of the heuristic algorithm used to determine the simulation accuracy (repetitions = 100 means that accuracy is precise to 1 %).

double confidence_level = 0.997

The confidence level represents the probability that the confidence interval calculated from the simulation contains the true value. For example, a 99.7 % (0.997) confidence level means that if the simulation were repeated many times, approximately 997 out of 1000 of the calculated confidence intervals would contain the true value.

utils::progress_callback on_progress = {}

Callback that receives the number of completed heuristic repetitions.

uint64_t timeout = {std::numeric_limits<uint64_t>::max()}

Millisecond budget for the reference simulation and all heuristic repetitions together. The maximum value means unlimited; zero expires immediately. Expiration throws utils::timeout_error without publishing statistics. Finite budgets reject ClusterComplete; QuickSim’s separate timeout still applies to each heuristic attempt.

std::chrono::steady_clock::time_point deadline = {std::chrono::steady_clock::time_point::max()}

Shared caller deadline. time_point::max() leaves the enclosing budget unlimited.

struct time_to_solution_stats

This struct stores the time-to-solution, the simulation accuracy and the average single simulation runtime of QuickSim, the single runtime of the exact simulator used, and the number of valid charge configurations found by the exact algorithm.

Public Functions

inline void report(std::ostream &out = std::cout) const

Print the results to the given output stream.

Parameters:

out – Output stream.

Public Members

double time_to_solution = {0}

Time-to-solution in seconds.

double acc = {}

Accuracy of the simulation in %.

double mean_single_runtime = {}

Average runtime of all heuristic attempts in seconds, including failed attempts.

double single_runtime_exact = {}

Single simulation runtime of the exact ground state simulation algorithm.

std::string algorithm

Exact simulation algorithm used to simulate the ground state as reference.

inline void fiction::sidb::simulation::analysis::time_to_solution(const layout &lyt, const engines::quicksim_params &qs_params, const time_to_solution_params &tts_params = {}, time_to_solution_stats *ps = nullptr)

Computes the time-to-solution (TTS) of QuickSim for a layout: the layout is simulated once with the exact engine of the parameters and tts_params.repetitions times with QuickSim, and the runs are combined with time_to_solution_for_given_simulation_results.

Failed attempts contribute elapsed wall time; successful attempts retain the engine runtime.

Parameters:

  • lyt – The layout to simulate.

  • qs_params – QuickSim parameters.

  • tts_params – TTS parameters.

  • ps – Statistics.

inline void fiction::sidb::simulation::analysis::time_to_solution_for_given_simulation_results(const result &results_exact, const std::vector<result> &results_heuristic, const double confidence_level = 0.997, time_to_solution_stats *ps = nullptr) noexcept

Computes the time-to-solution (TTS) of QuickSim from an exact result and a series of heuristic results: the accuracy is the share of heuristic runs that found the ground state, and TTS is the mean heuristic runtime scaled to reach the given confidence level, t · log(1 - c) / log(1 - acc). An empty sample yields zero accuracy, zero mean heuristic runtime, and infinite time-to-solution.

Parameters:

  • results_exact – The result of an exact engine, which provides the ground state.

  • results_heuristic – The results of the heuristic runs.

  • confidence_level – Confidence level for the TTS computation.

  • ps – Statistics.

class time_to_solution_stats

This struct stores the time-to-solution, the simulation accuracy and the average single simulation runtime of QuickSim, the single runtime of the exact simulator used, and the number of valid charge configurations found by the exact algorithm.

property acc

Accuracy of the simulation in %.

property algorithm

Exact simulation algorithm used to simulate the ground state as reference.

property mean_single_runtime

Average runtime of all heuristic attempts in seconds, including failed attempts.

property single_runtime_exact

Single simulation runtime of the exact ground state simulation algorithm.

property time_to_solution

Time-to-solution in seconds.

time_to_solution(lyt: sidb_layout, *, base: int = 3, mu_minus: float = -0.32, epsilon_r: float = 5.6, lambda_tf: float = 5.0, iteration_steps: int = 80, alpha: float = 0.7, number_threads: int | None = None, quicksim_timeout: int = 18446744073709551615, quicksim_on_progress: Callable[[str, int, int], None] | None = None, on_worker_progress: Callable[[int, int, str, int, int, bool], None] | None = None, timeout: int = 18446744073709551615, engine: exact_sidb_simulation_engine = exact_sidb_simulation_engine.QUICKEXACT, repetitions: int = 100, confidence_level: float = 0.997, on_progress: Callable[[str, int, int], None] | None = None, ps: time_to_solution_stats | None = None) → None

Compute QuickSim time-to-solution from one exact run and repetitions heuristic runs. quicksim_timeout bounds each heuristic run; timeout bounds the complete evaluation. Failed attempts contribute elapsed wall time, while successful attempts retain the engine runtime. ps receives completed statistics; expiration of the complete evaluation raises TimeoutError. Raises ValueError for confidence outside (0, 1) or ClusterComplete with a finite timeout.

Parameters:

  • base – Number of charge states: 2 for negative and neutral, or 3 to include positive charges.

  • mu_minus – Negative-charge transition energy in eV.

  • epsilon_r – Relative permittivity (dimensionless).

  • lambda_tf – Thomas-Fermi screening distance in nm.

  • number_threads – Number of QuickSim workers; None uses the available hardware threads.

  • quicksim_timeout – Execution budget for each heuristic run in milliseconds.

  • quicksim_on_progress – Progress callback for heuristic iterations; None disables these reports.

  • on_worker_progress – Callback receiving (worker, count, description, completed, total, active); None disables worker reports.

  • timeout – Execution budget in milliseconds.

  • engine – Exhaustive simulation algorithm used to simulate the ground state as reference.

  • repetitions – Number of iterations of the heuristic algorithm used to determine the simulation accuracy (repetitions = 100 means that accuracy is precise to 1 %).

  • confidence_level – Probability of finding the ground state used to compute time-to-solution, between 0 and 1.

  • on_progress – Callback receiving (task, completed, total); None disables progress reporting.

  • ps – Statistics object filled by the algorithm; None discards statistics.

  • iteration_steps – Number of QuickSim iterations.

  • alpha – QuickSim heuristic alpha parameter.

time_to_solution_for_given_simulation_results(results_exact: sidb_simulation_result, results_heuristic: Sequence[sidb_simulation_result], *, confidence_level: float = 0.997, ps: time_to_solution_stats | None = None) → None

Evaluate heuristic time-to-solution against an exact simulation result. confidence_level must be strictly between 0 and 1; invalid values raise ValueError. ps receives accuracy, runtimes, and time-to-solution statistics. Empty heuristic results yield zero accuracy and infinite time-to-solution.