| name | fmpy-simulate |
| description | Run an FMPy simulation for a given FMU file. Use when the user wants to simulate an FMU, run a Functional Mock-up Unit, or work with FMI-based models. Also handles follow-up messages from the simulation config widget (messages starting with "SIMULATE:"). |
| disable-model-invocation | false |
| user-invocable | true |
| argument-hint | <path-to-fmu> |
| allowed-tools | Bash, Read, Glob |
FMPy FMU Simulation
What is an FMU? A Functional Mock-up Unit (FMU) is a self-contained simulation model in the FMI standard format. It can represent physical systems, control loops, or entire plants. FMPy is a Python tool for running these models without installing any simulator software.
Phase detection
Check $ARGUMENTS:
- If it starts with
SIMULATE: → this is a Phase 2 call from the widget button. Jump to Phase 2.
- Otherwise → this is a Phase 1 call. Proceed below.
Phase 1 — Inspect FMU and show configuration widget
Step 1 — Resolve FMU path
Extract FMU_PATH as the first argument. If missing or not ending in .fmu, use the Glob tool to find .fmu files nearby and ask the user to pick one.
Step 2 — Inspect the FMU
uv run --with fmpy python3 - <<'PYEOF'
import sys, os, json
from fmpy import read_model_description, dump, supported_platforms
import platform as _platform
FMU_PATH = "$FMU_PATH"
if not os.path.isfile(FMU_PATH):
print(f"ERROR: File not found: {FMU_PATH}"); sys.exit(1)
dump(FMU_PATH)
md = read_model_description(FMU_PATH)
system = _platform.system().lower()
os_tag = "darwin64" if system == "darwin" else "linux64" if system == "linux" else "win64"
sp = supported_platforms(FMU_PATH)
if sp and os_tag not in sp and "c-code" not in sp:
print(f"\nERROR: FMU supports {sp}, cannot run on {os_tag}."); sys.exit(1)
de = md.defaultExperiment
inputs = [v for v in md.modelVariables if v.causality == 'input']
params = [v for v in md.modelVariables if v.causality == 'parameter']
outputs = [v for v in md.modelVariables if v.causality == 'output']
sim_type = "CoSimulation" if md.coSimulation else "ModelExchange"
start_time = float(de.startTime) if de and de.startTime is not None else 0.0
stop_time = float(de.stopTime) if de and de.stopTime is not None else 10.0
step_size = float(de.stepSize) if de and de.stepSize is not None else 0.01
info = {
"fmu_path": FMU_PATH,
"model_name": md.modelName,
"fmi_version": md.fmiVersion,
"sim_type": sim_type,
"start": start_time,
"stop": stop_time,
"step": step_size,
"inputs": [{"name": v.name, "start": v.start, "unit": v.unit or "", "desc": v.description or ""} for v in inputs],
"params": [{"name": v.name, "start": v.start, "unit": v.unit or "", "desc": v.description or ""} for v in params],
"outputs": [{"name": v.name, "unit": v.unit or "", "desc": v.description or ""} for v in outputs],
}
print("FMUINFO:" + json.dumps(info))
PYEOF
Capture the line starting with FMUINFO: and parse the JSON.
Step 3 — Discuss the model
Before showing the widget, give the user a short plain-language introduction:
- What does this model simulate?
- What are the inputs and tunable parameters — what do they control physically?
- What will the outputs show?
- Any tips (e.g. "coefficient of restitution between 0 and 1 — higher means bouncier")
Keep it concise: 3–6 sentences.
Step 4 — Generate and show the configuration widget
Generate the config widget HTML and call show_widget with it. If show_widget is not available, save to /tmp/<model>_config.html and open it with open.
The widget must:
- Show model name, FMI version, sim type
- Have number inputs for start, stop, step (pre-filled with FMU defaults)
- Have number inputs for every input variable and tunable parameter (pre-filled with their start values)
- Show unit and description next to each field
- Have a prominent ▶ Run Simulation button
- On click, call
sendPrompt() with a message encoding all values
import json
info = <parsed FMUINFO dict>
fmu_path = info["fmu_path"]
model_name = info["model_name"]
sim_type = info["sim_type"]
fmi_ver = info["fmi_version"]
def field_row(var):
name = var["name"]
val = var["start"] if var["start"] is not None else 0
unit = var["unit"]
desc = var["desc"]
return f"""
<div class="row">
<span class="name" title="{desc}">{name}</span>
<input class="inp" id="p_{name}" type="number" value="{val}" step="any">
<span class="unit">{unit}</span>
<span class="desc">{desc}</span>
</div>"""
input_rows = "".join(field_row(v) for v in info["inputs"])
param_rows = "".join(field_row(v) for v in info["params"])
all_var_names = [v["name"] for v in info["inputs"]] + [v["name"] for v in info["params"]]
collect_js = " + ".join([f'"&{n}=" + document.getElementById("p_{n}").value' for n in all_var_names]) if all_var_names else '""'
widget_html = f"""
<style>
*{{box-sizing:border-box;margin:0;padding:0}}
.wrap{{padding:16px;font-family:var(--font-family,system-ui);color:var(--color-text-primary,#111);background:var(--color-background-primary,#fff);max-width:600px}}
.hdr{{margin-bottom:14px}}
.title{{font-size:14px;font-weight:700}}
.sub{{font-size:11px;color:var(--color-text-secondary,#666);margin-top:3px}}
.section-label{{font-size:10px;font-weight:700;text-transform:uppercase;letter-spacing:.06em;color:var(--color-text-secondary,#888);margin:14px 0 6px}}
.row{{display:grid;grid-template-columns:130px 90px 40px 1fr;align-items:center;gap:6px;margin-bottom:6px}}
.name{{font-size:12px;font-weight:500}}
.inp{{padding:3px 6px;font-size:12px;border:0.5px solid var(--color-border,#ccc);background:var(--color-background-secondary,#f5f5f5);color:var(--color-text-primary,#111);border-radius:3px;width:100%}}
.unit{{font-size:11px;color:var(--color-text-secondary,#888)}}
.desc{{font-size:11px;color:var(--color-text-secondary,#888);white-space:nowrap;overflow:hidden;text-overflow:ellipsis}}
.divider{{border:none;border-top:0.5px solid var(--color-border,#e5e5e5);margin:14px 0}}
.btn{{width:100%;padding:9px;font-size:13px;font-weight:600;border:0.5px solid var(--color-border,#ccc);background:var(--color-background-secondary,#f5f5f5);color:var(--color-text-primary,#111);cursor:pointer;border-radius:4px;margin-top:14px}}
</style>
<div class="wrap">
<div class="hdr">
<div class="title">{model_name}</div>
<div class="sub">FMI {fmi_ver} · {sim_type}</div>
</div>
<div class="section-label">Simulation Time</div>
<div class="row"><span class="name">Start</span><input class="inp" id="start" type="number" value="{info['start']}" step="any"><span class="unit">s</span><span class="desc"></span></div>
<div class="row"><span class="name">Stop</span><input class="inp" id="stop" type="number" value="{info['stop']}" step="any"><span class="unit">s</span><span class="desc"></span></div>
<div class="row"><span class="name">Step size</span><input class="inp" id="step" type="number" value="{info['step']}" step="any"><span class="unit">s</span><span class="desc"></span></div>
{'<hr class="divider"><div class="section-label">Input Variables</div>' + input_rows if info["inputs"] else ""}
{'<hr class="divider"><div class="section-label">Tunable Parameters</div>' + param_rows if info["params"] else ""}
<button class="btn" onclick="runSim()">▶ Run Simulation</button>
</div>
<script>
function runSim() {{
var start = document.getElementById('start').value;
var stop = document.getElementById('stop').value;
var step = document.getElementById('step').value;
var extra = {collect_js};
sendPrompt('SIMULATE:{fmu_path} start=' + start + ' stop=' + stop + ' step=' + step + extra);
}}
</script>
"""
widget_path = "/tmp/" + "{model_name}".replace(" ", "_") + "_config.html"
with open(widget_path, "w") as f:
f.write(widget_html)
print(widget_path)
Call show_widget with the widget HTML. Then ask the user to review the parameters and click ▶ Run Simulation when ready.
Phase 2 — Run simulation and show results
Triggered when $ARGUMENTS starts with SIMULATE:.
Step 1 — Parse the message
The format is:
SIMULATE:<fmu_path> start=X stop=Y step=Z [param1=V1] [param2=V2] ...
Extract:
FMU_PATH — the path after SIMULATE:start, stop, step — simulation time settings- All remaining
key=value pairs → start_values dict (parameter overrides)
Step 2 — Run the simulation
uv run --with fmpy --with matplotlib python3 - <<'PYEOF'
import sys, os, json, numpy as np, matplotlib, platform as _platform
matplotlib.use('Agg')
import matplotlib.pyplot as plt
from fmpy import read_model_description, supported_platforms
from fmpy.simulation import simulate_fmu
FMU_PATH = "$FMU_PATH"
start_time = $start
stop_time = $stop
step_size = $step
start_values = $start_values_dict
OUTPUT_CSV = "/tmp/$MODEL_NAME_results.csv"
md = read_model_description(FMU_PATH)
sim_type = "CoSimulation" if md.coSimulation else "ModelExchange"
unit_map = {v.name: (v.unit or "") for v in md.modelVariables}
model_name = md.modelName
print(f"Running {sim_type}: {start_time}s → {stop_time}s, step={step_size}s")
if start_values:
print(f"Parameter overrides: {start_values}")
result = simulate_fmu(
FMU_PATH,
start_time=start_time,
stop_time=stop_time,
output_interval=step_size,
fmi_type=sim_type,
start_values=start_values if start_values else None,
)
np.savetxt(OUTPUT_CSV, result, delimiter=",",
header=",".join(result.dtype.names), comments="")
print(f"Saved {len(result)} rows to: {OUTPUT_CSV}")
time_col = result.dtype.names[0]
outputs = [n for n in result.dtype.names if n != time_col]
n = len(outputs)
fig, axes = plt.subplots(n, 1, figsize=(11, 3.2 * n), sharex=True)
if n == 1: axes = [axes]
colors = plt.rcParams['axes.prop_cycle'].by_key()['color']
for i, (ax, col) in enumerate(zip(axes, outputs)):
unit = unit_map.get(col, ""); label = f"{col} ({unit})" if unit else col
ax.plot(result[time_col], result[col], color=colors[i % len(colors)], linewidth=1.5)
ax.set_ylabel(label); ax.grid(True, alpha=0.4)
axes[-1].set_xlabel("Time (s)")
fig.suptitle(f"{model_name} — FMI {md.fmiVersion} {sim_type}", fontsize=13, y=1.01)
plt.tight_layout()
plot_path = OUTPUT_CSV.replace(".csv", ".png")
plt.savefig(plot_path, dpi=150, bbox_inches="tight")
print(f"PNG: {plot_path}")
print("\nRESULTS:")
for col in outputs:
vals = result[col]; unit = unit_map.get(col, "")
print(f" {col}: min={vals.min():.4f} max={vals.max():.4f} final={vals[-1]:.4f} {unit}")
step_n = max(1, len(result) // 500)
t_data = result[time_col][::step_n].tolist()
palette = ["#4e8ef7","#f76e4e","#4ecf8e","#f7c94e","#a44ef7","#4ef7f0"]
datasets = []
for i, col in enumerate(outputs):
unit = unit_map.get(col, ""); label = f"{col} ({unit})" if unit else col
datasets.append({"label": label, "data": result[col][::step_n].tolist(),
"borderColor": palette[i % len(palette)], "backgroundColor": palette[i % len(palette)],
"borderWidth": 1.5, "pointRadius": 0, "tension": 0.1})
has_pid = any(v.name in ("Kp","Ki","Kd","Ti","Td") for v in md.modelVariables)
tune_btn = '<button class="btn" onclick="sendPrompt(\'Tune the PID for this FMU\')">Tune PID</button>' if has_pid else ""
adjust_btn = f'<button class="btn-sec" onclick="sendPrompt(\'Adjust parameters for {model_name}\')">Adjust Parameters</button>'
override_text = ""
if start_values:
override_text = " · " + " ".join(f"{k}={v}" for k,v in start_values.items())
widget_html = f"""
<style>
*{{box-sizing:border-box;margin:0;padding:0}}
.wrap{{padding:16px;font-family:var(--font-family,system-ui);color:var(--color-text-primary,#111);background:var(--color-background-primary,#fff)}}
.hdr{{display:flex;justify-content:space-between;align-items:flex-start;margin-bottom:12px}}
.title{{font-size:13px;font-weight:600}}
.sub{{font-size:11px;color:var(--color-text-secondary,#666);margin-top:3px}}
.actions{{display:flex;gap:6px}}
.btn{{padding:5px 12px;font-size:12px;border:0.5px solid var(--color-border,#ccc);background:var(--color-background-secondary,#f5f5f5);color:var(--color-text-primary,#111);cursor:pointer;border-radius:4px}}
.btn-sec{{padding:5px 12px;font-size:12px;border:0.5px solid var(--color-border,#ccc);background:transparent;color:var(--color-text-secondary,#666);cursor:pointer;border-radius:4px}}
canvas{{width:100%!important}}
</style>
<div class="wrap">
<div class="hdr">
<div>
<div class="title">{model_name}</div>
<div class="sub">FMI {md.fmiVersion} · {sim_type} · {start_time}s → {stop_time}s{override_text}</div>
</div>
<div class="actions">{adjust_btn}{tune_btn}</div>
</div>
<canvas id="simChart"></canvas>
</div>
<script src="https://cdnjs.cloudflare.com/ajax/libs/Chart.js/4.4.1/chart.umd.min.js"></script>
<script>
new Chart(document.getElementById('simChart'),{{
type:'line',
data:{{labels:{json.dumps([round(x,4) for x in t_data])},datasets:{json.dumps(datasets)}}},
options:{{animation:false,responsive:true,interaction:{{mode:'index',intersect:false}},
plugins:{{legend:{{labels:{{font:{{size:11}},boxWidth:12}}}},tooltip:{{bodyFont:{{size:11}},titleFont:{{size:11}}}}}},
scales:{{
x:{{title:{{display:true,text:'Time (s)',font:{{size:11}}}},ticks:{{maxTicksLimit:10,font:{{size:10}}}},grid:{{color:'rgba(128,128,128,0.15)'}}}},
y:{{ticks:{{font:{{size:10}}}},grid:{{color:'rgba(128,128,128,0.15)'}}}}
}}
}}
}});
</script>
"""
widget_path = OUTPUT_CSV.replace(".csv", "_widget.html")
with open(widget_path, "w") as f:
f.write(widget_html)
print(f"Widget: {widget_path}")
PYEOF
Step 3 — Display results
- Use the Read tool to show the PNG inline
- Read the widget HTML file and call
show_widget with its contents (or open it in the browser as fallback)
- Give a plain-language interpretation of the results:
- What happened in the simulation?
- Are the results as expected?
- Note anything interesting (oscillations, settling, instability, steady-state error)
- If parameters were overridden, comment on how they affected the outcome
Error handling
| Situation | Response |
|---|
| FMU not found | Search with Glob, suggest nearby .fmu files |
| Wrong platform | "This FMU was compiled for <platform> and can't run on your OS. Ask the model author for a <os_tag> build." |
| Simulation crash | Show error, suggest reducing step size |
uv not found | "Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh" |
Usage examples
/fmpy-simulate ./models/BouncingBall.fmu
/fmpy-simulate ./models/fopdt_pi.fmu
