thrustlab 0.6.0__tar.gz → 0.7.0__tar.gz

{thrustlab-0.6.0 → thrustlab-0.7.0}/CHANGELOG.md

@@ -6,7 +6,92 @@ ThrustLab API version (which is permanently `/v1/`).
 
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
-## [Unreleased]
+## [0.7.0] - 2026-10-02
+
+### Added
+
+- `thrustlab.estimate`: the ThrustLab propeller equation, offline. Thrust, torque,
+  shaft power and the coefficients from a propeller's printed size, blade count,
+  rpm and airspeed, with an ISA atmosphere and a zero-thrust airspeed search. No API
+  key, no network, no dependencies. `thrustlab-estimate --diameter 10 --pitch 5
+  --rpm 8000` on the command line (`--airspeed 0:30:5` for a table, `--json`).
+  This is the closed form of the Fast propeller model in the simulator; the
+  simulator adds the motor, ESC, battery and thermal coupling.
+- The **Fast propeller model**. `propeller_model="fast"` on a single-point,
+  sweep or batch submission runs from a propeller's printed label rather than
+  its measured blade geometry: `PropellerLabel` carries `diameter_m`,
+  `pitch_m`, `num_blades`, a planform `family` (and `chord_ratio` for
+  `custom`) and `camber_pct`. Send it on a rotor whose propeller you typed;
+  send `propeller_component_id` alone for a catalog pick and the server derives
+  the label from that row. `propeller_model="full"` (the measured blade) is
+  still the default, so an existing call is byte-for-byte unchanged.
+- **Anonymous runs.** `POST /v1/public/simulate` needs no credentials at all —
+  it answers synchronously on the Fast model with a `run_…` token, a `/s/<token>`
+  link and the result — and `POST /v1/runs/{token}/claim` imports one into your
+  account's default project. Generated models for both, plus the public read
+  `GET /v1/public/runs/{token}`.
+- **The open catalog**, unauthenticated: `GET /v1/public/motors`,
+  `/v1/public/batteries` and the per-component `…/{id}` reads. Each list is
+  paged with a `starting_after` cursor and states the data licence in a
+  `license` field. There is no bulk export.
+- The five public routes now declare real response models, so
+  `PublicComponentList`, `PublicComponentResource`, `PublicSimulateResponse`,
+  `PublicRunView` and `PublicRunClaim` are generated types rather than untyped
+  objects. `PublicRunView` is deliberately open: its body is the same
+  projection the share route returns and it grows with the result shape.
+- `default_project_id`, `full_model_daily` and `full_model_used_today` on
+  `client.users.me()`.
+
+### Changed
+
+- **Every datasheet value is now public on every tier.** Motor `n`,
+  `iq_nominal`, `R`, `L` and `inertia` and battery `pack_resistance_mOhm` and
+  `internal_resistance_mOhm` come back from the component list, the detail read
+  and `/specs` alike. `/specs` no longer requires a paid plan, a Turnstile
+  challenge or a per-account budget, and filter bounds are arbitrary rather than
+  snapped to preset edges. A propeller's station arrays are still never served.
+- **`project_id` is optional** on the single-point, sweep and dynamic create
+  bodies. Omit it and the run lands in your account's default project ("My
+  simulations"), which is created on first use. `PATCH` accepts `project_id` on
+  all three resources, so a run can be moved after the fact.
+- The free tier's limit is no longer a daily simulation cap. Fast-model runs are
+  unlimited; `full_model_daily` counts Full-model JOBS per rolling 24 h, one per
+  run whether it is a single point or a bounded sweep.
+
+### Breaking (import names only)
+
+The wire contract is unchanged — every request and response body is the same
+shape 0.6.0 sent and received. What moved is the NAME of some generated model
+classes, because the OpenAPI schemas they are derived from changed. Only code
+that imports these by name from `thrustlab` breaks, and only at import time.
+
+- `SweepCreateBodyCoolingSource` → `SweepCreateBodyCoolingSourceType0`.
+  `cooling_source` on a sweep is nullable now (null means "resolve from the
+  deprecated `flight_regime`", matching the single-point body), and the
+  generator names the enum arm of a nullable union `…Type0`. The accepted
+  values are identical.
+- `PublicSimulateBodyInputSnapshotType0` is **gone**. `input_snapshot` is a
+  first-party field and is no longer published in the contract, so no model is
+  generated for it. The endpoint still accepts it.
+- Four inline response models are **gone**, replaced by the named models listed
+  under Added above:
+  `CreatePublicSimulationV1PublicSimulatePostResponseCreatePublicSimulationV1PublicSimulatePost`
+  → `PublicSimulateResponse`;
+  `ReadPublicRunV1PublicRunsTokenGetResponseReadPublicRunV1PublicRunsTokenGet`
+  → `PublicRunView`;
+  `ClaimPublicRunV1RunsTokenClaimPostResponseClaimPublicRunV1RunsTokenClaimPost`
+  → `PublicRunClaim`;
+  `ListPublicMotorsV1PublicMotorsGetResponseListPublicMotorsV1PublicMotorsGet`
+  and its batteries twin → `PublicComponentList`.
+  These existed for one unreleased day and named nothing a caller would have
+  typed on purpose, but they were importable, so they are listed.
+
+### Deprecated
+
+- `entitlements.db_access` and `entitlements.component_specs` on
+  `client.users.me()` are frozen at `"full"` and `True`, and `daily_cap` at
+  `null`. They are kept for one major so a pinned 0.6.x client keeps validating;
+  read `full_model_daily` instead of `daily_cap`.
 
 ## [0.6.0] - 2026-09-09
 

{thrustlab-0.6.0 → thrustlab-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thrustlab
-Version: 0.6.0
+Version: 0.7.0
 Summary: Official Python SDK for the ThrustLab API
 Project-URL: Homepage, https://thrustlab.com
 Project-URL: Documentation, https://thrustlab.com/docs
@@ -120,6 +120,26 @@ See [`examples/fmu/`](./examples/fmu/) for bundled ready-to-fly FMUs with
 quadcopter, Y6 coax, and tilt-tricopter missions, an endurance study, and
 replay rendering.
 
+## Offline propeller estimate
+
+`thrustlab.estimate` is the ThrustLab propeller equation: thrust, torque and
+power from the printed size, with no account and no network.
+
+```python
+from thrustlab.estimate import from_label
+
+point = from_label(diameter_in=10, pitch_in=5, rpm=8000, airspeed_mps=12.0)
+print(point.T, point.Q, point.P_shaft)   # N, N m, W
+```
+
+```shell
+thrustlab-estimate --diameter 10 --pitch 5 --rpm 8000 --airspeed 0:30:5
+```
+
+It is the closed form of the simulator's Fast propeller model. The simulator adds
+the motor, ESC, battery and thermal coupling; the Full model adds the measured
+blade geometry.
+
 ## Why the SDK (and not `urllib` / `wget`)?
 
 The SDK gives you automatic retries with backoff, idempotency keys, cursor

{thrustlab-0.6.0 → thrustlab-0.7.0}/README.md

@@ -84,6 +84,26 @@ See [`examples/fmu/`](./examples/fmu/) for bundled ready-to-fly FMUs with
 quadcopter, Y6 coax, and tilt-tricopter missions, an endurance study, and
 replay rendering.
 
+## Offline propeller estimate
+
+`thrustlab.estimate` is the ThrustLab propeller equation: thrust, torque and
+power from the printed size, with no account and no network.
+
+```python
+from thrustlab.estimate import from_label
+
+point = from_label(diameter_in=10, pitch_in=5, rpm=8000, airspeed_mps=12.0)
+print(point.T, point.Q, point.P_shaft)   # N, N m, W
+```
+
+```shell
+thrustlab-estimate --diameter 10 --pitch 5 --rpm 8000 --airspeed 0:30:5
+```
+
+It is the closed form of the simulator's Fast propeller model. The simulator adds
+the motor, ESC, battery and thermal coupling; the Full model adds the measured
+blade geometry.
+
 ## Why the SDK (and not `urllib` / `wget`)?
 
 The SDK gives you automatic retries with backoff, idempotency keys, cursor

{thrustlab-0.6.0 → thrustlab-0.7.0}/pyproject.toml

@@ -49,6 +49,7 @@ sitl = []
 
 [project.scripts]
 thrustlab-sitl = "thrustlab.sitl.cli:main"
+thrustlab-estimate = "thrustlab.estimate.cli:main"
 
 [project.urls]
 Homepage = "https://thrustlab.com"
@@ -61,11 +62,17 @@ path = "thrustlab/_version.py"
 
 [tool.hatch.build.targets.wheel]
 packages = ["thrustlab"]
+# The committed worked-example fixture is data, not code. `artifacts` names it
+# explicitly so neither a VCS-ignore rule nor a future `exclude` can drop it from the
+# wheel: `thrustlab.estimate` reads it at runtime and the Rust Fast-model port is gated
+# against it.
+artifacts = ["thrustlab/estimate/_fixture/*.json"]
 
 [tool.hatch.build.targets.sdist]
 # The bundled example FMUs live in the repo for out-of-the-box examples; the
 # sdist stays source-only (each is 4-10 MB of binary).
 exclude = ["*.fmu"]
+artifacts = ["thrustlab/estimate/_fixture/*.json"]
 include = [
   "/thrustlab",
   "/tests",

thrustlab-0.7.0/tests/estimate/test_equation.py

@@ -0,0 +1,234 @@
+"""Regression and invariant tests for ``thrustlab.estimate`` (the label-only propeller
+thrust and torque equation). Pure Python plus numpy for the quadrature oracle."""
+from __future__ import annotations
+
+import json
+import math
+
+import numpy as np
+import pytest
+
+from thrustlab import estimate as te
+from thrustlab.estimate import cli
+
+IN = 0.0254
+PI = math.pi
+APC_10x5 = dict(D=10 * IN, P=5 * IN, B=2, c=0.064 * 10 * IN, n=8000 / 60)
+
+
+# ----------------------------------------------------------------------------- pinned values
+
+
+def test_worked_examples_pinned():
+    """The four worked examples in the design spec, thrust in N and shaft power in W."""
+    cases = [
+        (dict(diameter_in=10, pitch_in=5, rpm=8000, chord_ratio=0.064), 8.10, 95.5),
+        (dict(diameter_in=10, pitch_in=5, rpm=8000, chord_ratio=0.064, airspeed_mps=15.0), 2.69, 59.4),
+        (dict(diameter_in=5, pitch_in=4.5, rpm=20000, blades=3, chord_ratio=0.11), 8.92, 245.4),
+        (dict(diameter_in=20, pitch_in=10, rpm=4000, chord_ratio=0.064), 32.87, 373.4),
+    ]
+    for kw, T, P in cases:
+        r = te.from_label(**kw, camber_pct=3.5 / 1.1)
+        assert r.converged
+        assert r.T == pytest.approx(T, rel=2e-3)
+        assert r.P_shaft == pytest.approx(P, rel=2e-3)
+    labels = [label for label, _, _ in te.worked_examples()]
+    assert labels[0].startswith("APC 10x5E static")
+
+
+# ----------------------------------------------------------------------------- the equation itself
+
+
+def _oracle(r, D, P, B, c, kw):
+    """Integrate the section law numerically at the returned state; return (ct_r, profile cq_r)."""
+    sec = kw.get("section", te.DEFAULT_SECTION)
+    xh = min(max(kw.get("x_hub", 0.15), 0.0), 0.5)
+    sigma, theta = B * c / (PI * D / 2), P / (PI * D)
+    a_eff = sec.a / math.sqrt(1 - min(r.mach, te.MACH_CORR_CAP) ** 2)
+    g = theta - r.lam
+    clmax, cd0 = r.CLmax, sec.cd0(r.Re)
+    alpha_stall = sec.alpha0 + clmax / a_eff
+    x = np.linspace(max(xh, 1e-6), 1.0, 400_001)
+    cl = np.minimum(a_eff * (g / x - sec.alpha0), clmax)
+    cd = cd0 + sec.k * (cl - sec.cl_d) ** 2 + sec.cd_stall * np.maximum(g / x - alpha_stall, 0.0)
+    lift = np.where(x <= r.Bt, cl * x ** 2, 0.0)
+    ct_r = 0.5 * sigma * np.trapezoid(lift, x)
+    prof = 0.5 * sigma * np.trapezoid(cd * x ** 3, x)
+    return ct_r, prof
+
+
+@pytest.mark.parametrize("case", [
+    dict(APC_10x5),                                             # ordinary static, partial stall
+    dict(APC_10x5, V=15.0),                                     # cruise, nearly attached
+    dict(APC_10x5, V=19.0),                                     # close to zero thrust
+    dict(D=10 * IN, P=10 * IN, B=1, c=0.064 * 10 * IN, n=8000 / 60),  # single blade, fully stalled past B_t
+    dict(D=5 * IN, P=4.5 * IN, B=4, c=0.11 * 5 * IN, n=20000 / 60),   # high solidity
+    dict(APC_10x5, x_hub=0.0),                                  # no hub cut-out
+    dict(APC_10x5, section=te.Section.from_camber(5.0)),        # more camber
+])
+def test_closed_form_matches_quadrature_and_momentum(case):
+    r = te.propeller_performance(**case)
+    assert r.converged and abs(r.residual) < 1e-9
+    f = (1 - r.a_prime) ** 2
+    ct_r = r.CT / f / (PI ** 3 / 4)
+    cq_r = r.CP / f / (PI ** 4 / 4)
+    lam_c = r.lam - r.lam_i
+    assert 2 * r.lam_i * (lam_c + r.lam_i) == pytest.approx(ct_r, rel=1e-7)
+    ct_oracle, prof_oracle = _oracle(r, case["D"], case["P"], case["B"], case["c"], case)
+    assert ct_r == pytest.approx(ct_oracle, rel=1e-5)
+    prof_code = cq_r - lam_c * ct_r - 1.10 * r.lam_i * ct_r
+    assert prof_code == pytest.approx(prof_oracle, rel=1e-5)
+
+
+def test_thrust_falls_with_airspeed_and_crosses_zero_above_pitch_speed():
+    pts = te.airspeed_sweep(**APC_10x5, speeds=[0, 5, 10, 15, 20])
+    thrusts = [p.T for p in pts]
+    assert thrusts == sorted(thrusts, reverse=True)
+    V0 = te.zero_thrust_speed(**APC_10x5)
+    pitch_speed = APC_10x5["n"] * APC_10x5["P"]
+    assert 1.05 * pitch_speed < V0 < 1.35 * pitch_speed
+    assert abs(te.propeller_performance(**APC_10x5, V=V0).T) < 1e-3
+
+
+def test_zero_thrust_speed_low_pitch_is_bracketed():
+    """Camber adds an aerodynamic pitch offset, so a near-zero label pitch still has a
+    zero-thrust speed well above 2 n P; the search must expand until it brackets it."""
+    kw = dict(D=10 * IN, P=0.01, B=2, c=0.064 * 10 * IN, n=8000 / 60)
+    V0 = te.zero_thrust_speed(**kw)
+    assert V0 > 2 * kw["n"] * kw["P"] + 1
+    assert abs(te.propeller_performance(**kw, V=V0).T) < 1e-3
+
+
+def test_brake_regime_is_flagged_not_faked():
+    r = te.propeller_performance(**APC_10x5, V=30.0)
+    assert r.T < 0 and r.regime == "brake"
+
+
+def test_more_blades_more_thrust_sublinear():
+    t2 = te.propeller_performance(**APC_10x5).T
+    t3 = te.propeller_performance(**{**APC_10x5, "B": 3}).T
+    t4 = te.propeller_performance(**{**APC_10x5, "B": 4}).T
+    assert 1.2 < t3 / t2 < 1.6
+    assert 1.4 < t4 / t2 < 2.0
+    assert t4 / t3 < t3 / t2
+
+
+def test_density_scaling_exact_and_torque_identities():
+    r1 = te.propeller_performance(**APC_10x5)
+    r2 = te.propeller_performance(**APC_10x5, rho=0.9 * 1.225)
+    assert r2.T == pytest.approx(0.9 * r1.T, rel=1e-9)
+    assert r2.CT == pytest.approx(r1.CT, rel=1e-9)
+    assert r1.Q == pytest.approx(r1.P_shaft / (2 * PI * APC_10x5["n"]), rel=1e-12)
+    assert r1.CQ == pytest.approx(r1.CP / (2 * PI), rel=1e-12)
+
+
+def test_similarity_scaling_with_matched_reynolds_and_mach():
+    """Double D, P, c, halve n, double nu: same Re and Mach, so CT and CP are unchanged,
+    thrust scales by 4 and torque by 8."""
+    r1 = te.propeller_performance(**APC_10x5)
+    r2 = te.propeller_performance(D=2 * APC_10x5["D"], P=2 * APC_10x5["P"], B=2, c=2 * APC_10x5["c"],
+                                  n=APC_10x5["n"] / 2, nu=2 * 1.46e-5)
+    assert r2.Re == pytest.approx(r1.Re, rel=1e-9) and r2.mach == pytest.approx(r1.mach, rel=1e-9)
+    assert r2.CT == pytest.approx(r1.CT, rel=1e-8) and r2.CP == pytest.approx(r1.CP, rel=1e-8)
+    assert r2.T == pytest.approx(4 * r1.T, rel=1e-8) and r2.Q == pytest.approx(8 * r1.Q, rel=1e-8)
+
+
+def test_swirl_converges_and_state_is_consistent_at_high_solidity():
+    """Six wide blades (solidity 0.5) at high pitch and airspeed: the swirl fixed point
+    must converge and the returned inflow must be consistent with the returned swirl."""
+    r = te.propeller_performance(D=10 * IN, P=20 * IN, B=6, c=1.3 * IN, n=8000 / 60, V=60.0)
+    assert r.converged and r.swirl_passes < 30
+    lam_c_from_swirl = 60.0 / (2 * PI * (8000 / 60) * (1 - r.a_prime) * 5 * IN)
+    assert r.lam - r.lam_i == pytest.approx(lam_c_from_swirl, rel=1e-5)
+
+
+def test_absurd_solidity_is_rejected_not_solved():
+    with pytest.raises(ValueError):
+        te.propeller_performance(D=0.254, P=2.0, B=100, c=1.0, n=8000 / 60)
+    with pytest.raises(ValueError):
+        te.propeller_performance(D=0.254, P=0.508, B=8, c=0.127, n=8000 / 60, V=67.7)
+
+
+def test_camber_raises_thrust_and_moves_zero_thrust_speed():
+    lo = te.propeller_performance(**APC_10x5, section=te.Section.from_camber(2.0))
+    hi = te.propeller_performance(**APC_10x5, section=te.Section.from_camber(5.0))
+    assert hi.T > lo.T
+    assert te.zero_thrust_speed(**APC_10x5, section=te.Section.from_camber(5.0)) > te.zero_thrust_speed(
+        **APC_10x5, section=te.Section.from_camber(2.0))
+
+
+def test_section_law_and_guards():
+    s = te.Section()
+    assert s.clmax(1e5) == pytest.approx(1.30)
+    assert s.clmax(5e4) == pytest.approx(1.30 * 0.5 ** 0.15)
+    assert s.clmax(1e7) == 1.45 and s.clmax(100) == 0.6
+    assert s.cd0(1e5) == pytest.approx(0.019)
+    with pytest.raises(ValueError):  # CL_max below the zero-angle lift is not a section
+        te.propeller_performance(**APC_10x5, section=te.Section(clmax_ref=0.3, clmax_cap=0.3, clmax_re_exp=0.0))
+
+
+def test_mach_is_reported_unclipped():
+    r = te.from_label(10, 5, 40000)
+    assert r.mach > 1.0
+
+
+# ----------------------------------------------------------------------------- helpers and API
+
+
+def test_air_density_isa_layers():
+    rho0, nu0 = te.air_density(0.0)
+    rho3, nu3 = te.air_density(3000.0)
+    assert rho0 == pytest.approx(1.225, rel=2e-3)
+    assert nu0 == pytest.approx(1.46e-5, rel=3e-2)
+    assert rho3 / rho0 == pytest.approx(0.742, rel=5e-3) and nu3 > nu0
+    lo, hi = te.air_density(10999.0)[0], te.air_density(11001.0)[0]
+    assert lo == pytest.approx(hi, rel=2e-3)
+    assert te.air_density(15000.0)[0] == pytest.approx(0.1937, rel=2e-3)
+    assert te.air_density(0.0, temperature_c=35.0)[0] < rho0
+    for bad in ((25000.0, None), (0.0, -300.0)):
+        with pytest.raises(ValueError):
+            te.air_density(*bad)
+
+
+def test_from_label_matches_si_api_and_forwards_section_and_atmosphere():
+    sec = te.Section.from_camber(4.0)
+    a = te.from_label(10, 5, 8000, chord_in=0.64, section=sec, rho=1.1, nu=1.5e-5, airspeed_mps=3.0)
+    b = te.propeller_performance(10 * IN, 5 * IN, 2, 0.64 * IN, 8000 / 60, 3.0, rho=1.1, nu=1.5e-5, section=sec)
+    assert a == b
+    with pytest.raises(ValueError):
+        te.from_label(10, 5, 8000, chord_in=0.0)
+
+
+def test_bad_inputs_raise():
+    bad = [
+        dict(D=0.0), dict(P=-1.0), dict(c=float("nan")), dict(n=float("inf")), dict(B=0), dict(B=2.5),
+        dict(V=-1.0), dict(V=float("nan")), dict(rho=0.0), dict(rho=-1.0), dict(nu=0.0), dict(nu=-1e-5),
+    ]
+    for kw in bad:
+        with pytest.raises(ValueError):
+            te.propeller_performance(**{**APC_10x5, **kw})
+
+
+# ----------------------------------------------------------------------------- command line
+
+
+def test_cli_table_and_json(capsys):
+    assert cli.main(["--diameter", "10", "--pitch", "5", "--rpm", "8000", "--chord-ratio", "0.064",
+                     "--camber", str(3.5 / 1.1)]) == 0
+    out = capsys.readouterr().out
+    assert "8.10" in out and "zero thrust at" in out
+
+    assert cli.main(["--diameter", "10", "--pitch", "5", "--rpm", "8000", "--airspeed", "0:10:5", "--json"]) == 0
+    payload = json.loads(capsys.readouterr().out)
+    assert [p["airspeed_mps"] for p in payload["points"]] == [0.0, 5.0, 10.0]
+    assert payload["points"][0]["T"] > payload["points"][2]["T"]
+    assert payload["zero_thrust_airspeed_mps"] > 10.0
+
+
+def test_cli_examples_and_errors(capsys):
+    assert cli.main(["--examples", "--json"]) == 0
+    rows = json.loads(capsys.readouterr().out)
+    assert len(rows) == 4 and rows[0]["T"] == pytest.approx(8.10, rel=2e-3)
+    assert cli.main(["--diameter", "10", "--pitch", "5", "--rpm", "8000", "--chord-in", "0"]) == 2
+    with pytest.raises(SystemExit):
+        cli.main(["--diameter", "10"])