# Iterative calculation

Iterative calculation allows circular references to converge over repeated evaluations, similar to Excel. This is useful for finance models where the result depends on its own output.

## Enable it

```ts
const state = useSpreadsheetState({
  iterativeCalculation: {
    enabled: true,
    maxIterations: 100,
    maxChange: 0.001,
  },
});
```

Notes:

* Defaults match Excel (100 iterations, 0.001 max change).
* When disabled, circular references return `#REF!`.
* When enabled, non-converging formulas return `#NUM!`.

## Supported modes

* **Single-threaded:** `useCalculation` runs iterative loops on the UI thread.
* **Worker mode:** `useCalculationWorker` delegates iterative groups to the worker.

## Example formulas to test

Converging loop:

```
// A1
0
// A1 (replace)
=(A1+10)/2
```

Expected: A1 converges to \~10.

Non-converging loop:

```
// A2
0
// A2 (replace)
=A2+1
```

Expected: A2 returns `#NUM!`.

## Testing

Unit tests for single-threaded iterative calculation:

```sh
yarn workspace @rowsncolumns/spreadsheet-state test -- use-calculation.spec.ts
```

Worker iterative tests:

```sh
yarn workspace @rowsncolumns/calculation-worker test
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.rowsncolumns.app/configuration/features/iterative-calculation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.