SiDB Layout¶

An SiDB layout places SiDBs and surface defects on the lattice sites of one hydrogen-passivated silicon surface. The surface is a Bravais lattice with a two-site basis: two lattice vectors a1 and a2 plus the two basis sites of the unit cell, exactly as SiQAD stores it. Site (x, y, z) lies at x * a1 + y * a2 + basis[z]. The H-Si(100)-2x1 and H-Si(111)-1x1 reconstructions are predefined; any other reconstruction with a two-site basis can be described by setting the vectors directly.

Lattice¶

C++

Header: fiction/technology/sidb/lattice.hpp

struct lattice_site¶

A site of the H-Si surface lattice. Site (x, y, z) is the z-th basis site of the unit cell reached by x steps along the first and y steps along the second lattice vector of a lattice. This is the (n, m, l) lattice coordinate of SiQAD’s SQD files. Both supported reconstructions have a two-site basis, so z is either 0 or 1.

Sites order in raster order: by y, then by z, then by x.

Public Functions

constexpr lattice_site() noexcept = default¶: Default constructor. Creates the site (0, 0, 0).

inline constexpr lattice_site(const int32_t x_coord, const int32_t y_coord, const int8_t basis_site)¶

Creates the site (x, y, z). Coordinates must be representable by the parameter types before the call.

Parameters:

x_coord – Steps along the first lattice vector.
y_coord – Steps along the second lattice vector.
basis_site – Basis site, 0 or 1.

Throws:

std::out_of_range – if the basis index is not 0 or 1.

inline constexpr lattice_site(const int32_t x_coord, const int32_t y_coord) noexcept¶

Creates the site (x, y, 0).

Parameters:

x_coord – Steps along the first lattice vector.
y_coord – Steps along the second lattice vector.

constexpr bool operator==(const lattice_site &other) const noexcept = default¶

Compares two sites for equality.

Parameters:: other – Right-hand side site.
Returns:: true iff both sites are identical.

inline constexpr std::strong_ordering operator<=>(const lattice_site &other) const noexcept¶

Orders two sites in raster order: by y, then by z, then by x.

Parameters:: other – Right-hand side site.
Returns:: The ordering of this site relative to other.

inline constexpr lattice_site operator+(const lattice_site &other) const¶

Adds another site to this one, carrying an overflowing basis index into the next unit cell along the second lattice vector. Does not modify this site.

Parameters:: other – Site to add.
Throws:: std::out_of_range – if a basis index is invalid or a result coordinate exceeds the lattice-site range.
Returns:: Sum of both sites.

inline constexpr lattice_site operator-(const lattice_site &other) const¶

Subtracts another site from this one, borrowing from the previous unit cell along the second lattice vector when the basis index underflows. Does not modify this site.

Parameters:: other – Site to subtract.
Throws:: std::out_of_range – if a basis index is invalid or a result coordinate exceeds the lattice-site range.
Returns:: Difference of both sites.

inline std::string str() const¶

Returns a string representation of the form "(x,y,z)".

Returns:: String representation of the form "(x,y,z)".

Public Members

int32_t x = {0}¶: Steps along the first lattice vector.

int32_t y = {0}¶: Steps along the second lattice vector.

int8_t z = {0}¶: Basis site within the unit cell, 0 or 1.

constexpr int64_t fiction::sidb::row_of(const lattice_site &s) noexcept¶

The row of a site counted in single SiDB rows: 2 * y + z. SiDB gate libraries describe their gates on a grid of such rows.

Parameters:: s – Site.
Returns:: Row of s.

constexpr lattice_site fiction::sidb::site_at_row(const int32_t x, const int64_t row)¶

The site at a given column and single-SiDB row, the inverse of row_of. Negative rows map to the unit cell below them, so (x, -1) is (x, -1, 1).

Parameters:

x – Column.
row – Row counted in single SiDB rows.

Throws:

std::out_of_range – if the row exceeds the range of lattice sites.

Returns:

The site (x, floor(row / 2), row mod 2).

inline std::vector<lattice_site> fiction::sidb::sites_in_area(const lattice_site &first_corner, const lattice_site &second_corner)¶

All sites in the rectangle spanned by two corner sites, in raster order (top to bottom, left to right), both corners included. The corners may be given in any order.

Parameters:

first_corner – One corner of the rectangle.
second_corner – The opposite corner.

Throws:

std::length_error – if the rectangle exceeds the maximum vector size.

Returns:

The sites in the rectangle in raster order.

template<std::uniform_random_bit_generator Rng> lattice_site fiction::sidb::random_site_in_area(const lattice_site &first_corner, const lattice_site &second_corner, Rng &rng)¶

A uniformly random site in the rectangle spanned by two corner sites, both corners included.

Template Parameters:

Rng – Uniform random bit generator type.

Parameters:

first_corner – One corner of the rectangle.
second_corner – The opposite corner.
rng – Random number generator to draw from.

Returns:

A random site in the rectangle.

struct lattice¶

A hydrogen-passivated silicon surface lattice: a Bravais lattice given by two lattice vectors plus a two-site basis. Site (x, y, z) lies at x * a1 + y * a2 + basis[z]. The vectors are stored in ångström, as SiQAD stores them; positions are reported in nanometers. The two reconstructions SiQAD defines are available as si_100_2x1() and si_111_1x1(); any other reconstruction with a two-site basis can be described by setting the vectors directly.

Public Types

using vector = std::pair<double, double>¶: A vector in the surface plane.

Public Functions

inline vector nm_position(const lattice_site &s) const¶

The position of a site relative to the site (0, 0, 0).

Parameters:: s – Site.
Throws:: std::out_of_range – if the basis index is not 0 or 1.
Returns:: The (x, y) position of s (unit: nm).

inline double nm_distance(const lattice_site &source, const lattice_site &target) const¶

The Euclidean distance between two sites.

Parameters:

source – First site.
target – Second site.

Throws:

std::out_of_range – if either basis index is not 0 or 1.

Returns:

Distance between source and target (unit: nm).

bool operator==(const lattice &other) const noexcept = default¶

Compares two lattices for equality.

Parameters:: other – Right-hand side lattice.
Returns:: true iff name, vectors, and basis are identical.

Public Members

std::string name = {}¶: Name of the reconstruction as SiQAD spells it in SQD files, e.g., "Si(100) 2x1".

vector a1 = {}¶: First lattice vector (unit: Å).

vector a2 = {}¶: Second lattice vector (unit: Å).

std::array<vector, 2> basis = {}¶: The two basis sites of the unit cell (unit: Å). The first one is the origin.

Public Static Functions

static inline lattice si_100_2x1()¶

The H-Si(100)-2x1 surface: dimer rows 7.68 Å apart, dimer atoms 3.84 Å apart along the row and 2.25 Å apart across it.

Returns:: The H-Si(100)-2x1 lattice.

static inline lattice si_111_1x1()¶

The H-Si(111)-1x1 surface: a hexagonal arrangement with 3.84 Å between neighboring sites, described by a rectangular 6.65 Å × 3.84 Å cell with a centered second site.

Returns:: The H-Si(111)-1x1 lattice.

Python

class lattice_site¶

class lattice_site(x: int, y: int, z: int)

class lattice_site(x: int, y: int)

Sites order in raster order: by y, then by z, then by x.

property x¶: Steps along the first lattice vector.

property y¶: Steps along the second lattice vector.

property z¶: Basis site within the unit cell, 0 or 1.

row_of(site: lattice_site) → int¶

The row of a site counted in single SiDB rows: 2 * y + z. SiDB gate libraries describe their gates on a grid of such rows.

Parameters:: s – Site.
Returns:: Row of s.

site_at_row(x: int, row: int) → lattice_site¶

The site at a given column and single-SiDB row, the inverse of row_of. Negative rows map to the unit cell below them, so (x, -1) is (x, -1, 1).

Parameters:

x – Column.
row – Row counted in single SiDB rows.

Returns:

The site (x, floor(row / 2), row mod 2).

Raises:

std::out_of_range – if the row exceeds the range of lattice sites.

sites_in_area(first_corner: lattice_site, second_corner: lattice_site) → list[lattice_site]¶

All sites in the rectangle spanned by two corner sites, in raster order (top to bottom, left to right), both corners included. The corners may be given in any order.

Parameters:

first_corner – One corner of the rectangle.
second_corner – The opposite corner.

Returns:

The sites in the rectangle in raster order.

Raises:

std::length_error – if the rectangle exceeds the maximum vector size.

class lattice¶

class lattice(name: str, a1: tuple[float, float], a2: tuple[float, float], basis: Sequence[tuple[float, float]])

property a1¶

Å).

Type:: First lattice vector (unit

property a2¶

Å).

Type:: Second lattice vector (unit

property basis¶

Å). The first one is the origin.

Type:: The two basis sites of the unit cell (unit

property name¶: Name of the reconstruction as SiQAD spells it in SQD files, e.g., "Si(100) 2x1".

nm_distance(source: lattice_site, target: lattice_site) → float¶

The Euclidean distance between two sites.

Parameters:

source – First site.
target – Second site.

Returns:

nm).

Return type:

Distance between source and target (unit

Raises:

std::out_of_range – if either basis index is not 0 or 1.

nm_position(site: lattice_site) → tuple[float, float]¶

The position of a site relative to the site (0, 0, 0).

Parameters:: s – Site.
Returns:: nm).
Return type:: The (x, y) position of s (unit
Raises:: std::out_of_range – if the basis index is not 0 or 1.

si_100_2x1 = <nanobind.nb_func object>¶

si_111_1x1 = <nanobind.nb_func object>¶

Layout¶

C++

Header: fiction/technology/sidb/layout.hpp

A dot is one silicon dangling bond. dot_tag records its role: NORMAL, INPUT, OUTPUT, or LOGIC. assign_sidb places an SiDB at a lattice site and defaults to NORMAL when no tag is given. Assigning EMPTY removes the dot. Use assign_sidb, get_dot_tag, num_dots, and dots_with_tag to manage dots; is_pi and is_po identify primary inputs and outputs. Python exposes the tags as sidb_dot_tag.

enum class fiction::sidb::dot_tag : uint8_t¶

Tags describing the role of a silicon dangling bond. EMPTY denotes an unoccupied site.

Values:

enumerator EMPTY¶: Unoccupied lattice site.

enumerator NORMAL¶: Untagged dot.

enumerator INPUT¶: Primary input dot.

enumerator OUTPUT¶: Primary output dot.

enumerator LOGIC¶: Logic dot (e.g., a canvas SiDB).

class layout¶

An SiDB layout: tagged SiDBs and surface defects placed on lattice sites of one H-Si lattice. The layout has value semantics; copies are independent.

Dots and defects are kept sorted in raster order, so sidbs() is the canonical SiDB order that index-based structures such as charge distributions refer to, and every foreach_* traversal is deterministic.

Public Types

using dot_tag = sidb::dot_tag ¶: SiDB dot tags.

using cell_type = dot_tag ¶: Element type of the gates of SiDB gate libraries.

Public Functions

layout() = default¶: Creates an empty layout on the H-Si(100)-2x1 lattice.

inline explicit layout(lattice lat, std::string name = "")¶

Creates an empty layout on the given lattice.

Parameters:

lat – Lattice of the surface.
name – Layout name.

inline const lattice &get_lattice() const noexcept¶

The lattice of the surface.

Returns:: The lattice.

inline void set_lattice(const lattice &lat)¶

Reassigns the lattice. Sites are kept as they are; only their physical positions change.

Parameters:: lat – New lattice.

inline const std::string &get_layout_name() const noexcept¶

The layout name.

Returns:: Layout name.

inline void set_layout_name(const std::string &name)¶

Sets the layout name.

Parameters:: name – New layout name.

inline void assign_sidb(const lattice_site &s, const dot_tag tag = dot_tag::NORMAL)¶

Assigns an SiDB to a lattice site with the given tag, or dot_tag::NORMAL by default. Reassigning an occupied site updates its tag. Assigning dot_tag::EMPTY removes the SiDB. Allocation failure leaves the dots unchanged.

Parameters:

s – Site.
tag – Dot tag to assign; defaults to dot_tag::NORMAL.

inline dot_tag get_dot_tag(const lattice_site &s) const noexcept¶

The dot tag at a site.

Parameters:: s – Site.
Returns:: Dot tag at s, dot_tag::EMPTY if no SiDB is there.

inline bool is_empty_site(const lattice_site &s) const noexcept¶

Whether no SiDB sits at a site.

Parameters:: s – Site.
Returns:: true iff s holds no SiDB.

inline bool is_empty() const noexcept¶

Whether the layout holds no SiDB. Defects do not count.

Returns:: true iff there is no SiDB.

inline uint64_t num_dots() const noexcept¶

Number of SiDBs.

Returns:: Number of SiDBs.

inline uint64_t num_dots_with_tag(const dot_tag tag) const noexcept¶

Number of tagged SiDBs.

Parameters:: tag – Dot tag.
Returns:: Number of SiDBs with tag tag.

inline std::vector<lattice_site> dots_with_tag(const dot_tag tag) const¶

All sites holding an SiDB of a given dot tag, in raster order.

Parameters:: tag – Dot tag.
Returns:: Sites with tag tag.

inline const std::vector<lattice_site> &sidbs() const noexcept¶

All sites holding an SiDB, in raster order. This is the canonical SiDB order that index-based structures refer to.

Returns:: Sorted SiDB sites.

inline std::optional<std::size_t> index_of(const lattice_site &s) const noexcept¶

The index of a site in sidbs().

Parameters:: s – Site.
Returns:: Index of s, or std::nullopt if s holds no SiDB.

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

Applies a function to every SiDB site in raster order. fn takes the site and optionally its index, and may return false to stop the traversal. The layout must not be modified during the traversal; collect the sites with dots_with_tag first to add or remove SiDBs.

Template Parameters:: Fn – Callable on (const lattice_site&) or (const lattice_site&, std::size_t).
Parameters:: fn – Function to apply.

inline uint32_t num_pis() const noexcept¶

Number of input SiDBs.

Returns:: Number of input SiDBs.

inline uint32_t num_pos() const noexcept¶

Number of output SiDBs.

Returns:: Number of output SiDBs.

inline bool is_pi(const lattice_site &s) const noexcept¶

Whether a site holds an input SiDB.

Parameters:: s – Site.
Returns:: true iff s holds an input SiDB.

inline bool is_po(const lattice_site &s) const noexcept¶

Whether a site holds an output SiDB.

Parameters:: s – Site.
Returns:: true iff s holds an output SiDB.

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

Applies a function to every input SiDB site in raster order. Same callable contract as foreach_dot.

Template Parameters:: Fn – Callable on (const lattice_site&) or (const lattice_site&, std::size_t).
Parameters:: fn – Function to apply.

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

Applies a function to every output SiDB site in raster order. Same callable contract as foreach_dot.

Template Parameters:: Fn – Callable on (const lattice_site&) or (const lattice_site&, std::size_t).
Parameters:: fn – Function to apply.

inline void assign_defect(const lattice_site &s, const model::defect &d)¶

Places a surface defect at a site. A defect of type defect_type::NONE removes the defect from the site.

Parameters:

s – Site.
d – Defect to place.

inline void move_defect(const lattice_site source, const lattice_site target)¶

Moves the defect at one site to another, replacing whatever defect the target site held. An empty source or identical source and target leaves the defects unchanged.

Parameters:

source – Site holding the defect.
target – Site to move the defect to.

inline model::defect get_defect(const lattice_site &s) const noexcept¶

The defect at a site.

Parameters:: s – Site.
Returns:: Defect at s, or a defect of type defect_type::NONE if there is none.

inline uint64_t num_defects() const noexcept¶

Number of surface defects.

Returns:: Number of defects.

inline uint64_t num_positively_charged_defects() const noexcept¶

Number of positively charged defects.

Returns:: Number of defects with positive charge.

inline uint64_t num_negatively_charged_defects() const noexcept¶

Number of negatively charged defects.

Returns:: Number of defects with negative charge.

inline uint64_t num_charged_defects() const noexcept¶

Number of charged defects.

Returns:: Number of defects with non-zero charge.

inline uint64_t num_neutral_defects() const noexcept¶

Number of neutral defects.

Returns:: Number of defects with zero charge.

inline const std::vector<std::pair<lattice_site, model::defect>> &defects() const noexcept¶

All defects with their sites, in raster order.

Returns:: Site-defect pairs.

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

Applies a function to every defect in raster order. fn takes the (site, defect) pair and optionally its index, and may return false to stop the traversal.

Template Parameters:: Fn – Callable on (const std::pair<lattice_site, model::defect>&) or the same plus std::size_t.
Parameters:: fn – Function to apply.

inline std::unordered_set<lattice_site> affected_sidbs(const lattice_site &s, const std::optional<std::pair<uint16_t, uint16_t>> &charged_defect_spacing_overwrite = std::nullopt, const std::optional<std::pair<uint16_t, uint16_t>> &neutral_defect_spacing_overwrite = std::nullopt) const¶

The sites whose SiDBs the defect at a given site would influence: the rectangle around the defect spanned by model::defect_extent, counted in unit cells along the lattice vectors and keeping the defect’s basis site. The rectangle is clipped to the representable lattice-site coordinates.

Parameters:

s – Site of the defect.
charged_defect_spacing_overwrite – Horizontal and vertical extent to use for charged defects instead of the default.
neutral_defect_spacing_overwrite – Horizontal and vertical extent to use for neutral defects instead of the default.

Returns:

Sites influenced by the defect at s; empty if s holds no defect.

inline std::unordered_set<lattice_site> all_affected_sidbs(const std::optional<std::pair<uint16_t, uint16_t>> &charged_defect_spacing_overwrite = std::nullopt, const std::optional<std::pair<uint16_t, uint16_t>> &neutral_defect_spacing_overwrite = std::nullopt) const¶

The union of affected_sidbs over every defect.

Parameters:

charged_defect_spacing_overwrite – Horizontal and vertical extent to use for charged defects instead of the default.
neutral_defect_spacing_overwrite – Horizontal and vertical extent to use for neutral defects instead of the default.

Returns:

Sites influenced by any defect.

inline std::pair<lattice_site, lattice_site> bounding_box() const noexcept¶

The smallest rectangle of sites containing every SiDB and every defect. The corners are the north-western and south-eastern site; an empty layout yields {(0,0,0), (0,0,0)}.

Returns:: North-western and south-eastern corner.

bool operator==(const layout &other) const noexcept = default¶

Compares two layouts for equality: same lattice, name, SiDBs, and defects.

Parameters:: other – Right-hand side layout.
Returns:: true iff both layouts are identical.

Public Static Attributes

static constexpr double CELL_WIDTH = 0.0¶: Width of an SiDB in nm. Dots are 0-dimensional entities for simulation purposes.

static constexpr double CELL_HEIGHT = 0.0¶: Height of an SiDB in nm. Dots are 0-dimensional entities for simulation purposes.

static constexpr double CELL_HSPACE = 0.384¶: Horizontal spacing between two SiDBs in nm, as in SiQAD.

static constexpr double CELL_VSPACE = 0.384¶: Average vertical spacing between two SiDB rows in nm, as in SiQAD. SiDBs on the same dimer row sit closer together, SiDBs on different dimer rows further apart.

Python

class sidb_dot_tag(*values)¶

Tags describing the role of a silicon dangling bond. EMPTY denotes an unoccupied site.

EMPTY = 32¶

NORMAL = 120¶

INPUT = 105¶

OUTPUT = 111¶

LOGIC = 108¶

class sidb_layout¶

class sidb_layout(lattice: lattice, name: str = '')

An SiDB layout: tagged SiDBs and surface defects placed on lattice sites of one H-Si lattice. The layout has value semantics; copies are independent.

affected_sidbs(site: lattice_site, charged_defect_spacing_overwrite: tuple[int, int] | None = None, neutral_defect_spacing_overwrite: tuple[int, int] | None = None) → set[lattice_site]¶

Parameters:

s – Site of the defect.
charged_defect_spacing_overwrite – Horizontal and vertical extent to use for charged defects instead of the default.
neutral_defect_spacing_overwrite – Horizontal and vertical extent to use for neutral defects instead of the default.

Returns:

Sites influenced by the defect at s; empty if s holds no defect.

all_affected_sidbs(charged_defect_spacing_overwrite: tuple[int, int] | None = None, neutral_defect_spacing_overwrite: tuple[int, int] | None = None) → set[lattice_site]¶

The union of affected_sidbs over every defect.

Parameters:

charged_defect_spacing_overwrite – Horizontal and vertical extent to use for charged defects instead of the default.
neutral_defect_spacing_overwrite – Horizontal and vertical extent to use for neutral defects instead of the default.

Returns:

Sites influenced by any defect.

assign_defect(site: lattice_site, defect: sidb_defect) → None¶

Places a surface defect at a site. A defect of type defect_type::NONE removes the defect from the site.

Parameters:

s – Site.
d – Defect to place.

assign_sidb(site: lattice_site, dot_tag: sidb_dot_tag = sidb_dot_tag.NORMAL) → None¶

Parameters:

s – Site.
tag – Dot tag to assign; defaults to dot_tag::NORMAL.

bounding_box() → tuple[lattice_site, lattice_site]¶

The smallest rectangle of sites containing every SiDB and every defect. The corners are the north-western and south-eastern site; an empty layout yields {(0,0,0), (0,0,0)}.

Returns:: North-western and south-eastern corner.

defects() → list[tuple[lattice_site, sidb_defect]]¶

All defects with their sites, in raster order.

Returns:: Site-defect pairs.

dots_with_tag(dot_tag: sidb_dot_tag) → list[lattice_site]¶

All sites holding an SiDB of a given dot tag, in raster order.

Parameters:: tag – Dot tag.
Returns:: Sites with tag tag.

get_defect(site: lattice_site) → sidb_defect¶

The defect at a site.

Parameters:: s – Site.
Returns:: Defect at s, or a defect of type defect_type::NONE if there is none.

get_dot_tag(site: lattice_site) → sidb_dot_tag¶

The dot tag at a site.

Parameters:: s – Site.
Returns:: Dot tag at s, dot_tag::EMPTY if no SiDB is there.

get_lattice() → lattice¶

The lattice of the surface.

Returns:: The lattice.

get_layout_name() → str¶

The layout name.

Returns:: Layout name.

index_of(site: lattice_site) → int | None¶

The index of a site in sidbs().

Parameters:: s – Site.
Returns:: Index of s, or std::nullopt if s holds no SiDB.

is_empty() → bool¶

Whether the layout holds no SiDB. Defects do not count.

Returns:: true iff there is no SiDB.

is_empty_site(site: lattice_site) → bool¶

Whether no SiDB sits at a site.

Parameters:: s – Site.
Returns:: true iff s holds no SiDB.

is_pi(site: lattice_site) → bool¶

Whether a site holds an input SiDB.

Parameters:: s – Site.
Returns:: true iff s holds an input SiDB.

is_po(site: lattice_site) → bool¶

Whether a site holds an output SiDB.

Parameters:: s – Site.
Returns:: true iff s holds an output SiDB.

move_defect(source: lattice_site, target: lattice_site) → None¶

Moves the defect at one site to another, replacing whatever defect the target site held. An empty source or identical source and target leaves the defects unchanged.

Parameters:

source – Site holding the defect.
target – Site to move the defect to.

num_charged_defects() → int¶

Number of charged defects.

Returns:: Number of defects with non-zero charge.

num_defects() → int¶

Number of surface defects.

Returns:: Number of defects.

num_dots() → int¶

Number of SiDBs.

Returns:: Number of SiDBs.

num_dots_with_tag(dot_tag: sidb_dot_tag) → int¶

Number of tagged SiDBs.

Parameters:: tag – Dot tag.
Returns:: Number of SiDBs with tag tag.

num_negatively_charged_defects() → int¶

Number of negatively charged defects.

Returns:: Number of defects with negative charge.

num_neutral_defects() → int¶

Number of neutral defects.

Returns:: Number of defects with zero charge.

num_pis() → int¶

Number of input SiDBs.

Returns:: Number of input SiDBs.

num_pos() → int¶

Number of output SiDBs.

Returns:: Number of output SiDBs.

num_positively_charged_defects() → int¶

Number of positively charged defects.

Returns:: Number of defects with positive charge.

pis() → list[lattice_site]¶: Returns the sites of all input SiDBs.

pos() → list[lattice_site]¶: Returns the sites of all output SiDBs.

set_lattice(lattice: lattice) → None¶

Reassigns the lattice. Sites are kept as they are; only their physical positions change.

Parameters:: lat – New lattice.

set_layout_name(name: str) → None¶

Sets the layout name.

Parameters:: name – New layout name.

sidbs() → list[lattice_site]¶

All sites holding an SiDB, in raster order. This is the canonical SiDB order that index-based structures refer to.

Returns:: Sorted SiDB sites.

Charge Distribution¶

A charge distribution assigns one charge state to every SiDB of a layout, in the order of layout::sidbs(), and carries the electrostatic potential energy of that assignment. Simulation engines return one distribution per physically valid state beside a single copy of the simulated layout.

C++

Header: fiction/technology/sidb/charge_distribution.hpp

class charge_distribution¶

A charge distribution assigns one charge state to every SiDB of a layout, in the layout’s canonical raster order (layout::sidbs()), and carries the electrostatic potential energy of that assignment. The site list is shared by every distribution of one simulation result, so a distribution costs one byte per SiDB.

Public Types

using site_list = std::shared_ptr<const std::vector<lattice_site>>¶: The shared list of sites a distribution refers to, in raster order.

Public Functions

charge_distribution() = default¶: Creates a distribution over no SiDBs.

inline explicit charge_distribution(const layout &lyt, const model::charge_state cs = model::charge_state::NEGATIVE)¶

Creates a distribution over the SiDBs of a layout with every SiDB in one charge state.

Parameters:

lyt – Layout whose SiDBs the distribution covers.
cs – Charge state of every SiDB.

inline explicit charge_distribution(site_list sites, const model::charge_state cs = model::charge_state::NEGATIVE)¶

Creates a distribution over a shared site list with every SiDB in one charge state.

Parameters:

sites – Distinct sites in raster order; callers must not mutate the shared list.
cs – Charge state of every SiDB.

Throws:

std::invalid_argument – if the sites are not distinct and in raster order.

inline charge_distribution(site_list sites, std::vector<model::charge_state> states, const double energy)¶

Creates a distribution over a shared site list from explicit charge states and an energy.

Parameters:

sites – Distinct sites in raster order; callers must not mutate the shared list.
states – One charge state per site.
energy – Electrostatic potential energy of the distribution (unit: eV).

Throws:

std::invalid_argument – if the site and state counts differ or sites are not distinct and in raster order.

inline const std::vector<lattice_site> &sites() const noexcept¶

The sites the distribution covers, in raster order.

Returns:: The sites.

inline const site_list &shared_sites() const noexcept¶

The shared site list, to build further distributions over the same SiDBs.

Returns:: The shared site list.

inline std::size_t size() const noexcept¶

Number of SiDBs.

Returns:: Number of SiDBs.

inline bool empty() const noexcept¶

Whether the distribution covers no SiDB.

Returns:: true iff there is no SiDB.

inline std::optional<std::size_t> index_of(const lattice_site &s) const noexcept¶

The index of a site in the distribution.

Parameters:: s – Site.
Returns:: Index of s, or std::nullopt if the distribution covers no SiDB at s.

inline model::charge_state get_charge_state(const lattice_site &s) const noexcept¶

The charge state of the SiDB at a site.

Parameters:: s – Site.
Returns:: Charge state at s, charge_state::NONE if the distribution covers no SiDB at s.

inline model::charge_state get_charge_state_by_index(const std::size_t index) const noexcept¶

The charge state of the SiDB at an index.

Parameters:: index – Index in raster order.
Returns:: Charge state at index, charge_state::NONE if the index is out of range.

inline void assign_charge_state(const lattice_site &s, const model::charge_state cs) noexcept¶

Assigns the charge state of the SiDB at a site. A site the distribution does not cover is ignored.

Parameters:

s – Site.
cs – Charge state to assign.

inline void assign_charge_state_by_index(const std::size_t index, const model::charge_state cs)¶

Assigns the charge state of the SiDB at an index.

Parameters:

index – Index in raster order.
cs – Charge state to assign.

Throws:

std::out_of_range – if the index is out of range.

inline void assign_all_charge_states(const model::charge_state cs) noexcept¶

Assigns one charge state to every SiDB.

Parameters:: cs – Charge state to assign.

inline const std::vector<model::charge_state> &charge_states() const noexcept¶

All charge states in raster order.

Returns:: The charge states.

inline double energy() const noexcept¶

The electrostatic potential energy of the distribution.

Returns:: Energy (unit: eV).

inline void assign_energy(const double e) noexcept¶

Sets the electrostatic potential energy of the distribution.

Parameters:: e – Energy (unit: eV).

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

Applies a function to the site of every SiDB in raster order.

Template Parameters:: Fn – Callable on (const lattice_site&).
Parameters:: fn – Function to apply.

inline bool charge_exists(const model::charge_state cs) const noexcept¶

Whether any SiDB has a given charge state.

Parameters:: cs – Charge state.
Returns:: true iff at least one SiDB is in state cs.

inline std::size_t num_negative_sidbs() const noexcept¶

Number of negatively charged SiDBs.

Returns:: Number of negatively charged SiDBs.

inline std::size_t num_neutral_sidbs() const noexcept¶

Number of neutrally charged SiDBs.

Returns:: Number of neutrally charged SiDBs.

inline std::size_t num_positive_sidbs() const noexcept¶

Number of positively charged SiDBs.

Returns:: Number of positively charged SiDBs.

inline uint64_t charge_index(const uint8_t base) const noexcept¶

The charge index: the distribution read as a number in the given base with the first SiDB as the most significant digit and digit sign + 1 per SiDB. The index wraps around past 64 base-2 digits, so it identifies distributions uniquely only for layouts of at most 64 (base 2) or 40 (base 3) SiDBs.

Parameters:: base – Base of the index, 2 or 3.
Returns:: The charge index.

inline bool same_charge_states(const charge_distribution &other) const noexcept¶

Compares two distributions for equal charge states, ignoring the energy.

Parameters:: other – Right-hand side distribution.
Returns:: true iff both assign the same charge states to the same number of SiDBs.

inline bool operator==(const charge_distribution &other) const noexcept¶

Compares two distributions: same charge states and same energy.

Parameters:: other – Right-hand side distribution.
Returns:: true iff charge states and energy are equal.

Python

class charge_distribution¶

class charge_distribution(layout: sidb_layout, charge_state: sidb_charge_state = sidb_charge_state.NEGATIVE)

assign_all_charge_states(charge_state: sidb_charge_state) → None¶

Assigns one charge state to every SiDB.

Parameters:: cs – Charge state to assign.

assign_charge_state(site: lattice_site, charge_state: sidb_charge_state) → None¶

Assigns the charge state of the SiDB at a site. A site the distribution does not cover is ignored.

Parameters:

s – Site.
cs – Charge state to assign.

assign_charge_state_by_index(index: int, charge_state: sidb_charge_state) → None¶

Assigns the charge state of the SiDB at an index.

Parameters:

index – Index in raster order.
cs – Charge state to assign.

Raises:

std::out_of_range – if the index is out of range.

assign_energy(energy: float) → None¶

Sets the electrostatic potential energy of the distribution.

Parameters:: e – Energy (unit: eV).

charge_exists(charge_state: sidb_charge_state) → bool¶

Whether any SiDB has a given charge state.

Parameters:: cs – Charge state.
Returns:: true iff at least one SiDB is in state cs.

charge_index(base: int) → int¶

or 40 (base 3) SiDBs.

Parameters:: base – Base of the index, 2 or 3.
Returns:: The charge index.

charge_states() → list[sidb_charge_state]¶

All charge states in raster order.

Returns:: The charge states.

empty() → bool¶

Whether the distribution covers no SiDB.

Returns:: true iff there is no SiDB.

energy() → float¶

The electrostatic potential energy of the distribution.

Returns:: eV).
Return type:: Energy (unit

get_charge_state(site: lattice_site) → sidb_charge_state¶

The charge state of the SiDB at a site.

Parameters:: s – Site.
Returns:: Charge state at s, charge_state::NONE if the distribution covers no SiDB at s.

get_charge_state_by_index(index: int) → sidb_charge_state¶

The charge state of the SiDB at an index.

Parameters:: index – Index in raster order.
Returns:: Charge state at index, charge_state::NONE if the index is out of range.

index_of(site: lattice_site) → int | None¶

The index of a site in the distribution.

Parameters:: s – Site.
Returns:: Index of s, or std::nullopt if the distribution covers no SiDB at s.

num_negative_sidbs() → int¶

Number of negatively charged SiDBs.

Returns:: Number of negatively charged SiDBs.

num_neutral_sidbs() → int¶

Number of neutrally charged SiDBs.

Returns:: Number of neutrally charged SiDBs.

num_positive_sidbs() → int¶

Number of positively charged SiDBs.

Returns:: Number of positively charged SiDBs.

same_charge_states(other: charge_distribution) → bool¶

Compares two distributions for equal charge states, ignoring the energy.

Parameters:: other – Right-hand side distribution.
Returns:: true iff both assign the same charge states to the same number of SiDBs.

sites() → list[lattice_site]¶

The sites the distribution covers, in raster order.

Returns:: The sites.

size() → int¶

Number of SiDBs.

Returns:: Number of SiDBs.

Gate-library Coordinates¶

SiDB gate libraries describe their gates on a grid whose rows are single SiDB rows. apply_gate_library maps these grid coordinates onto lattice sites with the following function.

Header: fiction/technology/sidb/lattice.hpp

template<typename Coordinate> constexpr lattice_site fiction::sidb::to_lattice_site(const Coordinate &c)¶

The site that a gate-library grid coordinate refers to. SiDB gate libraries describe gates on a grid whose rows are single SiDB rows, so row y becomes unit cell y / 2, basis site y mod 2.

Template Parameters:: Coordinate – Grid coordinate type, e.g., layouts::layout_base::coordinate.
Parameters:: c – Grid coordinate.
Throws:: std::out_of_range – if the row exceeds the range of lattice sites.
Returns:: The site of c.