Sections de la documentation

Résoudre pour une valeur cible

POSThttps://rftools.io/api/py/v1/calculate/solve

Trouve la valeur d'une entrée du calculateur qui amène l'une de ses sorties à une cible (la largeur de piste qui donne 50 Ω, l'écart qui donne une impédance différentielle cible) et la renvoie avec le résultat direct calculé exactement à cette valeur. Un seul appel décompté remplace les appels directs qu'un client dépenserait autrement à chercher à la main.

Déroulement de la recherche

La recherche parcourt les bornes indiquées de solveFor, resserrées par range lorsqu'il est fourni ; une entrée sans borne indiquée exige range. Lorsque grid est fourni, la value renvoyée est arrondie au multiple de la grille le plus proche dans la plage et unrounded porte la solution exacte ; sans grid, value et unrounded sont le même nombre. Dans tous les cas, result (exactement ce que /calculate renvoie pour ces entrées, provenance comprise) est l'exécution directe du calculateur exactement à la value renvoyée : ce qu'un client affiche est donc un vrai calcul direct, jamais l'estimation propre du solveur.

Corps de la requête

SolveRequest
Champ	Description
slugobligatoirestring	Le calculateur.
inputsobligatoireobject of numbers	Toutes les entrées sauf solveFor. Une valeur donnée pour solveFor n'est que le point de départ de la recherche, utilisé pour départager plusieurs solutions.
solveForobligatoirestring	Une entrée numérique déclarée du calculateur.
target.outputobligatoirestring	Une clé de sortie que renvoie le calculateur.
target.valueobligatoirenumber	La valeur que cette sortie doit atteindre.
gridnumber	Une grille de fabrication positive ; la valeur renvoyée est arrondie à son multiple le plus proche dans la plage.
range[number, number]	Resserre les bornes indiquées de solveFor ; obligatoire quand il n'en indique aucune.

Réponse

SolveResponse
Champ	Description
valuenumber	La valeur résolue, arrondie à grid lorsqu'une grille a été donnée.
unroundednumber	La solution exacte, avant l'arrondi à la grille.
reachedboolean	Si la cible a été atteinte ; false porte quand même la valeur la plus proche trouvée, pas une supposition.
evaluationsinteger	Le nombre d'évaluations directes utilisées par la recherche.
warningsstring[]	Les constats propres à la résolution : une autre solution dans la plage, ou une cible non atteinte.
resultobject	Exactement ce que /calculate renvoie pour les entrées avec solveFor fixé à value : values, warnings, errors et provenance.
slug, solveFor, target, gridecho	Les champs de la requête, tels que fournis ; grid vaut null quand aucune grille n'a été donnée.

Coût et solutions multiples

Coût

Un appel décompté, facturé comme /calculate après toutes les vérifications ci-dessous, et restitué si le service échoue ensuite. Une cible que la recherche ne peut pas atteindre reste un succès et est facturée, avec reached: false et la valeur la plus proche trouvée : l'appelant a demandé quelque chose que le service a fourni.

Plus d'une solution

Lorsque la sortie croise la cible plus d'une fois dans la plage, l'appel renvoie le croisement le plus proche de la valeur de départ (la valeur de l'appelant pour solveFor, sinon la valeur par défaut du calculateur) et ajoute un avertissement qui nomme l'autre.

Refus

Une requête impossible à résoudre est refusée avant toute facturation, et param nomme le champ en cause :

Refus de solve
Statut	Quand
404	Le slug du calculateur n'existe pas.
400	solveFor n'est pas l'une des entrées numériques déclarées du calculateur (param: solveFor, avec allowed).
400	target.output n'est pas l'une des sorties du calculateur (param: target.output, avec allowed).
400	grid est fourni et n'est pas un nombre fini et positif, ou n'a aucun multiple dans la plage.
400	Une valeur fournie (une entrée, target.value ou une borne de plage) n'est pas finie.
400	solveFor n'a pas de borne indiquée et le corps ne fournit pas de range, ou la plage fournie sort des bornes indiquées ou est vide.
400	Une entrée fixe dépasse une limite que le calculateur impose à sa propre durée d'exécution, comme pour /calculate.

curl -X POST https://rftools.io/api/py/v1/calculate/solve \
  -H "X-API-Key: $RFTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "microstrip-impedance",
    "inputs": {
      "substrateHeight": 1.51,
      "dielectricConstant": 4.5,
      "copperThickness": 35
    },
    "solveFor": "traceWidth",
    "target": {
      "output": "impedance",
      "value": 50
    },
    "grid": 0.001
  }'

import rftools

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

result = client.solve(
    "microstrip-impedance",
    {
        "substrateHeight": 1.51,
        "dielectricConstant": 4.5,
        "copperThickness": 35,
    },
    "traceWidth", "impedance", 50,
    grid=0.001,
)
print(result.value, result.reached)
print(result.result.values)

const response = await fetch("https://rftools.io/api/py/v1/calculate/solve", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.RFTOOLS_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "slug": "microstrip-impedance",
    "inputs": {
      "substrateHeight": 1.51,
      "dielectricConstant": 4.5,
      "copperThickness": 35
    },
    "solveFor": "traceWidth",
    "target": {
      "output": "impedance",
      "value": 50
    },
    "grid": 0.001
  }),
});
console.log(response.status, await response.json());

package main

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

func main() {
	body := []byte(`{
	  "slug": "microstrip-impedance",
	  "inputs": {
	    "substrateHeight": 1.51,
	    "dielectricConstant": 4.5,
	    "copperThickness": 35
	  },
	  "solveFor": "traceWidth",
	  "target": {
	    "output": "impedance",
	    "value": 50
	  },
	  "grid": 0.001
	}`)
	req, err := http.NewRequest("POST", "https://rftools.io/api/py/v1/calculate/solve", 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

{
  "slug": "microstrip-impedance",
  "solveFor": "traceWidth",
  "target": {
    "output": "impedance",
    "value": 50
  },
  "grid": 0.001,
  "value": 2.781,
  "unrounded": 2.780720522734193,
  "reached": true,
  "evaluations": 68,
  "warnings": [],
  "result": {
    "slug": "microstrip-impedance",
    "values": {
      "impedance": 49.99705984469245,
      "effectiveDielectric": 3.3944336801230706,
      "propagationDelay": 6.145581196647901,
      "guidedWavelength": 67.79939168226058,
      "quarterWavelength": 16.949847920565144
    },
    "warnings": [],
    "errors": [],
    "provenance": {
      "method": "calculator:microstrip-impedance",
      "version": "api@3f2c1a9b04de",
      "formulaRef": "Hammerstad & Jensen (1980); Wadell, \"Transmission Line Design Handbook\" 1991",
      "assumptions": [
        {
          "code": "quasi-static",
          "text": "Quasi-static: Z₀ and εeff are the Hammerstad–Jensen static values, with no frequency dependence; dispersion is not modelled."
        },
        {
          "code": "bare-microstrip",
          "text": "Bare microstrip: air above the trace, with no soldermask or other cover layer."
        },
        {
          "code": "homogeneous-substrate",
          "text": "One homogeneous, isotropic, non-magnetic substrate of relative permittivity εr over a solid ground plane, both extending well beyond the trace."
        },
        {
          "code": "thickness-effective-width",
          "text": "Copper thickness t is modelled as an effective width increase Δw = (t/π)(1 + ln(2h/t)), applied to both Z₀ and εeff."
        },
        {
          "code": "lossless",
          "text": "Lossless: conductor and dielectric losses are neglected, so Z₀ is real and the propagation delay is √εeff/c."
        }
      ],
      "validRange": {
        "status": "inside",
        "bounds": {
          "traceWidth": {
            "min": 0.01,
            "max": 50,
            "unit": "mm"
          },
          "substrateHeight": {
            "min": 0.05,
            "max": 10,
            "unit": "mm"
          },
          "dielectricConstant": {
            "min": 1,
            "max": 100,
            "unit": ""
          },
          "copperThickness": {
            "min": 1,
            "max": 200,
            "unit": "μm"
          },
          "frequency": {
            "min": 0.001,
            "max": 300,
            "unit": "GHz"
          }
        },
        "outside": [],
        "model": null
      },
      "computedAt": "2026-09-24T14:05:11.004Z",
      "inputs": {
        "traceWidth": 2.781,
        "substrateHeight": 1.51,
        "dielectricConstant": 4.5,
        "copperThickness": 35,
        "frequency": 2.4
      },
      "seed": null,
      "elapsedSeconds": 0.004
    }
  }
}

La largeur de piste qui atteint 50 Ω sur du FR-4 de 1,51 mm, sur une grille de 0,001 mm.

{
  "detail": "'impedance' is not an input of 'microstrip-impedance', so it cannot be solved for. Its inputs: traceWidth, substrateHeight, dielectricConstant, copperThickness, frequency.",
  "errorKind": "invalid_request",
  "param": "solveFor",
  "allowed": [
    "traceWidth",
    "substrateHeight",
    "dielectricConstant",
    "copperThickness",
    "frequency"
  ]
}

Une sortie indiquée comme solveFor. Rien n'a été facturé.

{
  "detail": "Calculator 'microstrip' not found",
  "errorKind": "invalid_request"
}

Un slug qui n'existe pas.