lua examples/probability_helpers.lua

[HubertRonald]

Summary

This PR prepares LuaSF for v0.7.0 by implementing lightweight probability and combinatorics helpers.

It builds on the modular source layout introduced in v0.5.0 and the shape statistics helpers added in v0.6.0.

What changed

Implemented probability helpers

Implemented:

src/luasf/probability.lua

The module adds:

stats.factorial(n)
stats.permutations(n, r)
stats.combinations(n, r)
stats.permutations_with_repetition(n, r)
stats.combinations_with_repetition(n, r)
stats.nPr(n, r)
stats.nCr(n, r)

Combinatorics scope

This release makes the distinction between combinatorics without repetition and with repetition explicit:

stats.permutations(n, r)                 -- ordered selections without repetition
stats.combinations(n, r)                 -- unordered selections without repetition
stats.permutations_with_repetition(n, r) -- ordered selections with repetition
stats.combinations_with_repetition(n, r) -- unordered selections with repetition

Aliases were also added:

stats.nPr(n, r) -- alias for permutations(n, r)
stats.nCr(n, r) -- alias for combinations(n, r)

Added tests

Added:

spec/test_probability.lua

The tests cover:

• factorial(n)
• permutations without repetition
• combinations without repetition
• permutations with repetition
• combinations with repetition
• nPr and nCr aliases
• validation for invalid inputs

Added example

Added:

examples/probability_helpers.lua

The example demonstrates:

stats.factorial(5)
stats.permutations(5, 3)
stats.combinations(5, 3)
stats.permutations_with_repetition(5, 3)
stats.combinations_with_repetition(5, 3)

Added LuaRocks rockspec

Added:

rockspec/luasf-0.7.0-1.rockspec

The rockspec prepares LuaSF for the v0.7.0 LuaRocks package release.

Updated workflows

Updated GitHub Actions workflows to include the new probability helper test and example:

lua spec/test_probability.lua
lua examples/probability_helpers.lua

Updated files:

.github/workflows/ci.yml
.github/workflows/publish-luarocks.yml

Updated documentation

Updated documentation for the new helpers:

README.md
docs/api.md
CHANGELOG.md
CONTRIBUTING.md

Compatibility notes

This PR does not remove or rename existing public functions.

Existing usage remains supported:

local stats = require("luasf")
local stats = require("LuaSF")
local stats = require("LuaStat")

Legacy function names remain available.

Numeric precision note

Probability helpers use Lua numbers. Very large inputs may exceed the practical numeric precision or range of the Lua runtime.

Arbitrary-precision arithmetic is intentionally not included in this release to keep LuaSF small, pure-Lua, and dependency-light.

Testing

Test locally with:

lua spec/test_stats.lua
lua spec/test_distributions.lua
lua spec/test_sampling.lua
lua spec/test_bivariate.lua
lua spec/test_shape.lua
lua spec/test_probability.lua

Examples can be run with:

lua examples/dice_simulation.lua
lua examples/normal_quality_control.lua
lua examples/gamma_distribution.lua
lua examples/weighted_loot_drop.lua
lua examples/monte_carlo_pi.lua
lua examples/poisson_arrivals.lua
lua examples/binomial_coin_flips.lua
lua examples/bootstrap_mean.lua
lua examples/covariance_correlation.lua
lua examples/skewness_kurtosis.lua
lua examples/probability_helpers.lua

Release target

This PR prepares LuaSF for:

v0.7.0 - Probability Helpers

Scope note

LuaSF remains focused on lightweight statistics, probability helpers, random variables, sampling, and simulation utilities.

Optimization-based modeling, machine learning workflows, model training pipelines, and non-linear regression remain outside the current scope of LuaSF.