# Linear residual check

`linear-residual-check` · version 1.0.0 · Numbers & math · free, no key needed

Check a claimed residual r = b - A x (per component and/or its max norm) exactly for an approximate solution x.

**Use when you need to: check the residual of an approximate solution exactly · verify b minus A x for a numerical solution · is my residual max norm below the tolerance.**

## Decide before calling

Read the [versioned contract](/v1/tools/linear-residual-check/versions/1.0.0) and the supported scope below. Reuse `linear-residual-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 `linear-residual-check@1.0.0` for check the residual of an approximate solution exactly. 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 the residual of an approximate solution exactly
- verify b minus A x for a numerical solution
- is my residual max norm below the tolerance
- exact residual vector of a float solver result
- validate claimed residuals component by component
- compute and compare residual infinity norm
- בדיקת שארית של פתרון מקורב

## Not supported

- the A x - b sign convention (the residual is b - A x)
- 2-norms, condition numbers or backward error bounds
- inexact or tolerance-based comparison of the claimed residual
- JSON floating-point numbers (pass decimals as strings)

## Behavior

- Exact rationals are strings: an integer, a fraction p/q with q >= 1 or a finite decimal; JSON numbers, exponents, NaN and Infinity are rejected; outputs are canonical (reduced p/q, or an integer).
- matrix is m x n (1-64 each) with equal row lengths; rhs and claimed_residual have m entries and solution n entries; dimensions are checked before any dot product.
- The residual is r = b - A x: r_i = b_i - sum_j a_ij x_j, exact. inf_norm = max_i |r_i| is always returned.
- At least one of claimed_residual and claimed_inf_norm (nonnegative) must be given; an omitted claim is not checked.
- Check order: claimed_residual components in row order (residual_mismatch), then claimed_inf_norm (inf_norm_mismatch); first_discrepancy gives check, index (null for the norm), claimed and the exact actual value.

## Input

- `matrix` (array of array of string, required): min items 1; max items 64; each min items 1; each max items 64; each each min length 1; each each max length 64; each each pattern `^-?(0|[1-9][0-9]*)(/[1-9][0-9]*|\.[0-9]+)?$`
- `rhs` (array of string, required): min items 1; max items 64; each min length 1; each max length 64; each pattern `^-?(0|[1-9][0-9]*)(/[1-9][0-9]*|\.[0-9]+)?$`
- `solution` (array of string, required): min items 1; max items 64; each min length 1; each max length 64; each pattern `^-?(0|[1-9][0-9]*)(/[1-9][0-9]*|\.[0-9]+)?$`
- `claimed_residual` (array of string, optional): min items 1; max items 64; each min length 1; each max length 64; each pattern `^-?(0|[1-9][0-9]*)(/[1-9][0-9]*|\.[0-9]+)?$`
- `claimed_inf_norm` (string, optional): min length 1; max length 64; pattern `^-?(0|[1-9][0-9]*)(/[1-9][0-9]*|\.[0-9]+)?$`

## Output

- `valid` (boolean, required)
- `reason` (one of "residual_mismatch", "inf_norm_mismatch", null, required)
- `first_discrepancy` (object or null, required)
- `inf_norm` (string, required): pattern `^-?(0|[1-9][0-9]*)(/[1-9][0-9]*)?$`
- `reference_version` (constant "r49-linear-residual-1.0.0 (residual r = b - A x, Higham 2002; NIST DLMF section 1.2(v), equation 1.2.34; exact rational arithmetic)", required)

## Limits

- max rows: 64
- max columns: 64
- max number chars: 64

## Example

Request input:

```json
{
  "matrix": [
    [
      "1",
      "2"
    ],
    [
      "3",
      "4"
    ]
  ],
  "rhs": [
    "5",
    "6"
  ],
  "solution": [
    "-3.9999999",
    "4.49999995"
  ],
  "claimed_residual": [
    "0",
    "-0.0000001"
  ],
  "claimed_inf_norm": "1/10000000"
}
```

Response:

```json
{
  "result": {
    "valid": true,
    "reason": null,
    "first_discrepancy": null,
    "inf_norm": "1/10000000",
    "reference_version": "r49-linear-residual-1.0.0 (residual r = b - A x, Higham 2002; NIST DLMF section 1.2(v), equation 1.2.34; exact rational arithmetic)"
  }
}
```

## How to call it

### MCP

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

```json
{
  "id": "linear-residual-check",
  "version": "1.0.0",
  "input": {
    "matrix": [
      [
        "1",
        "2"
      ],
      [
        "3",
        "4"
      ]
    ],
    "rhs": [
      "5",
      "6"
    ],
    "solution": [
      "-3.9999999",
      "4.49999995"
    ],
    "claimed_residual": [
      "0",
      "-0.0000001"
    ],
    "claimed_inf_norm": "1/10000000"
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/linear-residual-check/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"matrix":[["1","2"],["3","4"]],"rhs":["5","6"],"solution":["-3.9999999","4.49999995"],"claimed_residual":["0","-0.0000001"],"claimed_inf_norm":"1/10000000"}'
```

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

### CLI

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

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

## Related tools

- [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.
- [Lp primal feasibility check](/tools/lp-primal-feasibility-check): Check that a claimed LP point satisfies x >= 0 and Ax <= b exactly; report the first violated bound or row.
- [Linear solution check](/tools/linear-solution-check): Check that a proposed solution x satisfies A x = b exactly over the rationals and report the first row that fails.
- [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 residuals check](/tools/regression-residuals-check): Check claimed residuals and SSE for given regression coefficients and exact samples; reports the first wrong residual.
- [Linear inconsistency certificate check](/tools/linear-inconsistency-certificate-check): Check a witness y that A x = b has no solution (yA = 0, yb != 0) or no x >= 0 solution (Farkas: yA >= 0, yb < 0).