From ce39a855047fd1be7f7a47d1e5fc75b7ca9ee941 Mon Sep 17 00:00:00 2001 From: Fabian Hingerl Date: Thu, 26 Feb 2026 20:23:25 +0100 Subject: [PATCH 1/4] Added notice about potentially unexpected index-out-of-range-errors during inversion of ForStatement during synthesis of UncallStatement --- docs/syrec_language_semantics.md | 33 ++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/docs/syrec_language_semantics.md b/docs/syrec_language_semantics.md index f807b970f..631626469 100644 --- a/docs/syrec_language_semantics.md +++ b/docs/syrec_language_semantics.md @@ -275,6 +275,39 @@ The parser will not report an overlap in the assignment due to the index of the - The value of the step size of a ForStatement cannot be defined as or evaluate to 0 to prevent an infinite loop. +````{warning} + +Uncalling modules containing a _ForStatement_ could lead to unexpected index-out-of-range errors if one is not familiar with the semantics of how a _ForStatement_ or more specifically its value range is inverted, with the inversion semantics being inherited by SyReC from its reversible programming language predecessor Janus {cite:p}`yokoyama2007janus`. + +A loop (_ForStatement_) defined as {math}`for \ e_1 \ to \ e_2 \ step \ s \ do \ s_1, s_2, \dots, s_n \ rof` +is inverted by inverting not only the sequence of statements in its loop body but also by inverting its value range thus the inversion of the given loop is equal to +{math}`for \ e_2 \ to \ e_1 \ step \ s \ do \ {s_n}^{-1}, \dots, {s_2}^{-1}, {s_1}^{-1} \ rof`. + +The inversion result of the _ForStatement_ as well as its enclosing module `basicBitwiseIncr` is equal to the module `invrBitwiseIncr` with both modules being shown in the example below: + +```text +module basicBitwiseIncr(inout a(4), inout b(4)) +for $i = 0 to #a do + ++= a.$i; + --= b.$i +rof + +// Inversion of basicBitwiseIncr equal to "uncall basicBitwiseIncr(a, b)" +module invrBitwiseIncr(inout a(4), inout b(4)) +for $i = #a to 0 do + ++= b.$i; + --= a.$i +rof + +module main(inout a(4), inout b(4)) + // An index-out-of-range error would be reported here due to the value range of the ForStatement of the uncalled module + // being inverted with the loop variable $i being initialized with #a instead of 0 in the inverted ForStatement thus the assignments + // ++b.$i and --= a.$i would both result in an index-out-of-range error. + uncall basicBitwiseIncr(a, b) +``` + +```` + ### IfStatement - The components of an IfStatement will be referred to as _if then else fi Date: Thu, 26 Feb 2026 21:26:03 +0100 Subject: [PATCH 2/4] Fixed small typos and updated module names in examples of newly added warning section of ForStatement --- docs/syrec_language_semantics.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/syrec_language_semantics.md b/docs/syrec_language_semantics.md index 631626469..2ffa02834 100644 --- a/docs/syrec_language_semantics.md +++ b/docs/syrec_language_semantics.md @@ -283,7 +283,7 @@ A loop (_ForStatement_) defined as {math}`for \ e_1 \ to \ e_2 \ step \ s \ do \ is inverted by inverting not only the sequence of statements in its loop body but also by inverting its value range thus the inversion of the given loop is equal to {math}`for \ e_2 \ to \ e_1 \ step \ s \ do \ {s_n}^{-1}, \dots, {s_2}^{-1}, {s_1}^{-1} \ rof`. -The inversion result of the _ForStatement_ as well as its enclosing module `basicBitwiseIncr` is equal to the module `invrBitwiseIncr` with both modules being shown in the example below: +The inversion result of the _ForStatement_ as well as its enclosing module `basicBitwiseIncr` is equal to the module `invrBasicBitwiseIncr` with both modules being shown in the example below: ```text module basicBitwiseIncr(inout a(4), inout b(4)) @@ -293,7 +293,7 @@ for $i = 0 to #a do rof // Inversion of basicBitwiseIncr equal to "uncall basicBitwiseIncr(a, b)" -module invrBitwiseIncr(inout a(4), inout b(4)) +module invrBasicBitwiseIncr(inout a(4), inout b(4)) for $i = #a to 0 do ++= b.$i; --= a.$i @@ -302,7 +302,7 @@ rof module main(inout a(4), inout b(4)) // An index-out-of-range error would be reported here due to the value range of the ForStatement of the uncalled module // being inverted with the loop variable $i being initialized with #a instead of 0 in the inverted ForStatement thus the assignments - // ++b.$i and --= a.$i would both result in an index-out-of-range error. + // ++= b.$i and --= a.$i would both result in an index-out-of-range error. uncall basicBitwiseIncr(a, b) ``` From 3772bb2eaa25283f0398556a0c332086ea949d9d Mon Sep 17 00:00:00 2001 From: Fabian Hingerl Date: Fri, 27 Feb 2026 09:43:42 +0100 Subject: [PATCH 3/4] Fixed library documentation that still used snake_casing instead of PascalCasing were appropriate --- docs/library/AnnotatableQuantumComputation.rst | 4 ++-- docs/library/ConfigurableOptions.rst | 4 ++-- docs/library/InlinedQubitInformation.rst | 6 +++--- docs/library/NBitValuesContainer.rst | 2 +- docs/library/Parser.rst | 2 +- docs/library/Statistics.rst | 2 +- 6 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/library/AnnotatableQuantumComputation.rst b/docs/library/AnnotatableQuantumComputation.rst index 9b7222641..43f42b50d 100644 --- a/docs/library/AnnotatableQuantumComputation.rst +++ b/docs/library/AnnotatableQuantumComputation.rst @@ -3,12 +3,12 @@ AnnotatableQuantumComputation The following enum defines the possible qubit label types that can be generated for a qubit of the annotatable quantum computation - .. autoclass:: mqt.syrec.qubit_label_type + .. autoclass:: mqt.syrec.QubitLabelType :undoc-members: :members: A class to build a MQT::Core QuantumComputation that also offers functionality to annotate its quantum operations with string key value pairs. - .. autoclass:: mqt.syrec.annotatable_quantum_computation + .. autoclass:: mqt.syrec.AnnotatableQuantumComputation :undoc-members: :members: diff --git a/docs/library/ConfigurableOptions.rst b/docs/library/ConfigurableOptions.rst index 74c3a47be..a8788183a 100644 --- a/docs/library/ConfigurableOptions.rst +++ b/docs/library/ConfigurableOptions.rst @@ -3,12 +3,12 @@ ConfigurableOptions An object that provides read and write access to the configurable options of the SyReC parser and the various supported synthesis algorithms. - .. autoclass:: mqt.syrec.configurable_options + .. autoclass:: mqt.syrec.ConfigurableOptions :undoc-members: :members: The following enum defines the integer constant truncation operations supported by the SyReC parser and the various supported synthesis algorithms. - .. autoclass:: mqt.syrec.pysyrec.integer_constant_truncation_operation + .. autoclass:: mqt.syrec.IntegerConstantTruncationOperation :undoc-members: :members: diff --git a/docs/library/InlinedQubitInformation.rst b/docs/library/InlinedQubitInformation.rst index ee717e1b6..18ed91e9a 100644 --- a/docs/library/InlinedQubitInformation.rst +++ b/docs/library/InlinedQubitInformation.rst @@ -3,19 +3,19 @@ InlinedQubitInformation Stores debug information about the ancillary and local module variable qubits that can be used to determine the origin of the qubit in the SyReC program or to determine the user declared identifier of the associated variable for a qubit. This information is not available for the parameters of a SyReC module. - .. autoclass:: mqt.syrec.inlined_qubit_information + .. autoclass:: mqt.syrec.InlinedQubitInformation :undoc-members: :members: Utility class to track the origin of a qubit in a hierarchy of Call-/UncallStatements. - .. autoclass:: mqt.syrec.qubit_inlining_stack + .. autoclass:: mqt.syrec.QubitInliningStack :undoc-members: :members: :special-members: __getitem__ Contains information about the source code line as well as the type of call performed to call/uncall the target module. - .. autoclass:: mqt.syrec.qubit_inlining_stack_entry + .. autoclass:: mqt.syrec.QubitInliningStackEntry :undoc-members: :members: diff --git a/docs/library/NBitValuesContainer.rst b/docs/library/NBitValuesContainer.rst index d46a7bdba..c373695fe 100644 --- a/docs/library/NBitValuesContainer.rst +++ b/docs/library/NBitValuesContainer.rst @@ -3,6 +3,6 @@ NBitValuesContainer Simplified reimplementation of boost::dynamic_bitset<>. - .. autoclass:: mqt.syrec.n_bit_values_container + .. autoclass:: mqt.syrec.NBitValuesContainer :undoc-members: :members: diff --git a/docs/library/Parser.rst b/docs/library/Parser.rst index 8e9e84c78..684e32150 100644 --- a/docs/library/Parser.rst +++ b/docs/library/Parser.rst @@ -3,6 +3,6 @@ Parser This class is the superclass providing template functionality needed for parsing every SyReC program. - .. autoclass:: mqt.syrec.program + .. autoclass:: mqt.syrec.Program :undoc-members: :members: diff --git a/docs/library/Statistics.rst b/docs/library/Statistics.rst index d9a76f487..08f1bae95 100644 --- a/docs/library/Statistics.rst +++ b/docs/library/Statistics.rst @@ -3,6 +3,6 @@ Statistics An object that stores statistics collected during parsing/synthesis. - .. autoclass:: mqt.syrec.statistics + .. autoclass:: mqt.syrec.Statistics :undoc-members: :members: From 3b5e69e8d12305743a16bf3b4b8b0affc8c87cfa Mon Sep 17 00:00:00 2001 From: Fabian Hingerl Date: Fri, 27 Feb 2026 09:51:00 +0100 Subject: [PATCH 4/4] Renamed Parser.rst to Program.rst for consistency between the documentation and the actual python bindings --- docs/library/Library.rst | 2 +- docs/library/{Parser.rst => Program.rst} | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) rename docs/library/{Parser.rst => Program.rst} (91%) diff --git a/docs/library/Library.rst b/docs/library/Library.rst index 3ca1e2c2e..0d7985875 100644 --- a/docs/library/Library.rst +++ b/docs/library/Library.rst @@ -7,7 +7,7 @@ Library AnnotatableQuantumComputation ConfigurableOptions NBitValuesContainer - Parser + Program InlinedQubitInformation Simulation Statistics diff --git a/docs/library/Parser.rst b/docs/library/Program.rst similarity index 91% rename from docs/library/Parser.rst rename to docs/library/Program.rst index 684e32150..54d90ec79 100644 --- a/docs/library/Parser.rst +++ b/docs/library/Program.rst @@ -1,5 +1,5 @@ -Parser -====== +Program +======= This class is the superclass providing template functionality needed for parsing every SyReC program.