From 9f73676c97487d3661ca44d8070360be710c330d Mon Sep 17 00:00:00 2001 From: Marcel Walter Date: Wed, 22 Nov 2023 10:29:56 +0100 Subject: [PATCH] :art: Improve structure and documentation of the SiDB defects --- .../pyfiction/technology/sidb_defects.hpp | 4 +- docs/technology/defects.rst | 22 +-- include/fiction/technology/sidb_defects.hpp | 139 ++++++++++++------ test/technology/sidb_defects.cpp | 56 +++---- 4 files changed, 137 insertions(+), 84 deletions(-) diff --git a/bindings/pyfiction/include/pyfiction/technology/sidb_defects.hpp b/bindings/pyfiction/include/pyfiction/technology/sidb_defects.hpp index 3c0dbff09..43461869e 100644 --- a/bindings/pyfiction/include/pyfiction/technology/sidb_defects.hpp +++ b/bindings/pyfiction/include/pyfiction/technology/sidb_defects.hpp @@ -55,7 +55,9 @@ inline void sidb_defects(pybind11::module& m) ; - m.def("is_charged_defect", &fiction::is_charged_defect, "defect"_a, DOC(fiction_is_charged_defect)); + m.def("is_charged_defect_type", &fiction::is_charged_defect_type, "defect"_a, DOC(fiction_is_charged_defect)); + m.def("is_neutral_defect_type", &fiction::is_neutral_defect_type, "defect"_a, DOC(fiction_is_neutral_defect)); + m.def("is_positively_charged_defect", &fiction::is_positively_charged_defect, "defect"_a, DOC(fiction_is_positively_charged_defect)); m.def("is_negatively_charged_defect", &fiction::is_negatively_charged_defect, "defect"_a, diff --git a/docs/technology/defects.rst b/docs/technology/defects.rst index 752075f3a..f41764d85 100644 --- a/docs/technology/defects.rst +++ b/docs/technology/defects.rst @@ -15,11 +15,12 @@ SiDB Defect Types .. doxygenstruct:: fiction::sidb_defect :members: - .. doxygenfunction:: fiction::is_charged_defect + .. doxygenfunction:: fiction::is_charged_defect_type + .. doxygenfunction:: fiction::is_neutral_defect_type + .. doxygenfunction:: fiction::is_positively_charged_defect .. doxygenfunction:: fiction::is_negatively_charged_defect .. doxygenfunction:: fiction::is_neutrally_charged_defect - .. doxygenfunction:: fiction::is_neutral_defect .. doxygenvariable:: fiction::SIDB_CHARGED_DEFECT_HORIZONTAL_SPACING .. doxygenvariable:: fiction::SIDB_CHARGED_DEFECT_VERTICAL_SPACING @@ -29,19 +30,20 @@ SiDB Defect Types .. doxygenfunction:: fiction::defect_extent .. tab:: Python - .. autoclass:: fiction.technology.sidb_defect_type + .. autoclass:: fiction.pyfiction.sidb_defect_type :members: - .. autoclass:: fiction.technology.sidb_defect + .. autoclass:: fiction.pyfiction.sidb_defect :members: - .. autofunction:: fiction.technology.is_charged_defect - .. autofunction:: fiction.technology.is_positively_charged_defect - .. autofunction:: fiction.technology.is_negatively_charged_defect - .. autofunction:: fiction.technology.is_neutrally_charged_defect - .. autofunction:: fiction.technology.is_neutral_defect + .. autofunction:: fiction.pyfiction.is_charged_defect_type + .. autofunction:: fiction.pyfiction.is_neutral_defect_type + + .. autofunction:: fiction.pyfiction.is_positively_charged_defect + .. autofunction:: fiction.pyfiction.is_negatively_charged_defect + .. autofunction:: fiction.pyfiction.is_neutrally_charged_defect - .. autofunction:: fiction.technology.defect_extent + .. autofunction:: fiction.pyfiction.defect_extent SiDB Defect Surface diff --git a/include/fiction/technology/sidb_defects.hpp b/include/fiction/technology/sidb_defects.hpp index a7433839a..82ae832fd 100644 --- a/include/fiction/technology/sidb_defects.hpp +++ b/include/fiction/technology/sidb_defects.hpp @@ -20,20 +20,62 @@ namespace fiction */ enum class sidb_defect_type { - NONE, // H-Si - DB, // an extra dangling bond - SI_VACANCY, // missing silicon - SINGLE_DIHYDRIDE, // double hydrogen passivation - DIHYDRIDE_PAIR, // missing bond between dimers leading to two double hydrogen passivations - ONE_BY_ONE, // collection of dihydride pairs - THREE_BY_ONE, // collection of 1 by 1's - SILOXANE, // oxidized dimer - RAISED_SI, // raised silicon dimer - MISSING_DIMER, // dimer missing altogether - ETCH_PIT, // collection of missing dimers - STEP_EDGE, // break in the surface - GUNK, // residual material - UNKNOWN // unknown defect + /** + * Defect-free H-Si. + */ + NONE, + /** + * A stray dangling bond. + */ + DB, + /** + * A missing silicon atom. + */ + SI_VACANCY, + /** + * Double hydrogen passivation. + */ + SINGLE_DIHYDRIDE, + /** + * A missing bond between dimers that leads to two double hydrogen passivations. + */ + DIHYDRIDE_PAIR, + /** + * A collection of dihydride pairs. + */ + ONE_BY_ONE, + /** + * A collection of 1 by 1's. + */ + THREE_BY_ONE, + /** + * An oxidized dimer. + */ + SILOXANE, + /** + * A raised silicon dimer. + */ + RAISED_SI, + /** + * The dimer is missing altogether. + */ + MISSING_DIMER, + /** + * A collection of missing dimers. + */ + ETCH_PIT, + /** + * A step edge, which is a break in the surface reconstruction. + */ + STEP_EDGE, + /** + * Residual material. + */ + GUNK, + /** + * Unknown defect. + */ + UNKNOWN }; /** * In accordance with the paper mentioned above, the `sidb_defect` struct is used to represent a specific defect on the @@ -77,16 +119,20 @@ struct sidb_defect */ double lambda_tf; /** - * This operator compares two sidb_defect instances for equality. It checks if the type, charge, - * epsilon_r, and lambda_tf members of the two instances are equal. + * This operator compares two `sidb_defect` instances for equality. It checks if the `type`, `charge`, + * `epsilon_r`, and `lambda_tf` members of the two instances are equal. + * + * @param rhs `sidb_defect` instance to compare against. */ constexpr bool operator==(const sidb_defect& rhs) const noexcept { return type == rhs.type && charge == rhs.charge && epsilon_r == rhs.epsilon_r && lambda_tf == rhs.lambda_tf; } /** - * This operator compares two sidb_defect instances for inequality. It uses the operator== to check + * This operator compares two `sidb_defect` instances for inequality. It uses the `operator==` to check * if the two instances are equal and returns the negation of the result. + * + * @param rhs `sidb_defect` instance to compare against. */ constexpr bool operator!=(const sidb_defect& rhs) const noexcept { @@ -94,58 +140,61 @@ struct sidb_defect } }; /** - * Checks whether the given defect is charged. Charged defects are to be avoided by a larger distance. + * Checks whether the given defect type is a charged one. `DB` and `SI_VACANCY` types are charged. Those charged defects + * are to be avoided by a larger distance. * - * @param defect Defect type to check. - * @return `true` iff defect is charged. + * @param defect Defect to check. + * @return `true` iff `defect` is of a charged type. */ -[[nodiscard]] static constexpr bool is_charged_defect(const sidb_defect& defect) noexcept +[[nodiscard]] static constexpr bool is_charged_defect_type(const sidb_defect& defect) noexcept { return defect.type == sidb_defect_type::DB || defect.type == sidb_defect_type::SI_VACANCY; } /** - * Checks whether the given defect is positively charged. + * Checks whether the given defect type is not a charged one. Neutral defects are to be avoided as well, but not by such + * a large distance. Even though the `NONE` defect type is technically neutral, it is not a defect per se which is why + * this function returns false on the `NONE` defect input. + * + * @param defect Defect to check. + * @return `true` iff `defect` is not of a charged type. + */ +[[nodiscard]] static constexpr bool is_neutral_defect_type(const sidb_defect& defect) noexcept +{ + return defect.type != sidb_defect_type::NONE && !is_charged_defect_type(defect); +} +/** + * Checks whether the given defect has a positive charge value assigned to it. This function is irrespective of the + * associated defect type. * * @param defect Defect to check. - * @return `true` iff defect is positively charged. + * @return `true` iff `defect` has a positive charge value. */ [[nodiscard]] static constexpr bool is_positively_charged_defect(const sidb_defect& defect) noexcept { return defect.charge > 0; } /** - * Checks whether the given defect is negatively charged. + * Checks whether the given defect has a negative charge value assigned to it. This function is irrespective of the + * associated defect type. * * @param defect Defect to check. - * @return `true` iff defect is negatively charged. + * @return `true` iff `defect` has a negative charge value. */ [[nodiscard]] static constexpr bool is_negatively_charged_defect(const sidb_defect& defect) noexcept { return defect.charge < 0; } /** - * Checks whether the given defect is neutrally charged. + * Checks whether the given defect has a neutral charge value, i.e., `0`, assigned to it. This function is irrespective + * of the associated defect type. * * @param defect Defect to check. - * @return `true` iff defect is neutrally charged. + * @return `true` iff `defect` has a neutral charge value. */ [[nodiscard]] static constexpr bool is_neutrally_charged_defect(const sidb_defect& defect) noexcept { return defect.charge == 0; } -/** - * Checks whether the given defect is not charged. Neutral defects are to be avoided but not by such a large distance. - * Even though the `NONE` defect type is technically neutral, it is not a defect per se which is why this function - * returns false on the `NONE` defect input. Additionally, the `UNKNOWN` defect cannot be guaranteed to be either - * neutral or charged which is why this function returns false for `UNKNOWN` defect inputs as well. - * - * @param defect Defect type to check. - * @return `true` iff defect is not charged. - */ -[[nodiscard]] static constexpr bool is_neutral_defect(const sidb_defect& defect) noexcept -{ - return defect.type != sidb_defect_type::NONE && !is_charged_defect(defect); -} /** * Horizontal distance to keep from charged SiDB defects. The value is to be understood as the number of DB positions * rather than the number of dimers. This is true even though each defect always affects the entire dimer. @@ -167,19 +216,19 @@ inline constexpr const uint16_t SIDB_NEUTRAL_DEFECT_HORIZONTAL_SPACING = 1u; */ inline constexpr const uint16_t SIDB_NEUTRAL_DEFECT_VERTICAL_SPACING = 0u; /** - * Returns the extent of a defect as a pair of SiDB distances in horizontal and vertical direction. If defect is the + * Returns the extent of a defect as a pair of SiDB distances in horizontal and vertical direction. If `defect` has the * `NONE` defect type, `{0, 0}` is returned. * - * @param defect Defect type to evaluate. - * @return Number of horizontal and vertical SiDBs that are affected by the given defect type. + * @param defect Defect to evaluate. + * @return Number of horizontal and vertical SiDBs that are affected by the given defect. */ [[nodiscard]] static constexpr std::pair defect_extent(const sidb_defect& defect) noexcept { - if (is_charged_defect(defect)) + if (is_charged_defect_type(defect)) { return {SIDB_CHARGED_DEFECT_HORIZONTAL_SPACING, SIDB_CHARGED_DEFECT_VERTICAL_SPACING}; } - if (is_neutral_defect(defect)) + if (is_neutral_defect_type(defect)) { return {SIDB_NEUTRAL_DEFECT_HORIZONTAL_SPACING, SIDB_NEUTRAL_DEFECT_VERTICAL_SPACING}; } diff --git a/test/technology/sidb_defects.cpp b/test/technology/sidb_defects.cpp index b83e1209a..7e72c1515 100644 --- a/test/technology/sidb_defects.cpp +++ b/test/technology/sidb_defects.cpp @@ -10,35 +10,35 @@ using namespace fiction; TEST_CASE("Charged and uncharged defect types", "[sidb-defects]") { - CHECK(!is_charged_defect(sidb_defect{sidb_defect_type::NONE})); - CHECK(is_charged_defect(sidb_defect{sidb_defect_type::DB})); - CHECK(is_charged_defect(sidb_defect{sidb_defect_type::SI_VACANCY})); - CHECK(!is_charged_defect(sidb_defect{sidb_defect_type::SINGLE_DIHYDRIDE})); - CHECK(!is_charged_defect(sidb_defect{sidb_defect_type::DIHYDRIDE_PAIR})); - CHECK(!is_charged_defect(sidb_defect{sidb_defect_type::ONE_BY_ONE})); - CHECK(!is_charged_defect(sidb_defect{sidb_defect_type::THREE_BY_ONE})); - CHECK(!is_charged_defect(sidb_defect{sidb_defect_type::SILOXANE})); - CHECK(!is_charged_defect(sidb_defect{sidb_defect_type::RAISED_SI})); - CHECK(!is_charged_defect(sidb_defect{sidb_defect_type::MISSING_DIMER})); - CHECK(!is_charged_defect(sidb_defect{sidb_defect_type::ETCH_PIT})); - CHECK(!is_charged_defect(sidb_defect{sidb_defect_type::STEP_EDGE})); - CHECK(!is_charged_defect(sidb_defect{sidb_defect_type::GUNK})); - CHECK(!is_charged_defect(sidb_defect{sidb_defect_type::UNKNOWN})); + CHECK(!is_charged_defect_type(sidb_defect{sidb_defect_type::NONE})); + CHECK(is_charged_defect_type(sidb_defect{sidb_defect_type::DB})); + CHECK(is_charged_defect_type(sidb_defect{sidb_defect_type::SI_VACANCY})); + CHECK(!is_charged_defect_type(sidb_defect{sidb_defect_type::SINGLE_DIHYDRIDE})); + CHECK(!is_charged_defect_type(sidb_defect{sidb_defect_type::DIHYDRIDE_PAIR})); + CHECK(!is_charged_defect_type(sidb_defect{sidb_defect_type::ONE_BY_ONE})); + CHECK(!is_charged_defect_type(sidb_defect{sidb_defect_type::THREE_BY_ONE})); + CHECK(!is_charged_defect_type(sidb_defect{sidb_defect_type::SILOXANE})); + CHECK(!is_charged_defect_type(sidb_defect{sidb_defect_type::RAISED_SI})); + CHECK(!is_charged_defect_type(sidb_defect{sidb_defect_type::MISSING_DIMER})); + CHECK(!is_charged_defect_type(sidb_defect{sidb_defect_type::ETCH_PIT})); + CHECK(!is_charged_defect_type(sidb_defect{sidb_defect_type::STEP_EDGE})); + CHECK(!is_charged_defect_type(sidb_defect{sidb_defect_type::GUNK})); + CHECK(!is_charged_defect_type(sidb_defect{sidb_defect_type::UNKNOWN})); - CHECK(!is_neutral_defect(sidb_defect{sidb_defect_type::NONE})); - CHECK(!is_neutral_defect(sidb_defect{sidb_defect_type::DB})); - CHECK(!is_neutral_defect(sidb_defect{sidb_defect_type::SI_VACANCY})); - CHECK(is_neutral_defect(sidb_defect{sidb_defect_type::SINGLE_DIHYDRIDE})); - CHECK(is_neutral_defect(sidb_defect{sidb_defect_type::DIHYDRIDE_PAIR})); - CHECK(is_neutral_defect(sidb_defect{sidb_defect_type::ONE_BY_ONE})); - CHECK(is_neutral_defect(sidb_defect{sidb_defect_type::THREE_BY_ONE})); - CHECK(is_neutral_defect(sidb_defect{sidb_defect_type::SILOXANE})); - CHECK(is_neutral_defect(sidb_defect{sidb_defect_type::RAISED_SI})); - CHECK(is_neutral_defect(sidb_defect{sidb_defect_type::MISSING_DIMER})); - CHECK(is_neutral_defect(sidb_defect{sidb_defect_type::ETCH_PIT})); - CHECK(is_neutral_defect(sidb_defect{sidb_defect_type::STEP_EDGE})); - CHECK(is_neutral_defect(sidb_defect{sidb_defect_type::GUNK})); - CHECK(is_neutral_defect(sidb_defect{sidb_defect_type::UNKNOWN})); + CHECK(!is_neutral_defect_type(sidb_defect{sidb_defect_type::NONE})); + CHECK(!is_neutral_defect_type(sidb_defect{sidb_defect_type::DB})); + CHECK(!is_neutral_defect_type(sidb_defect{sidb_defect_type::SI_VACANCY})); + CHECK(is_neutral_defect_type(sidb_defect{sidb_defect_type::SINGLE_DIHYDRIDE})); + CHECK(is_neutral_defect_type(sidb_defect{sidb_defect_type::DIHYDRIDE_PAIR})); + CHECK(is_neutral_defect_type(sidb_defect{sidb_defect_type::ONE_BY_ONE})); + CHECK(is_neutral_defect_type(sidb_defect{sidb_defect_type::THREE_BY_ONE})); + CHECK(is_neutral_defect_type(sidb_defect{sidb_defect_type::SILOXANE})); + CHECK(is_neutral_defect_type(sidb_defect{sidb_defect_type::RAISED_SI})); + CHECK(is_neutral_defect_type(sidb_defect{sidb_defect_type::MISSING_DIMER})); + CHECK(is_neutral_defect_type(sidb_defect{sidb_defect_type::ETCH_PIT})); + CHECK(is_neutral_defect_type(sidb_defect{sidb_defect_type::STEP_EDGE})); + CHECK(is_neutral_defect_type(sidb_defect{sidb_defect_type::GUNK})); + CHECK(is_neutral_defect_type(sidb_defect{sidb_defect_type::UNKNOWN})); } TEST_CASE("Defect extent", "[sidb-defects]")