feat: random_advance

[jake-arkinstall]

• Add selene_random_advance(delta: u64) function to selene
  • This advances the random state by the specified number of 32 bit reads
  • As this is cyclic in 2^64, a negative value can be bitcast and accepted.
  • If no prng state is set, an error is raised (as with e.g. selene_random_u32)
• Add random_advance to the QIS wrapper, calling the above.
• Add pytest, though it is currently skipped as random_advance support isn't available in guppy yet.

Future work:

I do not like managing static RNG state in selene:

• It's done this way because that's how QIS uses RNG.
• It makes sense there. - but the static state is an antipattern in the context of selene itself.
• Instead, Selene can offer stateful RNG, and we should handle state in the QIS wrapper.

[qartik]

LGTM, it will be nice to have @jordan-qtm or Alex review the expected behavior.

[jordan-qtm]

• Add selene_random_advance(delta: u64) function to selene

  • This advances the random state by the specified number of 32 bit reads
  • As this is cyclic in 2^64, a negative value can be bitcast and accepted.
  • If no prng state is set, an error is raised (as with e.g. selene_random_u32)

• Add random_advance to the QIS wrapper, calling the above.

• Add pytest, though it is currently skipped as random_advance support isn't available in guppy yet.

Future work:

I do not like managing static RNG state in selene:

• It's done this way because that's how QIS uses RNG.
• It makes sense there. - but the static state is an antipattern in the context of selene itself.
• Instead, Selene can offer stateful RNG, and we should handle state in the QIS wrapper.

Yes, this appears to have the correct behavior I would expect.

[Copilot]

Pull Request Overview

This PR adds random state advancement functionality to the selene simulator. It allows users to advance or rewind the PRNG state by a specified number of steps, which is useful for deterministic testing and debugging scenarios.

• Adds random_advance function to advance PRNG state by a delta value
• Implements FFI wrapper and QIS interface integration
• Adds test coverage for the new functionality (currently skipped pending guppy support)

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
selene-sim/rust/selene_instance/rng.rs	Implements core random_advance method and improves documentation
selene-sim/rust/ffi_interface.rs	Adds FFI wrapper selene_random_advance for C interface
selene-sim/c/include/selene/selene.h	Declares the new C API function
selene-ext/interfaces/helios_qis/c/src/interface.c	Implements QIS wrapper function
selene-sim/python/tests/test_guppy.py	Adds comprehensive test for advance functionality

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

The comment mentions 'i64s with negative values' but the function parameter is u64. This is confusing since u64 cannot have negative values. Consider clarifying that negative values should be cast to u64 or revising the documentation to match the actual parameter type.

Suggested change

	/// rewinding behaviour.
	/// is cyclic, advancing by large unsigned values will wrap around
	/// the PRNG state as expected.

[Copilot]

The comment mentions 'i64s with negative values' but the function signature uses uint64_t. This creates confusion about how negative values should be handled. The documentation should clarify the casting behavior or use a signed parameter type.

Suggested change

	struct selene_void_result_t selene_random_advance(struct SeleneInstance *instance, uint64_t delta);
	* is cyclic, int64_t values (including negative values) have well defined
	* rewinding behaviour.
	*
	* Requires the PRNG to be seeded with random_seed,
	* otherwise an error will be returned.
	*/
	struct selene_void_result_t selene_random_advance(struct SeleneInstance *instance, int64_t delta);