Spaces:
Sleeping
Sleeping
| # -*- coding: utf-8 -*- | |
| """natural_language_gradio.ipynb | |
| Automatically generated by Colab. | |
| Original file is located at | |
| https://colab.research.google.com/drive/135ewhMpX2YZA9ysE_QNN0yFQVWYaeW34 | |
| """ | |
| import json, pandas as pd | |
| from dataclasses import dataclass, asdict | |
| import math | |
| from dataclasses import dataclass, asdict | |
| from typing import Dict, Any | |
| 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() |