Bibliothèque Python rftools

Installation

pip install rftools-io. Python 3.12 ou ultérieur ; elle installe httpx, pydantic et click. Voir sur PyPI.

Clé d'API

rftools login (ou rftools.Client().login()) affiche une page et un code : ouvrez la page, connectez-vous, approuvez le code, et la clé est enregistrée dans le fichier d'identifiants de votre utilisateur, lisible par vous seul. Ou définissez RFTOOLS_API_KEY, qui a la priorité. rftools.Client() et les fonctions utilitaires du module lisent l'un ou l'autre ; un api_key= explicite l'emporte sur les deux. Les clés commencent par rfc_ ; voir Authentification.

Démarrage rapide

rftools.calculate() renvoie un CalculatorResult : lisez les sorties par nom, ou .values, .warnings et .provenance.

Stubs typés par catégorie

Un module par catégorie de calculateurs, une fonction par calculateur, avec des noms de paramètres et des valeurs par défaut identiques à ceux des pages web. Un slug devient un nom de fonction où - devient _, et un nom qui commencerait par un chiffre reçoit le préfixe calc_.

Résoudre pour une valeur cible

client.solve() trouve la valeur d'une entrée qui amène une sortie à une cible et la renvoie avec le résultat direct calculé exactement à cette valeur, par POST /api/py/v1/calculate/solve. Un appel décompté. Disponible à partir de 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) renvoie un SolveResult avec .value, .unrounded, .reached, .evaluations, .warnings et .result, le même CalculatorResult que client.calculate() renvoie pour les entrées avec solve_for fixé à .value. Une cible que la recherche ne peut pas atteindre renvoie tout de même un résultat, avec .reached à False et la valeur la plus proche trouvée, et coûte tout de même un appel. Voir Résoudre pour une valeur cible pour les champs, la plage de recherche et les refus.

Calcul par lots

Jusqu'à 50 calculs en une requête, pour les balayages ; un appel par élément calculé. Le point de terminaison par lots fait partie de l'offre API ; voir les tarifs (API $19 par mois, 10 000 appels).

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)

Usage

Le quota mensuel appartient au compte ; chaque clé du compte y puise.

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

Tâches de simulation

Les paramètres et les fichiers sont vérifiés localement par rapport au contrat du type de tâche avant tout envoi. Une tâche qui se termine en failed lève JobFailed avec son errorKind dans .kind. Voir Tâches de simulation.

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

Prise en charge asynchrone

AsyncClient pour les services FastAPI, les notebooks asynchrones ou les balayages concurrents.

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

La commande rftools est installée avec le paquet.

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

Gestion des erreurs

Les erreurs sont classées selon le statut HTTP, jamais selon le texte du message. Un 500, 502, 503, 504 est retenté avec un délai croissant avant que l'exception ne soit levée. Voir Erreurs.

Prêt à automatiser ?

Installez la bibliothèque, obtenez une clé gratuite et lancez un premier calcul en moins d'une minute. L'API REST sous-jacente est documentée dans la référence de l'API.