add quantum memory layout for quantum data by JaipreethTiruvaipati · Pull Request #132 · hhat-lang/hhat_lang

JaipreethTiruvaipati · 2026-06-09T12:47:33Z

Closes #113.

A qubit-only memory layout for quantum data, kept separate from the classical layout, plus a quantum program built when a quantum variable is cast. The classical layout (base/adt/primitives) is untouched - the quantum side is derived from the Ty and lives in its own modules.

What's in it:

primitives report a qubit count - @Bool=1, @u2/@u3/@u4/@U8 = 2/3/4/8
a struct sums its quantum fields back-to-back with no alignment/padding (classical fields carry no qubits and are skipped); nested structs recurse
a 2-variant quantum enum is 1 qubit, first/second variant -> |0>/|1>
QuantumLayout is built from the Ty, not the classical TypeLayout (the classical layout is quantum-blind - quantum primitives are zero-sized and quantum struct fields are dropped)
QuantumLayoutCache lays each quantum type out once and reuses it
QuantumInstr carries an ancilla count; QuantumProgram holds the variable's layout, instructions and cast attributes, and works out data qubits, ancillas (summed), total quantum memory and the classical register size
QuantumProgram::attr_qubits(attr) -> (offset, width) so the Q3L emitter knows which qubits each attribute maps to, for measurement

Structure:

layout/quantum/ - the quantum layout definition + its cache (layout concerns)
program/ - QuantumInstr + QuantumProgram, separate from layout/ since that module is just for laying out types
the classical layout files are untouched

Tests (cargo test -p hhat_core): all primitive quantum types, a struct, an enum (+ variant order), a nested struct, a mixed classical/quantum struct, a mixed inner struct, type -> quantum layout, the cache, a QuantumProgram from a struct and from a primitive (ancillas 0-3), the classical register width, and the attribute -> qubit mapping.

Follow-ups (discussed with the maintainer): wiring QuantumProgram into the actual cast pass, and quantum arrays (left as todo!() for now).

Generative AI/LLM disclosure

Code and Logic Architecture/Design:

The code and logic architecture/design contain no generative AI/LLM
The code and logic architecture/design are partially performed by generative AI/LLM
- 60% performed by the author(s)
The code and logic architecture/design are fully performed by generative AI/LLM

Code content:

The code contains no generative AI/LLM work
The code is partially written by generative AI/LLM
- 80% performed by the author(s)
The code is fully written by generative AI/LLM

Code review:

The code review contains no generative AI/LLM
The code review is partially done by generative AI/LLM
- 50% performed by the author(s)
The code review is fully done by generative AI/LLM

Code tests:

The code tests contain no generative AI/LLM
The code tests are partially written by generative AI/LLM
The code tests are fully written by generative AI/LLM

Doomsk · 2026-06-09T13:37:15Z

Hi @JaipreethTiruvaipati thank you for this PR. Please make sure all the AI disclaimer fields are properly filled in.

JaipreethTiruvaipati · 2026-06-09T20:42:45Z

Thanks @Doomsk - updated, all four disclosure fields are filled now (added the missing author % under Code content).

Doomsk · 2026-06-09T21:03:03Z

Thank you @JaipreethTiruvaipati .
I will start with the review now.

Doomsk

Hey @JaipreethTiruvaipati for now those are the points to address. Later I will continue with the rest.

Doomsk · 2026-06-09T21:03:44Z

        let mut struct_offset: u32 = 0;
+        let mut struct_qubits: u32 = 0;
        let mut prev_size: u32 = 0;


why quantum layout logic is in the classical layout?

good point - reverted this. StructLayout::layout is back to the original, no qubit logic. the quantum struct layout is built in layout/quantum.rs from the Ty now.

Doomsk · 2026-06-09T21:04:59Z

+    /// quantum fields, kept apart since they do not live in classical memory;
+    /// their offset is the starting qubit inside the struct
+    pub quantum_members: Vec<MemberLayout>,
+    /// number of qubits used by the quantum fields; classical fields are 0
+    pub qubits: u32,
 }


why did you do it? The members are already handled inside the members field.

agreed - removed both. StructLayout keeps only members. quantum fields live in QuantumStructLayout in quantum.rs, which skips the classical ones.

Doomsk · 2026-06-09T21:07:09Z


+    pub fn qubits(&self) -> u32 {
+        match self {
+            TypeLayout::Primitive(layout, _) => layout.qubits,
+            TypeLayout::Struct(layout, _) => layout.qubits,
+            TypeLayout::Enum(layout, _) => layout.qubits,
+            TypeLayout::Array(layout, _) => layout.qubits,
+        }
+    }
+


Quantum logic shouldn't sit in the same place as the classical logic for the quantum memory layout.

removed - TypeLayout is untouched now. qubit counts come from QuantumLayout::qubits() in quantum.rs.

JaipreethTiruvaipati · 2026-06-09T21:58:11Z

thanks for the review - moved all the quantum logic out of the classical layout.

base.rs / adt.rs / primitives.rs are back to the original, no quantum fields
everything lives in layout/quantum.rs now, built from the Ty
QuantumLayout (primitive/struct/enum), a small cache, QuantumInstr + QuantumProgram
diff is 3 files: quantum.rs, one line in mod.rs, one re-export in lib.rs

pushed the update.

@Bool

a qubit-only layout kept separate from the classical layout, plus a quantum program built when a quantum variable is cast. the classical layout (base/adt/primitives) is untouched - everything lives in layout/quantum.rs and is built from the Ty. - QuantumLayout (primitive/struct/enum), qubits only, no alignment/padding - @Bool=1, @u2/@u3/@u4/@U8 = 2/3/4/8 - a struct stacks its quantum fields back-to-back; classical fields skipped - a 2-variant quantum enum is 1 qubit (first/second variant = |0>/|1>) - QuantumLayoutCache so each quantum type is laid out once and reused - QuantumInstr (ancilla count) and QuantumProgram holding the variable's layout, instructions and cast attributes, with qubit and classical register sizes - tests for primitives, struct, enum, nested/mixed structs, the cache, and programs from a struct and a primitive

Doomsk

Other than the comments in the code, I'd like to know what was you rationale behind organizing the code logic in that file in particular.

Is there a better way to do it? Answer it without using LLM.

Doomsk · 2026-06-10T00:05:36Z

+    /// variant names in order; the first and second map to `|0>` and `|1>`
+    pub variants: Vec<SymbolId>,
+}


why using vector here? can you justify without using LLM?

A quantum enum maps variants to basis states: first → |0>, second → |1>. Order is the meaning. A Vec keeps insertion order, so variants[0]=|0>, variants[1]=|1> - the index is the basis-state assignment Q3L needs.

Did not used fixed arrray like ( [SymbolId; 2] ) because : "2-variant for now", but a Vec doesn't hard-code 2 if it grows (n variants → ceil(log2 n) qubits later).

Also didn't used set or map too since a set loses order (the whole point) and a name -> index map is redundant since the position already is the index

Doomsk · 2026-06-10T00:09:43Z

+/// Permanent store for quantum type layouts so each quantum type is laid out
+/// once and reused across every quantum variable in the program.
+///
+pub struct QuantumLayoutCache {
+    cache: HashMap<Ty, QuantumLayout>,
+}


can you explain the reason why this struct is in the file without using LLM?

The issues says quantum type layouts should be "stored in a more permanent place to avoid redoing work", so did for cache too. Like many variables can share a type(several @bell_ts) → lay each type out once, reuse. layout_of builds on miss, returns cached on hit.

also it mirrors the classical LayoutCache (HashMap<Ty, …>, new/has/layout_of) so it's consistent

Doomsk · 2026-06-10T00:14:03Z

+#[derive(Clone, Debug)]
+pub struct QuantumProgram {
+    pub var: SymbolId,
+    pub layout: QuantumLayout,
+    pub instrs: Vec<QuantumInstr>,
+    pub cast: Vec<SymbolId>,
+}


can you explain why you chose this structure for the QuantumProgram without using LLM?

Similar to above, issue defines a program as "everything under a quantum variable @v".

The 4 fields are exactly the inputs to the numbers the issue wants:
- var = the root variable it's scoped to
- layout = its qubits (data)
- instrs = primitive instructions, each carrying ancillas → needed for total qubit count
- cast = which attributes were measured → defines the classical register

and data qubits ( layout) + ancillas (instrs) = total quantum memory... and here cast means measuring a quantum attribute and reading the result into classical memory

Doomsk · 2026-06-10T00:15:14Z

+
+    pub fn add_cast(&mut self, attr: &SymbolId) {
+        self.cast.push(attr.clone())
+    }


what does cast mean in this case?

In Heather, a cast (the * in res:bool = @v.@t * bool) measures a quantum attribute and reads the outcome into classical memory. So cast here holds the attributes that get measured - each measured qubit becomes one classical bit in the register. In the issue only @v.@t is cast, which lowers to measure qv_qt -> res with creg res[1].

Doomsk · 2026-06-10T00:17:11Z

+    /// Classical register size: the qubits of the cast attributes, since
+    /// measuring an attribute yields that many classical bits.
+    ///
+    pub fn csize(&self) -> u32 {
+        // casting the whole variable measures the whole register


can you explain this function without using LLM?

csize returns how many classical bits the program needs, which is just the total qubits of the attributes that were cast (measured) - one bit per qubit.

First branch: if the whole variable was cast, the entire register is measured, so it returns qsize() (all the data qubits). Otherwise, for a struct it walks the members, keeps the ones whose name is in cast, and sums their qubits. A bare primitive that wasn't wholly cast measures nothing, so it's 0.

Example: @v:@bell_t casting only @v.@t (a @Bool, 1 qubit) → csize = 1 → creg res[1], matching the issue.

Doomsk · 2026-06-13T11:58:12Z

@JaipreethTiruvaipati would you like to have a discussion on Discord? I'm not convinced yet you (or the LLM) understood some parts. Happy to interact and clarify in real time.

JaipreethTiruvaipati · 2026-06-13T12:51:07Z

Sure.. I will try joining discord and ping you there...

Doomsk · 2026-06-15T13:23:33Z

@JaipreethTiruvaipati I reached you out there but you haven't replied yet. I will wait for tomorrow to close this PR if no response is given.

JaipreethTiruvaipati · 2026-06-15T19:43:48Z

Hey @Doomsk , was travelling whole day... I pinged you in discord... Will be active there to discuss things...

…pping after discussing the design with the maintainer: - layout/ is only for laying out types, so QuantumInstr and QuantumProgram move into a new program/ module - the quantum layout and its cache stay under layout/quantum/ - add QuantumProgram::attr_qubits(attr) -> (offset, width) so the Q3L emitter knows which qubits each attribute maps to, for measurement - ancillas are summed for the total (not freed), per the discussion - arrays and wiring into the cast pass left as follow-ups

github-project-automation Bot moved this to Backlog in H-hat lang kanban Jun 9, 2026

github-project-automation Bot added this to H-hat lang kanban Jun 9, 2026

Doomsk requested changes Jun 9, 2026

View reviewed changes

JaipreethTiruvaipati force-pushed the feat/quantum-memory-layout branch from f306b24 to 50d763c Compare June 9, 2026 21:59

JaipreethTiruvaipati requested a review from Doomsk June 9, 2026 22:02

Doomsk requested changes Jun 10, 2026

View reviewed changes

Uh oh!

Conversation

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

Uh oh!

Generative AI/LLM disclosure

Uh oh!

Doomsk commented Jun 9, 2026

Uh oh!

JaipreethTiruvaipati commented Jun 9, 2026

Uh oh!

Doomsk commented Jun 9, 2026

Uh oh!

Doomsk left a comment

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!

JaipreethTiruvaipati commented Jun 9, 2026

Uh oh!

Doomsk left a comment

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!

Doomsk commented Jun 13, 2026

Uh oh!

JaipreethTiruvaipati commented Jun 13, 2026

Uh oh!

Doomsk commented Jun 15, 2026

Uh oh!

JaipreethTiruvaipati commented Jun 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

JaipreethTiruvaipati commented Jun 9, 2026 •

edited

Loading