Coin Lab

Coin Lab is the Editor-facing experiment for fair or biased two-outcome coin systems and exact Heads-count analysis.

It provides an intuitive Bernoulli/Binomial workflow without creating a second Coin mathematics engine.

For the underlying concept and gameplay API choices, see Coins.md.

1. Purpose

Use Coin Lab to:

Visualize a fair coin.
Bias toward Heads or Tails.
Analyze multiple-coin Heads counts.
Compare exact theory with Automatic Flips.
Reproduce an empirical experiment with a Fixed Seed.
Run an unpredictable Secure experiment.
Export the configured experiment.

2. Main Inputs

The approved Coin Lab authoring surface includes:

Number of Coins.
Number of Flips.
Bias Toward:
- Neutral.
- Heads.
- Tails.
Bias magnitude.
Random mode:
- Fixed Seed.
- Secure.

Coin terminology is intentional because it is easier to understand for this specialized workflow.

3. Number of Coins

Number of Coins defines the Heads-count variable being analyzed.

For N coins:

0 ... N Heads

Example:

Number of Coins = 5

produces theoretical outcomes:

0, 1, 2, 3, 4, 5 Heads

4. Number of Flips

Number of Flips controls the Lab’s requested empirical flip/trial workload.

It belongs to observed sampling, not to the exact definition of one coin’s probability.

The export includes the empirical trial count so observed results can be interpreted correctly.

5. Bias

A neutral coin gives Heads and Tails equal probability.

Coin Bias moves the probability toward:

Heads.
Tails.

The Lab uses a normal probabilistic authoring range up to:

99.999%

rather than exposing deterministic 100% endpoints as ordinary Lab tuning values.

6. Exact Heads-Count Analysis

The theoretical result is an exact Heads-count PMF.

For two neutral coins:

0 Heads = 1/4
1 Head  = 1/2
2 Heads = 1/4

Changing Bias changes the underlying single-coin Heads probability and therefore the exact multi-coin count distribution.

7. Evaluate

Evaluate updates the exact theoretical coin configuration.

It does not require a gameplay Runtime Stream.

When the authored configuration changes, stale observed Automatic Flips must not remain presented as if they belonged to the new configuration.

8. Automatic Flips

Automatic Flips performs the Lab’s empirical observation experiment.

It uses isolated Probability Director random behavior rather than consuming an unrelated gameplay Stream.

The observed result can be compared directly with the exact Heads-count theory.

9. Fixed Seed

Fixed mode makes the isolated empirical experiment reproducible.

Equivalent:

Coin configuration.
Flip workload.
Fixed Seed.

reproduces the same compatible empirical experiment.

Use Fixed for debugging/comparison.

10. Secure

Secure mode uses Probability Director’s Secure random infrastructure.

Secure internal state is not exposed or persisted by Coin Lab.

Use Secure for a fresh unpredictable empirical experiment.

Do not expect Secure export metadata to reproduce the run.

11. Chart Semantics

Coin Lab uses the shared semantic chart colors.

Color	Meaning
Blue	Base / theoretical
Green	Configured / Bias where applicable
Orange	Empirical / Automatic Flips

A finite empirical run is not the exact probability.

12. Base and Configured

Neutral:

Base is the fair reference.
No redundant identical Configured series is needed.

Nonzero Bias:

Blue remains Base.
Green shows the Bias-configured result.

This isolates the effect of Coin Bias.

13. Observed Sampling Variation

Automatic Flips produces a finite sample.

Finite empirical percentages can differ from exact theory.

That is expected.

The relevant interpretation is whether repeated/larger experiments behave consistently with the theoretical configuration, not whether one finite run matches every exact percentage.

14. Stale-State Protection

Changing meaningful coin configuration invalidates old empirical observations.

Examples:

Number of Coins.
Bias direction.
Bias magnitude.
Other configuration that changes the analyzed experiment.

The Lab must not leave old Automatic Flips attached to new theory.

15. Export

Coin Lab exports the current theoretical/empirical experiment using approved Lab export formats.

The export includes relevant concepts such as:

Number of Coins.
Number of Flips / trial count.
Bias mode/magnitude.
Random mode.
Fixed Seed when applicable.
Exact theoretical result.
Empirical result.

Secure exports never contain reconstructable Secure state.

16. Coin Lab vs. Probability Director Lab

Use Coin Lab for intuitive coin terminology:

Heads / Tails
Number of Coins
Automatic Flips

Use Probability Director Lab when the general probability model is the focus:

Numerator / Denominator
Probability Bias
Bernoulli/Binomial
Monte Carlo
isolated Lab Samples

17. Coin Lab vs. Distribution Lab

Distribution Lab exposes Bernoulli/Binomial as general families alongside other distributions.

Coin Lab is the specialized educational/analysis view.

Choose the presentation that best matches the developer’s task.

18. Gameplay Stream Isolation

Coin Lab’s empirical experiment is isolated.

It does not execute live stream operations; use Probability Director Runtime Controls for an intentional live probe.

For gameplay stream behavior, use:

Runtime Bernoulli/Binomial APIs, or
Probability Director Runtime Controls live stream probes when intentional gameplay-stream consumption is required.

19. Failure Handling

Invalid authoring should be rejected visibly.

Examples:

Invalid coin count.
Invalid empirical flip count.
Invalid Bias input.
Invalid Fixed Seed-related input where applicable.

A failed Evaluate must not leave a stale successful chart as the apparent current result.

20. Recommended Workflow

1. Set Number of Coins
2. Select Neutral / Heads / Tails Bias
3. Set Bias magnitude
4. Evaluate exact theory
5. Choose Fixed or Secure
6. Set Number of Flips
7. Run Automatic Flips
8. Compare observed vs theory
9. Export

21. Common Mistakes

Every finite run should match theory exactly

No. Sampling variation is normal.

Secure is more fair

No. Probability fairness and Seed Source are separate.

Number of Flips defines the exact PMF

No. It controls the empirical workload.

Coin Lab mutates my gameplay Stream

No. The empirical experiment is isolated.

22. Quick Reference

Number of Coins
    = Heads-count support 0..N

Bias
    = move probability toward Heads/Tails

Evaluate
    = exact theoretical result

Automatic Flips
    = isolated empirical experiment

Fixed Seed
    = reproducible experiment

Secure
    = fresh unpredictable experiment