Refactor RearrangementGenerator load/store methods to reduce complexity and duplication

[coderabbitai]

Context

This issue tracks a follow-up refactoring task identified during review of PR #848.

Problem

The loadRowByRow, loadColumnByColumn, storeRowByRow, and storeColumnByColumn methods in src/na/zoned/code_generator/CodeGenerator.cpp are quite large (100-300 lines each) and contain substantial duplicated structure:

• Row vs. column variants share similar logic
• Storage vs. entanglement handling has near-duplicate patterns
• "Pack additional rows/columns if mapped sets match" logic is repeated
• Virtual offset and neighbor-pushing logic appears across all four methods

This complexity makes it hard to reason about correctness and has contributed to subtle bugs in the past.

Proposed Solution

Extract shared patterns into reusable helpers, for example:

1. buildCoordinateToAodIndex - Common mapping creation from keys to AOD indices
2. collectQubitsPerLine - Materialize x/y → set
3. applyVirtualOffsetAndPushNeighbors - Handle virtual offset insertion and neighboring push logic with min/max bounds, parameterized by axis and site kind
4. packCompatibleLines - Merge additional adjacent lines when isSameMappedSet matches

Then refactor the four large methods to call these helpers with axis/site-specific lambdas.

Requirements

• Observable behavior must remain identical
• Add focused unit tests for each helper (especially neighbor-push and packing)
• Reduce duplication between row/column variants
• Lower the chance of future copy-paste errors

References

• Original PR: ✨ [NA] Enable Code Generation for Relaxed Routing Constraints #848
• Discussion: ✨ [NA] Enable Code Generation for Relaxed Routing Constraints #848 (comment)
• Requested by: @ystade

[coderabbitai]

Follow-up: Refactor RearrangementGenerator complex methods

As discussed in PR #848, the RearrangementGenerator class contains several very long and complex methods that would benefit from refactoring:

Primary concern: storeColumnByColumn method

• Location: src/na/zoned/code_generator/CodeGenerator.cpp lines 756-1036
• Size: ~280 lines
• Issue: Mixes handling for STORAGE and ENTANGLEMENT columns with nested conditionals, making it hard to read and maintain

Suggested refactoring approach:

Extract the distinct packing/spacing logic into smaller helper methods:

• alignStorageColumn(...)
• alignEntanglementColumn(...)
• pushAwayLowerColumns(...)
• pushAwayUpperColumns(...)
• collectColsToStore(...)

Replace the inlined STORAGE/ENTANGLEMENT blocks with calls to these helpers while preserving all behavior and computed variables (aodColsToX_, aodRowsToY_, colsToStore, allQubitsToStore, nextX/freeCols/left logic, and calls to addTargetMove and StoreOp).

Other methods to consider:

Similar complexity exists in:

• loadRowByRow
• loadColumnByColumn
• storeRowByRow

These could benefit from similar refactoring patterns.

Reference: PR #848 discussion