Dynamic simulations

"""Dynamic (time-domain) simulation: auth -> submit -> wait() -> read the result.

Run it:
    export THRUSTLAB_API_KEY=key_...        # never hard-code the key
    python examples/dynamic/run_and_poll.py

A dynamic run integrates the powertrain through a throttle/airspeed *schedule*
until a *termination* condition (here: a 2 s spin-up ramp, then a 20 s hover
at 70% — a fixed-duration mission). It returns per-step `samples` (each a full
steady-shaped result),
time `series`, a `scorecard`, and `events`. Swap in your own component IDs, or
resolve them by name with client.components.find(...).
"""

from thrustlab import Client

client = Client()  # reads $THRUSTLAB_API_KEY from the environment

project = client.projects.create(name="sdk dynamic example")

# Resolve by name, or paste explicit IDs: motor_id = "comp_motor_xxx"
motor = client.components.find(name="BadAss 2826-820Kv")
prop = client.components.find(name="10.5x4.5")
battery = client.components.find(
    name="Liperior 5000mAh 4S 35C 14.8V Lipo Battery With XT90 Plug"
)

dyn = client.dynamic_simulations.create(
    project_id=project["id"],
    battery_component_id=battery["id"],
    density_kg_m3=1.225,
    battery_charge_pct=100,
    ambient_temp_c=25,
    rotor_groups=[
        {
            "label": "main",
            "count": 4,
            "motor_component_id": motor["id"],
            "propeller_component_id": prop["id"],
        }
    ],
    # Ramp to 70% over 2 s, then hold for 20 s. The soft-start matters:
    # stepping 70% onto a stationary rotor draws an in-rush that can sag the
    # pack below the low-voltage cutoff and end the run immediately — exactly
    # as it would on real hardware. Endurance ("until depleted") missions work
    # the same way but integrate minutes of pack time; keep examples short.
    schedule={
        "mode": "segments",
        "segments": [
            {
                "duration_s": 2.0,
                "airspeed_target": 0.0,
                "per_group": {"main": {"throttle_target": 70, "throttle_ramp": "linear"}},
            },
            {
                "duration_s": 20.0,
                "airspeed_target": 0.0,
                "per_group": {"main": {"throttle_target": 70}},
            },
        ],
    },
    # Fixed-duration mission: run the schedule to its end.
    termination={"mode": "fixed"},
)
print(f"created {dyn['id']}, status={dyn['status']}")

result = client.dynamic_simulations.wait(dyn["id"], timeout=600)
print(f"final status: {result['status']}")

if result["status"] == "completed":
    blob = result["result"]

    # scorecard: whole-run headline metrics (canonical snake_case).
    sc = blob["scorecard"]
    print(f"peak winding temp: {sc['peak_winding_temp_c']:.1f} C")
    print(f"avg efficiency:    {sc['avg_efficiency']:.3f}")
    print(f"peak current:      {sc['peak_current_a']:.1f} A")
    print(f"min cell voltage:  {sc['min_cell_voltage_v']:.2f} V")

    # samples[]: each entry is a full steady-shaped snapshot at one time step —
    # read the same canonical per-rotor / aggregate keys as a single-point run.
    samples = blob["samples"]
    first, last = samples[0], samples[-1]
    print(f"steps: {len(samples)}")
    print(f"  t0 total thrust: {first['All']['total_thrust_n']:.2f} N")
    print(f"  tN total thrust: {last['All']['total_thrust_n']:.2f} N")

"""Dynamic progress + cancel: submit -> watch `progress` -> cancel -> read the partial.

Run it:
    export THRUSTLAB_API_KEY=key_...        # never hard-code the key
    python examples/dynamic/watch_and_cancel.py

Submits a mission that flies until the pack is empty, watches `progress` while
it runs, cancels it part-way through, and reads the partial result.

`progress` is {fraction, sim_time_s, sim_time_total_s, wall_s, updated_at}, and
is None until the worker picks the run up.

Cancelling a RUNNING dynamic mission does not stop it instantly. The response
keeps status "running" and sets `cancel_requested_at`; the worker stops at its
next integration window, at most 20 seconds of mission time. What comes back is
a real partial result: `run_meta.partial` is true, `run_meta.canceled_at_t_s`
gives the mission time it stopped at, and the credits are refunded.

This mission runs to depletion, so `fraction` is an estimate rather than an
exact ratio.
"""

import time

from thrustlab import Client

client = Client()  # reads $THRUSTLAB_API_KEY from the environment

project = client.projects.create(name="sdk dynamic progress example")

motor = client.components.find(name="BadAss 2826-820Kv")
prop = client.components.find(name="10.5x4.5")
battery = client.components.find(
    name="Liperior 5000mAh 4S 35C 14.8V Lipo Battery With XT90 Plug"
)

# A hover flown until the pack is empty.
#
# The schedule steps to 15% before it ramps, rather than ramping up from rest.
# One external study observed ramps starting at near-zero duty producing a
# handful of non-converged rows in their first milliseconds; as a fraction of a
# short flight's rows that was enough to get a run rejected with
# `solver_no_convergence`. Stepping to a working throttle first avoided it.
dyn = client.dynamic_simulations.create(
    project_id=project["id"],
    battery_component_id=battery["id"],
    density_kg_m3=1.225,
    battery_charge_pct=100,
    ambient_temp_c=25,
    rotor_groups=[
        {
            "label": "main",
            "count": 4,
            "motor_component_id": motor["id"],
            "propeller_component_id": prop["id"],
        }
    ],
    schedule={
        "mode": "segments",
        "segments": [
            # Step to the ESC's working range first.
            {
                "duration_s": 0.2,
                "airspeed_target": 0.0,
                "per_group": {"main": {"throttle_target": 15, "throttle_ramp": "step"}},
            },
            # Then ramp from there to the hover setting.
            {
                "duration_s": 2.0,
                "airspeed_target": 0.0,
                "per_group": {"main": {"throttle_target": 65, "throttle_ramp": "linear"}},
            },
            # Hold until the pack is empty. `until_depleted` takes no duration.
            {
                "until_depleted": True,
                "airspeed_target": 0.0,
                "per_group": {"main": {"throttle_target": 65}},
            },
        ],
    },
    # The total mission time is not known in advance, so progress["fraction"]
    # is an estimate rather than an exact ratio.
    termination={"mode": "until_depleted", "soc_cutoff_pct": 20.0},
)
print(f"created {dyn['id']}, status={dyn['status']}")

# Watch progress. 2-5 s is the right cadence; anything faster spends requests
# on a value the worker only rewrites once per integration window.
CANCEL_AFTER_S = 45.0
deadline = time.monotonic() + CANCEL_AFTER_S

while time.monotonic() < deadline:
    time.sleep(3.0)
    run = client.dynamic_simulations.retrieve(dyn["id"])
    if run["status"] not in ("queued", "running"):
        break
    # `progress` is None until the worker picks the run up.
    p = run.get("progress")
    if p is None:
        print(f"  {run['status']}, no progress yet")
        continue
    frac = p.get("fraction")
    pct = f"{frac * 100:5.1f}%" if frac is not None else "   ? %"
    print(f"  {pct}  sim {p['sim_time_s']:.1f} s  wall {p['wall_s']:.1f} s")

run = client.dynamic_simulations.retrieve(dyn["id"])
if run["status"] in ("queued", "running"):
    # Cancel whatever state the deadline caught it in. A queued run comes back
    # `canceled` immediately, with the compute units refunded and no result. A
    # running one comes back still `running` with cancel_requested_at set, and
    # the worker stops at its next integration window.
    #
    # Cancelling both matters here: with every execution slot busy this run can
    # still be queued at the deadline, and skipping it would leave it to
    # execute later against a script that has already exited.
    accepted = client.dynamic_simulations.cancel(dyn["id"])
    print(f"\ncancel accepted: status={accepted['status']}, "
          f"cancel_requested_at={accepted.get('cancel_requested_at')}")
    run = client.dynamic_simulations.wait(dyn["id"], timeout=300)

print(f"final status: {run['status']}")

blob = run.get("result")
if blob:
    meta = blob["run_meta"]
    if meta.get("partial"):
        print(f"partial result, stopped at t = {meta['canceled_at_t_s']:.1f} s of mission time")
    sc = blob["scorecard"]
    print(f"flight time:      {sc['flight_time_s']:.1f} s")
    print(f"energy:           {sc['energy_wh']:.1f} Wh")
    print(f"peak winding:     {sc['peak_winding_temp_c']:.1f} C")
    print(f"samples returned: {len(blob['samples'])}")