English

Biased Random Number Generation

This Rust library provides a simple yet effective function, biased_random(n, bias), for generating non-uniformly distributed random numbers. It allows for the creation of random values where lower numbers have a higher probability of being selected, controlled by a bias factor. This is particularly useful in scenarios like game development (e.g., for weighted loot drops), simulations, or any application requiring a controlled, non-uniform probability distribution.

Demonstration

The core of the library is the biased_random function. Here's how to use it to generate a distribution of numbers and visualize it as a histogram.

Example Code

This example generates 10,000 random numbers between 0 and 19, with a bias factor of 3.0, and then prints a histogram of the results.

use std::collections::BTreeMap;
use biased::biased_random;

fn main() {
    const N: u32 = 20;      // Upper bound
    const BIAS: f64 = 3.0;  // Bias factor
    const SAMPLES: u32 = 10000; // Number of samples

    let mut histogram = BTreeMap::new();
    for _ in 0..SAMPLES {
        let num = biased_random(N, BIAS);
        *histogram.entry(num).or_insert(0) += 1;
    }

    let max_freq = histogram.values().max().cloned().unwrap_or(0);
    const MAX_BAR_WIDTH: usize = 20;

    println!("> ASCII Histogram of the results (n={}, bias={}):", N, BIAS);

    for i in 0..N {
        let freq = histogram.get(&i).cloned().unwrap_or(0);
        let bar_width = if max_freq > 0 {
            (freq as usize * MAX_BAR_WIDTH) / max_freq as usize
        } else {
            0
        };
        let bar: String = "█".repeat(bar_width);
        let percentage = (freq as f64 / SAMPLES as f64) * 100.0;
        println!("{:>3}: {:<5} ({:>5.2}%) |{}", i, freq, percentage, bar);
    }
}

Output

As you can see from the histogram, lower numbers appear much more frequently, demonstrating the effect of the bias.

> ASCII Histogram of the results (n=20, bias=3):
  0: 3715  (37.15%) |████████████████████
  1: 988   ( 9.88%) |█████
  2: 655   ( 6.55%) |███
  3: 495   ( 4.95%) |██
  4: 436   ( 4.36%) |██
  5: 412   ( 4.12%) |██
  6: 344   ( 3.44%) |█
  7: 321   ( 3.21%) |█
  8: 317   ( 3.17%) |█
  9: 268   ( 2.68%) |█
 10: 240   ( 2.40%) |█
 11: 263   ( 2.63%) |█
 12: 213   ( 2.13%) |█
 13: 217   ( 2.17%) |█
 14: 203   ( 2.03%) |█
 15: 215   ( 2.15%) |█
 16: 203   ( 2.03%) |█
 17: 159   ( 1.59%) |
 18: 173   ( 1.73%) |
 19: 163   ( 1.63%) |

Design and Technology

Algorithm

The biasing algorithm is straightforward and efficient:

A uniformly distributed random number r is generated in the range [0.0, 1.0).
This number is transformed using a power function: r.powf(bias). When bias > 1, this operation "warps" the distribution, pushing more values closer to 0.
The result is scaled from the [0.0, 1.0) range to the desired integer range [0, n).

This technique is a simple form of what is known as Inverse Transform Sampling, where a uniform distribution is mapped to a desired custom distribution.

Tech Stack

Language: Rust (2024 Edition)
Core Dependency: rand for the underlying uniform random number generation.

The project follows modern Rust practices, emphasizing clarity, safety, and minimal dependencies.

File Structure

The project is organized as follows:

.
├── Cargo.toml      # Package manifest and dependencies
├── src
│   └── lib.rs      # The core library code for biased_random
└── tests
    └── main.rs     # Integration tests and histogram generation

A Brief History of Randomness

The quest for high-quality random numbers is as old as computing itself. In the 1940s, during the Manhattan Project, scientists like John von Neumann required vast quantities of random numbers for their Monte Carlo simulations of neutron chain reactions. Initially, they used mechanical devices and published tables of random digits. However, these methods were slow and cumbersome.

Von Neumann proposed the "middle-square" method for generating pseudo-random numbers algorithmically: take a number, square it, and extract the middle digits as the next number. While innovative, it had flaws, such as tending to fall into short, repeating cycles. This early work highlighted the profound difficulty of making a deterministic machine produce something that appears truly random, paving the way for the sophisticated, statistically robust pseudo-random number generators (PRNGs) we rely on today in fields from cryptography to, well, biased random number generation in Rust!

中文

偏向性随机数生成

这个 Rust 库提供了一个简单而有效的函数 biased_random(n, bias)，用于生成非均匀分布的随机数。它允许创建随机值，其中较小的数字具有更高的被选中概率，这由一个 bias（偏向）因子控制。这在游戏开发（例如，用于加权战利品掉落）、模拟或任何需要受控的非均匀概率分布的应用中特别有用。

功能演示

该库的核心是 biased_random 函数。以下是如何使用它来生成数字分布并将其可视化为直方图。

示例代码

此示例生成 10,000 个介于 0 和 19 之间的随机数，偏向因子为 3.0，然后打印结果的直方图。

use std::collections::BTreeMap;
use biased::biased_random;

fn main() {
    const N: u32 = 20;      // 上限
    const BIAS: f64 = 3.0;  // 偏向因子
    const SAMPLES: u32 = 10000; // 采样次数

    let mut histogram = BTreeMap::new();
    for _ in 0..SAMPLES {
        let num = biased_random(N, BIAS);
        *histogram.entry(num).or_insert(0) += 1;
    }

    let max_freq = histogram.values().max().cloned().unwrap_or(0);
    const MAX_BAR_WIDTH: usize = 20;

    println!("> ASCII 直方图结果 (n={}, bias={}):", N, BIAS);

    for i in 0..N {
        let freq = histogram.get(&i).cloned().unwrap_or(0);
        let bar_width = if max_freq > 0 {
            (freq as usize * MAX_BAR_WIDTH) / max_freq as usize
        } else {
            0
        };
        let bar: String = "█".repeat(bar_width);
        let percentage = (freq as f64 / SAMPLES as f64) * 100.0;
        println!("{:>3}: {:<5} ({:>5.2}%) |{}", i, freq, percentage, bar);
    }
}

输出

从直方图中可以看出，较小的数字出现得更频繁，这展示了偏向因子的效果。

> ASCII 直方图结果 (n=20, bias=3):
  0: 3715  (37.15%) |████████████████████
  1: 988   ( 9.88%) |█████
  2: 655   ( 6.55%) |███
  3: 495   ( 4.95%) |██
  4: 436   ( 4.36%) |██
  5: 412   ( 4.12%) |██
  6: 344   ( 3.44%) |█
  7: 321   ( 3.21%) |█
  8: 317   ( 3.17%) |█
  9: 268   ( 2.68%) |█
 10: 240   ( 2.40%) |█
 11: 263   ( 2.63%) |█
 12: 213   ( 2.13%) |█
 13: 217   ( 2.17%) |█
 14: 203   ( 2.03%) |█
 15: 215   ( 2.15%) |█
 16: 203   ( 2.03%) |█
 17: 159   ( 1.59%) |
 18: 173   ( 1.73%) |
 19: 163   ( 1.63%) |

设计与技术

算法

偏向性算法直接且高效：

在 [0.0, 1.0) 范围内生成一个均匀分布的随机数 r。
使用幂函数 r.powf(bias) 对该数字进行变换。当 bias > 1 时，此操作会“扭曲”分布，将更多值推向 0。
将结果从 [0.0, 1.0) 范围缩放到所需的目标整数范围 [0, n)。

这种技术是所谓的“逆变换采样”的一种简单形式，它将一个均匀分布映射到一个期望的自定义分布。

技术栈

语言: Rust (2024 Edition)
核心依赖: rand 用于底层的均匀随机数生成。

该项目遵循现代 Rust 实践，强调代码的清晰性、安全性以及最小化依赖。

文件结构

项目结构组织如下：

.
├── Cargo.toml      # 包清单与依赖项
├── src
│   └── lib.rs      # biased_random 的核心库代码
└── tests
    └── main.rs     # 集成测试与直方图生成

随机性的简史

对高质量随机数的追求与计算本身一样古老。在 1940 年代的曼哈顿计划期间，像约翰·冯·诺伊曼这样的科学家需要大量的随机数来进行中子链式反应的蒙特卡洛模拟。最初，他们使用机械设备和已出版的随机数字表。然而，这些方法缓慢且笨拙。

冯·诺伊曼提出了用于算法生成伪随机数的“平方取中法”：取一个数，将其平方，然后提取中间的数字作为下一个数。虽然这个方法很有创意，但它存在缺陷，比如容易陷入简短的重复循环。这项早期工作凸显了让确定性机器产生看起来真正随机的东西的巨大困难，为我们今天在密码学乃至 Rust 中的偏向性随机数生成等领域所依赖的、统计上稳健的伪随机数生成器（PRNG）铺平了道路。

About

This project is an open-source component of i18n.site ⋅ Internationalization Solution.

i18 : MarkDown Command Line Translation Tool

The translation perfectly maintains the Markdown format.

It recognizes file changes and only translates the modified files.

The translated Markdown content is editable; if you modify the original text and translate it again, manually edited translations will not be overwritten (as long as the original text has not been changed).
i18n.site : MarkDown Multi-language Static Site Generator

Optimized for a better reading experience

关于

本项目为 i18n.site ⋅ 国际化解决方案的开源组件。

i18 : MarkDown 命令行翻译工具

翻译能够完美保持 Markdown 的格式。能识别文件的修改，仅翻译有变动的文件。

Markdown 翻译内容可编辑；如果你修改原文并再次机器翻译，手动修改过的翻译不会被覆盖（如果这段原文没有被修改）。
i18n.site : MarkDown 多语言静态站点生成器为阅读体验而优化。

biased 0.1.2