ドキュメントのセクション

rftools Python ライブラリ

RF・電子回路の計算ツール 255 種すべてとシミュレーションジョブに、プログラムからアクセスできます。型付き関数、バッチ呼び出し、目標値からの逆算、非同期対応、CLI を備えています。呼び出しにはキーが必要で、無料のキーで月 5 回呼び出せます。

インストール

pip install rftools-io。Python 3.12 以降が必要で、httpx、pydantic、click も一緒にインストールされます。PyPI で見る。

API キー

rftools login（または rftools.Client().login()）はページとコードを表示します。ページを開いてログインし、コードを承認すると、キーはユーザーの認証情報ファイル（本人だけが読める）に保存されます。または RFTOOLS_API_KEY を設定します（こちらが優先されます）。rftools.Client() とモジュールレベルのヘルパーはどちらも読み取り、明示的な api_key= はその両方より優先されます。キーは rfc_ で始まります。認証をご覧ください。

クイックスタート

rftools.calculate() は CalculatorResult を返します。出力を名前で読み取るか、.values、.warnings、.provenance を使います。

カテゴリ別の型付きスタブ

計算ツールのカテゴリごとに 1 モジュール、計算ツールごとに 1 関数があり、パラメーター名と既定値はウェブページと一致します。スラッグは - を _ に置き換えた関数名になり、数字で始まる名前には calc_ の接頭辞が付きます。

SDK のモジュール
モジュール	計算ツール	例
`rftools.calculators.rf`	36	rf.calc_5g_nr_band_lookup(), rf.calc_5g_nr_link_budget()
`rftools.calculators.pcb`	36	pcb.aperture_diagonal(), pcb.asymmetric_stripline()
`rftools.calculators.power`	23	power.battery_charge_time(), power.battery_internal_resistance()
`rftools.calculators.signal`	14	signal.adc_snr(), signal.am_modulation_index()
`rftools.calculators.antenna`	11	antenna.antenna_beamwidth(), antenna.antenna_downtilt()
`rftools.calculators.general`	24	general.calc_555_timer(), general.bjt_bias_point()
`rftools.calculators.motor`	22	motor.battery_runtime_motor(), motor.bldc_efficiency()
`rftools.calculators.protocol`	11	protocol.can_bus_timing(), protocol.clock_jitter()
`rftools.calculators.emc`	16	emc.cable_shield_effectiveness(), emc.chassis_resonance()
`rftools.calculators.thermal`	6	thermal.heatsink_calculator(), thermal.heatsink_selection()
`rftools.calculators.sensor`	17	sensor.calc_4_20ma_transmitter(), sensor.accelerometer_sensitivity()
`rftools.calculators.unit_conversion`	19	unit_conversion.angle_units(), unit_conversion.awg_wire()
`rftools.calculators.audio`	18	audio.amplifier_clipping(), audio.audio_adc_snr()
`rftools.calculators.iot`	2	iot.ble_link_budget(), iot.lora_link_budget()

目標値からの逆算

client.solve() は、出力を目標値にする入力の値を求め、その値でのフォワード計算の結果とともに返します。計算は POST /api/py/v1/calculate/solve が行います。計上対象の呼び出し 1 回です。rftools-io 0.4.0 から利用できます。

Python

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) は、.value、.unrounded、.reached、.evaluations、.warnings、.result を持つ SolveResult を返します。最後のものは、solve_for を .value にした入力に対して client.calculate() が返すのと同じ CalculatorResult です。探索で到達できない目標値でも結果は返り、.reached は False で、見つかった最も近い値が入ります。この場合も呼び出し 1 回分の費用がかかります。フィールド、探索範囲、拒否については目標値からの逆算をご覧ください。

バッチ

1 リクエストで最大 50 件の計算を実行でき、掃引に使えます。計算した項目ごとに 1 回の呼び出しです。バッチエンドポイントは API プランに含まれます。料金（API は月 $19、10,000 回）をご覧ください。

Python

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)

使用状況

月間の利用枠はアカウントに属し、アカウントのすべてのキーがそこから消費します。

Python

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

シミュレーションジョブ

パラメーターとファイルは、送信前にローカルでジョブタイプの契約に照らしてチェックされます。failed で終わったジョブは JobFailed を送出し、その errorKind が .kind に入ります。シミュレーションジョブをご覧ください。

Python

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

非同期対応

FastAPI のサービス、非同期のノートブック、並行する掃引には AsyncClient を使います。

Python

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

rftools コマンドはパッケージと一緒にインストールされます。

Shell

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

エラー処理

エラーはメッセージの文言ではなく HTTP ステータスで分類されます。500, 502, 503, 504 はバックオフ付きで再試行してから送出されます。エラーをご覧ください。

SDK の例外
例外	送出される場合
ValidationError	HTTP 400, 422
AuthError	HTTP 401, 403
QuotaError	HTTP 402
NotFound	HTTP 404
APIError	HTTP 409, 500, 503
RateLimitError	HTTP 429
JobFailed	failed で終わったジョブ。.kind はその errorKind です。
LoginError	rftools login がキーを受け取れませんでした。.error は access_denied または expired_token です。

自動化を始めますか？

ライブラリをインストールし、無料のキーを取得すれば、1 分以内に最初の計算を実行できます。その背後にある REST API は API リファレンスで説明しています。

API アクセスを利用する（$19/月）REST API ドキュメント

インストール

pip install rftools-io
rftools login   # get a key without copying it anywhere

クイックスタート

import rftools

result = rftools.calculate("vswr-return-loss", {"vswr": 2.5})
print(result["returnLoss"])      # dB
print(result.values)             # every output by key
print(result.provenance.formula_ref)