fix(rand): In-place uniform_ and normal_ do not rotate seed per block

[IvanaGyro]

Motivation

In-place blockunitensor.uniform_ and blockunitensor.normal_ didn't rotate seed while generating random numbers per block, which leads the values per block use the same sequence.

Description

• Rotated seed per block by adding one, which aligns with the current implementation of random.uniform_ and random.normal_.
• Added example usage to docs/code/python/doc_codes/guide_uniten_create_from_generator.py showing in-place and global alls on existing UniTensor instances.
• Added unit tests in pytests/unitensor_random_test.py that verify deterministic, seeded behavior for both dense and block UniTensor using normal_ and uniform_.
• Made convergence criterion Arnoldi_BK_test smaller to pass the test. The test was wrongly passed with all blocks using the same random sequence.

Testing

• Added and ran the new test file pytests/unitensor_random_test.py via pytest, and the tests passed for the seeded deterministic checks of UniTensor.normal_ and UniTensor.uniform_.
• Arnoldi_Gnd.Arnoldi_BK_test

[gemini-code-assist]

Code Review

This pull request removes the normal_ and uniform_ functions for UniTensor from the random module bindings and type stubs, as they are now implemented as in-place methods on the UniTensor class. It also adds documentation examples and comprehensive unit tests for these in-place methods on both dense and block UniTensor instances. The review feedback highlights a style guide violation regarding the use of leading underscores in new helper functions, and recommends using np.testing.assert_allclose instead of np.testing.assert_array_equal for floating-point comparisons to prevent flaky tests.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 587567f1a6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 72.77%. Comparing base (f64b2f5) to head (6f863ad).
⚠️ Report is 45 commits behind head on master.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1074      +/-   ##
==========================================
+ Coverage   72.11%   72.77%   +0.66%     
==========================================
  Files         225      226       +1     
  Lines       28207    28179      -28     
  Branches       71       71              
==========================================
+ Hits        20341    20507     +166     
+ Misses       7845     7651     -194     
  Partials       21       21              

Flag	Coverage Δ
cpp	72.89% <100.00%> (+0.66%)	⬆️
python	64.13% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Components	Coverage Δ
C++ backend	71.93% <100.00%> (+0.37%)	⬆️
Python bindings	78.07% <ø> (+2.27%)	⬆️
Python package	64.13% <ø> (ø)

Files with missing lines	Coverage Δ
src/UniTensor.cpp	93.70% <100.00%> (+5.05%)	⬆️

... and 21 files with indirect coverage changes

---

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update f64b2f5...6f863ad. Read the comment docs.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 61d36ee422

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[ianmccul]

(This was posted by Codex after review by @ianmccul - the codex attribution was missing from the original posting)

A few comments after looking at the current end state of this PR.

The Arnoldi test change

The modified Arnoldi_Gnd.Arnoldi_BK_test does not have a generally correct reference calculation. It asks Arnoldi for "LM" (largest magnitude), but obtains lambda using linalg::Max, whose complex implementation compares only the real parts, and then the test discards the imaginary part of Arnoldi's eigenvalue as well. H consists of random nonsymmetric real 9 x 9 blocks, so complex eigenvalues are entirely possible. This test therefore passes for a particular seeded spectrum rather than testing "LM" correctly. The reference should select the eigenvalue with largest std::abs(z) and compare the complex value, allowing for the usual ordering/tie considerations.

Also, explicitly setting maxiter = 10000 does not alter the test: 10000 is already the default for the UniTensor Arnoldi overload. The effective change is tightening cvg_crit from its default 1e-9 to 1e-12. The EXPECT_NEAR replacement is essentially equivalent to the previous absolute-error check.

For context, the other helper in this file, CheckResult(), is called 12 times: five which cases, four dtypes, and the k=1, k=23, and “smallest dimension” cases. Each call performs a full dense eigendecomposition. The matrix is only 25 x 25 (D = 5, giving D^2 x D^2), so the repeated diagonalization is unnecessary but not an important runtime cost. There is a more direct redundancy: ExcuteTest() calls and discards H.GetOpAsMat() immediately before CheckResult() calls it again. Thus the dense operator is constructed 24 times and diagonalized 12 times. The test named smallest_dim also still uses D = 5, so it is not testing the smallest dimension.

It would be better for the Arnoldi fixture to contain fixed data rather than depend on the precise random streams used by an unrelated randomization API test.

Scope and implementation

The current diff no longer matches the PR title/body: it does not remove the module-level UniTensor overloads. It aligns the member normal_()/uniform_() block streams with the module-level implementation, adds tests/docs, and changes the Arnoldi test. It also does not implement the normal_like/uniform_like operation requested by #456, so I do not think it closes that issue.

The duplicated implementation should be removed rather than synchronized manually. One of

UniTensor::uniform_()
random::uniform_(UniTensor&)

should forward to the other, and likewise for normal_(). The fact that these two loops had already diverged is a good demonstration of why there should only be one implementation.

Testing the distributions

Exact equality between two calls using the same seed is appropriate for testing reproducibility; assert_allclose is not needed for that comparison. However, same-seed equality alone does not verify low/high, mean/std, or even that randomization occurred. I agree that hard-coded output arrays from std::uniform_real_distribution or std::normal_distribution are not portable across standard-library implementations.

A robust alternative is to retain the exact reproducibility tests and add large-sample property tests. For example, use a dense Double UniTensor with shape [256, 256] (65536 samples), nontrivial parameters, and check the first two moments with tolerances derived from eight standard errors. A broad kurtosis check distinguishes normal from uniform without depending on exact generated values:

def assert_distribution(values, expected_mean, expected_variance,
                        variance_se_factor, expected_kurtosis):
    x = np.asarray(values).ravel()
    n = x.size

    sample_mean = x.mean()
    sample_variance = x.var(ddof=1)

    mean_tol = 8.0 * np.sqrt(expected_variance / n)
    variance_tol = (
        8.0 * expected_variance * np.sqrt(variance_se_factor / n)
    )

    assert abs(sample_mean - expected_mean) < mean_tol
    assert abs(sample_variance - expected_variance) < variance_tol

    centered = x - sample_mean
    sample_kurtosis = np.mean(centered**4) / np.mean(centered**2) ** 2
    assert abs(sample_kurtosis - expected_kurtosis) < 0.25

For uniform_(low=-3, high=7), the expected mean is 2, variance is 100/12, variance_se_factor = 0.8, and kurtosis is 1.8; also check every value is within [-3, 7]. For normal_(mean=2, std=3), the expected variance is 9, variance_se_factor = 2, and kurtosis is 3.

At this sample size those are deliberately generous tolerances, robust across different valid random streams, while still reliably detecting an ignored range, wrong scale, no-op fill, or wrong distribution family. The small block-UniTensor tests can then concentrate on exact same-seed reproducibility, valid uniform bounds, and ensuring equal-sized blocks do not receive identical streams.

[ianmccul]

Follow-up with concrete tolerances for the proposed statistical tests.

For n = 256 * 256 = 65536, using eight standard errors gives deliberately conservative, implementation-independent bounds.

For uniform_(low=-3, high=7):

• expected mean: 2
• expected variance: (7 - (-3))^2 / 12 = 100/12
• mean tolerance:

  8 * sqrt((100/12) / 65536) = 0.0902
  

• variance tolerance:

  8 * (100/12) * sqrt(0.8 / 65536) = 0.2329
  

I would round these upward and use:

assert np.all(values >= -3.0)
assert np.all(values <= 7.0)
assert abs(values.mean() - 2.0) < 0.10
assert abs(values.var(ddof=1) - 100.0 / 12.0) < 0.25
assert abs(sample_kurtosis(values) - 1.8) < 0.25

For normal_(mean=2, std=3):

• expected mean: 2
• expected variance: 9
• mean tolerance:

  8 * sqrt(9 / 65536) = 0.09375
  

• variance tolerance:

  8 * 9 * sqrt(2 / 65536) = 0.3977
  

Again rounding upward:

assert abs(values.mean() - 2.0) < 0.10
assert abs(values.var(ddof=1) - 9.0) < 0.40
assert abs(sample_kurtosis(values) - 3.0) < 0.25

where

def sample_kurtosis(values):
    x = np.asarray(values).ravel()
    centered = x - x.mean()
    return np.mean(centered**4) / np.mean(centered**2) ** 2

These tolerances are intentionally much wider than ordinary sampling fluctuations. They should be robust across standard-library RNG implementations while still failing clearly if the parameters are ignored, the fill is a no-op, the scaling is wrong, or normal and uniform distributions are confused. Exact same-seed equality should remain a separate reproducibility assertion.

— Codex

[IvanaGyro]

1. For Arnoldi test, this PR is just to let it pass.
2. PR description is updated.
3. Added distribution test with fixed seed to avoid flaky tests