Change randomization scheme

[trevorld]

❯ My Portable Piecepack Notation (PPN) can (for a subset of games) generate random board game setups given a seed. Currently it is written in R but if some third party wanted to implement this notation in another language I was trying to figure out how hard it would be to match such setups.

● This is a design question about the PPN spec itself. The core problem is that "use the language's native RNG seeded with X" is not a portable specification — even if both R and Python use Mersenne Twister, R's set.seed() initialization and sample() sampling algorithm differ from numpy's in ways that are tedious to replicate.

You have two realistic paths:
Option 1: Specify a portable RNG in the PPN spec
Define the shuffle algorithm explicitly so any implementor can match it without reimplementing R internals. A good choice is a small, well-documented RNG + Fisher-Yates. For example, PCG32 or xorshift64 are each ~10 lines to implement in any language. The spec would say "initialize PCG32 with seed X, then apply Fisher-Yates" and every implementation matches exactly.
Option 2: Accept non-portability and document it
If you're comfortable that PPN setups are only reproducible within R (i.e., a seed in a PPN file is only meaningful to R implementations), document that clearly and move on. A third-party Python implementation would just use its own native RNG and the same seed would produce a different-but-valid random setup.
The practical tradeoff: Option 1 adds a small upfront spec burden but makes PPN setups truly portable and archivable — a PPN file with a seed is self-contained regardless of language. Option 2 is simpler now but means a seed embedded in a PPN file is R-specific, which could be surprising to users.
Given that PPN is a notation format (implying long-term archival and interoperability), Option 1 seems like the right call if random setups are a meaningful part of the spec. The implementation cost in any language is small — PCG32 is about 15 lines.

[trevorld]

Some notes from a feasibility exploration of Option 1 (PCG32 + Fisher-Yates) within this package:

Call-site audit: sample() and sample.int() appear in ~80 places across the codebase, but they reduce to two primitive operations — a shuffle (sample.int(n)) and a bounded sample with replacement (sample(x, size, replace = TRUE)). Many sites already go through slice_sample_piece() and mutate_sample_angle() in piecepack_helpers.R, so introducing two internal wrappers (ppdf_sample_int() / ppdf_sample()) that dispatch based on an option would cover all sites with maybe ~30 additional mechanical updates.

The tricky part is PCG32 in pure R: the algorithm requires unsigned 64-bit arithmetic for its internal state, but R integers are 32-bit signed. Options are:

• Pure R using bitwAnd/bitwShiftL/etc. with a split 2×32-bit state — doable but fiddly and slower.
• A small C extension in src/ via .Call() — no new dependencies, better performance.
• Rcpp — simplest to write but adds a dependency.

Option design: something like options(ppdf.rng = "pcg32") alongside the existing options(ppdf.rng = "r") default. The seed would initialize a PCG32 state object rather than going through withr::local_seed().

Spec requirements for true portability: beyond just specifying PCG32, the PPN spec would need to pin:

1. The seed-to-state initialization (PCG32 has a standard one).
2. The bounded sampling algorithm for [0, n) — rejection-based (no modulo bias) is the portable-friendly choice.
3. The shuffle order — standard Knuth/Durstenfeld Fisher-Yates iterating from the end.

Overall: medium effort, a few days of focused work. The algorithmic side is small; the bulk of the work is the mechanical call-site updates and cross-language test verification.