Stim compiler by joao-boechat · Pull Request #3305 · microsoft/qdk

joao-boechat · 2026-06-11T19:54:20Z

This is an initial PR for the Stim compiler, which includes the setup for supporting the language. We still will need to add tests, better error handling, more language features, among other things, but the compiler introduced by this PR is supposed to be fully functional and minimally faulty.

All of the code was designed around the stim language, which is mostly defined by these two documents:

Stim/doc/file_format_stim_circuit.md at main · quantumlib/Stim
Stim/doc/gates.md at main · quantumlib/Stim

amcasey

Some questions about the lexer. I'm just learning, so don't take any of this as blocking.

amcasey · 2026-06-15T16:40:13Z

+};
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct Token {


Is there a concept of a known-but-erroneous token? For example, in many languages 0.2 is valid, but .2 is not, but you'd want both to appear as Double tokens for error recovery purposes. (This is almost certainly out of scope for this proof-of-concept implementation.)

amcasey · 2026-06-15T16:47:08Z

+        self.eat_while(|c| c.is_ascii_digit());
+        let mut is_double = false;
+        if self.chars.next_if(|(_, c)| *c == '.').is_some() {
+            self.eat_while(|c| c.is_ascii_digit());


Is this guaranteed to consume at least one digit? Or does the language allow 2. as a valid double?

Looks like we allow scientific notation. Surely, 2.e isn't allowed?

amcasey · 2026-06-15T16:49:11Z

+        self.whitespace();
+    }
+
+    fn scan_number(&mut self) -> TokenKind {


Can there be a sign for the whole number? +2?

nope! numbers are very basic in stim, nothing fancy (not even computations)

So, to confirm, there are no negative angles? You have to normalize to a positive angle?

amcasey · 2026-06-15T16:49:41Z

+    }
+
+    fn scan_identifier(&mut self, lo: usize) -> TokenKind {
+        self.eat_while(|c| c.is_alphanumeric() || c == '_');


A lot of languages don't allow identifiers to start with digits. Not sure if that's true of stim.

It is! per their grammar this is what a name can be: [a-zA-Z][a-zA-Z0-9_]*
granted the "identifier" concept isn't exactly from stim, but I used it to simplify the code. Will have to revisit it later for correctness, though

The regex you provided doesn't seem to allow the identifier to start with a digit.

amcasey · 2026-06-15T16:51:14Z

+            .map_or(self.input_len as usize, |(i, _)| *i);
+        // TODO: What if some identifier starts with "rec" but is not a rec token?
+        match &self.input[lo..hi] {
+            "rec" => {


I'm probably just blanking, but where did we check for the open [?

The three cases we could have [] are:
1- rec[...]
2- sweep[...]
3- tags! For example in the statement: X_ERRORa 3 4

But parsing the brackets individually added a ton of complexity to distinguish between these three cases, so I chose to just consume them as a whole with those tokens, and then strip them away for the content. Will also revisit this later!

I'm not sure I understand the complexity. But it looks like maybe the single token includes the contents of the square brackets and isn't a keyword followed by punctuation, etc?

amcasey · 2026-06-15T16:53:11Z

+        while self.chars.next_if(|i| f(i.1)).is_some() {}
+    }
+
+    fn whitespace(&mut self) {


Is this going to consume newlines without creating corresponding tokens?

amcasey

Parser comments. Still non-blocking. Happy to chat if my questions don't make sense (which is reasonably likely).

amcasey · 2026-06-15T18:33:14Z

+
+#[derive(Debug)]
+pub struct Line {
+    pub span: Span,


Is this different from the span that's in the Instruction?

amcasey · 2026-06-15T18:37:13Z

+                None => break,
+            }
+        }
+        let closing_brace = self.expect(TokenKind::Close(Brace));


In the future, we might want to synthesize a missing closing brace for recovery purposes.

amcasey · 2026-06-15T18:38:00Z

+    }
+
+    fn parse_line(&mut self, instruction: Instruction) -> Line {
+        self.expect(TokenKind::Newline);


Personally, I find it a little strange to start a line with a newline, rather than end it with a newline. Does this cause any problems at file boundaries?

amcasey · 2026-06-15T18:40:35Z

+    }
+
+    fn extract_uint(&mut self, token: Token, span: Option<Span>) -> u32 {
+        self.extract_string(token, span).parse().unwrap()


I think this panics if the number is too large to fit in a u32, for example?

billti · 2026-06-16T16:42:02Z

+from typing import List, Literal, Optional, Tuple
+
+
+def compile(src: str, noise: Optional[NoiseConfig]) -> Tuple[str, NoiseConfig]:


I'm not a fan of this returning a tuple. I keep forgetting to destructure the results and wondering why I have a list. Also qsharp.compile and openqasm.compile return a QirInputData. We should be consistent.

(It's OK if we return the QIR string for now rather than QirInputData, but let's still just return the QIR and not a tuple)

…rings' into joaoboechat/stim-compiler

…iler

billti · 2026-06-20T20:39:13Z

        shot.unitary[1] = op.unitary[1];
        shot.unitary[4] = cplxNeg(op.unitary[4]);
        shot.unitary[5] = cplxNeg(op.unitary[5]);
+    } else if (rand < (p_x + p_z + p_y)) {


Why did this get moved? Was there an issue to fix or optimization to be had?

joao-boechat added 12 commits June 4, 2026 11:35

initial lexer implementation

cacd362

add display implementation for TokenKind

8716674

temporary commit to save progress

35804ba

update lex

d250224

update package name

5462765

first finalized parser

c66a59d

fix bugs, improve debugging

2c03a10

make tests consume from arbitrary example.stim file

561e3e9

fix repeated newline bug, improve parsing of custom instructions

c07ee11

fix bug of custom function without target

a73fc12

handle scientific notation in the lexer

85b0955

improve lex and parse manual testing

a6cbe23

github-advanced-security AI found potential problems Jun 11, 2026

View reviewed changes

billti reviewed Jun 12, 2026

View reviewed changes

Comment thread source/compiler/qsc_stim_parser/examples/lex_stim.rs Outdated

joao-boechat and others added 13 commits June 11, 2026 17:54

save initial qir emitting code

9c724bb

python, interop, and cpu-simulators changes

3459edc

gpu changes

8fb9f95

delete commented out code

4ff3d45

fix cargo clippy warning

5c1cc10

fix issue in benchmark

c566376

add qirWriter for separating responsibilities

3a30469

file for manual testing e2e compilation

ff29da3

output header, footer, and declarations

8bcb3e7

fix clippy warnings

fa9973d

add run_qir api to python

c0bdb22

use FxHashMap from rustc_hash

c0d7155

finish implementing preselect

fc18cc3

amcasey reviewed Jun 15, 2026

View reviewed changes

joao-boechat changed the base branch from main to oscarpuente/add-loss-to-fault-strings June 15, 2026 19:59

billti reviewed Jun 16, 2026

View reviewed changes

joao-boechat and others added 6 commits June 16, 2026 09:44

improve write_call api

4a92c66

support m, swap, s_dag qir generation

e492edb

Merge branch 'main' into oscarpuente/add-loss-to-fault-strings

16eae95

minor fixes on stim_to_qir notebook

438f3c3

clear metadata from notebook

d4df932

cargo lock

44f52b7

joao-boechat force-pushed the joaoboechat/stim-compiler branch from e1767ae to 44f52b7 Compare June 16, 2026 17:24

joao-boechat added 9 commits June 16, 2026 10:28

Merge remote-tracking branch 'origin/oscarpuente/add-loss-to-fault-st…

a1616c3

…rings' into joaoboechat/stim-compiler

fix widgets import

2f31d2e

give default value of None to NoiseConfig in compile stim

533017a

simplify instruction compilation

29eeb98

simplify instruction compilation, support more gates

96e48b2

add basic error handling for qir generation

99e71da

mark all stim apis as experimental

1da048c

add unsupported targets and temporary unsupported arguments error

b75721c

fix incorrect ordering when broadcasting instructions

fafa3e7

joao-boechat marked this pull request as ready for review June 19, 2026 02:55

joao-boechat requested review from idavis, minestarks and swernli as code owners June 19, 2026 02:55

joao-boechat added 4 commits June 19, 2026 11:24

fix semantics for correlated error

53382db

support more gates

0b08f38

remove unwrap from QirWriter

f72be0d

remove remaining unwraps

e0210b0

Base automatically changed from oscarpuente/add-loss-to-fault-strings to main June 19, 2026 23:20

billti added 2 commits June 19, 2026 16:29

Merge remote-tracking branch 'origin/main' into joaoboechat/stim-comp…

a28b17b

…iler

Fix markdown cell

d51d0bd

billti reviewed Jun 20, 2026

View reviewed changes

billti approved these changes Jun 20, 2026

View reviewed changes

		from typing import List, Literal, Optional, Tuple


		def compile(src: str, noise: Optional[NoiseConfig]) -> Tuple[str, NoiseConfig]:

Conversation

joao-boechat commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

amcasey left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

amcasey left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

billti Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

joao-boechat commented Jun 11, 2026 •

edited

Loading

billti Jun 16, 2026 •

edited

Loading