Rainfall depth and standing water — reproducible teaching arithmetic
Recorded for the Gumi article dated 2026-10-14.

FILES
- rainfall-depth-teaching.py
- rainfall-depth-teaching-README.txt
- rainfall-depth-teaching/results.json

RUN
Requires Python 3.9 or newer; standard library only.
From the directory containing the script:

python3 rainfall-depth-teaching.py rainfall-depth-output

This writes rainfall-depth-output/results.json and prints a summary.
The supplied results were generated with:

python3 public/examples/rainfall-depth-teaching.py public/examples/rainfall-depth-teaching

Recorded environment: Python 3.9.6, macOS 27.0.1 / Darwin, arm64.
Re-running changes recorded_at and environment fields; numerical cases stay fixed.

中文说明
所有数值都是合成的教学输入，不是任何地点的实测雨量或天气预报。
公式：雨量 r(mm) × 水平总面积 A(m²) = 输入水量(L)。
地表最终留水量 = 输入水量 × 给定比例 f。
固定面积内的模型平均水深(mm) = 最终留水量(L) ÷ 接收面积 B(m²)。
假设整个 A 上均匀降液态雨；A 已含 B；初始存水为零；没有 A 外来水。
f 是给定的最终留水量比例，不是估计或标定的径流系数；B 固定。
只计算平均深度，不计算最低处水深、地形变化、渗入、排水或溢流。
实际运行验证了算术、时间序列汇总和下列输入检查，没有验证实物雨量计
或真实积水情况，不能用来预测洪水、现场水位或判断道路是否可通行。

日本語説明
すべての数値は合成の教材入力で、実測雨量や天気予報ではありません。
雨量 r(mm) × 水平の全体面積 A(m²) = 入力水量(L)。
地表に最後に残る水量 = 入力水量 × 与えた割合 f。
固定面積でのモデル平均水深(mm) = 残る水量(L) ÷ 受ける面積 B(m²)。
A 全体に一様な液体の雨が降り、A は B を含み、初期貯留はゼロで、
A 外からの流入はないと仮定します。f は与えた最終貯留の割合で、
推定・校正した流出係数ではありません。B は一定とします。
平均水深だけを計算し、最も低い点の深さ、地形、浸透、排水、越流を
計算しません。実行で確認したのは算術、系列の集計と入力チェックです。
実物の雨量計や実際の滞水を検証しておらず、洪水、現場の水位、道路の
通行可否を予測するためには使えません。

RECORDED CASES
All three use r=10 mm and A=100 m² (A includes B), input volume 1000 L.
1. f=1,   B=100 m²: retained 1000 L, mean depth 10 mm.
2. f=0.3, B=100 m²: retained 300.0 L, mean depth 3.0 mm.
3. f=1,   B=20 m²:  retained 1000 L, mean depth 50 mm.
No additional direct rainfall on B is added a second time.

BOUNDARY CHECKS
1 mm on 1 m² gives 1 L. With the stated zero-initial/zero-external-water
conditions, zero rain or zero retained fraction gives zero mean depth.
Seven invalid inputs are rejected with ValueError: negative rain, zero A,
zero B, f<0, f>1, B>A under this model's definition, and nonfinite rain (NaN).
B>A is rejected because A was defined to contain B, not because real water
surfaces cannot expand.

TIME PROFILES
Each profile contains 24 fixed clock-hour amounts, not instantaneous rates.
- 24 × 1.25 mm: total 30.00 mm, mean 1.25 mm/h, largest clock-hour 1.25 mm.
- 30 mm then 23 × 0 mm: total 30 mm, mean 1.25 mm/h, largest clock-hour 30 mm.
- 6 × 5 mm then 18 × 0 mm: total 30 mm, mean 1.25 mm/h, largest clock-hour 5 mm.
Largest clock-hour amount is not an arbitrary rolling 60-minute maximum.
The trailing zeros in 30.00 are Decimal representation, not observational
precision. No physical flow, infiltration, drainage, or flood model is run.

PRIMARY REFERENCES (checked 2026-10-14)
Rainfall definition, simple cylinder, time labels:
https://www.jma.go.jp/jma/kishou/know/faq/faq1.html
Specific tipping-bucket instrument described by JMA (20 cm, 0.5 mm/tip):
https://www.jma.go.jp/jma/kishou/know/faq/faq11.html
Units:
https://www.nist.gov/pml/owm/metric-si-prefixes
https://www.nist.gov/pml/owm/si-units-volume
Water-budget and runoff background:
https://www.usgs.gov/water-science-school/science/watersheds-and-drainage-basins
https://www.usgs.gov/water-science-school/science/surface-runoff-and-water-cycle

The calculations are independent synthetic teaching cases. The references
do not supply or validate the chosen retained fractions or local water depths.