README.md

---
title: Beam UDL Calculator — Deterministic + Explainable
emoji: 🧮
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 5.48.0
app_file: app.py
pinned: false
license: mit
---

# Beam UDL Calculator — Deterministic + Explainable

A transparent, first‑principles **simply supported beam** calculator under a **uniformly distributed load (UDL)**.  
The math is **deterministic**; an optional LLM produces a **plain‑English explanation** grounded purely in the computed numbers.

- Deterministic backend returns a **structured record** (JSON) with inputs, units, equations (LaTeX), results, and pass/fail checks — so users can **see the math**.
- Gradio UI shows (i) **Numerical results** and (ii) **Explain the results**.
- Optional LLM explanation (Hugging Face Transformers). When disabled, a deterministic template explainer is used.

---

## Scope & Assumptions

- Euler–Bernoulli beam, small deflections; linear elastic material.
- Uniformly distributed load across the entire span; simply supported ends.
- Educational helper; **not** a design code. Use engineering judgment and applicable standards.

---

## Inputs, Units, and Valid Ranges

| Name         | Unit | Range        | Default | Notes                                 |
|--------------|------|--------------|---------|----------------------------------------|
| `L`          | m    | 0.5–30       | 6.0     | Span length                            |
| `w_kN_per_m` | kN/m | 0–50         | 10.0    | Uniformly distributed load             |
| `E_GPa`      | GPa  | 50–210       | 200     | Young’s modulus (steel ≈ 200)          |
| `I_m4`       | m⁴   | 1e−7–1e−2    | 5.0e−5  | Second moment of area                  |
| `S_m3`       | m³   | 1e−6–1e−1    | 5.0e−4  | Section modulus                        |
| `Fy_MPa`     | MPa  | 150–700 (opt)| 250     | Yield strength (optional stress check) |
| `defl_ratio` | L/–  | 180–1000     | 360     | Allowable deflection limit             |

---

## Governing Equations (first principles)

- Max bending moment: \( M_{\max} = \dfrac{w L^2}{8} \)  
- Max shear: \( V_{\max} = \dfrac{w L}{2} \)  
- Max elastic deflection: \( \delta_{\max} = \dfrac{5 w L^4}{384 E I} \)  
- Bending stress: \( \sigma_{\max} = \dfrac{M_{\max}}{S} \)

---

## What the app returns (structured record)

Example (abridged):
```json
{
  "meta": {"calc_name": "Simply supported beam under UDL", "version": "1.0.0", "timestamp_utc": "…"},
  "assumptions": ["Euler–Bernoulli…", "UDL over full span…", "No partial factors…"],
  "equations_TeX": {
    "M_max": "M_{\\max} = \\frac{w L^2}{8}",
    "V_max": "V_{\\max} = \\frac{w L}{2}",
    "delta": "\\delta_{\\max} = \\frac{5 w L^4}{384 E I}",
    "sigma": "\\sigma_{\\max} = \\frac{M_{\\max}}{S}"
  },
  "units": {
    "inputs": {"L": "m", "w_kN_per_m": "kN/m", "E_GPa": "GPa", "I_m4": "m^4", "S_m3": "m^3", "Fy_MPa": "MPa", "defl_ratio": "L/ratio"},
    "outputs": {"M_max_kN_m": "kN·m", "V_max_kN": "kN", "delta_mm": "mm", "sigma_MPa": "MPa"}
  },
  "inputs": { "L": 6.0, "w_kN_per_m": 10.0, "E_GPa": 200.0, "I_m4": 5e-5, "S_m3": 5e-4, "Fy_MPa": 250.0, "defl_ratio": 360 },
  "results": { "M_max_kN_m": 45.0, "V_max_kN": 30.0, "delta_mm": 16.9, "sigma_MPa": 90.0 },
  "checks": {
    "stress": {"criterion": "sigma <= Fy", "utilization": 0.36, "status": "OK"},
    "deflection": {"criterion": "delta <= L/360", "allowable_mm": 16.67, "utilization": 1.01, "status": "NG"}
  },
  "validation": {"passed": true, "messages": []},
  "notes": "Educational tool; not a substitute for design codes or professional judgement."
}
```

---

## References

1. Gere, J.M., & Timoshenko, S.P. _Mechanics of Materials_.
2. Roark, R.J., & Young, W.C. _Roark’s Formulas for Stress and Strain_.
3. Beer, F.P., & Johnston, E.R. _Mechanics of Materials_.  
   _(Used to confirm the standard UDL formulas and assumptions.)_

## License
- MIT

## Acknowledgments
- GenAI usage: Explanatory text and repo scaffolding were assisted by ChatGPT.
- All engineering formulas and outputs are deterministic and were verified against standard references.