diff --git a/include/backend/dd/DDSimDiagnostics.hpp b/include/backend/dd/DDSimDiagnostics.hpp index a174a67..ed40d5a 100644 --- a/include/backend/dd/DDSimDiagnostics.hpp +++ b/include/backend/dd/DDSimDiagnostics.hpp @@ -16,13 +16,37 @@ #include #include +/** + * @brief Represents an equality assertion that should be inserted into the + * program. + */ struct InsertEqualityAssertion { + + /** + * @brief The index of the instruction where the assertion should be inserted. + */ size_t instructionIndex; + + /** + * @brief The amplitudes that the assertion should check for equality. + */ std::vector amplitudes; + + /** + * @brief The similarity threshold for the assertion. + */ double similarity; + + /** + * @brief The target qubits of the assertion. + */ std::vector targets; - // Define operator== to support equality comparisons + /** + * @brief Check whether two InsertEqualityAssertion instances are equal. + * @param other The other InsertEqualityAssertion instance to compare with. + * @return True if the instances are equal, false otherwise. + */ bool operator==(const InsertEqualityAssertion& other) const { if (instructionIndex != other.instructionIndex || targets != other.targets) { @@ -78,9 +102,22 @@ struct DDDiagnostics { */ std::map>> actualQubits; + /** + * @brief Assertions that have been identified to be moved in the program. + */ std::vector> assertionsToMove; + + /** + * @brief The entanglement assertions that have been identified to be added to + * the program. + */ std::map, size_t>>> assertionsEntToInsert; + + /** + * @brief The equality assertions that have been identified to be added to the + * program. + */ std::map> assertionsEqToInsert; }; diff --git a/include/common/parsing/AssertionTools.hpp b/include/common/parsing/AssertionTools.hpp index eed9d98..b3c037a 100644 --- a/include/common/parsing/AssertionTools.hpp +++ b/include/common/parsing/AssertionTools.hpp @@ -5,15 +5,40 @@ #include +/** + * @brief Define a general commutation rule. + * + * @param name The name of the commutation rule. + * @param expression The expression that performs the check. + */ #define COMMUTATION_RULE_GENERAL(name, expression) \ COMMUTATION_RULE_TEMPLATE(Assertion, name, expression) +/** + * @brief Define a commutation rule for entanglement assertions. + * + * @param name The name of the commutation rule. + * @param expression The expression that performs the check. + */ #define COMMUTATION_RULE_ENT(name, expression) \ COMMUTATION_RULE_TEMPLATE(EntanglementAssertion, name, expression) +/** + * @brief Define a commutation rule for superposition assertions. + * + * @param name The name of the commutation rule. + * @param expression The expression that performs the check. + */ #define COMMUTATION_RULE_SUP(name, expression) \ COMMUTATION_RULE_TEMPLATE(SuperpositionAssertion, name, expression) +/** + * @brief Define a template for commutation rules. + * + * @param type The type of assertion to check. + * @param name The name of the commutation rule. + * @param expression The expression that performs the check. + */ #define COMMUTATION_RULE_TEMPLATE(type, name, expression) \ const auto name = [](const type* assertion, \ const std::string& instructionName, \ @@ -24,11 +49,32 @@ return expression; \ } +/** + * @brief The possible results of a commutation check. + * + * Can be either `Commutes`, `DoesNotCommute`, or `Unknown`. + */ enum class CommutationResult { + /** + * @brief Indicates that the instructions commute with certainty. + */ Commutes, + /** + * @brief Indicates that the instructions do not commute with certainty. + */ DoesNotCommute, + /** + * @brief Indicates that it cannot be said with certainty whether the + * instructions commute or not. + */ Unknown, }; +/** + * @brief Check if an assertion commutes with an instruction. + * @param assertion The assertion to check. + * @param instruction The instruction to check. + * @return True if the assertion commutes with the instruction, false otherwise. + */ bool doesCommute(const std::unique_ptr& assertion, const Instruction& instruction); diff --git a/include/frontend/cli/CliFrontEnd.hpp b/include/frontend/cli/CliFrontEnd.hpp index 493e27e..02fe572 100644 --- a/include/frontend/cli/CliFrontEnd.hpp +++ b/include/frontend/cli/CliFrontEnd.hpp @@ -55,5 +55,10 @@ class CliFrontEnd { */ void initCode(const char* code); + /** + * @brief Output a new code with updated assertions based on the assertion + * refinement rules. + * @param state The simulation state. + */ void suggestUpdatedAssertions(SimulationState* state); }; diff --git a/src/backend/dd/DDSimDiagnostics.cpp b/src/backend/dd/DDSimDiagnostics.cpp index 5bf5d6f..5d619e4 100644 --- a/src/backend/dd/DDSimDiagnostics.cpp +++ b/src/backend/dd/DDSimDiagnostics.cpp @@ -678,6 +678,12 @@ findUniquePath(const std::set>& graph, return path; } +/** + * @brief Suggest new assertions based on a failed entanglement assertion. + * @param self The diagnostics instance. + * @param instructionIndex The index of the assertion that failed. + * @param assertion The assertion that failed. + */ void suggestBasedOnFailedEntanglementAssertion( DDDiagnostics* self, size_t instructionIndex, const EntanglementAssertion* assertion) { @@ -753,6 +759,13 @@ void suggestBasedOnFailedEntanglementAssertion( } } +/** + * @brief Suggest new assertions based on the splitting of an equality + * assertion. + * @param self The diagnostics instance. + * @param instructionIndex The index of the assertion to split. + * @param assertion The assertion to split. + */ void suggestSplitEqualityAssertion( DDDiagnostics* self, size_t instructionIndex, const StatevectorEqualityAssertion* assertion) { diff --git a/src/common/parsing/AssertionTools.cpp b/src/common/parsing/AssertionTools.cpp index da8f4e9..a675634 100644 --- a/src/common/parsing/AssertionTools.cpp +++ b/src/common/parsing/AssertionTools.cpp @@ -68,6 +68,13 @@ static const std::vector& targets) { @@ -80,6 +87,13 @@ bool doesCommuteEnt(const EntanglementAssertion* assertion, return false; } +/** + * @brief Check if a superposition assertion commutes with an instruction. + * @param assertion The assertion to check. + * @param instructionName The name of the instruction to check. + * @param targets The targets of the instruction. + * @return True if the assertion commutes with the instruction, false otherwise. + */ bool doesCommuteSup(const SuperpositionAssertion* assertion, const std::string& instructionName, const std::vector& targets) { @@ -92,6 +106,12 @@ bool doesCommuteSup(const SuperpositionAssertion* assertion, return false; } +/** + * @brief Check if a general assertion commutes with an instruction. + * @param assertion The assertion to check. + * @param instruction The instruction to check in string form. + * @return True if the assertion commutes with the instruction, false otherwise. + */ bool doesCommute(const std::unique_ptr& assertion, const std::string& instruction) { const auto targets = parseParameters(instruction);