Sections de la documentation

Tâches de simulation

Les calculateurs répondent en une seule requête. Pas les simulateurs (une résolution pleine onde dure de quelques minutes à quelques heures) : ils sont donc soumis comme tâches, puis interrogés. Chaque type de tâche publie son contrat de paramètres à /api/py/v1/jobs/types : type, unité, plage ou options, valeur par défaut et caractère obligatoire de chaque paramètre, ainsi que les limites de votre offre. Le formulaire du navigateur est construit à partir de ce document et le worker valide d'après lui : lisez-le plutôt que de recopier les noms de paramètres de cette page.

Points de terminaison

Points de terminaison des tâches
Point de terminaison	Ce qu'il fait	Identifiant
GET /api/py/v1/jobs/types	Chaque type de tâche de simulation, ses offres, sa durée maximale, ses limites et ses fichiers.	Aucun
GET /api/py/v1/jobs/types/{job_type}	Le contrat de paramètres d'un type de tâche, en JSON Schema.	Aucun
POST /api/py/v1/jobs/estimate	Ce que coûterait une tâche et sa durée, sans la soumettre.	Aucun
POST /api/py/v1/upload	Un formulaire présigné pour le fichier d'entrée d'une tâche.	Clé d'API ou session connectée
POST /api/py/v1/jobs	Soumettre une tâche de simulation.	Facultatif : clé d'API
GET /api/py/v1/jobs/{job_id}	Le statut et la progression d'une tâche et, une fois terminée, le lien vers son résultat.	L'identité qui l'a soumise
GET /api/py/v1/jobs	Les tâches récentes de l'appelant, de toutes les clés du compte.	Clé d'API ou session connectée

Soumettre et interroger

Lisez le contrat, envoyez la tâche en POST avec ses params (et inputFileKeys pour un fichier envoyé), et recevez 202 avec un jobId. Avec une clé, une soumission est décomptée du quota comme un appel.

Interrogez GET /api/py/v1/jobs/{jobId} avec la même identité que celle qui l'a soumise. Le statut porte progress, stage, finishedAt, elapsedSeconds, errorKind et, une fois la tâche terminée, une resultUrl présignée. GET /api/py/v1/jobs liste vos tâches récentes, y compris celles soumises avec n'importe quelle clé du compte. La bibliothèque Python interroge comme l'application web : job.wait() vérifie immédiatement, puis toutes les 2 s, 5 s et 15 s à mesure que la tâche se prolonge.

Types de tâches

13 types de tâches. La liste des paramètres de chacun se trouve à /api/py/v1/jobs/types/{jobType}.

Types de tâches
jobType	Simulateur	Fichiers
`antenna_sim`14 paramètres	Simulateur d'antenne filaire (NEC-2)	Aucun
`emi_radiated`11 paramètres	Estimateur d'émissions rayonnées EMI	Aucun
`eye_diagram`11 paramètres	Schéma oculaire à partir de S-Parameters	Obligatoire, jusqu'à 1 × .s2p / .s4p
`fdtd_sparam`17 paramètres	Simulateur de ligne de transmission FDTD	Aucun
`filter_monte_carlo`15 paramètres	Analyse Monte Carlo du filtre RF	Aucun
`impedance_match`14 paramètres	Synthétiseur d'adaptation d'impédance haut débit	Facultatif, jusqu'à 2 × .s2p / .s1p
`magnetics_optimizer`14 paramètres	Optimiseur de conception des composants magnétiques et des transformateurs	Aucun
`pdn_impedance`16 paramètres	Analyseur d'impédance PDN et optimiseur de condensateur de découplage	Aucun
`radar_detection`15 paramètres	Performances de détection radar Monte Carlo	Aucun
`rf_cascade`8 paramètres	Analyseur de budget RF Cascade	Facultatif, jusqu'à 12 × .s2p
`sat_link_budget`14 paramètres	Budget des liaisons par satellite et terrestre	Aucun
`smps_control_loop`36 paramètres	Analyseur de stabilité de boucle de contrôle SMPS	Aucun
`sparam_pipeline`3 paramètres	Pipeline d'analyse des paramètres S	Obligatoire, jusqu'à 4 × .s1p / .s2p / .s3p / .s4p

Ce que coûterait une tâche

POST /api/py/v1/jobs/estimate reçoit le corps qu'une soumission enverrait et indique l'environnement de calcul dans lequel la tâche tournerait, la durée prévue, si elle tient dans le budget de cet environnement et, dans l'environnement payant, les crédits qu'elle enregistrerait. L'estimation n'est jamais facturée, ne demande aucune clé et passe les mêmes vérifications qu'une soumission : elle refuse donc exactement quand une soumission serait refusée. Les crédits sont affichés et enregistrés, mais pas encore facturés.

Quand une requête est refusée

Une soumission est vérifiée par rapport à son contrat avant toute mise en file d'attente ou facturation. Une requête hors contrat reçoit un 400 qui nomme chaque paramètre en cause, pas seulement le premier rencontré ; rien n'est mis en file d'attente et aucun quota n'est consommé. Les clés de paramètre inconnues sont refusées plutôt qu'ignorées.

Types d'erreur

Chaque échec porte errorKind à côté de son message, sur une soumission refusée comme sur une tâche qui a échoué après avoir été acceptée. C'est un ensemble fermé ; basez votre logique sur lui plutôt que sur la formulation du message, écrite pour des personnes et susceptible de changer.

Types d'erreur
errorKind	Signification
invalid_request	Un paramètre manque, est du mauvais type, sort de sa plage, ne figure pas parmi les options déclarées ou n'est pas un paramètre de ce type de tâche. Le corps du 400 liste chaque paramètre en cause.
too_large	La requête respecte le contrat mais dépasse ce que l'environnement de calcul de cette offre peut traiter. Réduisez la taille du problème.
not_available	La requête demande un mode ou une fonction que cette offre ne comprend pas. Le message nomme ce que l'offre comprend.
rate_limited	Une limite de tâches simultanées ou un quota mensuel est épuisé. Porte Retry-After et, pour un quota mensuel, resetAt.
timeout	La tâche a dépassé la durée maximale de son type. Elle n'est pas facturée.
interrupted	L'exécution s'est arrêtée avant la fin : un worker a été remplacé ou une tâche a été arrêtée. Elle n'est pas facturée.
result_expired	La tâche s'est terminée, mais son résultat n'est plus stocké. Le statut reste completed et ne porte pas de resultUrl.
transient	Le service n'a pas pu accepter ou vérifier la requête à ce moment-là. Rien n'a été mis en file d'attente ni facturé ; réessayez.
fault	Le service a échoué pendant le calcul. Le message indique l'étape ; rien n'est facturé.

Limites, doublons et durées de vie

Concurrence

3 tâches en file d'attente ou en cours à la fois, par appelant. Au-delà, l'API renvoie 429 avec Retry-After et un corps portant pending et limit.

Soumissions en double

Une requête identique du même appelant dans un délai de 60 s renvoie la tâche existante, avec son statut réel : une tâche qui a déjà échoué revient donc en échec, avec sa raison. Envoyez Idempotency-Bypass: true pour l'exécuter à nouveau malgré tout.

Fichiers

POST /api/py/v1/upload demande une clé ou une session connectée et renvoie un formulaire POST présigné valable 5 minutes. Au plus 10 MB par fichier, imposés par le formulaire lui-même. Formats acceptés : .s1p .s2p .s3p .s4p .s6p .s8p .snp .csv .txt. L'objet envoyé est conservé 24 heures : soumettez la tâche qui l'utilise dans la journée. 20 formulaires par minute et par adresse.

Résultats

Deux échéances distinctes. resultExpiresAt indique quand le résultat lui-même disparaît : après 30 jours avec l'offre Free, conservé sans limite de durée avec Pro et API. resultUrlExpiresIn indique combien de temps dure la resultUrl présignée : 15 minutes. Interrogez à nouveau pour obtenir un lien neuf ; ne mettez pas l'URL en cache. Une fois le résultat supprimé, le statut reste completed, avec le type result_expired et sans URL.

Ce qui a changé pour les appelants qui omettent un paramètre

Chaque type de tâche a une seule définition de ses paramètres, et les valeurs de repli propres aux gestionnaires ont disparu. Si vous envoyez tous les champs, rien n'a changé. Si vous omettez l'un de ceux-ci, la valeur utilisée n'est plus la même qu'avant, et la réponse non plus.

Valeurs par défaut modifiées
jobType	Paramètre	Avant	Désormais
`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`	"[]"	obligatoire — pas de valeur par défaut
`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`	centre de la carte (boardWidth_mm / 2)	point au tiers (boardWidth_mm / 3)
`pdn_impedance`	`portY_mm`	centre de la carte (boardLength_mm / 2)	point au tiers (boardLength_mm / 3)

Les clés de paramètre inconnues étaient auparavant ignorées et la réponse utilisait une valeur par défaut. Elles sont désormais refusées, et le refus liste les clés que le type de tâche accepte.

Pour les types de tâches qui échantillonnent (filter_monte_carlo et les autres optimiseurs), la graine aléatoire est dérivée du corps que vous soumettez : la même conception envoyée avec des clés différentes tire un échantillon différent. Omettre un paramètre et l'envoyer avec sa valeur par défaut constituent la même requête pour le solveur, mais pas le même corps ; c'est pourquoi une exécution depuis le formulaire web et une exécution via cette API peuvent différer dans les limites de l'erreur d'échantillonnage. Envoyez randomSeed pour figer exactement une exécution.

Changements de la version de septembre 2026

Comportements qui ont changé pour une intégration existante. Si vous envoyez tous les paramètres et vérifiez errorKind plutôt que le texte du message, les seules différences que vous devriez constater sont celles-ci. Les changements ultérieurs, et la date d'annonce de chacun, figurent dans le journal des modifications de l'API.

Ce qui a changé

Les clés de paramètre inconnues et les valeurs hors plage sont refusées à la soumission par un 400 qui nomme le paramètre en cause, au lieu d'être ignorées ou bornées et traitées malgré tout.
11 valeurs par défaut de paramètres ont changé pour les appelants qui omettent le champ ; voir le tableau ci-dessus.
Un quota mensuel épuisé donne désormais HTTP 402 (errorKind rate_limited) avec Retry-After et resetAt, jamais un 401 ni un simple 429. Cela couvre à la fois le mois de la clé d'API et le quota des modes de résolution FDTD.
Un envoi de fichier exige désormais une session connectée ou une clé d'API ; une requête anonyme reçoit un 401 avant tout stockage. L'environnement gratuit anonyme perd entièrement les deux outils à fichier d'entrée (eye_diagram, sparam_pipeline), car aucun ne fonctionne sans fichier envoyé.
Une tâche soumise avec une clé d'API appartient désormais au compte propriétaire de la clé : elle est autorisée d'après ce propriétaire, et pas seulement d'après l'identifiant de clé ou l'IP de soumission, et elle apparaît dans la liste des tâches du tableau de bord du propriétaire.
Un résultat terminé porte désormais warnings et provenance (method, version, seed et les entrées normalisées réellement utilisées) à côté des valeurs calculées.
Chaque échec — une soumission refusée comme une tâche qui a échoué après avoir été acceptée — porte désormais errorKind. Voir l'ensemble fermé ci-dessus.
Une tâche dont le worker tombe en cours d'exécution — remplacé, ou sa tâche arrêtée — est désormais marquée en échec avec le type interrupted au lieu de rester bloquée, et toute facturation la concernant est annulée.
Un résultat est conservé exactement aussi longtemps que l'indique son enregistrement : voir resultExpiresAt dans la carte Résultats ci-dessus.
La topologie Auto du synthétiseur d'impédance compare désormais les cinq topologies et renvoie celle qui a le meilleur affaiblissement de réflexion dans le pire cas — auparavant, elle construisait toujours un réseau en L, en mode rapide comme avec le réglage avancé par défaut.
Le synthétiseur d'impédance respecte désormais maxQ et componentSeries ; les deux étaient auparavant acceptés et ignorés sans avertissement.
L'alignement sur les valeurs normalisées de la série E arrondit désormais une mantisse supérieure à environ 9,55 vers le haut, à la première valeur de la décade suivante (9,9 nF → 10 nF), au lieu de l'arrondir vers le bas. Cela peut changer la valeur d'un composant dans une conception d'adaptation d'impédance ou dans une exécution Monte Carlo de filtre pour la même entrée.
Les netlists SPICE exportées depuis la page d'impédance portent désormais les valeurs normalisées (alignées) des composants, et non les valeurs idéales, avec une ligne d'en-tête qui nomme la série.
Les conceptions d'inductances de puissance et d'inductances couplées sont désormais dimensionnées à partir de l'inductance et du courant crête que vous indiquez, au lieu d'être déduites d'autres entrées ; les transformateurs flyback et forward ne changent pas. Une requête dont le courant crête indiqué ne concorde pas avec l'ondulation de l'inductance indiquée revient avec un avertissement ripple_exceeds_peak.
Note de déploiement : le validateur de l'API a été déployé avant le worker pendant ce déploiement ; une tâche mise en file d'attente dans cet intervalle dont le corps portait une clé mal orthographiée — auparavant acceptée sans avertissement avec une valeur par défaut — a donc été refusée à la soumission au lieu d'être exécutée jusqu'au bout.

Soumettre

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
}

En file d'attente. Interrogez le jobId.

{
  "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
    }
  ]
}

Tous les paramètres hors contrat, d'un coup. Rien n'a été mis en file d'attente.

{
  "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"
}

Trop de tâches à la fois, avec Retry-After.

Interroger

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))
}

Estimer, sans soumettre

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))
}