rftools-Python-Bibliothek

Installation

pip install rftools-io. Python 3.12 oder neuer; sie bringt httpx, pydantic und click mit. Auf PyPI ansehen.

API-Schlüssel

rftools login (oder rftools.Client().login()) gibt eine Seite und einen Code aus: Öffnen Sie die Seite, melden Sie sich an, geben Sie den Code frei, und der Schlüssel wird in der Zugangsdaten-Datei Ihres Benutzers gespeichert, die nur Sie lesen können. Oder setzen Sie RFTOOLS_API_KEY, das Vorrang hat. rftools.Client() und die Hilfsfunktionen auf Modulebene lesen beides; ein ausdrückliches api_key= hat Vorrang vor beidem. Schlüssel beginnen mit rfc_; siehe Authentifizierung.

Schnellstart

rftools.calculate() gibt ein CalculatorResult zurück: Lesen Sie die Ausgaben nach Namen oder .values, .warnings und .provenance.

Typisierte Kategorie-Stubs

Ein Modul pro Rechnerkategorie, eine Funktion pro Rechner, mit Parameternamen und Standardwerten wie auf den Webseiten. Aus einem Slug wird ein Funktionsname mit - als _, und ein Name, der mit einer Ziffer beginnen würde, erhält das Präfix calc_.

Nach einem Zielwert auflösen

client.solve() findet den Wert einer Eingabe, der eine Ausgabe auf einen Zielwert bringt, und gibt ihn mit dem Vorwärtsergebnis genau bei diesem Wert zurück, berechnet von POST /api/py/v1/calculate/solve. Ein gezählter Aufruf. Verfügbar ab rftools-io 0.4.0.

import rftools

client = rftools.Client()

# The trace width that reaches 50 Ω on 1.51 mm FR-4, rounded to a 0.001 mm grid
result = client.solve(
    "microstrip-impedance",
    {"substrateHeight": 1.51, "dielectricConstant": 4.5, "copperThickness": 35},
    "traceWidth", "impedance", 50,
    grid=0.001,
)
print(result.value, result.reached, result.evaluations)
print(result.result.values["impedance"])

Client.solve(slug, inputs, solve_for, target_output, target_value, grid=None, range=None) gibt ein SolveResult mit .value, .unrounded, .reached, .evaluations, .warnings und .result zurück, dasselbe CalculatorResult, das client.calculate() für die Eingaben mit solve_for auf .value gesetzt zurückgibt. Ein Zielwert, den die Suche nicht erreichen kann, liefert trotzdem ein Ergebnis, mit .reached False und dem nächstgelegenen gefundenen Wert, und kostet trotzdem einen Aufruf. Siehe Nach einem Zielwert auflösen für die Felder, den Suchbereich und die Ablehnungen.

Batch

Bis zu 50 Berechnungen in einer Anfrage, für Sweeps; ein Aufruf pro berechnetem Eintrag. Der Batch-Endpunkt gehört zum Tarif API; siehe Preise (API $19 pro Monat, 10.000 Aufrufe).

results = client.batch([
    ("vswr-return-loss", {"vswr": 1.5}),
    ("vswr-return-loss", {"vswr": 2.0}),
    ("free-space-path-loss", {"frequency": 2400, "distance": 0.05}),
])
for r in results:
    print(r.values if r.ok else r.error)

Nutzung

Das monatliche Kontingent gehört dem Konto; jeder Schlüssel des Kontos zehrt davon.

usage = client.usage()             # GET /v1/usage, never metered
print(usage.used, "of", usage.allowance, "used; resets", usage.reset_at)
for key in usage.keys:
    print(key.key_id, key.label, key.used)

result = client.calculate("vswr-return-loss", {"vswr": 2.5})
print(result.usage.remaining)      # from this response's X-Usage-* headers

Simulationsjobs

Parameter und Dateien werden lokal gegen den Vertrag des Jobtyps geprüft, bevor etwas gesendet wird. Ein Job, der mit failed endet, löst JobFailed aus, mit seinem errorKind als .kind. Siehe Simulationsjobs.

job = client.submit_job("sat_link_budget", {"latitude_deg": 40.7, "longitude_deg": -74.0})
job = job.wait(timeout=600)        # polls as the web app does
print(job.status, job.result())    # a summary; job.result(full=True) for all of it

est = client.estimate_job("fdtd_sparam", {"traceW": 0.42, "subH": 0.51, "solveMode": "express"})
print(est.lane, est.within_budget)  # never charged, no key needed

Async-Unterstützung

AsyncClient für FastAPI-Dienste, asynchrone Notebooks oder parallele Sweeps.

import asyncio
import rftools

async def main():
    async with rftools.AsyncClient() as client:
        result = await client.calculate("vswr-return-loss", {"vswr": 2.5})
        print(result["returnLoss"])

asyncio.run(main())

CLI

Der Befehl rftools wird mit dem Paket installiert.

rftools login                                   # get a key; saved, never printed
rftools calc vswr-return-loss --vswr 2.5
rftools calc vswr-return-loss --vswr 2.5 --json | jq .values
rftools list --category rf
rftools info free-space-path-loss
rftools solve microstrip-impedance --for traceWidth --target impedance=50 --grid 0.001 \
    --param substrateHeight=1.51 --param dielectricConstant=4.5 --param copperThickness=35
rftools sim fdtd_sparam --param solveMode=express --no-wait
rftools estimate fdtd_sparam --param traceW=0.42 --param subH=0.51
rftools version

Fehlerbehandlung

Fehler werden nach HTTP-Status eingeordnet, nie nach dem Meldungstext. Ein 500, 502, 503, 504 wird mit Backoff wiederholt, bevor die Ausnahme ausgelöst wird. Siehe Fehler.

Bereit für die Automatisierung?

Installieren Sie die Bibliothek, holen Sie sich einen kostenlosen Schlüssel und führen Sie in weniger als einer Minute eine erste Berechnung aus. Die REST-API dahinter ist in der API-Referenz dokumentiert.