Agent-Skills.md

Agent Skills: numpy-random

Modern random number generation using the Generator API, focusing on statistical properties, parallel streams, and reproducibility. Triggers: random, rng, default_rng, SeedSequence, probability distributions, shuffle.

UncategorizedID: cuba6112/skillfactory/numpy-random

Repository

cuba6112/skillfactory
cuba6112

Install this agent skill to your local

pnpm dlx add-skill https://github.com/cuba6112/skillfactory/tree/HEAD/skills/numpy-random

Skill Files

Browse the full folder contents for numpy-random.

Download Skill

Loading file tree…

skills/numpy-random/SKILL.md

Skill Metadata

Name
numpy-random
Description
Modern random number generation using the Generator API, focusing on statistical properties, parallel streams, and reproducibility. Triggers: random, rng, default_rng, SeedSequence, probability distributions, shuffle.

Overview

NumPy's random module shifted from the legacy RandomState to the modern Generator API. This new approach provides better statistical properties, faster algorithms, and a robust system for parallel random number generation using SeedSequence.

When to Use

  • Stochastic simulations requiring high-quality random bits.
  • Shuffling datasets for machine learning training.
  • Generating independent random streams for parallel computing workers.
  • Creating reproducible experiments across different runs.

Decision Tree

  1. Starting a new project?
    • Use np.random.default_rng(). Do not use np.random.seed().
  2. Need independent streams for multiple CPUs?
    • Use SeedSequence.spawn() to create children.
  3. Shuffling in-place?
    • Use rng.shuffle(arr). For a copy, use rng.permuted(arr).

Workflows

  1. Parallel Random Stream Generation

    • Initialize a SeedSequence with a high-quality entropy source.
    • Use the .spawn(n) method to create independent seed sequences for workers.
    • Instantiate a new Generator for each worker using its specific child sequence.

  2. Reproducible Simulation Setup

    • Obtain a 128-bit seed (e.g., using secrets.randbits(128)).
    • Initialize the generator: rng = np.random.default_rng(seed).
    • Log the seed to allow exact reproduction of the stochastic results in future runs.

  3. In-Place Array Shuffling

    • Create a Generator instance.
    • Pass an existing array to rng.shuffle(arr) to modify it in-place.
    • Specify the axis parameter if only certain dimensions (e.g., rows) should be rearranged.

Non-Obvious Insights

  • Legacy Discouragement: RandomState is essentially in maintenance mode; Generator is faster and has better statistical distribution qualities.
  • Small Seed Limitation: Seeding with small integers (0-100) limits the reachable state space; SeedSequence ensures high-entropy starting states.
  • Bitstream Instability: Even with the same seed, the bitstream is not guaranteed to be identical across different NumPy versions due to algorithmic improvements.

Evidence

  • "In general, users will create a Generator instance with default_rng and call the various methods on it to obtain samples." Source
  • "SeedSequence mixes sources of entropy in a reproducible way to set the initial state for independent and very probably non-overlapping BitGenerators." Source

Scripts

  • scripts/numpy-random_tool.py: Implements parallel seed spawning and reproducible RNG.
  • scripts/numpy-random_tool.js: Basic random sampling logic.

Dependencies

  • numpy (Python)

References