Documentation sections

Crystal PPM Tolerance & Frequency Error Calculator

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

Slug frequency-ppm-tolerance. Convert crystal tolerance in ppm to absolute frequency error in Hz. Stacks initial tolerance, temperature stability, and aging into worst-case and RSS budgets, with clock drift in seconds per day.

Inputs

Send every one of these in inputs, in the units shown. Most are required: a call without one is refused (400) and costs nothing; one the calculator can do without takes the default shown. An input outside its range is still computed and flagged in the provenance.

Inputs of frequency-ppm-tolerance
Name	Unit	Range	Default	Description
nominalFrequencynumber	MHz	0.000001 … 1000	25	Marked frequency of the crystal or oscillator.
initialTolerancenumber	ppm	0 … 1000	20	Calibration accuracy at room temperature, from the datasheet.
tempStabilitynumber	ppm	0 … 1000	15	Frequency deviation over the full operating temperature range.
agingPerYearnumber	ppm/yr	0 … 100	3	Long-term drift per year. AT-cut crystals are typically 1–5 ppm in year one.
yearsnumber	years	0 … 30	3	How long the aging term is accumulated for.

Outputs

Returned in values, by key. A value that is unbounded or undefined is null.

Outputs of frequency-ppm-tolerance
Field	Unit	Description
totalPpmWorstheadline	ppm	Total Error (worst case)
totalPpmRss	ppm	Total Error (RSS)
agingTotalPpm	ppm	Accumulated Aging
deviationHz	Hz	Frequency Deviation
fMinHz	Hz	Minimum Frequency
fMaxHz	Hz	Maximum Frequency
spanHz	Hz	Total Frequency Span
driftSecPerDay	s/day	Clock Drift
driftMinPerYear	min/year	Clock Drift

Calling it

Calculate: one call, the request and response in full, and its errors.
Batch: this calculator with others, or a sweep, in one request.
Solve for a target: the value of one input that brings an output to a target.

curl -X POST https://rftools.io/api/py/v1/calculate \
  -H "X-API-Key: $RFTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "frequency-ppm-tolerance",
    "inputs": {
      "nominalFrequency": 25,
      "initialTolerance": 20,
      "tempStability": 15,
      "agingPerYear": 3,
      "years": 3
    }
  }'

import rftools

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

result = client.calculate("frequency-ppm-tolerance", {
    "nominalFrequency": 25,
    "initialTolerance": 20,
    "tempStability": 15,
    "agingPerYear": 3,
    "years": 3,
})
print(result.values)
print(result.warnings, result.provenance.formula_ref)

const response = await fetch("https://rftools.io/api/py/v1/calculate", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.RFTOOLS_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "slug": "frequency-ppm-tolerance",
    "inputs": {
      "nominalFrequency": 25,
      "initialTolerance": 20,
      "tempStability": 15,
      "agingPerYear": 3,
      "years": 3
    }
  }),
});
console.log(response.status, await response.json());

package main

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

func main() {
	body := []byte(`{
	  "slug": "frequency-ppm-tolerance",
	  "inputs": {
	    "nominalFrequency": 25,
	    "initialTolerance": 20,
	    "tempStability": 15,
	    "agingPerYear": 3,
	    "years": 3
	  }
	}`)
	req, err := http.NewRequest("POST", "https://rftools.io/api/py/v1/calculate", 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": "frequency-ppm-tolerance",
  "values": {
    "totalPpmWorst": 44,
    "totalPpmRss": 26.570660511172846,
    "agingTotalPpm": 9,
    "deviationHz": 1100,
    "fMinHz": 24998900,
    "fMaxHz": 25001100,
    "spanHz": 2200,
    "driftSecPerDay": 3.8016,
    "driftMinPerYear": 23.1264
  },
  "warnings": [],
  "errors": [],
  "provenance": {
    "method": "calculator:frequency-ppm-tolerance",
    "version": "api@3f2c1a9b04de",
    "formulaRef": "IEEE 177 quartz resonator definitions; typical AT-cut crystal datasheet parameters",
    "assumptions": [],
    "validRange": {
      "status": "inside",
      "bounds": {
        "nominalFrequency": {
          "min": 0.000001,
          "max": 1000,
          "unit": "MHz"
        },
        "initialTolerance": {
          "min": 0,
          "max": 1000,
          "unit": "ppm"
        },
        "tempStability": {
          "min": 0,
          "max": 1000,
          "unit": "ppm"
        },
        "agingPerYear": {
          "min": 0,
          "max": 100,
          "unit": "ppm/yr"
        },
        "years": {
          "min": 0,
          "max": 30,
          "unit": "years"
        }
      },
      "outside": [],
      "model": null
    },
    "computedAt": "2026-09-24T14:05:11.003Z",
    "inputs": {
      "nominalFrequency": 25,
      "initialTolerance": 20,
      "tempStability": 15,
      "agingPerYear": 3,
      "years": 3
    },
    "seed": null,
    "elapsedSeconds": 0.003
  }
}

{
  "detail": [
    {
      "type": "float_parsing",
      "loc": [
        "body",
        "inputs",
        "nominalFrequency"
      ],
      "msg": "Input should be a valid number, unable to parse string as a number",
      "input": "abc"
    }
  ]
}

An input sent as text. Nothing was counted.

{
  "detail": "More than 120 requests in 60 seconds from this address.",
  "errorKind": "rate_limited",
  "limit": 120,
  "windowSeconds": 60,
  "upgradeUrl": "https://rftools.io/pricing/"
}

Too many requests in a minute, with Retry-After.

Same inputs on the calculator pageCrystal PPM Tolerance & Frequency Error Calculator, at these values