Simulation Engines¶

Heuristic Ground State Simulation¶

C++

Header: fiction/technology/sidb/simulation/engines/quicksim.hpp

struct quicksim_params¶

This struct stores the parameters for the QuickSim algorithm.

Public Members

sidb::model::simulation_parameters sim_params = {}¶: Simulation parameters for the simulation of the physical SiDB system.

uint64_t iteration_steps = {80}¶: Number of iterations to run the simulation for.

double alpha = {0.7}¶: alpha parameter for the QuickSim algorithm.

uint64_t number_threads = {std::thread::hardware_concurrency()}¶: Number of threads to spawn. By default the number of threads is set to the number of available hardware threads.

uint64_t timeout = std::numeric_limits<uint64_t>::max()¶: Timeout limit (in ms).

std::chrono::steady_clock::time_point deadline = {std::chrono::steady_clock::time_point::max()}¶: Shared caller deadline. Expiration throws instead of returning an incomplete simulation. time_point::max() leaves the caller budget unlimited; timeout still applies.

utils::progress_callback on_progress = {}¶: Callback that receives the number of completed iterations across all threads.

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

inline std::optional<result> fiction::sidb::simulation::engines::quicksim(const layout &lyt, const quicksim_params &ps = quicksim_params{})¶

QuickSim is a heuristic ground-state simulation of SiDB layouts proposed in “QuickSim: Efficient and Accurate Physical Simulation of Silicon Dangling Bond Logic” by J. Drewniok, M. Walter, S. S. H. Ng, K. Walus, and R. Wille in IEEE NANO 2023 (https://ieeexplore.ieee.org/document/10231266). It grows candidate charge distributions from the SiDBs that have to be negative by repeatedly charging the neutral SiDB farthest from every negative one, keeping the physically valid intermediate states. Every worker thread owns one simulation state and shares the layout’s potential landscape. Charged surface defects are not supported: a layout that holds any yields std::nullopt.

Parameters:

lyt – Layout to simulate.
ps – QuickSim parameters.

Throws:

std::out_of_range – if a site has an invalid lattice basis index.
utils::timeout_error – if the shared caller deadline expires. No partial result is returned.

Returns:

The physically valid charge distributions found, or std::nullopt if the layout is empty, holds charged defects, the iteration count is zero, the timeout was hit, or no valid distribution was found.

Python

class quicksim_params¶

This struct stores the parameters for the QuickSim algorithm.

property alpha¶: alpha parameter for the QuickSim algorithm.

property iteration_steps¶: Number of iterations to run the simulation for.

property number_threads¶: Number of threads to spawn. By default the number of threads is set to the number of available hardware threads.

property on_progress¶: Callback that receives the number of completed iterations across all threads.

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

property simulation_parameters¶: Simulation parameters for the simulation of the physical SiDB system.

property timeout¶: Timeout limit (in ms).

quicksim(lyt: sidb_layout, params: quicksim_params = <mnt.pyfiction.sidb.simulation.engines.quicksim_params object at 0x579c36d9b730>) → sidb_simulation_result | None¶

QuickSim is a heuristic ground-state simulation of SiDB layouts proposed in "QuickSim: Efficient and Accurate Physical Simulation of Silicon Dangling Bond Logic" by J. Drewniok, M. Walter, S. S. H. Ng, K. Walus, and R. Wille in IEEE NANO 2023 (https://ieeexplore.ieee.org/document/10231266). It grows candidate charge distributions from the SiDBs that have to be negative by repeatedly charging the neutral SiDB farthest from every negative one, keeping the physically valid intermediate states. Every worker thread owns one simulation state and shares the layout’s potential landscape. Charged surface defects are not supported: a layout that holds any yields std::nullopt.

Parameters:

lyt – Layout to simulate.
ps – QuickSim parameters.

Returns:

The physically valid charge distributions found, or std::nullopt if the layout is empty, holds charged defects, the iteration count is zero, the timeout was hit, or no valid distribution was found.

Raises:

std::out_of_range – if a site has an invalid lattice basis index.
utils::timeout_error – if the shared caller deadline expires. No partial result is returned.

Exhaustive Ground State Simulation¶

C++

Header: fiction/technology/sidb/simulation/engines/quickexact.hpp

struct quickexact_params¶

This struct stores the parameters for the QuickExact algorithm.

Public Types

enum class automatic_base_number_detection : uint8_t¶

Modes to use for the QuickExact algorithm.

Values:

enumerator ON¶: Simulation is conducted with the required base number (i.e., if positively charged SiDBs can occur, three state simulation is conducted).

enumerator OFF¶: The base number from the physical parameters is used for the simulation.

Public Members

sidb::model::simulation_parameters sim_params = {}¶: All parameters for physical SiDB simulations.

automatic_base_number_detection base_number_detection = automatic_base_number_detection::ON ¶: If ON, QuickExact checks which base number is required for the simulation, i.e., whether positively charged SiDBs can occur. If OFF, the base number from the physical parameters is used.

std::unordered_map<lattice_site, double> local_external_potential = {}¶: Local external electrostatic potentials (e.g., locally applied electrodes), per site (unit: V).

double global_potential = 0¶: Global external electrostatic potential (unit: V). Value is applied on each SiDB.

std::chrono::steady_clock::time_point deadline = {std::chrono::steady_clock::time_point::max()}¶: Shared caller deadline. time_point::max() leaves the simulation unlimited.

utils::progress_callback on_progress = {}¶: Callback that receives the number of enumerated charge configurations.

inline result fiction::sidb::simulation::engines::quickexact(const layout &lyt, const quickexact_params &params = {})¶

QuickExact is a quick and exact physical simulation algorithm designed specifically for SiDB layouts. It was proposed in “The Need for Speed: Efficient Exact Simulation of Silicon Dangling Bond Logic” by J. Drewniok, M. Walter, and R. Wille in ASP-DAC 2024 (https://ieeexplore.ieee.org/document/10473946). It determines all physically valid charge configurations of a given SiDB layout, providing a significant performance advantage of more than three orders of magnitude over ExGS.

The performance improvement stems from the use of physically informed search space pruning: SiDBs whose local potential forces them negative are removed from the enumeration and modeled as fixed negative charges, one SiDB’s charge state follows from the others, and positively charged SiDBs are enumerated only where they can occur. Charged surface defects of the layout and external potentials enter the potential landscape.

Parameters:

lyt – Layout to simulate.
params – Parameter required for the simulation.

Throws:

std::out_of_range – if a site has an invalid lattice basis index.
utils::timeout_error – if the shared caller deadline expires. No partial result is returned.

Returns:

Simulation result: every physically valid charge distribution of lyt.

Header: fiction/technology/sidb/simulation/engines/clustercomplete.hpp

struct clustercomplete_params¶

The struct containing the parameters both passed on to pre-simulator Ground State Space, and used during simulation.

Public Types

enum class ground_state_space_reporting : uint8_t¶

This enum class provides meaningful options for configuring the reporting of the Ground State Space statistics. These statistic may be used especially to configure the validity witness partitioning options for Ground State Space, that may impair runtimes when set too high, but could provide a large benefit to the complexity of the unfolding process of large simulation problems by performing more involved pruning procedures in the construction stage.

Values:

enumerator ON¶: Enabling this option will output Ground State Space statistics to the standard output.

enumerator OFF¶: Disabling this option will suppress the output of Ground State Space statistics.

Public Members

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

std::unordered_map<lattice_site, double> local_external_potential = {}¶: Local external electrostatic potentials (e.g., locally applied electrodes).

double global_potential = 0¶: Global external electrostatic potential. Value is applied to each dot in the layout.

uint64_t validity_witness_partitioning_max_cluster_size_gss = 6¶: This specifies the maximum cluster size for which Ground State Space will solve an NP-complete sub-problem exhaustively. The sets of SiDBs that witness local population stability for each respective charge state may be partitioned into disjoint sets such that the number of required witnesses for each respective charge state is satisfied. If no such partition exists, the multiset charge configuration associated with the requirements may be rejected.

uint64_t num_overlapping_witnesses_limit_gss = 6¶: The complexity is of validity witness partitioning bounded by a factorial in the number of overlapping witnesses. This parameter thus allows the validity witness partitioning procedure to perform the reduction to overlapping witnesses for larger cluster sizes that could be runtime-impairing, then limiting specifically the length of the input to the factorial call.

uint64_t available_threads = std::thread::hardware_concurrency()¶: Number of threads to make available to ClusterComplete for the unfolding stage.

ground_state_space_reporting report_gss_stats = ground_state_space_reporting::OFF ¶: Option to decide if the Ground State Space statistics are reported to the standard output. By default, this option is disabled.

utils::progress_callback on_progress = {}¶: Callback that receives the number of unfolded charge space compositions.

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

inline result fiction::sidb::simulation::engines::clustercomplete(const layout &lyt, const clustercomplete_params &params = {})¶

ClusterComplete is an instantiation of a general solution to exhaustive state assignment searching for which all local predicates hold, given respective local evaluations that may be aggregated from individual inter-variable interactions. Applied to the problem of exact physical simulation of SiDBs, it is able to efficiently consider positive charges that are rare to occur, but drastically blow up exact simulation runtimes when hierarchical pruning methods are not applied. In fact, the exponential growth in problem complexity for added SiDBs is tamed by ClusterComplete, as SiDB layouts to simulate in practise amount to a high pruning efficacy, resulting in a layout-dependent reduction of the simulation base. This amounts to an effective simulation base in the real number range \([1,b]\), where \(b\in\{2,3\}\) is the given simulation base.

The part of the ClusterComplete algorithm that is implemented in this file is the destructive phase of the procedure that employs the duality of construction and destruction, folding and unfolding. The phase preceding it is the key ingredient to the achieved efficiency: the Ground State Space algorithm, which constructs a minimized hierarchical search space of charge configurations that adhere to the critical population stability criterion. In particular, it generalizes physically informed space pruning that contributes to the capabilities of the QuickExact simulator, now applying to all charge states equally, and, most importantly, it lifts the associated potential equations to higher order, allowing us to reason over potential bounds in a cluster hierarchy.

ClusterComplete was proposed in “Mastering the Exponential Complexity of Exact Physical Simulation of Silicon Dangling Bonds” by W. Lambooy, J. Drewniok, M. Walter, and R. Wille in ASP-DAC 2026.

Parameters:

lyt – Layout to simulate.
params – Parameter required for both the invocation of Ground State Space, and the simulation following.

Throws:

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

Returns:

Simulation results.

Header: fiction/technology/sidb/simulation/engines/exhaustive_ground_state_simulation.hpp

inline result fiction::sidb::simulation::engines::exhaustive_ground_state_simulation(const layout &lyt, const model::simulation_parameters &params = model::simulation_parameters{}, const utils::progress_callback &on_progress = {}, const std::chrono::steady_clock::time_point deadline = std::chrono::steady_clock::time_point::max())¶

Exhaustive Ground State Simulation (ExGS) which was proposed in “Computer-Aided Design of Atomic Silicon Quantum Dots and Computational Applications” by S. S. H. Ng (https://dx.doi.org/10.14288/1.0392909) enumerates every charge distribution of the layout in base 2 or 3 and keeps the physically valid ones. Charged surface defects of the layout enter the potential landscape.

Parameters:

lyt – Layout to simulate.
params – Physical parameters.
on_progress – Callback that receives the number of enumerated charge configurations.
deadline – Shared caller deadline. time_point::max() leaves the simulation unlimited.

Throws:

std::out_of_range – if a site has an invalid lattice basis index.
utils::timeout_error – if the shared caller deadline expires. No partial result is returned.

Returns:

The physically valid charge distributions.

Python

class quickexact_params¶

This struct stores the parameters for the QuickExact algorithm.

property base_number_detection¶: If ON, QuickExact checks which base number is required for the simulation, i.e., whether positively charged SiDBs can occur. If OFF, the base number from the physical parameters is used.

property global_potential¶

V). Value is applied on each SiDB.

Type:: Global external electrostatic potential (unit

property local_external_potential¶: Local external electrostatic potentials (e.g., locally applied electrodes), per site (unit: V).

property on_progress¶: Callback that receives the number of enumerated charge configurations.

property simulation_parameters¶: All parameters for physical SiDB simulations.

class automatic_base_number_detection(*values)¶

Modes to use for the QuickExact algorithm.

ON = 0¶

OFF = 1¶

quickexact(lyt: sidb_layout, params: quickexact_params = <mnt.pyfiction.sidb.simulation.engines.quickexact_params object at 0x579c36d98960>) → sidb_simulation_result¶

QuickExact is a quick and exact physical simulation algorithm designed specifically for SiDB layouts. It was proposed in "The Need for Speed: Efficient Exact Simulation of Silicon Dangling Bond Logic" by J. Drewniok, M. Walter, and R. Wille in ASP-DAC 2024 (https://ieeexplore.ieee.org/document/10473946). It determines all physically valid charge configurations of a given SiDB layout, providing a significant performance advantage of more than three orders of magnitude over ExGS.

Parameters:

lyt – Layout to simulate.
params – Parameter required for the simulation.

Returns:

every physically valid charge distribution of lyt.

Return type:

Simulation result

Raises:

std::out_of_range – if a site has an invalid lattice basis index.
utils::timeout_error – if the shared caller deadline expires. No partial result is returned.

class clustercomplete_params¶

The struct containing the parameters both passed on to pre-simulator Ground State Space, and used during simulation.

property available_threads¶: Number of threads to make available to ClusterComplete for the unfolding stage.

property global_potential¶: Global external electrostatic potential. Value is applied to each dot in the layout.

property local_external_potential¶: Local external electrostatic potentials (e.g., locally applied electrodes).

property num_overlapping_witnesses_limit_gss¶: The complexity is of validity witness partitioning bounded by a factorial in the number of overlapping witnesses. This parameter thus allows the validity witness partitioning procedure to perform the reduction to overlapping witnesses for larger cluster sizes that could be runtime-impairing, then limiting specifically the length of the input to the factorial call.

property on_progress¶: Callback that receives the number of unfolded charge space compositions.

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

property report_gss_stats¶: Option to decide if the Ground State Space statistics are reported to the standard output. By default, this option is disabled.

property simulation_parameters¶: Physical simulation parameters.

property validity_witness_partitioning_max_cluster_size_gss¶: This specifies the maximum cluster size for which Ground State Space will solve an NP-complete sub-problem exhaustively. The sets of SiDBs that witness local population stability for each respective charge state may be partitioned into disjoint sets such that the number of required witnesses for each respective charge state is satisfied. If no such partition exists, the multiset charge configuration associated with the requirements may be rejected.

class ground_state_space_reporting(*values)¶

ON = 0¶

OFF = 1¶

clustercomplete(lyt: sidb_layout, params: clustercomplete_params = <mnt.pyfiction.sidb.simulation.engines.clustercomplete_params object at 0x579c3618bee0>) → sidb_simulation_result¶

ClusterComplete was proposed in "Mastering the Exponential Complexity of Exact Physical Simulation of Silicon Dangling Bonds" by W. Lambooy, J. Drewniok, M. Walter, and R. Wille in ASP-DAC 2026.

Parameters:

lyt – Layout to simulate.
params – Parameter required for both the invocation of Ground State Space, and the simulation following.

Returns:

Simulation results.

Raises:

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

exhaustive_ground_state_simulation(lyt: mnt.pyfiction.sidb.sidb_layout, params: mnt.pyfiction.sidb.model.sidb_simulation_parameters = <mnt.pyfiction.sidb.model.sidb_simulation_parameters object at 0x579c35c498e0>, on_progress: collections.abc.Callable[[str, int, int], None] | None = None) → sidb_simulation_result¶

Exhaustive Ground State Simulation (ExGS) which was proposed in "Computer-Aided Design of Atomic Silicon Quantum Dots and Computational Applications" by S. S. H. Ng (https://dx.doi.org/10.14288/1.0392909) enumerates every charge distribution of the layout in base 2 or 3 and keeps the physically valid ones. Charged surface defects of the layout enter the potential landscape.

Parameters:

lyt – Layout to simulate.
params – Physical parameters.
on_progress – Callback that receives the number of enumerated charge configurations.
deadline – Shared caller deadline. time_point::max() leaves the simulation unlimited.

Returns:

The physically valid charge distributions.

Raises:

std::out_of_range – if a site has an invalid lattice basis index.
utils::timeout_error – if the shared caller deadline expires. No partial result is returned.

Ground State Space Construction¶

Header: fiction/technology/sidb/simulation/engines/ground_state_space.hpp

struct ground_state_space_results¶

This struct is used to store the results of the Ground State Space construction.

Public Functions

inline void report(std::ostream &os = std::cout) const noexcept¶

Report Ground State Space statistics. A quick heuristic to assess the quality of the pruning is captured by the size of the charge space of the top cluster, which depends on the charge spaces of all clusters below it.

Parameters:: os – The output stream to write to (default: standard output).

Public Members

const detail::cluster_ptr top_cluster = {nullptr}¶: The root of the cluster hierarchy the construction built, with the charge space of every cluster below it. The hierarchy is the engines’ working state: detail::cluster and what it points to are implementation, not API, and may change without notice.

const std::chrono::duration<double> runtime = {}¶: The runtime of the construction is stored.

const uint64_t maximum_top_level_multisets = {}¶: The maximum size of the charge space of the top cluster, given the simulation base, can be inferred by the “stars and bars” combinatorial idea: the solution to this analogous problem determines the maximum amount of multisets of size \(N\) (where \(N\) is the number of SiDBs in the layout, and therefore in the top cluster) for the given base \(b\). In particular, the analogy is as follows: any such multiset can be seen as \(N\) stars and \(b - 1\) bars separating those stars. Then, the \(b\) partitions forming from these \(b - 1\) separators each have a respective size, adding up to \(N\). Therefore each partition is associated with an amount of one of the charge states of the multiset. Now we may compute total number of possible multisets for the top cluster as the number of combinations of \(N\) stars and \(b - 1\) bars. Hence this is computed with the following combinatorial formula: \(\binom{N + b - 1}{b - 1}\).

const uint64_t projector_state_count = {}¶: The total number of distinct projector states is counted. At each merge, the projector states in charge space compositions in the charge spaces of the clusters to merge are locked in the final construct, and can therefore be counted. This may be used to estimate the time it would take ClusterComplete to unfold the hierarchy.

inline ground_state_space_results fiction::sidb::simulation::engines::ground_state_space(const potential_landscape &land, const ground_state_space_params &params = {})¶

Constructs the pruned cluster hierarchy used by ClusterComplete.

Ground State Space extends the physically informed pruning of QuickExact from individual SiDBs to multiset charge configurations throughout a cluster hierarchy. Clustering groups SiDBs by position and lets pruning analyze charge-state-dependent interactions within those groups before merging larger groups.

Construction starts with singleton clusters whose charge spaces contain negative, neutral, and, for base 3, positive charge states. Potential-bound analysis repeatedly removes configurations that cannot satisfy population stability until a fixed point is reached. Merging children into their parent then exposes interactions between larger groups of SiDBs. Repeating pruning and merging folds the charge spaces into the top cluster, which retains the configurations and compositions of the complete hierarchy. ClusterComplete unfolds this hierarchy to enumerate physically valid charge distributions.

Validity witness partitioning can strengthen the pruning of large layouts. Its subproblems can grow factorially, so the pruning parameters limit their size and overlap. Raising those limits trades construction time for a smaller search space during ClusterComplete simulation.