Add low-memory direct random fills

[cliffburdick]

Currently the random() call allocates space for state variables equivalent to the size of the tensor. This is wasteful on direct assignments since the operator is not being reused after that. This change bypasses the state allocation when the random variable won't be used later.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[cliffburdick]

/build

[greptile-apps]

Greptile Summary

This PR adds a low-memory direct-fill path for random() and randomi() operators, bypassing per-element curandStatePhilox4_32_10_t state allocation when the operator is assigned directly into a CUDA tensor. It also fixes the long-standing host NORMAL double-scale bug and introduces RAII guards (CurandGeneratorGuard, ValuesGuard) for exception-safe resource cleanup.

• Direct-fill path: A new matx_direct_assign_op trait causes base_operator.h to route direct tensor assignment through TransformExec → RandomOp::Exec, which either uses cuRAND bulk generation (contiguous float/double/complex tensors) or a per-element Philox kernel without a separate state buffer.
• Expression path unchanged: PreRun materializes values into a temporary values_ buffer; ValuesGuard ensures cleanup on exception.
• Host NORMAL scale fix: The host operator() previously double-applied the affine transform; it now generates N(0,1) and applies the transform once.

Confidence Score: 4/5

Safe to merge with minor cleanup; the new direct-fill and materialize paths are correctly exception-safe and the host double-scale bug is fixed.

The CUDA code paths (cuRAND bulk, Philox tail, RAII guards, ValuesGuard rollback) are correct and well-tested. The host NORMAL scale fix is verified by a new statistical test. A dead unreachable assert and a missing can_alias guard are the only observations; neither affects correctness today.

include/matx/generators/random.h (dead assert in GenerateCurandContiguous) and include/matx/operators/base_operator.h (missing can_alias guard in new direct-fill dispatch branch).

Important Files Changed

Filename	Overview
include/matx/generators/random.h	Core change: replaces per-element cuRAND state with a materialized value buffer for the expression path, and adds a stateless direct-fill path (cuRAND bulk or per-element Philox). Exception safety is handled via ValuesGuard and CurandGeneratorGuard. Contains one dead-code MATX_ASSERT_STR that is always satisfied after the has_tail adjustment.
include/matx/operators/base_operator.h	Adds a new dispatch branch for matx_direct_assign_op types, routing direct tensor assignment through TransformExec without allocating temporary output memory. Missing the can_alias short-circuit guard present in the adjacent transform-op path.
test/00_operators/GeneratorTests.cu	Adds comprehensive tests: seeded reproducibility, odd-size NORMAL, complex UNIFORM/NORMAL, integer direct fill, rank-0, shape-mismatch throw, expression materialize consistency, and host single-scale verification.
docs_input/api/random/random.rst	Documentation updated to describe the direct-fill path, path-selection criteria, reproducibility caveats, and complex beta-only-real-shift behavior.
docs_input/quickstart.rst	Quickstart updated to reflect materialize-once semantics in compound expressions and recommend direct assignment for large tensors.
docs_input/executor_compatibility.rst	Compatibility table updated with accurate notes about the direct-fill and expression-materialize paths for random and randomi.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["(out = random_op).run(exec)"] --> B{is_matx_direct_assign_op
&& tensor_view && CUDA?}
    B -- yes --> C{CanDirectFill
shapes match?}
    C -- no --> D[MATX_THROW matxInvalidSize]
    C -- yes --> E[TransformExec InnerPreRun=no-op]
    E --> F{CanUseCurandGenerator
contiguous float/double/complex?}
    F -- yes --> G[GenerateCurandContiguous
cuRAND bulk fill on stream]
    G --> H{NORMAL float/double
odd count? has_tail}
    H -- yes --> I[ScaleContiguous first gen_count]
    I --> J[LaunchMaterializeFill tail via Philox]
    H -- no --> K[ScaleContiguous all elements]
    F -- no --> L[LaunchStateFreeFill
per-element Philox DirectValue]

Loading

_{Reviews (18): Last reviewed commit: "Fix host random normal scaling" | Re-trigger Greptile}

[cliffburdick]

@greptile review

[cliffburdick]

@greptile review

[cliffburdick]

@greptile review

[cliffburdick]

@greptile review

[cliffburdick]

/build

[cliffburdick]

/build

[cliffburdick]

@greptile review

[cliffburdick]

@greptile review

[cliffburdick]

@greptile review

[cliffburdick]

@greptile review latest commit 610f40c

[cliffburdick]

@greptile review

[cliffburdick]

/build