You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: language/directives.html
+36-12Lines changed: 36 additions & 12 deletions
Original file line number
Diff line number
Diff line change
@@ -35,19 +35,41 @@
35
35
36
36
<sectionid="directives">
37
37
<h1>Directives<aclass="headerlink" href="#directives" title="Link to this heading">¶</a></h1>
38
-
<p>OpenQASM supports directive mechanisms that allows other information to
38
+
<p>OpenQASM supports directive mechanisms that allow other information to
39
39
be included in the program. Directives are either pragmas or annotations.
40
40
Both are used to supply additional information to the compiler passes and the
41
41
target system or simulator. Ideally the meaning of the program does not change
42
42
if some or all of the directives are ignored, so they can be interpreted
43
43
at the discretion of the consuming process.</p>
44
+
<sectionid="pragma-and-annotation-namespacing">
45
+
<h2>Pragma and annotation namespacing<aclass="headerlink" href="#pragma-and-annotation-namespacing" title="Link to this heading">¶</a></h2>
46
+
<p>It is intended that different implementators of the specification might
47
+
define their own pragmas and annotations. This creates the possibility that
48
+
different implementations might define pragmas or annotations that collide.</p>
49
+
<p>To avoid such collisions we recommend that implementations namespace their
50
+
pragmas and annotations as follows:</p>
51
+
<ulclass="simple">
52
+
<li><p>Pragmas start with <cite>pragma <namespace>.<name>(.<name>)*</cite>.</p></li>
53
+
<li><p>Annotations start with <cite>@<namespace>.<name>(.<name>)*</cite>.</p></li>
54
+
</ul>
55
+
<p>Where <cite>namespace</cite> and <cite>name</cite> are valid OpenQASM identifiers.</p>
56
+
<p>If the pragma or annotation takes additional arguments the
57
+
final <cite><name></cite> should be followed by a single space before the
58
+
additional text.</p>
59
+
<p>The namespace should be a short name that identifies the organization that
60
+
defines behaviour of the pragmas and annotations contained within it.</p>
61
+
<p>The namespace <cite>openqasm</cite> is reserved for future use by the OpenQASM
62
+
specification.</p>
63
+
</section>
44
64
<sectionid="pragmas">
45
65
<h2>Pragmas<aclass="headerlink" href="#pragmas" title="Link to this heading">¶</a></h2>
46
66
<p>Pragma directives start with <codeclass="docutils literal notranslate"><spanclass="pre">pragma</span></code> and continue to the end of line. The
47
67
text after <codeclass="docutils literal notranslate"><spanclass="pre">pragma</span></code> is a single string, and parsing is left to the specific
48
-
implementation. Implementations may optionally choose to support the older <codeclass="docutils literal notranslate"><spanclass="pre">#pragma</span></code>
49
-
keyword as a custom extension.
50
-
Pragmas should be processed as soon as they are encountered; if a
68
+
implementation, although implementors are encourage to use the namespacing
69
+
described above.</p>
70
+
<p>Implementations may optionally choose to support the older <codeclass="docutils literal notranslate"><spanclass="pre">#pragma</span></code> keyword
71
+
as a custom extension.</p>
72
+
<p>Pragmas should be processed as soon as they are encountered; if a
51
73
pragma is not supported by a compiler pass it should be ignored and preserved
52
74
intact for future passes. Pragmas should avoid stateful or positional
53
75
interactions to avoid unexpected behaviors between included source files. If the
@@ -57,18 +79,18 @@ <h2>Pragmas<a class="headerlink" href="#pragmas" title="Link to this heading">¶
57
79
<p>*Note: The following examples are simply possible implementations, this
58
80
specification does not define any pragmas. Please consult your tool’s
59
81
documentation for supported pragmas.</p>
60
-
<divclass="highlight-qasm3 notranslate"><divclass="highlight"><pre><span></span><spanclass="cp">pragma</span> simulator noise model "qpu1.noise"
82
+
<divclass="highlight-qasm3 notranslate"><divclass="highlight"><pre><span></span><spanclass="cp">pragma</span>qiskit.simulator noise model "qpu1.noise"
61
83
</pre></div>
62
84
</div>
63
85
<p>Pragmas can also be used to specify system-level information or assertions for
@@ -78,7 +100,8 @@ <h2>Pragmas<a class="headerlink" href="#pragmas" title="Link to this heading">¶
78
100
<h2>Annotations<aclass="headerlink" href="#annotations" title="Link to this heading">¶</a></h2>
79
101
<p>Annotations can be added to supply additional information to the following
80
102
OpenQASM <codeclass="docutils literal notranslate"><spanclass="pre">statement</span></code> as defined in the grammar. Annotations will start with a
81
-
<codeclass="docutils literal notranslate"><spanclass="pre">@</span></code> symbol, have an identifying keyword and continue to the end of the line.</p>
103
+
<codeclass="docutils literal notranslate"><spanclass="pre">@</span></code> symbol, have a dotted list of identifying keywords and continue to the end
104
+
of the line.</p>
82
105
<p>Multiple annotations may be added to a single statement. No ordering or
83
106
interaction between annotations are prescribed by this specification.</p>
84
107
<p>*Note: The following examples are simply possible implementations, this
@@ -89,21 +112,21 @@ <h2>Annotations<a class="headerlink" href="#annotations" title="Link to this hea
0 commit comments