Simulation Analysis¶

Energy Calculation¶

C++

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

struct energy_state¶

This struct stores the energy state of an SiDB layout. The energy state consists of the electrostatic potential energy and the degeneracy of the state.

Public Functions

inline energy_state(const double energy, const uint64_t state_degeneracy)¶

Default constructor.

Parameters:

energy – The electrostatic potential energy of the charge distribution (eV).
state_degeneracy – The degeneracy of the state.

Public Members

double electrostatic_potential_energy¶: The electrostatic potential energy of the charge distribution (eV).

uint64_t degeneracy¶: The degeneracy of the state.

class energy_distribution¶

This class is used to store the energy distribution of an SiDB layout. The energy distribution is a map that contains the electrostatic potential as a key and its degeneracy as a value. To be more precise, if two different charge distributions occur with the same energy, the degeneracy value of the energy state is 2.

Public Functions

energy_distribution() = default¶: Default constructor.

inline std::optional<energy_state> get_nth_state(const uint64_t state_index) const noexcept¶

Returns the nth state (energy + degeneracy) in the energy distribution.

Parameters:: state_index – The index of the state to be retrieved.
Returns:: Energy state. If the index is out of range, std::nullopt is returned instead.

inline std::optional<uint64_t> degeneracy(const double energy) const noexcept¶

Returns the degeneracy value (number of states) with the given energy value.

Parameters:: energy – The energy value for which the excited state number is to be determined.
Returns:: The degeneracy of the given energy. If the energy value is not found, std::nullopt is returned instead.

inline void add_energy_state(const energy_state &state) noexcept¶

Adds a state to the energy distribution.

Parameters:: state – The energy state to be added.

inline std::size_t size() const noexcept¶

Returns the number of energy states in the energy distribution.

Returns:: The number of energy states in the energy distribution.

inline bool empty() const noexcept¶

Checks if the energy distribution is empty.

Returns:: true if the energy distribution is empty, false otherwise.

inline double max_energy() const noexcept¶

Returns the maximum energy value in the energy distribution.

Returns:: The maximum energy value in the energy distribution.

inline double min_energy() const noexcept¶

Returns the minimum energy value in the energy distribution.

Returns:: The minimum energy value in the energy distribution.

template<typename Fn> inline void for_each(Fn &&fn) const¶

Applies a function to all states in the energy distribution.

Template Parameters:: Fn – Functor type.
Parameters:: fn – Functor to apply to each key-value pair.

inline energy_distribution fiction::sidb::simulation::analysis::calculate_energy_distribution(const std::vector<charge_distribution> &charge_distributions)¶

The energy distribution of a set of charge distributions: every distinct energy with the number of distinct charge distributions that have it. Distributions with identical charge states count once.

Parameters:: charge_distributions – Charge distributions of one layout.
Returns:: The energy distribution.

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

template<typename InputIt> double fiction::sidb::simulation::analysis::minimum_energy(const InputIt first, const InputIt last) noexcept¶

Computes the minimum energy of a range of charge distributions. If the range is empty, infinity is returned to indicate no valid energy value exists.

Template Parameters:

InputIt – Must meet the requirements of LegacyInputIterator.

Parameters:

first – Begin of the range to examine.
last – End of the range to examine.

Returns:

Value of the minimum energy found in the input range (unit: eV), or std::numeric_limits<double>::infinity() if the range is empty.

template<typename InputIt> InputIt fiction::sidb::simulation::analysis::minimum_energy_distribution(const InputIt first, const InputIt last) noexcept¶

Returns an iterator to the charge distribution of minimum energy contained in a range. If the range is empty, last is returned.

Template Parameters:

InputIt – Must meet the requirements of LegacyInputIterator.

Parameters:

first – Begin of the range to examine.
last – End of the range to examine.

Returns:

Iterator to the minimum energy charge distribution found in the input range, or last if the range is empty.

Python

class energy_state(electrostatic_potential_energy: float, degeneracy: int)¶

property degeneracy¶: The degeneracy of the state.

property electrostatic_potential_energy¶: The electrostatic potential energy of the charge distribution (eV).

class energy_distribution¶

add_energy_state(state: energy_state) → None¶

Adds a state to the energy distribution.

Parameters:: state – The energy state to be added.

degeneracy(energy: float) → int | None¶

Returns the degeneracy value (number of states) with the given energy value.

Parameters:: energy – The energy value for which the excited state number is to be determined.
Returns:: The degeneracy of the given energy. If the energy value is not found, std::nullopt is returned instead.

empty() → bool¶

Checks if the energy distribution is empty.

Returns:: true if the energy distribution is empty, false otherwise.

get_nth_state(state_index: int) → energy_state | None¶

Returns the nth state (energy + degeneracy) in the energy distribution.

Parameters:: state_index – The index of the state to be retrieved.
Returns:: Energy state. If the index is out of range, std::nullopt is returned instead.

max_energy() → float¶

Returns the maximum energy value in the energy distribution.

Returns:: The maximum energy value in the energy distribution.

min_energy() → float¶

Returns the minimum energy value in the energy distribution.

Returns:: The minimum energy value in the energy distribution.

size() → int¶

Returns the number of energy states in the energy distribution.

Returns:: The number of energy states in the energy distribution.

calculate_energy_distribution(charge_distributions: Sequence[charge_distribution]) → energy_distribution¶

The energy distribution of a set of charge distributions: every distinct energy with the number of distinct charge distributions that have it. Distributions with identical charge states count once.

Parameters:: charge_distributions – Charge distributions of one layout.
Returns:: The energy distribution.

minimum_energy(charge_distributions: Sequence[charge_distribution]) → float¶

Computes the minimum energy of a range of charge distributions. If the range is empty, infinity is returned to indicate no valid energy value exists.

Parameters:

first – Begin of the range to examine.
last – End of the range to examine.

Template Args:

InputIt – Must meet the requirements of LegacyInputIterator.

Returns:

eV), or std::numeric_limits<double>::infinity() if the range is empty.

Return type:

Value of the minimum energy found in the input range (unit

Temperature Behavior¶

C++

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

struct critical_temperature_params¶

This struct stores the parameters for the Critical Temperature algorithm.

Public Members

sidb::simulation::logic::is_operational_params operational_params = {}¶: Operational parameters. Their timeout bounds the entire temperature calculation, including every input pattern and temperature step. Finite budgets reject ClusterComplete and throw utils::timeout_error on expiration.

double confidence_level = {0.99}¶: Probability threshold for ground state population. The temperature at which the simulation finds the ground state to be populated with a probability of less than the given percentage, is determined to be the critical temperature. For gate-based simulation, this is the probability of erroneous calculations of the gate.

double max_temperature = {400}¶: Maximum simulation temperature beyond which no simulation will be conducted (~ 126 °C by default) (unit: K).

uint64_t iteration_steps = {80}¶: Number of iteration steps for the QuickSim algorithm (only applicable if engine == QUICKSIM).

double alpha = {0.7}¶: Alpha parameter for the QuickSim algorithm (only applicable if engine == QUICKSIM).

utils::progress_callback on_progress = {}¶: Callback that receives the number of simulated input patterns (gate-based) or the progress of the physical simulation (non-gate-based).

utils::worker_progress_callback on_worker_progress = {}¶: Reports logical worker activity with a fixed worker count for each invocation.

inline double fiction::sidb::simulation::analysis::critical_temperature_gate_based(const layout &lyt, const std::vector<kitty::dynamic_truth_table> &spec, const critical_temperature_params &params = {}, critical_temperature_stats *pst = nullptr)¶

This algorithm performs temperature-aware SiDB simulation as proposed in “Temperature Behavior of Silicon Dangling Bond Logic” by J. Drewniok, M. Walter, and R. Wille in IEEE NANO 2023 (https://ieeexplore.ieee.org/document/10231259). It comes in two flavors: gate-based and non-gate based.

For Gate-based Critical Temperature Simulation, the Critical Temperature is defined as follows: The temperature at which the erroneous charge distributions are populated by more than \(1 - \eta\), where \(\eta \in [0,1]\).

Parameters:

lyt – The layout to simulate.
spec – Expected Boolean function of the layout given as a multi-output truth table.
params – Simulation and physical parameters.
pst – Statistics.

Returns:

The critical temperature (unit: K).

inline double fiction::sidb::simulation::analysis::critical_temperature_gate_based(const std::vector<layout> &input_pattern_layouts, const std::vector<kitty::dynamic_truth_table> &spec, const critical_temperature_params &params, const std::vector<logic::bdl_pair> &output_bdl_pairs, const std::vector<logic::bdl_wire> &input_bdl_wires, const std::vector<logic::bdl_wire> &output_bdl_wires, critical_temperature_stats *pst = nullptr)¶

Gate-based Critical Temperature simulation of an SiDB layout from its pre-generated input pattern layouts.

This overload takes one layout per input pattern together with the BDL detection results, instead of deriving all of them from the layout. Since neither the input configuration nor the BDL pairs and wires depend on the simulation parameters, a caller that simulates the same layout under many parameter settings can determine them once with generate_bdl_input_pattern_layouts, detect_bdl_pairs and detect_bdl_wires and pass them to every call, instead of re-deriving them each time.

The layouts and the detection results are only read and may be shared by concurrent calls.

Parameters:

input_pattern_layouts – One layout per input pattern, indexed by input pattern, as generated by generate_bdl_input_pattern_layouts.
spec – Expected Boolean function of the layout given as a multi-output truth table.
params – Simulation and physical parameters.
output_bdl_pairs – Output BDL pairs of the layout.
input_bdl_wires – BDL input wires of the layout.
output_bdl_wires – BDL output wires of the layout.
pst – Statistics.

Throws:

std::invalid_argument – if spec is empty, if the number of input pattern layouts does not match the number of input combinations of spec, or if the number of output BDL pairs does not match the number of truth tables.

Returns:

The critical temperature (unit: K).

inline double fiction::sidb::simulation::analysis::critical_temperature_non_gate_based(const layout &lyt, const critical_temperature_params &params = {}, critical_temperature_stats *pst = nullptr)¶

For Non-gate-based Critical Temperature simulation, the Critical Temperature is defined as follows: The temperature at which the excited charge distributions are populated by more than \(1 - \eta\), where \(\eta \in [0,1]\) is the confidence level for the presence of a working gate.

Parameters:

lyt – The layout to simulate.
params – Simulation and physical parameters.
pst – Statistics.

Returns:

The critical temperature (unit: K)

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

inline double fiction::sidb::simulation::analysis::calculate_boltzmann_factor(const double energy, const double min_energy, const double temperature) noexcept¶

This function computes the Boltzmann factor for a given energy, the minimal energy, and the temperature.

Parameters:

energy – Boltzmann factor for the given energy is calculated.
min_energy – Minimum energy of the system.
temperature – Temperature of the system (unit: K).

Returns:

Boltzmann factor.

inline double fiction::sidb::simulation::analysis::occupation_probability_gate_based(const energy_and_state_type &est, const double temperature) noexcept¶

This function computes the occupation probability of erroneous charge distributions (output charge does not match the expected output according the truth table) at a given temperature.

Parameters:

est – This contains the energies of all possible charge distributions together with the information if the charge distribution (state) is transparent or erroneous.
temperature – System temperature to assume (unit: K).

Returns:

The occupation probability of all erroneous states is returned.

inline double fiction::sidb::simulation::analysis::occupation_probability_non_gate_based(const energy_distribution &energy_dist, const double temperature) noexcept¶

This function computes the occupation probability of excited states (charge distributions with energy higher than the ground state) at a given temperature.

Parameters:

energy_dist – This contains the energies in eV of all possible charge distributions with the degeneracy.
temperature – System temperature to assume (unit: K).

Returns:

The total occupation probability of all excited states is returned.

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

enum class fiction::sidb::simulation::analysis::state_type : uint8_t¶

Label to categorize ground and excited states of an SiDB layout.

Values:

enumerator ACCEPTED¶: A state is accepted if the charge distribution encodes the desired logic.

enumerator REJECTED¶: A state is rejected if the charge distribution does not encode the desired logic. Moreover, if kinks are rejected, a charge distribution that encodes the logic, but does show kinks, is rejected.

using fiction::sidb::simulation::analysis::energy_and_state_type = std::vector<std::pair<double, state_type>>¶: Electrostatic potential energies (in eV) paired with their accepted or rejected state types.

inline energy_and_state_type fiction::sidb::simulation::analysis::calculate_energy_and_state_type_with_kinks_accepted(const energy_distribution &energy_dist, const std::vector<charge_distribution> &valid_charge_distributions, const std::vector<logic::bdl_pair> &output_bdl_pairs, const std::vector<kitty::dynamic_truth_table> &spec, const uint64_t input_index)¶

Labels every energy level of an energy distribution by whether the physically valid charge distributions at that level encode the expected output for the given input pattern (ACCEPTED) or not (REJECTED). Kinks in the wires are tolerated: only the output BDL pairs are inspected.

Parameters:

energy_dist – The energy distribution of the charge distributions.
valid_charge_distributions – The physically valid charge distributions.
output_bdl_pairs – The output BDL pairs of the layout.
spec – The Boolean function(s) to implement.
input_index – The input pattern the charge distributions were simulated for.

Returns:

The energies with their state types, ascending by energy.

inline energy_and_state_type fiction::sidb::simulation::analysis::calculate_energy_and_state_type_with_kinks_rejected(const layout &lyt, const energy_distribution &energy_dist, const std::vector<charge_distribution> &valid_charge_distributions, const std::vector<kitty::dynamic_truth_table> &spec, const uint64_t input_index, const std::vector<logic::bdl_wire> &input_bdl_wires, const std::vector<logic::bdl_wire> &output_bdl_wires)¶

Like calculate_energy_and_state_type_with_kinks_accepted, but a charge distribution with kinks in its wires is REJECTED as well: every energy level is ACCEPTED, and additionally REJECTED if any of its charge distributions fails the logic match with kinks rejected.

Parameters:

lyt – The layout the charge distributions belong to.
energy_dist – The energy distribution of the charge distributions.
valid_charge_distributions – The physically valid charge distributions.
spec – The Boolean function(s) to implement.
input_index – The input pattern the charge distributions were simulated for.
input_bdl_wires – The input BDL wires of lyt.
output_bdl_wires – The output BDL wires of lyt.

Throws:

std::out_of_range – if logic validation encounters an invalid lattice basis index.

Returns:

The energies with their state types.

Python

class critical_temperature_stats¶

This struct stores the result of the temperature simulation.

property algorithm_name¶: Name of the algorithm used to compute the physically valid charge distributions.

property energy_between_ground_state_and_first_erroneous¶: Energy difference between the ground state and the first (erroneous) excited state (unit: meV).

property num_valid_lyt¶: Number of physically valid charge configurations.

class critical_temperature_params¶

This struct stores the parameters for the Critical Temperature algorithm.

property confidence_level¶: Probability threshold for ground state population. The temperature at which the simulation finds the ground state to be populated with a probability of less than the given percentage, is determined to be the critical temperature. For gate-based simulation, this is the probability of erroneous calculations of the gate.

property max_temperature¶: Maximum simulation temperature beyond which no simulation will be conducted (~ 126 °C by default) (unit: K).

property on_progress¶: Callback that receives the number of simulated input patterns (gate- based) or the progress of the physical simulation (non-gate-based).

property on_worker_progress¶: Reports logical worker activity with a fixed worker count for each invocation.

property operational_params¶: This struct stores the parameters for the Critical Temperature algorithm.

critical_temperature_gate_based(lyt: mnt.pyfiction.sidb.sidb_layout, spec: collections.abc.Sequence[mnt.pyfiction.synthesis.dynamic_truth_table], params: mnt.pyfiction.sidb.simulation.analysis.critical_temperature_params = <mnt.pyfiction.sidb.simulation.analysis.critical_temperature_params object at 0x579c36dd4bc0>, stats: mnt.pyfiction.sidb.simulation.analysis.critical_temperature_stats | None = None) → float¶

critical_temperature_gate_based(input_pattern_layouts: Sequence[sidb_layout], spec: Sequence[mnt.pyfiction.synthesis.dynamic_truth_table], params: critical_temperature_params, output_bdl_pairs: Sequence[bdl_pair], input_bdl_wires: Sequence[bdl_wire], output_bdl_wires: Sequence[bdl_wire], stats: critical_temperature_stats | None = None) → float

Overloaded function.

critical_temperature_gate_based(lyt: mnt.pyfiction.sidb.sidb_layout, spec: collections.abc.Sequence[mnt.pyfiction.synthesis.dynamic_truth_table], params: mnt.pyfiction.sidb.simulation.analysis.critical_temperature_params = <mnt.pyfiction.sidb.simulation.analysis.critical_temperature_params object at 0x579c36dd4bc0>, stats: mnt.pyfiction.sidb.simulation.analysis.critical_temperature_stats | None = None) -> float

This algorithm performs temperature-aware SiDB simulation as proposed in "Temperature Behavior of Silicon Dangling Bond Logic" by J. Drewniok, M. Walter, and R. Wille in IEEE NANO 2023 (https://ieeexplore.ieee.org/document/10231259). It comes in two flavors: gate-based and non-gate based.

Parameters:

lyt – The layout to simulate.
spec – Expected Boolean function of the layout given as a multi- output truth table.
params – Simulation and physical parameters.
pst – Statistics.

Returns:

K).

Return type:

The critical temperature (unit

critical_temperature_gate_based(input_pattern_layouts: collections.abc.Sequence[mnt.pyfiction.sidb.sidb_layout], spec: collections.abc.Sequence[mnt.pyfiction.synthesis.dynamic_truth_table], params: mnt.pyfiction.sidb.simulation.analysis.critical_temperature_params, output_bdl_pairs: collections.abc.Sequence[mnt.pyfiction.sidb.simulation.logic.bdl_pair], input_bdl_wires: collections.abc.Sequence[mnt.pyfiction.sidb.simulation.logic.bdl_wire], output_bdl_wires: collections.abc.Sequence[mnt.pyfiction.sidb.simulation.logic.bdl_wire], stats: mnt.pyfiction.sidb.simulation.analysis.critical_temperature_stats | None = None) -> float

Gate-based Critical Temperature simulation of an SiDB layout from its pre-generated input pattern layouts.

The layouts and the detection results are only read and may be shared by concurrent calls.

Parameters:

input_pattern_layouts – One layout per input pattern, indexed by input pattern, as generated by generate_bdl_input_pattern_layouts.
spec – Expected Boolean function of the layout given as a multi- output truth table.
params – Simulation and physical parameters.
output_bdl_pairs – Output BDL pairs of the layout.
input_bdl_wires – BDL input wires of the layout.
output_bdl_wires – BDL output wires of the layout.
pst – Statistics.

Returns:

K).

Return type:

The critical temperature (unit

Raises:

std::invalid_argument – if spec is empty, if the number of input pattern layouts does not match the number of input combinations of spec, or if the number of output BDL pairs does not match the number of truth tables.

critical_temperature_non_gate_based(lyt: sidb_layout, params: critical_temperature_params = <mnt.pyfiction.sidb.simulation.analysis.critical_temperature_params object at 0x579c36dd5900>, stats: critical_temperature_stats | None = None) → float¶

Parameters:

lyt – The layout to simulate.
params – Simulation and physical parameters.
pst – Statistics.

Returns:

Return type:

The critical temperature (unit

occupation_probability_gate_based(energy_and_state_type: Sequence[tuple[float, state_type]], temperature: float) → float¶

This function computes the occupation probability of erroneous charge distributions (output charge does not match the expected output according the truth table) at a given temperature.

Parameters:

est – This contains the energies of all possible charge distributions together with the information if the charge distribution (state) is transparent or erroneous.
temperature – System temperature to assume (unit: K).

Returns:

The occupation probability of all erroneous states is returned.

occupation_probability_non_gate_based(calculate_energy_distribution: energy_distribution, temperature: float) → float¶

class state_type(*values)¶

Label to categorize ground and excited states of an SiDB layout.

ACCEPTED = 0¶

REJECTED = 1¶

calculate_energy_and_state_type_with_kinks_accepted(energy_distribution: energy_distribution, valid_charge_distributions: Sequence[charge_distribution], output_bdl_pairs: Sequence[bdl_pair], spec: Sequence[mnt.pyfiction.synthesis.dynamic_truth_table], input_index: int) → list[tuple[float, state_type]]¶

Parameters:

energy_dist – The energy distribution of the charge distributions.
valid_charge_distributions – The physically valid charge distributions.
output_bdl_pairs – The output BDL pairs of the layout.
spec – The Boolean function(s) to implement.
input_index – The input pattern the charge distributions were simulated for.

Returns:

The energies with their state types, ascending by energy.

calculate_energy_and_state_type_with_kinks_rejected(lyt: sidb_layout, energy_distribution: energy_distribution, valid_charge_distributions: Sequence[charge_distribution], spec: Sequence[mnt.pyfiction.synthesis.dynamic_truth_table], input_index: int, input_bdl_wires: Sequence[bdl_wire], output_bdl_wires: Sequence[bdl_wire]) → list[tuple[float, state_type]]¶

Parameters:

lyt – The layout the charge distributions belong to.
energy_dist – The energy distribution of the charge distributions.
valid_charge_distributions – The physically valid charge distributions.
spec – The Boolean function(s) to implement.
input_index – The input pattern the charge distributions were simulated for.
input_bdl_wires – The input BDL wires of lyt.
output_bdl_wires – The output BDL wires of lyt.

Returns:

The energies with their state types.

Raises:

std::out_of_range – if logic validation encounters an invalid lattice basis index.

Time-to-Solution (TTS) Statistics¶

C++

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.

Python

class time_to_solution_params¶

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

property confidence_level¶: 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.

property engine¶: Exhaustive simulation algorithm used to simulate the ground state as reference.

property on_progress¶: Callback that receives the number of completed heuristic repetitions.

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

property timeout¶: 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.

class time_to_solution_stats¶

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, quicksim_params: quicksim_params, tts_params: time_to_solution_params = <mnt.pyfiction.sidb.simulation.analysis.time_to_solution_params object at 0x579c36de2df0>, ps: time_to_solution_stats | None = None) → None¶

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.

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¶

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.

Physically Valid Parameters¶

C++

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

inline domain<logic::parameter_point, uint64_t> fiction::sidb::simulation::analysis::physically_valid_parameters(const layout &lyt, const charge_distribution &cd, const logic::operational_domain_params &params = {})¶

Determines the physical parameters under which a given charge distribution of a layout is physically valid: every parameter point of the sweep dimensions in params is checked, and for each one where the charge distribution is valid, its excited-state number (the number of valid configurations with lower energy under those parameters) is recorded.

Parameters:

lyt – The layout.
cd – The charge distribution whose validity is checked.
params – Parameters; the sweep dimensions and the engine that determines the excited-state number.

Throws:

std::invalid_argument – if a sweep range has non-finite or reversed bounds, a non-positive or non-finite step, or more points than the storage range permits.

Returns:

The parameter points where cd is physically valid, each with its excited-state number; empty if cd does not cover the layout’s SiDBs in raster order.

Python

class physically_valid_parameters_domain¶

get_excited_state_number_for_parameter(pp: parameter_point) → int¶

class physically_valid_parameters(lyt: sidb_layout, cd: charge_distribution, params: operational_domain_params = <mnt.pyfiction.sidb.simulation.logic.operational_domain_params object at 0x579c36dde9f0>)¶

Parameters:

lyt – The layout.
cd – The charge distribution whose validity is checked.
params – Parameters; the sweep dimensions and the engine that determines the excited-state number.

Returns:

The parameter points where cd is physically valid, each with its excited-state number; empty if cd does not cover the layout’s SiDBs in raster order.

Raises:

std::invalid_argument – if a sweep range has non-finite or reversed bounds, a non-positive or non-finite step, or more points than the storage range permits.

Charge Detection¶

C++

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

inline bool fiction::sidb::simulation::analysis::can_positive_charges_occur(const potential_landscape &land)¶

Checks whether positively charged SiDBs can occur in a layout under the given physical parameters, i.e., whether the band bending of the fully negatively charged layout, which maximizes every local potential, pushes any SiDB past its positive transition threshold. If it does not in this extreme case, it does not for any other charge distribution either.

Parameters:: land – The potential landscape of the layout under the parameters to check.
Returns:: true if at least one SiDB can be positively charged, false otherwise.

inline bool fiction::sidb::simulation::analysis::can_positive_charges_occur(const layout &lyt, const model::simulation_parameters &sim_params)¶

Checks whether positively charged SiDBs can occur in a layout under the given physical parameters. See the potential_landscape overload.

Parameters:

lyt – The layout to check.
sim_params – The physical parameters.

Throws:

std::out_of_range – if a SiDB or defect site has an invalid lattice basis index.

Returns:

true if at least one SiDB can be positively charged, false otherwise.

Python

can_positive_charges_occur(lyt: sidb_layout, sim_params: sidb_simulation_parameters) → bool¶

Checks whether positively charged SiDBs can occur in a layout under the given physical parameters. See the potential_landscape overload.

Parameters:

lyt – The layout to check.
sim_params – The physical parameters.

Returns:

true if at least one SiDB can be positively charged, false otherwise.

Raises:

std::out_of_range – if a SiDB or defect site has an invalid lattice basis index.

Assess Population Stability¶

C++

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

enum class fiction::sidb::simulation::analysis::transition_type : uint8_t¶

Possible types of charge transitions that can occur in an SiDB layout. These transitions represent changes in the charge state of SiDBs, including transitions from neutral to negative, negative to neutral, neutral to positive, and positive to neutral.

Values:

enumerator NEUTRAL_TO_NEGATIVE¶: SiDB is neutrally charged, but is closest to being negatively charged.

enumerator NEGATIVE_TO_NEUTRAL¶: SiDB is negatively charged, but is closest to being neutrally charged.

enumerator NEUTRAL_TO_POSITIVE¶: SiDB is neutrally charged, but is closest to being positively charged.

enumerator POSITIVE_TO_NEUTRAL¶: SiDB is positively charged, but is closest to being neutrally charged.

struct population_stability_information¶

Population stability of one physically valid charge distribution: for every transition type, the SiDB that is closest to that transition and the potential change it would take, plus the distance an SiDB would have to be placed at to induce that potential change.

Public Members

lattice_site critical_dot = {}¶: SiDB with the minimum potential difference to any charge transition threshold.

std::unordered_map<transition_type, std::pair<lattice_site, double>> transition_potentials = {}¶: For each transition type, the SiDB closest to it and the required potential difference (unit: V).

std::unordered_map<transition_type, double> distance_corresponding_to_potential = {}¶: For each transition type, the distance (unit: nm) an additional SiDB would have to be placed at to induce the required potential difference.

double system_energy = {}¶: Electrostatic potential energy of the charge distribution (unit: eV).

struct physical_population_stability_params¶

Parameters of the population stability analysis.

Public Members

model::simulation_parameters sim_params = {}¶: Physical parameters of the simulation.

uint64_t precision_for_distance_corresponding_to_potential = 2¶: Number of decimal places of the distance corresponding to a potential difference.

uint64_t timeout = {std::numeric_limits<uint64_t>::max()}¶: Millisecond budget for simulation and population analysis. The maximum value means unlimited; zero expires immediately. Expiration throws utils::timeout_error without returning a partial result.

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.

inline std::vector<population_stability_information> fiction::sidb::simulation::analysis::physical_population_stability(const layout &lyt, const physical_population_stability_params &params)¶

Assesses the population stability of an SiDB layout: for every physically valid charge distribution (found with QuickExact), it determines the SiDB closest to each charge transition and the potential change required for it, in ascending order of the distributions’ energies. The distance an SiDB would have to be placed at to cause that potential change is reported as well.

Parameters:

lyt – The layout to analyze.
params – Parameters.

Returns:

The population stability information, one entry per distinct charge distribution.

Python

class transition_type(*values)¶

NEUTRAL_TO_NEGATIVE = 0¶

NEGATIVE_TO_NEUTRAL = 1¶

NEUTRAL_TO_POSITIVE = 2¶

POSITIVE_TO_NEUTRAL = 3¶

class population_stability_information¶

property critical_dot¶: SiDB with the minimum potential difference to any charge transition threshold.

property distance_corresponding_to_potential¶

nm) an additional SiDB would have to be placed at to induce the required potential difference.

Type:: For each transition type, the distance (unit

property system_energy¶

eV).

Type:: Electrostatic potential energy of the charge distribution (unit

property transition_potentials¶: For each transition type, the SiDB closest to it and the required potential difference (unit: V).

class physical_population_stability_params¶

Parameters of the population stability analysis.

property precision_for_distance_corresponding_to_potential¶: Number of decimal places of the distance corresponding to a potential difference.

property simulation_parameters¶: Parameters of the population stability analysis.

property timeout¶: Millisecond budget for simulation and population analysis. The maximum value means unlimited; zero expires immediately. Expiration throws utils::timeout_error without returning a partial result.

physical_population_stability(lyt: sidb_layout, params: physical_population_stability_params = <mnt.pyfiction.sidb.simulation.analysis.physical_population_stability_params object at 0x579c36dddc60>) → list[population_stability_information]¶

Parameters:

lyt – The layout to analyze.
params – Parameters.

Returns:

The population stability information, one entry per distinct charge distribution.

Band-Bending Resilience¶

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

struct band_bending_resilience_params¶

This struct stores the parameters required to simulate the band bending resilience of an SiDB layout

Public Members

physical_population_stability_params assess_population_stability_params = {}¶: Population stability parameters. Their timeout bounds the entire resilience calculation across all input patterns.

sidb::simulation::logic::bdl_input_iterator_params bdl_iterator_params = {}¶: Parameters for the input BDL iterator.

inline double fiction::sidb::simulation::analysis::band_bending_resilience(const layout &lyt, const std::vector<kitty::dynamic_truth_table> &spec, const band_bending_resilience_params &params = {}, const std::optional<transition_type> transition_type = std::nullopt)¶

Calculates the band bending resilience of an SiDB gate: the minimum potential change (unit: V) that any charge transition requires in the ground state of any input pattern. A larger value means the gate tolerates more band bending before its ground state changes.

Parameters:

lyt – The gate layout.
spec – The Boolean function(s) the gate implements; determines the number of input patterns.
params – Parameters.
transition_type – The transition to consider; all transitions if omitted.

Returns:

The minimum potential difference over all input patterns, or infinity if the input wires cannot represent the specification or no charge transition exists.