Abschnitte der Dokumentation

Simulationsjobs

Die Rechner antworten in einer Anfrage. Die Simulatoren nicht (eine Vollwellen-Lösung läuft Minuten bis Stunden), deshalb werden sie als Jobs eingereicht und abgefragt. Jeder Jobtyp veröffentlicht seinen Parametervertrag unter /api/py/v1/jobs/types: Typ, Einheit, Bereich oder Optionen, Standardwert und Pflichtangabe für jeden Parameter sowie die Limits Ihres Tarifs. Das Browserformular wird aus diesem Dokument aufgebaut, und der Worker prüft dagegen, also lesen Sie es, statt Parameternamen von dieser Seite abzutippen.

Endpunkte

Job-Endpunkte
Endpunkt	Was er tut	Zugangsdaten
GET /api/py/v1/jobs/types	Jeder Simulationsjobtyp, seine Tarife, seine Zeitobergrenze, seine Limits und Uploads.	Keine
GET /api/py/v1/jobs/types/{job_type}	Der Parametervertrag eines Jobtyps, als JSON Schema.	Keine
POST /api/py/v1/jobs/estimate	Was ein Job kosten und wie lange er laufen würde, ohne ihn einzureichen.	Keine
POST /api/py/v1/upload	Ein vorsigniertes Formular für die Eingabedatei eines Jobs.	API-Schlüssel oder angemeldete Sitzung
POST /api/py/v1/jobs	Einen Simulationsjob einreichen.	Optional: API-Schlüssel
GET /api/py/v1/jobs/{job_id}	Status und Fortschritt eines Jobs und, sobald er fertig ist, der Link zu seinem Ergebnis.	Die Identität, die ihn eingereicht hat
GET /api/py/v1/jobs	Die letzten Jobs des Aufrufers, aus allen Schlüsseln des Kontos.	API-Schlüssel oder angemeldete Sitzung

Einreichen und abfragen

Lesen Sie den Vertrag, senden Sie den Job per POST mit seinen params (und inputFileKeys für eine hochgeladene Datei) und erhalten Sie 202 mit einer jobId. Mit Schlüssel wird eine Einreichung als ein Aufruf auf das Kontingent angerechnet.

Fragen Sie GET /api/py/v1/jobs/{jobId} mit derselben Identität ab, die den Job eingereicht hat. Der Status trägt progress, stage, finishedAt, elapsedSeconds, errorKind und, sobald der Job fertig ist, eine vorsignierte resultUrl. GET /api/py/v1/jobs listet Ihre letzten Jobs auf, auch solche, die mit einem beliebigen Schlüssel des Kontos eingereicht wurden. Die Python-Bibliothek fragt so ab wie die Web-App: job.wait() prüft sofort, dann alle 2 s, 5 s und 15 s, während der Job weiterläuft.

Jobtypen

13 Jobtypen. Die Parameterliste jedes Typs steht unter /api/py/v1/jobs/types/{jobType}.

Jobtypen
jobType	Simulator	Uploads
`antenna_sim`14 Parameter	Drahtantennen-Simulator (NEC-2)	Keine
`emi_radiated`11 Parameter	Schätzer für EMI-Strahlemissionen	Keine
`eye_diagram`11 Parameter	Augendiagramm aus S-Parametern	Erforderlich, bis zu 1 × .s2p / .s4p
`fdtd_sparam`17 Parameter	FDTD-Übertragungsleitungssimulator	Keine
`filter_monte_carlo`15 Parameter	HF-Filter Monte-Carlo-Analyse	Keine
`impedance_match`14 Parameter	Breitband-Impedanzanpassungssynthesizer	Optional, bis zu 2 × .s2p / .s1p
`magnetics_optimizer`14 Parameter	Designoptimierer für Magnetik und Transformatoren	Keine
`pdn_impedance`16 Parameter	PDN-Impedanzanalysator und Entkopplungskondensator-Optimierer	Keine
`radar_detection`15 Parameter	Leistung der Radarerkennung Monte Carlo	Keine
`rf_cascade`8 Parameter	RF Cascade Budgetanalysator	Optional, bis zu 12 × .s2p
`sat_link_budget`14 Parameter	Budget für Satelliten- und terrestrische Verbindungen	Keine
`smps_control_loop`36 Parameter	SMPS-Regelkreisstabilitätsanalysator	Keine
`sparam_pipeline`3 Parameter	S-Parameter-Analysepipeline	Erforderlich, bis zu 4 × .s1p / .s2p / .s3p / .s4p

Was ein Job kosten würde

POST /api/py/v1/jobs/estimate nimmt den Body, den eine Einreichung senden würde, und antwortet mit der Rechenumgebung, in der der Job laufen würde, der erwarteten Laufzeit, der Angabe, ob er in das Budget dieser Umgebung passt, und, in der bezahlten Umgebung, den Credits, die er verbuchen würde. Die Schätzung wird nie abgerechnet, braucht keinen Schlüssel und durchläuft dieselben Prüfungen wie eine Einreichung, lehnt also genau dann ab, wenn eine Einreichung abgelehnt würde. Credits werden angezeigt und verbucht, aber noch nicht abgerechnet.

Wenn eine Anfrage abgelehnt wird

Eine Einreichung wird gegen ihren Vertrag geprüft, bevor etwas eingereiht oder abgerechnet wird. Eine Anfrage außerhalb davon ist ein 400, der jeden fehlerhaften Parameter nennt, nicht nur den ersten; es wird nichts eingereiht und kein Kontingent verbraucht. Unbekannte Parameterschlüssel werden abgelehnt statt ignoriert.

Fehlerarten

Jeder Fehlschlag trägt errorKind neben seiner Meldung, bei einer abgelehnten Einreichung und bei einem Job, der nach seiner Annahme scheiterte. Dies ist eine geschlossene Menge; verzweigen Sie danach statt nach dem Wortlaut der Meldung, der für Menschen geschrieben ist und sich ändern kann.

Fehlerarten
errorKind	Bedeutung
invalid_request	Ein Parameter fehlt, hat den falschen Typ, liegt außerhalb des Bereichs, ist keine der deklarierten Optionen oder kein Parameter dieses Jobtyps. Der 400-Body listet jeden fehlerhaften Parameter auf.
too_large	Die Anfrage liegt innerhalb des Vertrags, aber jenseits dessen, was die Rechenumgebung dieses Tarifs ausführen kann. Verkleinern Sie das Problem.
not_available	Die Anfrage verlangt einen Modus oder eine Funktion, die dieser Tarif nicht enthält. Die Meldung nennt, was der Tarif enthält.
rate_limited	Ein Limit für gleichzeitige Jobs oder ein monatliches Kontingent ist ausgeschöpft. Trägt Retry-After und, bei einem monatlichen Kontingent, resetAt.
timeout	Der Job hat die Zeitobergrenze seines Typs überschritten. Dafür wird nichts abgerechnet.
interrupted	Der Lauf endete, bevor er fertig war — ein Worker wurde ersetzt oder ein Task gestoppt. Dafür wird nichts abgerechnet.
result_expired	Der Job wurde abgeschlossen, aber sein Ergebnis ist nicht mehr gespeichert. Der Status lautet weiterhin completed und trägt keine resultUrl.
transient	Der Dienst konnte die Anfrage gerade nicht annehmen oder prüfen. Es wurde nichts eingereiht oder abgerechnet; versuchen Sie es erneut.
fault	Der Dienst ist bei der Berechnung gescheitert. Die Meldung nennt den Schritt; dafür wird nichts abgerechnet.

Limits, Duplikate und Lebensdauer

Gleichzeitigkeit

3 Jobs gleichzeitig in der Warteschlange oder in Ausführung, pro Aufrufer. Darüber antwortet die API mit 429, mit Retry-After und einem Body mit pending und limit.

Doppelte Einreichungen

Eine identische Anfrage desselben Aufrufers innerhalb von 60 s liefert den bestehenden Job mit seinem tatsächlichen Status zurück, sodass ein bereits gescheiterter Job als gescheitert mit seinem Grund zurückkommt. Senden Sie Idempotency-Bypass: true, um ihn trotzdem erneut auszuführen.

Uploads

POST /api/py/v1/upload braucht einen Schlüssel oder eine angemeldete Sitzung und liefert ein vorsigniertes POST-Formular, das 5 Minuten gültig ist. Höchstens 10 MB pro Datei, vom Formular selbst durchgesetzt. Angenommen: .s1p .s2p .s3p .s4p .s6p .s8p .snp .csv .txt. Das hochgeladene Objekt wird 24 Stunden aufbewahrt; reichen Sie den Job, der es verwendet, also noch am selben Tag ein. 20 Formulare pro Minute und Adresse.

Ergebnisse

Zwei verschiedene Fristen. resultExpiresAt gibt an, wann das Ergebnis selbst gelöscht wird: nach 30 Tagen im Free-Tarif, unbefristet aufbewahrt bei Pro und API. resultUrlExpiresIn gibt an, wie lange die vorsignierte resultUrl gilt: 15 Minuten. Fragen Sie für einen neuen Link erneut ab; speichern Sie die URL nicht. Ist das Ergebnis gelöscht, lautet der Status weiterhin completed, mit der Art result_expired und ohne URL.

Was sich für Aufrufer geändert hat, die einen Parameter weglassen

Jeder Jobtyp hat eine einzige Definition seiner Parameter, und die eigenen Ersatzwerte der Handler sind entfallen. Wenn Sie jedes Feld senden, hat sich nichts geändert. Wenn Sie einen dieser Parameter weglassen, ist der verwendete Wert ein anderer als zuvor, und damit auch die Antwort.

Geänderte Standardwerte
jobType	Parameter	Vorher	Jetzt
`rf_cascade`	`nfSpec_db`	10 dB	6 dB
`rf_cascade`	`inputPower_dbm`	−60 dBm	−70 dBm
`rf_cascade`	`bandwidth_hz`	1 MHz	10 MHz
`rf_cascade`	`stages`	"[]"	erforderlich — kein Standardwert
`smps_control_loop`	`toleranceDistribution`	uniform	gaussian
`filter_monte_carlo`	`freqCutoff`	1 MHz	1 GHz
`impedance_match`	`freqStart`	1 MHz	800 MHz
`impedance_match`	`freqStop`	100 MHz	1,2 GHz
`antenna_sim`	`freq (instant solve)`	145 MHz	146 MHz
`pdn_impedance`	`portX_mm`	Platinenmitte (boardWidth_mm / 2)	Drittelpunkt (boardWidth_mm / 3)
`pdn_impedance`	`portY_mm`	Platinenmitte (boardLength_mm / 2)	Drittelpunkt (boardLength_mm / 3)

Unbekannte Parameterschlüssel wurden früher verworfen und mit einem Standardwert beantwortet. Jetzt werden sie abgelehnt, und die Ablehnung listet die Schlüssel auf, die der Jobtyp annimmt.

Bei den Jobtypen, die Stichproben ziehen (filter_monte_carlo und den anderen Optimierern), wird der Zufalls-Seed aus dem eingereichten Body abgeleitet, sodass derselbe Entwurf, mit anderen Schlüsseln gesendet, eine andere Stichprobe zieht. Einen Parameter wegzulassen und ihn mit seinem Standardwert zu senden, ist für den Löser dieselbe Anfrage, aber nicht derselbe Body; deshalb können ein Lauf aus dem Webformular und ein Lauf über diese API im Rahmen des Stichprobenfehlers voneinander abweichen. Senden Sie randomSeed, um einen Lauf genau festzulegen.

Änderungen im Release vom September 2026

Verhalten, das sich für eine bestehende Integration geändert hat. Wenn Sie jeden Parameter senden und errorKind statt des Meldungstexts prüfen, sollten Sie nur diese Unterschiede sehen. Spätere Änderungen und das Datum ihrer Ankündigung stehen im API-Änderungsprotokoll.

Was sich geändert hat

Unbekannte Parameterschlüssel und Werte außerhalb des Bereichs werden beim Einreichen mit einem 400 abgelehnt, der den fehlerhaften Parameter nennt, statt verworfen oder begrenzt und trotzdem beantwortet zu werden.
11 Parameter-Standardwerte haben sich für Aufrufer geändert, die das Feld weglassen; siehe die Tabelle oben.
Ein verbrauchtes Monatskontingent ist jetzt HTTP 402 (errorKind rate_limited) mit Retry-After und resetAt, nie ein 401 und nie ein einfacher 429. Das gilt sowohl für den Monat des API-Schlüssels als auch für das Kontingent der FDTD-Lösungsmodi.
Ein Upload braucht jetzt eine angemeldete Sitzung oder einen API-Schlüssel; eine anonyme Anfrage erhält einen 401, bevor etwas gespeichert wird. Die anonyme kostenlose Rechenumgebung verliert die beiden Werkzeuge mit Dateieingabe (eye_diagram, sparam_pipeline) vollständig, da keines ohne hochgeladene Datei läuft.
Ein mit einem API-Schlüssel eingereichter Job gehört jetzt dem Konto, dem der Schlüssel gehört: Er wird nach dem Eigentümer autorisiert, nicht nur nach Schlüssel-ID oder einreichender IP, und erscheint in der Jobliste im Dashboard des Eigentümers.
Ein abgeschlossenes Ergebnis trägt jetzt warnings und provenance (method, version, seed und die tatsächlich verwendeten normalisierten Eingaben) neben den berechneten Werten.
Jeder Fehlschlag — eine abgelehnte Einreichung und ein Job, der nach seiner Annahme scheiterte — trägt jetzt errorKind. Siehe die geschlossene Menge oben.
Ein Job, dessen Worker mitten im Lauf ausfällt — ersetzt oder sein Task gestoppt —, wird jetzt mit der Art interrupted als gescheitert markiert, statt hängen zu bleiben, und eine dafür vorgemerkte Abrechnung wird aufgehoben.
Ein Ergebnis wird genau so lange aufbewahrt, wie sein Datensatz angibt: siehe resultExpiresAt in der Karte „Ergebnisse“ oben.
Die Topologie „Auto“ des Impedanz-Synthesizers vergleicht jetzt alle fünf Topologien und liefert die mit der besten Rückflussdämpfung im ungünstigsten Fall — zuvor baute sie immer ein L-Netzwerk, im Schnellmodus wie in der erweiterten Standardeinstellung.
Der Impedanz-Synthesizer berücksichtigt jetzt maxQ und componentSeries; beide wurden zuvor angenommen und stillschweigend ignoriert.
Das Einrasten auf E-Reihen-Normwerte rundet eine Mantisse über etwa 9,55 jetzt auf den ersten Wert der nächsten Dekade auf (9,9 nF → 10 nF) statt ab. Das kann bei gleicher Eingabe einen Bauteilwert in einem Impedanzanpassungs-Entwurf oder in einem Monte-Carlo-Lauf eines Filters ändern.
Von der Impedanzseite exportierte SPICE-Netzlisten tragen jetzt die Normwerte (eingerastet) der Bauteile, nicht die idealen, mit einer Kopfzeile, die die Reihe nennt.
Entwürfe von Leistungs- und gekoppelten Induktivitäten werden jetzt aus der Induktivität und dem Spitzenstrom dimensioniert, die Sie angeben, statt aus anderen Eingaben abgeleitet zu werden; Sperr- und Durchflusswandler-Transformatoren sind unverändert. Eine Anfrage, deren angegebener Spitzenstrom nicht zur Welligkeit ihrer angegebenen Induktivität passt, kommt mit einer Warnung ripple_exceeds_peak zurück.
Hinweis zum Deployment: Der API-Validator wurde während dieses Rollouts vor dem Worker ausgerollt, sodass ein in diesem Zeitfenster eingereihter Job, dessen Body einen falsch geschriebenen Schlüssel trug — zuvor stillschweigend mit einem Standardwert angenommen —, beim Einreichen abgelehnt statt zu Ende ausgeführt wurde.

Einreichen

curl -X POST https://rftools.io/api/py/v1/jobs \
  -H "X-API-Key: $RFTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jobType": "sat_link_budget",
    "params": {
      "latitude_deg": 40.7,
      "longitude_deg": -74,
      "frequency_ghz": 12
    }
  }'

import rftools

client = rftools.Client()  # reads RFTOOLS_API_KEY, or the key `rftools login` saved

job = client.submit_job("sat_link_budget", {"latitude_deg": 40.7, "longitude_deg": -74, "frequency_ghz": 12})
job = job.wait(timeout=600)
print(job.status, job.result())

const response = await fetch("https://rftools.io/api/py/v1/jobs", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.RFTOOLS_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "jobType": "sat_link_budget",
    "params": {
      "latitude_deg": 40.7,
      "longitude_deg": -74,
      "frequency_ghz": 12
    }
  }),
});
console.log(response.status, await response.json());

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
	  "jobType": "sat_link_budget",
	  "params": {
	    "latitude_deg": 40.7,
	    "longitude_deg": -74,
	    "frequency_ghz": 12
	  }
	}`)
	req, err := http.NewRequest("POST", "https://rftools.io/api/py/v1/jobs", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("RFTOOLS_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(out))
}

application/json

{
  "jobId": "6f1c2d4e-…",
  "status": "queued",
  "queuePosition": 1,
  "queueTotal": 1
}

In der Warteschlange. Fragen Sie die jobId ab.

{
  "errorKind": "invalid_request",
  "detail": [
    {
      "param": "frequency_ghz",
      "value": 900,
      "reason": "Frequency (frequency_ghz) must be between 0.1 and 100 GHz (got 900 GHz).",
      "allowed": "0.1 to 100 GHz"
    },
    {
      "param": "longitude_deg",
      "value": null,
      "reason": "Site Longitude (longitude_deg) is required.",
      "allowed": null
    }
  ]
}

Jeder Parameter außerhalb des Vertrags, auf einmal. Es wurde nichts eingereiht.

{
  "detail": "You already have 3 jobs queued or running, and the limit is 3. Wait for one to finish.",
  "pending": 3,
  "limit": 3,
  "errorKind": "rate_limited"
}

Zu viele Jobs gleichzeitig, mit Retry-After.

Abfragen

curl https://rftools.io/api/py/v1/jobs/JOB_ID \
  -H "X-API-Key: $RFTOOLS_API_KEY"

import os

import httpx

response = httpx.get(
    "https://rftools.io/api/py/v1/jobs/JOB_ID",
    headers={"X-API-Key": os.environ["RFTOOLS_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch("https://rftools.io/api/py/v1/jobs/JOB_ID", {
  headers: {
    "X-API-Key": process.env.RFTOOLS_API_KEY,
  },
});
console.log(response.status, await response.json());

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://rftools.io/api/py/v1/jobs/JOB_ID", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("RFTOOLS_API_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(out))
}

Schätzen, ohne einzureichen

curl -X POST https://rftools.io/api/py/v1/jobs/estimate \
  -H "Content-Type: application/json" \
  -d '{
    "jobType": "fdtd_sparam",
    "params": {
      "traceW": 0.42,
      "subH": 0.51,
      "solveMode": "express"
    }
  }'

import rftools

client = rftools.Client()  # reads RFTOOLS_API_KEY, or the key `rftools login` saved

est = client.estimate_job("fdtd_sparam", {"traceW": 0.42, "subH": 0.51, "solveMode": "express"})
print(est.lane, est.wall_seconds, est.within_budget)

const response = await fetch("https://rftools.io/api/py/v1/jobs/estimate", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "jobType": "fdtd_sparam",
    "params": {
      "traceW": 0.42,
      "subH": 0.51,
      "solveMode": "express"
    }
  }),
});
console.log(response.status, await response.json());

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

func main() {
	body := []byte(`{
	  "jobType": "fdtd_sparam",
	  "params": {
	    "traceW": 0.42,
	    "subH": 0.51,
	    "solveMode": "express"
	  }
	}`)
	req, err := http.NewRequest("POST", "https://rftools.io/api/py/v1/jobs/estimate", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(out))
}