Upload app.py

app.py

@@ -0,0 +1,355 @@
+# -*- coding: utf-8 -*-
+"""natural_language_gradio.ipynb
+
+Automatically generated by Colab.
+
+Original file is located at
+    https://colab.research.google.com/drive/135ewhMpX2YZA9ysE_QNN0yFQVWYaeW34
+"""
+
+!pip install gradio transformers sentencepiece pandas
+
+import json, pandas as pd
+from dataclasses import dataclass, asdict
+
+import math
+from dataclasses import dataclass, asdict
+from typing import Dict, Any
+
+@dataclass
+class PIDInputs:
+    tau_s: float            # plant time constant [s], tau > 0
+    Kp: float               # proportional gain
+    Ki: float               # integral gain (>0 for step tracking)
+    Kd: float               # derivative gain
+    step_amplitude: float = 1.0   # unit step default
+    settling_pct: float = 0.02    # 2% criterion for settling time
+
+def validate_inputs(x: PIDInputs) -> Dict[str, Any]:
+    issues = []
+    # Reasonable ranges for a compact, safe demo. Adjust as needed.
+    if not (0.01 <= x.tau_s <= 10.0):
+        issues.append(f"tau must be in [0.01, 10] s, got {x.tau_s:.4g}")
+    if not (-0.9 <= x.Kp <= 200.0):
+        issues.append(f"Kp should be in [-0.9, 200], got {x.Kp:.4g}")
+    if not (1e-6 <= x.Ki <= 1e4):
+        issues.append(f"Ki should be in [1e-6, 1e4], got {x.Ki:.4g}")
+    if not (-0.009 <= x.Kd <= 100.0):
+        issues.append(f"Kd should be in [-0.009, 100], got {x.Kd:.4g}")
+    if x.tau_s + x.Kd <= 0:
+        issues.append("tau + Kd must be > 0 for a proper 2nd-order form.")
+    if x.step_amplitude == 0:
+        issues.append("step amplitude should be non-zero for meaningful metrics.")
+    if not (0.005 <= x.settling_pct <= 0.1):
+        issues.append("settling_pct should be within [0.005, 0.1] (i.e., 0.5% to 10%).")
+    return {"ok": len(issues) == 0, "issues": issues}
+
+def compute_pid(x: PIDInputs) -> Dict[str, Any]:
+    val = validate_inputs(x)
+    status = "ok" if val["ok"] else "invalid"
+
+    wn = None
+    zeta = None
+    if (x.tau_s + x.Kd) > 0 and x.Ki > 0:
+        wn = math.sqrt(x.Ki / (x.tau_s + x.Kd))
+        denom = 2.0 * math.sqrt(x.Ki * (x.tau_s + x.Kd))
+        zeta = (x.Kp + 1.0) / denom
+
+    # --- NEW: poles & damping classification ---
+    poles = None
+    damping_class = None
+    if wn is not None and wn > 0 and zeta is not None:
+        # Standard 2nd-order characteristic: s^2 + 2ζωn s + ωn^2 = 0
+        # Poles: s = -ζωn ± ωn*sqrt(ζ^2 - 1)
+        re = -zeta * wn
+        disc = zeta**2 - 1.0
+        if disc < 0:
+            # complex-conjugate poles
+            im = wn * math.sqrt(1.0 - zeta**2)
+            poles = [complex(re,  im), complex(re, -im)]
+            damping_class = "underdamped (ζ<1): complex-conjugate poles"
+        elif abs(disc) < 1e-12:
+            poles = [complex(re, 0.0), complex(re, 0.0)]
+            damping_class = "critically damped (ζ≈1): repeated real pole"
+        else:
+            # distinct real poles
+            root = wn * math.sqrt(disc)
+            poles = [complex(re + root, 0.0), complex(re - root, 0.0)]
+            damping_class = "overdamped (ζ>1): two distinct real poles"
+
+    metrics = {}
+    if wn is not None and zeta is not None and wn > 0 and zeta > 0:
+        if zeta < 1.0:
+            wd = wn * math.sqrt(1.0 - zeta**2)
+            Tp = math.pi / wd
+            Mp = math.exp(-math.pi * zeta / math.sqrt(1.0 - zeta**2))  # ratio
+        else:
+            wd = None
+            Tp = None
+            Mp = 0.0
+        Ts = 4.0 / (zeta * wn) * (0.02 / x.settling_pct)
+        if zeta < 1.0:
+            theta = math.acos(zeta)
+            Tr = (math.pi - theta) / (wn * math.sqrt(1.0 - zeta**2))
+        else:
+            Tr = 2.0 / wn
+        ess = 0.0
+
+        metrics = {
+            "wn_rad_s": wn,
+            "zeta": zeta,
+            "wd_rad_s": wd,
+            "Mp_pct": 100.0 * Mp,
+            "Tp_s": Tp,
+            "Ts_s": Ts,
+            "Tr_s": Tr,
+            "ess": ess,
+        }
+
+    structured = {
+        "meta": {
+            "model": "PID_on_1stOrder_v1",
+            "deterministic": True,
+            "assumptions": [
+                "Unity feedback.",
+                "1st-order plant G(s) = 1/(tau s + 1).",
+                "Linear time-invariant dynamics.",
+                "PID controller C(s) = Kp + Ki/s + Kd s.",
+                "Small-signal step response analysis."
+            ],
+            "units": {
+                "tau_s": "s",
+                "wn_rad_s": "rad/s",
+                "wd_rad_s": "rad/s",
+                "Tp_s": "s",
+                "Ts_s": "s",
+                "Tr_s": "s",
+                "Mp_pct": "%"
+            },
+            "valid_ranges": {
+                "tau_s": "[0.01, 10] s",
+                "Kp": "[-0.9, 200]",
+                "Ki": "[1e-6, 1e4]",
+                "Kd": "[-0.009, 100]",
+                "tau+Kd": "> 0",
+                "Ki_positive": "> 0",
+                "settling_pct": "[0.005, 0.1]"
+            }
+        },
+        "inputs": asdict(x),
+        "validation": val,
+        "normalized_second_order": {
+            "a2": x.tau_s + x.Kd,
+            "a1": 1.0 + x.Kp,
+            "a0": x.Ki,
+            "wn": wn,
+            "zeta": zeta
+        },
+        # --- NEW: add poles & classification in the payload ---
+        "poles": [complex(p).real if abs(p.imag) < 1e-15 else p for p in (poles or [])],
+        "damping_class": damping_class,
+        "metrics": metrics,
+        "status": status
+    }
+    return structured
+
+import gradio as gr
+import pandas as pd
+from transformers import pipeline
+from typing import Dict, Any
+
+# from core import PIDInputs, compute_pid
+
+from transformers import AutoTokenizer, AutoModelForCausalLM, pipeline
+MODEL_ID = "HuggingFaceTB/SmolLM2-135M-Instruct"
+_tokenizer = AutoTokenizer.from_pretrained(MODEL_ID)
+_model = AutoModelForCausalLM.from_pretrained(MODEL_ID, device_map="auto")
+explainer = pipeline(task="text-generation", model=_model, tokenizer=_tokenizer)
+
+def explain_structured(d: dict) -> str:
+    """
+    Explain what the OUTPUT means (stability class, ωn, ζ, poles, overshoot, Tr/Tp/Ts, ess).
+    Uses the SmolLM explainer with deterministic decoding, then falls back to a
+    deterministic Markdown explanation if the model returns too little text.
+    """
+    meta  = d.get("meta", {})
+    m     = d.get("metrics", {})
+    norm  = d.get("normalized_second_order", {})
+    poles = d.get("poles", [])
+    dampc = d.get("damping_class", None)
+    val   = d.get("validation", {})
+    status = d.get("status")
+    issues = val.get("issues", [])
+
+    # ---------- helpers ----------
+    def r(v, n=4, na="N/A"):
+        try:
+            return f"{float(v):.{n}g}"
+        except Exception:
+            return na if v is None else str(v)
+
+    def pstr(p):
+        try:
+            # p may already be complex or a float
+            if isinstance(p, complex) or (hasattr(p, "imag") and p.imag != 0):
+                return f"{p.real:+.4g} {'+' if p.imag>=0 else '-'} j{abs(p.imag):.4g}"
+            return f"{float(p):+.4g}"
+        except Exception:
+            return str(p)
+
+    def dedup_lines(md: str) -> str:
+        seen, out = set(), []
+        for line in md.splitlines():
+            key = line.strip()
+            # never dedup headers; only de-dup plain bullet/paragraph lines
+            if key and not key.startswith("#") and key in seen:
+                continue
+            seen.add(key)
+            out.append(line)
+        return "\n".join(out)
+
+    # ---------- invalid → deterministic, no LLM ----------
+    if status != "ok" or issues:
+        bullets = "\n".join([f"- {iss}" for iss in issues]) if issues else "- Check inputs."
+        return f"""# Results Explanation
+
+**Status:** ❌ Invalid inputs
+
+Fix these first:
+{bullets}
+
+**Why it matters**
+- τ+Kd must be > 0 to form a valid 2nd-order model.
+- Ki > 0 (type-1) gives zero steady-state error to a step.
+"""
+
+    # ---------- numeric snapshot for prompt & fallback ----------
+    wn   = norm.get("wn")
+    zeta = norm.get("zeta")
+    Mp   = m.get("Mp_pct")
+    Tp   = m.get("Tp_s")
+    Ts   = m.get("Ts_s")
+    Tr   = m.get("Tr_s")
+    ess  = m.get("ess")
+    poles_text = ", ".join(pstr(p) for p in poles) if poles else "N/A"
+
+    snapshot = (
+        f"- ωₙ (natural frequency): {r(wn)} rad/s\n"
+        f"- ζ (damping ratio): {r(zeta)}  → {dampc or 'N/A'}\n"
+        f"- Poles: {poles_text}\n"
+        f"- Overshoot: ≈ {r(Mp,3)} %\n"
+        f"- Rise time Tr: ≈ {r(Tr)} s\n"
+        f"- Peak time Tp: ≈ {r(Tp)} s\n"
+        f"- Settling time Ts: ≈ {r(Ts)} s\n"
+        f"- Steady-state error (step): {r(ess)}"
+    )
+
+    # ---------- LLM prompt (deterministic, stability-focused) ----------
+    prompt = (
+        "You are a controls engineer. Explain what the OUTPUT VALUES MEAN.\n"
+        "Write CLEAR MARKDOWN with short, specific bullets. No repetition.\n\n"
+        "## Stability classification (what ζ and the poles tell you)\n"
+        "- State whether the system is underdamped, critically damped, or overdamped based on ζ and the pole pattern.\n"
+        "- Explain what complex vs real poles imply for oscillations and smoothness.\n\n"
+        "## What ωₙ means (speed)\n"
+        "- Explain that ωₙ sets the overall speed scale of the response (larger ωₙ → shorter Tr and Ts).\n\n"
+        "## What ζ means (smoothness vs overshoot)\n"
+        "- Interpret ζ ranges (<1, ≈1, >1) in terms of oscillation and overshoot.\n\n"
+        "## What each time/percent metric means\n"
+        "- Overshoot: how much the peak exceeds final value.\n"
+        "- Tr: time to go from low to near-final (e.g., 10–90%).\n"
+        "- Tp: time to first peak.\n"
+        "- Ts: time to settle within the chosen band.\n"
+        "- ess: final error for a step; with Ki>0 it is 0.\n\n"
+        "## How the poles relate to that behavior\n"
+        "- Connect pole real part to decay speed; imaginary part to oscillation frequency.\n\n"
+        "## Numeric snapshot\n"
+        f"{snapshot}\n"
+    )
+
+    # ---------- deterministic generation with anti-repetition ----------
+    gen = explainer(
+        prompt,
+        max_new_tokens=220,
+        do_sample=False,
+        temperature=0.0,
+        top_p=1.0,
+        top_k=0,
+        repetition_penalty=1.15,
+        no_repeat_ngram_size=4,
+        eos_token_id=_tokenizer.eos_token_id,
+        pad_token_id=_tokenizer.eos_token_id,
+        return_full_text=False
+    )[0]["generated_text"]
+
+    # ---------- SHORT-OUTPUT FALLBACK (your requested addition) ----------
+    MIN_WORDS = 30
+    if not gen or len(gen.split()) < MIN_WORDS:
+        gen = f"""## Stability classification
+- ζ = {r(zeta)} → {dampc or 'N/A'}.
+
+## Meaning of ωₙ and ζ
+- ωₙ = {r(wn)} rad/s sets the speed scale (larger ωₙ → faster rise/settle).
+- ζ controls smoothness/overshoot: ζ<1 underdamped; ζ≈1 critically damped; ζ>1 overdamped.
+
+## Poles and behavior
+- Poles: {poles_text}
+- More negative real part → faster decay; nonzero imaginary part → oscillations.
+
+## Time-domain metrics
+- Overshoot ≈ {r(Mp,3)} %  |  Tr ≈ {r(Tr)} s  |  Tp ≈ {r(Tp)} s  |  Ts ≈ {r(Ts)} s  |  ess = {r(ess)}
+
+## Tuning tip
+- Raise Ki to increase ωₙ (speed). If overshoot or oscillation appears (ζ too low), add Kd or increase Kp to raise damping.
+"""
+
+    return dedup_lines(gen)
+
+def run_calc(tau_s, Kp, Ki, Kd, step_amp, settling_pct):
+    x = PIDInputs(
+        tau_s=float(tau_s), Kp=float(Kp), Ki=float(Ki), Kd=float(Kd),
+        step_amplitude=float(step_amp), settling_pct=float(settling_pct) / 100.0  # slider in %, convert to fraction
+    )
+    structured = compute_pid(x)
+
+    # Display normalized form + metrics in a compact table
+    rows = []
+    for k, v in structured.get("normalized_second_order", {}).items():
+        rows.append(["2nd-order", k, v])
+    for k, v in structured.get("metrics", {}).items():
+        rows.append(["metrics", k, v])
+    df = pd.DataFrame(rows, columns=["section", "key", "value"])
+
+    explanation = explain_structured(structured)
+    return df, explanation, structured
+
+with gr.Blocks(title="PID Controls Calculator (1st-Order Plant)", theme=gr.themes.Soft()) as demo:
+    gr.Markdown("# PID Feedback Controls — Deterministic Calculator")
+    gr.Markdown(
+        "Unity-feedback PID on a first-order plant G(s)=1/(τs+1). "
+        "We derive the equivalent 2nd-order parameters (ωₙ, ζ) and step-response metrics (overshoot, rise, peak, settling)."
+    )
+
+    with gr.Row():
+        with gr.Column():
+            tau_s = gr.Slider(0.01, 10.0, value=0.5, step=0.01, label="Plant time constant τ [s]")
+            Kp = gr.Slider(-0.9, 200.0, value=1.0, step=0.1, label="Kp")
+            Ki = gr.Slider(1e-6, 1e4, value=1.0, step=0.1, label="Ki")
+            Kd = gr.Slider(-0.009, 100.0, value=0.0, step=0.001, label="Kd")
+            step_amp = gr.Slider(0.1, 10.0, value=1.0, step=0.1, label="Step amplitude")
+            settling_pct = gr.Slider(0.5, 10.0, value=2.0, step=0.1, label="Settling band [%]")
+            go = gr.Button("Compute", variant="primary")
+
+        with gr.Column():
+            gr.Markdown("### Numerical Results")
+            table = gr.Dataframe(headers=["section", "key", "value"], interactive=False)
+            gr.Markdown("### Explain the Results")
+            explanation = gr.Markdown()
+            gr.Markdown("### Raw Structured Output")
+            json_out = gr.JSON(label="Structured JSON")
+
+    go.click(run_calc, inputs=[tau_s, Kp, Ki, Kd, step_amp, settling_pct],
+             outputs=[table, explanation, json_out])
+
+if __name__ == "__main__":
+    demo.launch()