# Unit factor check

`unit-factor-check` · version 1.0.0 · Numbers & math · free, no key needed

Check a claimed conversion factor and offset between two unit expressions using caller-defined exact unit definitions

**Use when you need to: check unit conversion factor · verify conversion formula between units · is this unit factor correct.**

## Decide before calling

Read the [versioned contract](/v1/tools/unit-factor-check/versions/1.0.0) and the supported scope below. Reuse `unit-factor-check@1.0.0` when your input, required output and limits match it. Choose another approach for an unsupported operation.

## Explain the choice

"I can use `unit-factor-check@1.0.0` for check unit conversion factor. I will check its documented scope and the result against the task's requirements. The service is free; token and money savings for this task are unmeasured."

## Supported

- check unit conversion factor
- verify conversion formula between units
- is this unit factor correct
- check affine temperature conversion formula
- validate compound unit conversion factor
- exact conversion factor checker
- check offset and scale between units

## Not supported

- a built-in unit catalog (every unit is defined by the caller)
- logarithmic units such as dB or pH
- irrational factors such as degree to radian (pi)
- currency or other time-varying rates

## Behavior

- units: caller-defined catalog {symbol, dimension (7 integers L, M, T, I, Theta, N, J), factor > 0, offset}, meaning value_SI = value x factor + offset; symbols are compared code unit for code unit. Numbers are exact strings: integer, decimal or p/q, at most 60 characters, no exponent.
- Claim: v_to = v_from x claimed_factor + claimed_offset. Check order: unknown units in from_unit then to_unit (term order), affine misuse in from_unit then to_unit, dimensions (dimension_mismatch with the 7-integer vectors), factor = F(from) / F(to) (factor_mismatch), offset = (O(from) - O(to)) / F(to) (offset_mismatch).
- quantity_kind "absolute": an affine unit (non-zero offset) must be the only term, power 1, else invalid_affine_composition; "interval": offsets are ignored, the offset is always 0 and affine units compose freely (temperature differences, gradients).
- Claims are compared by exact value (3600, 3600.0 and 7200/2 are equal). factor and offset are output in canonical exact form (plain decimal when terminating, else reduced p/q) whenever the units are compatible, otherwise null.
- Structural problems throw invalid_input; more than 200 units, 8 terms, |power| 6, 32-byte symbols, 60-character numbers or a 4000-digit exact intermediate throws limit_exceeded.
- Reference: JCGM 200:2012 (VIM) 1.24 and SI Brochure 9th ed. (2019) 2.3.3-2.3.4; reference_version "jcgm-200-2012-vim3-si-brochure-9e-2019".

## Input

- `units` (array of object, required): min items 1; max items 200
- `quantity_kind` (one of "absolute", "interval", required)
- `from_unit` (array of object, required): max items 8
- `to_unit` (array of object, required): max items 8
- `claimed_factor` (string, required): min length 1; max length 60; pattern `^-?(0|[1-9][0-9]*)(\.[0-9]+|/[1-9][0-9]*)?$`
- `claimed_offset` (string, required): min length 1; max length 60; pattern `^-?(0|[1-9][0-9]*)(\.[0-9]+|/[1-9][0-9]*)?$`

## Output

- `valid` (boolean, required)
- `reason` (one of null, "unknown_unit", "invalid_affine_composition", "dimension_mismatch", "factor_mismatch", "offset_mismatch", required)
- `first_discrepancy` (object or null, required)
- `factor` (string or null, required)
- `offset` (string or null, required)
- `reference_version` (constant "jcgm-200-2012-vim3-si-brochure-9e-2019", required)

## Limits

- max units: 200
- max symbol bytes: 32
- max terms: 8
- max abs power: 6
- max number chars: 60
- max exact digits: 4000

## Example

Request input:

```json
{
  "units": [
    {
      "symbol": "m",
      "dimension": [
        1,
        0,
        0,
        0,
        0,
        0,
        0
      ],
      "factor": "1",
      "offset": "0"
    },
    {
      "symbol": "km",
      "dimension": [
        1,
        0,
        0,
        0,
        0,
        0,
        0
      ],
      "factor": "1000",
      "offset": "0"
    },
    {
      "symbol": "s",
      "dimension": [
        0,
        0,
        1,
        0,
        0,
        0,
        0
      ],
      "factor": "1",
      "offset": "0"
    },
    {
      "symbol": "h",
      "dimension": [
        0,
        0,
        1,
        0,
        0,
        0,
        0
      ],
      "factor": "3600",
      "offset": "0"
    }
  ],
  "quantity_kind": "absolute",
  "from_unit": [
    {
      "unit": "km",
      "power": 1
    },
    {
      "unit": "h",
      "power": -1
    }
  ],
  "to_unit": [
    {
      "unit": "m",
      "power": 1
    },
    {
      "unit": "s",
      "power": -1
    }
  ],
  "claimed_factor": "5/18",
  "claimed_offset": "0"
}
```

Response:

```json
{
  "result": {
    "valid": true,
    "reason": null,
    "first_discrepancy": null,
    "factor": "5/18",
    "offset": "0",
    "reference_version": "jcgm-200-2012-vim3-si-brochure-9e-2019"
  }
}
```

## How to call it

### MCP

Connect `https://computefirst.net/mcp` ([setup](/docs#connect)), then call `execute` with:

```json
{
  "id": "unit-factor-check",
  "version": "1.0.0",
  "input": {
    "units": [
      {
        "symbol": "m",
        "dimension": [
          1,
          0,
          0,
          0,
          0,
          0,
          0
        ],
        "factor": "1",
        "offset": "0"
      },
      {
        "symbol": "km",
        "dimension": [
          1,
          0,
          0,
          0,
          0,
          0,
          0
        ],
        "factor": "1000",
        "offset": "0"
      },
      {
        "symbol": "s",
        "dimension": [
          0,
          0,
          1,
          0,
          0,
          0,
          0
        ],
        "factor": "1",
        "offset": "0"
      },
      {
        "symbol": "h",
        "dimension": [
          0,
          0,
          1,
          0,
          0,
          0,
          0
        ],
        "factor": "3600",
        "offset": "0"
      }
    ],
    "quantity_kind": "absolute",
    "from_unit": [
      {
        "unit": "km",
        "power": 1
      },
      {
        "unit": "h",
        "power": -1
      }
    ],
    "to_unit": [
      {
        "unit": "m",
        "power": 1
      },
      {
        "unit": "s",
        "power": -1
      }
    ],
    "claimed_factor": "5/18",
    "claimed_offset": "0"
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/unit-factor-check/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"units":[{"symbol":"m","dimension":[1,0,0,0,0,0,0],"factor":"1","offset":"0"},{"symbol":"km","dimension":[1,0,0,0,0,0,0],"factor":"1000","offset":"0"},{"symbol":"s","dimension":[0,0,1,0,0,0,0],"factor":"1","offset":"0"},{"symbol":"h","dimension":[0,0,1,0,0,0,0],"factor":"3600","offset":"0"}],"quantity_kind":"absolute","from_unit":[{"unit":"km","power":1},{"unit":"h","power":-1}],"to_unit":[{"unit":"m","power":1},{"unit":"s","power":-1}],"claimed_factor":"5/18","claimed_offset":"0"}'
```

The machine-readable contract is at [/v1/tools/unit-factor-check/versions/1.0.0](/v1/tools/unit-factor-check/versions/1.0.0).

### CLI

```sh
node cli.mjs run unit-factor-check 1.0.0 --input input.json --base-url https://computefirst.net
```

Get the client at [/clients/cli/](/clients/cli/).

## Related tools

- [Unit result check](/tools/unit-result-check): Check a claimed converted value exactly or under declared rounding; returns the exact value and the claim error
- [Lp optimality certificate check](/tools/lp-optimality-certificate-check): Check an LP optimum claim from a primal x and dual y: feasibility, complementary slackness and zero duality gap.
- [Polynomial division check](/tools/polynomial-division-check): Check a claimed polynomial division A = BQ + R over exact rationals: remainder degree, quotient degree, coefficients.
- [Polynomial factorization check](/tools/polynomial-factorization-check): Check a claimed factorization c * prod f_i^e_i of a rational polynomial: monic distinct factors, degrees, coefficients.
- [Rational expression check](/tools/rational-expression-check): Check a claimed exact rational value of an integer/fraction expression; reports the true value and the difference.
- [Regression coefficients check](/tools/regression-coefficients-check): Check claimed least-squares regression coefficients against exact samples; reports rank and the first mismatch.