fix(stim-parser): reject *pi in bare R_X/R_Y/R_Z/U3 args (half-turn double-scale)

Bare rotation/U3 args are in half-turns and get multiplied by pi when
lowering (R_Z(0.5) == I[R_Z(theta=0.5*pi)]). But args flow through the
generic pi_expr parser, so R_Z(0.5*pi) / R_Z(pi) were silently scaled by
pi twice (0.5*pi*pi instead of 0.5*pi) with no diagnostic — the inverse
of the ambiguity the *pi tag requirement was added to prevent.

args_block now carries a had_pi flag (via the existing pi_expr_flagged);
the validator rejects a *pi argument on the bare R_X/R_Y/R_Z/U3 mnemonics
with a clear half-turn-arg error. pi-expressions remain valid in args for
every other instruction (stim.rs compatibility, e.g. X_ERROR(0.5*pi)).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Roger-luo

crates/stim-parser/src/pipeline/lower.rs

@@ -767,6 +767,42 @@ mod tests {
         assert_eq!(err.last().unwrap().code, Some("invalid-tag"));
     }
 
+    #[test]
+    fn bare_rotation_with_pi_arg_is_rejected() {
+        // The bare arg is in half-turns and gets multiplied by pi when
+        // lowering, so `R_Z(0.5*pi)` would scale by pi twice. The `*pi` form
+        // is only valid in the tag (I[R_Z(theta=0.5*pi)]); reject it here.
+        for src in ["R_X(0.5*pi) 0", "R_Y(1*pi) 0", "R_Z(0.5*pi) 0", "R_Z(pi) 0"] {
+            let err = lower_extended(src).unwrap_err();
+            assert_eq!(err.last().unwrap().code, Some("half-turn-arg"), "src={src}");
+        }
+    }
+
+    #[test]
+    fn bare_u3_with_pi_arg_is_rejected() {
+        // Every U3 angle is in half-turns; a `*pi` (or bare `pi`) in any slot
+        // would double-scale.
+        for src in [
+            "U3(0.5*pi, 0.0, 0.0) 0",
+            "U3(0.0, 0.5*pi, 0.0) 0",
+            "U3(0.0, 0.0, pi) 0",
+        ] {
+            let err = lower_extended(src).unwrap_err();
+            assert_eq!(err.last().unwrap().code, Some("half-turn-arg"), "src={src}");
+        }
+    }
+
+    #[test]
+    fn bare_rotation_plain_arg_is_accepted() {
+        // The half-turn plain form is the canonical bare spelling and lowers
+        // to the same radians as the tagged `*pi` form.
+        let prog = lower_extended("R_Z(0.5) 0").expect("lower");
+        assert!(matches!(
+            &prog.instructions[0],
+            ExtendedInstruction::Rotation { axis: Axis::Z, .. }
+        ));
+    }
+
     #[test]
     fn bare_u3_with_tag_is_rejected() {
         let err = lower_extended("U3[foo](0.5, 1.0, 1.5) 0").unwrap_err();

crates/stim-parser/src/pipeline/validate.rs

@@ -14,7 +14,9 @@ use crate::ast::shared::{
 };
 use crate::ast::vanilla::{Instruction, Program};
 use crate::diagnostics::{Aborted, DiagnosticSink, LineMap, Span};
-use crate::instructions::{ArgCount, EntryKind, MeasureName, TableEntry, TargetArity, lookup};
+use crate::instructions::{
+    ArgCount, EntryKind, GateName, MeasureName, TableEntry, TargetArity, lookup,
+};
 use crate::syntax::{RawSyntaxNode, RawSyntaxTree, RawTarget};
 
 use super::emit_skip;
@@ -64,6 +66,7 @@ fn validate_node(
             name,
             tags,
             args,
+            args_had_pi,
             targets,
             span,
         } => {
@@ -148,6 +151,31 @@ fn validate_node(
                 );
             }
 
+            // Bare rotation/U3 mnemonics take their angle in half-turns and
+            // multiply by pi when lowering, so a `*pi` argument would be scaled
+            // by pi twice. The `*pi` form is a tag convention
+            // (`I[R_Z(theta=0.5*pi)]`); reject it on the bare gate with a clear
+            // message rather than silently double-scaling.
+            if args_had_pi
+                && matches!(
+                    entry.kind,
+                    EntryKind::Gate(
+                        GateName::RotX | GateName::RotY | GateName::RotZ | GateName::U3
+                    )
+                )
+            {
+                return emit_skip(
+                    sink,
+                    span,
+                    "half-turn-arg",
+                    format!(
+                        "'{canonical}' takes angle arguments in half-turns; remove the '*pi' \
+                         suffix (the '*pi' form is only valid in tags, e.g. \
+                         I[R_Z(theta=0.5*pi)])"
+                    ),
+                );
+            }
+
             let divisor = match target_rule {
                 TargetArity::Any => None,
                 TargetArity::AtLeastOne => Some(1),
@@ -339,6 +367,7 @@ mod tests {
             name: name.to_string(),
             tags: vec![],
             args,
+            args_had_pi: false,
             targets: targets
                 .into_iter()
                 .map(|t| RawTarget {
@@ -360,6 +389,7 @@ mod tests {
             name: name.to_string(),
             tags: vec![],
             args,
+            args_had_pi: false,
             targets: targets
                 .into_iter()
                 .map(|(text, span)| RawTarget {
@@ -376,6 +406,7 @@ mod tests {
             name: name.to_string(),
             tags,
             args: vec![],
+            args_had_pi: false,
             targets: vec![RawTarget {
                 text: "0".to_string(),
                 span: SimpleSpan::from(2..3),
@@ -454,6 +485,45 @@ mod tests {
         assert_eq!(items[0].code, Some("arg-count"));
     }
 
+    #[test]
+    fn rotation_gate_with_pi_arg_is_half_turn_arg_error() {
+        // A bare rotation/U3 mnemonic whose arg used the `*pi` form is
+        // rejected: the half-turn arg already gets multiplied by pi when
+        // lowering, so accepting `*pi` would double-scale.
+        let node = RawSyntaxNode::Instruction {
+            name: "R_Z".to_string(),
+            tags: vec![],
+            args: vec![std::f64::consts::PI],
+            args_had_pi: true,
+            targets: vec![RawTarget {
+                text: "0".to_string(),
+                span: SimpleSpan::from(0..1),
+            }],
+            span: SimpleSpan::from(0..3),
+        };
+        let items = collect_errors(vec![node], &lm());
+        assert_eq!(items[0].code, Some("half-turn-arg"));
+    }
+
+    #[test]
+    fn non_rotation_gate_keeps_pi_arg() {
+        // Only the bare rotation/U3 mnemonics reject `*pi` args; for everything
+        // else the pi-expression stays valid (stim.rs compatibility).
+        let node = RawSyntaxNode::Instruction {
+            name: "X_ERROR".to_string(),
+            tags: vec![],
+            args: vec![0.5 * std::f64::consts::PI],
+            args_had_pi: true,
+            targets: vec![RawTarget {
+                text: "0".to_string(),
+                span: SimpleSpan::from(0..1),
+            }],
+            span: SimpleSpan::from(0..7),
+        };
+        let prog = ok_program(vec![node], &lm());
+        assert!(matches!(&prog.instructions[0], Instruction::Noise(_)));
+    }
+
     #[test]
     fn target_pair_errors() {
         let items = collect_errors(

crates/stim-parser/src/syntax/grammar.rs

@@ -141,9 +141,14 @@ pub(crate) fn tags_block<'src>() -> impl Parser<'src, &'src str, Vec<Tag>, Extra
         .delimited_by(just('[').then(inline_pad()), inline_pad().then(just(']')))
 }
 
-/// `(pi_expr, pi_expr, ...)`.
-pub(crate) fn args_block<'src>() -> impl Parser<'src, &'src str, Vec<f64>, Extra<'src>> + Clone {
-    pi_expr()
+/// `(pi_expr, pi_expr, ...)`. Each argument is paired with whether it was
+/// written with the `*pi` (half-turn) form. Most callers ignore the flag,
+/// but the bare rotation mnemonics (`R_X`/`R_Y`/`R_Z`/`U3`) take their angle
+/// in half-turns and multiply by pi when lowering, so they reject a `*pi`
+/// argument — which would otherwise be multiplied by pi twice.
+pub(crate) fn args_block<'src>()
+-> impl Parser<'src, &'src str, Vec<(f64, bool)>, Extra<'src>> + Clone {
+    pi_expr_flagged()
         .separated_by(inline_pad().then(just(',')).then(inline_pad()))
         .allow_trailing()
         .collect::<Vec<_>>()
@@ -168,22 +173,21 @@ pub(crate) fn target_lexeme<'src>() -> impl Parser<'src, &'src str, RawTarget, E
         })
 }
 
-/// `<ident> [<tags>]? (<args>)?`. Returns name, tags, args, and the
-/// span of the identifier (used for line-number reporting).
+/// `<ident> [<tags>]? (<args>)?`. Returns name, tags, args, whether any
+/// argument used the `*pi` (half-turn) form, and the span of the identifier
+/// (used for line-number reporting).
 pub(crate) fn instruction_head<'src>()
--> impl Parser<'src, &'src str, (String, Vec<Tag>, Vec<f64>, SimpleSpan<usize>), Extra<'src>> + Clone
-{
+-> impl Parser<'src, &'src str, (String, Vec<Tag>, Vec<f64>, bool, SimpleSpan<usize>), Extra<'src>>
++ Clone {
     ident()
         .map_with(|name, e| (name, e.span()))
         .then(tags_block().or_not())
         .then(args_block().or_not())
         .map(|(((name, span), tags), args)| {
-            (
-                name,
-                tags.unwrap_or_default(),
-                args.unwrap_or_default(),
-                span,
-            )
+            let args = args.unwrap_or_default();
+            let args_had_pi = args.iter().any(|&(_, had_pi)| had_pi);
+            let values = args.into_iter().map(|(value, _)| value).collect();
+            (name, tags.unwrap_or_default(), values, args_had_pi, span)
         })
 }
 
@@ -212,10 +216,11 @@ pub(crate) fn instruction_line<'src>()
                 .collect::<Vec<RawTarget>>(),
         )
         .map(
-            |((name, tags, args, span), targets)| RawSyntaxNode::Instruction {
+            |((name, tags, args, args_had_pi, span), targets)| RawSyntaxNode::Instruction {
                 name,
                 tags,
                 args,
+                args_had_pi,
                 targets,
                 span,
             },
@@ -371,14 +376,21 @@ mod tests {
     #[test]
     fn args_block_parses_csv_floats() {
         let a = run(args_block(), "(0.1, 0.2, 0.3)");
-        assert_eq!(a, vec![0.1, 0.2, 0.3]);
+        // Each arg is paired with whether it used the `*pi` form (none here).
+        assert_eq!(a, vec![(0.1, false), (0.2, false), (0.3, false)]);
     }
 
     #[test]
     fn args_block_with_pi_exprs() {
-        let a = run(args_block(), "(pi, 0.5*pi)");
-        assert!((a[0] - std::f64::consts::PI).abs() < 1e-12);
-        assert!((a[1] - 0.5 * std::f64::consts::PI).abs() < 1e-12);
+        // Args still accept pi-expressions (for stim.rs compatibility); the
+        // `had_pi` flag records that they did so callers can reject it where
+        // the half-turn convention applies.
+        let a = run(args_block(), "(pi, 0.5*pi, 2.0)");
+        assert!((a[0].0 - std::f64::consts::PI).abs() < 1e-12);
+        assert!(a[0].1);
+        assert!((a[1].0 - 0.5 * std::f64::consts::PI).abs() < 1e-12);
+        assert!(a[1].1);
+        assert_eq!(a[2], (2.0, false));
     }
 
     #[test]
@@ -399,7 +411,7 @@ mod tests {
 
     #[test]
     fn instruction_head_with_tags_and_args() {
-        let (name, tags, args, _span) = run(instruction_head(), "S[T](0.5)");
+        let (name, tags, args, _had_pi, _span) = run(instruction_head(), "S[T](0.5)");
         assert_eq!(name, "S");
         assert_eq!(tags.len(), 1);
         assert_eq!(tags[0].name, "T");
@@ -408,7 +420,7 @@ mod tests {
 
     #[test]
     fn instruction_head_no_tags_no_args() {
-        let (name, tags, args, _span) = run(instruction_head(), "H");
+        let (name, tags, args, _had_pi, _span) = run(instruction_head(), "H");
         assert_eq!(name, "H");
         assert!(tags.is_empty());
         assert!(args.is_empty());

crates/stim-parser/src/syntax/raw.rs

@@ -17,6 +17,10 @@ pub(crate) enum RawSyntaxNode {
         name: String,
         tags: Vec<Tag>,
         args: Vec<f64>,
+        /// Whether any argument was written with the `*pi` (half-turn) form.
+        /// The bare rotation mnemonics (`R_X`/`R_Y`/`R_Z`/`U3`) reject it,
+        /// since they already scale their half-turn argument by pi.
+        args_had_pi: bool,
         targets: Vec<RawTarget>,
         span: SimpleSpan<usize>,
     },