Module regular_classical 

Deterministic Regular Classical Matrices

qec_code::regular_classical provides the repository-owned deterministic sampler for regular binary parity-check matrices. It is intended for random code families that need reproducible sampling across Rust versions and platforms.

Versioning Policy

The algorithm_version field is part of every generation request. Version 1 is immutable: a behavioral change to the stream, bounded-index rule, stub ordering, retry progression, duplicate-edge handling, or canonicalization must use a new algorithm version rather than changing version 1.

SplitMix64V1

SplitMix64V1 starts with:

state = seed

Each next_u64() call advances and maps the state with wrapping u64 arithmetic:

state = state + 0x9E3779B97F4A7C15 mod 2^64
z = state
z = (z xor (z >> 30)) * 0xBF58476D1CE4E5B9 mod 2^64
z = (z xor (z >> 27)) * 0x94D049BB133111EB mod 2^64
output = z xor (z >> 31)

For seed 7, the first eight output words are:

0x63CBE1E459320DD7
0x044C3CD7F43C661C
0xE6984080BAB12A02
0x953AEB70673E29CB
0x73D33B666A1E21DA
0x3FDABE86CBBEAA11
0x77CBC4A133C2D0F6
0x53FCD6513D02BEFE

Bounded Index

bounded_index_v1(stream, upper_bound) maps stream words to the unbiased range [0, upper_bound).

For upper_bound == 0, it returns None and does not consume the stream. For positive bounds:

threshold = 2^64 mod upper_bound
draw x = stream.next_u64()
if x < threshold, reject x and draw again
return x mod upper_bound

The accepted interval has a length divisible by upper_bound, so each returned index is selected by the same number of accepted u64 words.

Matrix Generation

Validation happens before the stream is created and before any random word is consumed:

• algorithm_version must be 1.
• column_count, row_count, column_weight, row_weight, and retry_limit must be greater than zero.
• column_weight must be at most row_count.
• row_weight must be at most column_count.
• column_count * column_weight and row_count * row_weight must not overflow usize.
• The checked column and row stub counts must be equal.

Each attempt starts with row slots in row-major order:

[0 repeated row_weight times, 1 repeated row_weight times, ...]

Columns are visited in ascending order. For each column, version 1 selects column_weight row slots with bounded_index_v1. A row may appear at most once for the current column. Slots whose row is already selected for the current column are skipped before the bounded index is applied. If no non-duplicate row slot remains for the current column, the attempt is rejected.

The stream is created once from seed before attempt 1. Retry attempts continue from the current stream state; they do not reseed or rewind. Exhausting retry_limit attempts returns RegularClassicalMatrixGenerationExhausted.

On success, every row support is sorted ascending, and then the rows are sorted lexicographically. This canonical row ordering makes row-order-equivalent parity-check matrices compare identically.

For:

column_count = 6
row_count = 4
column_weight = 2
row_weight = 3
seed = 7
algorithm_version = 1

the canonical rows are:

[[0, 1, 2], [0, 3, 4], [1, 3, 5], [2, 4, 5]]

Structs

RegularClassicalMatrixConfig

SplitMix64V1

Constants

REGULAR_CLASSICAL_MATRIX_ALGORITHM_V1

Functions

bounded_index_v1

deterministic_regular_matrix