# Evaluator

Responsible for computing cell values based on their formulas and dependencies.

Uses topological sorting for acyclic portions and iterative calculation for cycles.
Maintains integration with column search index for VLOOKUP/MATCH optimization.

## Evaluation Workflow

1. **Topological Sort with SCC Detection**
   - Sorts vertices (cells/ranges) by dependency order
   - Identifies Strongly Connected Components (SCCs) as cycles

2. **Pre-cycle Evaluation**
   - Computes all vertices that don't depend on cycles
   - These provide stable inputs for cycle resolution

3. **Cycle Resolution** (if cycles exist)
   - If iterative calculation disabled: sets #CYCLE! error on all cycle members
   - If enabled: iterates the cycle calculation until convergence or max iterations

4. **Post-cycle Evaluation**
   - Recomputes vertices that depend on cycle results
   - Uses subgraph traversal for efficiency

## Iterative Calculation Algorithm

When circular references exist and `enableIterativeCalculation` is true:

1. Initialize all cycle cells to `iterativeCalculationInitialValue`
2. Repeat up to `iterativeCalculationLimit` times:
   a. Clear caches for ranges containing cycle cells
   b. Store current values
   c. Recompute all cycle cells in address order (Gauss-Seidel style)
   d. Check convergence: |new - old| < `iterativeCalculationThreshold`
3. If all cells converge, stop early; otherwise continue to max iterations

## Entry Points

- `recomputeWholeGraph()`: Full evaluation from scratch (initial load or major changes)
- `recomputeSubgraph()`: Incremental evaluation starting from changed vertices
- `evaluateSingleFormula()`: One-off formula evaluation without side effects

## Constructors

### constructor 

\+ **new Evaluator**(`config`: [Config](config.md), `stats`: [Statistics](statistics.md), `interpreter`: Interpreter, `lazilyTransformingAstService`: [LazilyTransformingAstService](lazilytransformingastservice.md), `dependencyGraph`: DependencyGraph, `columnSearch`: [ColumnSearchStrategy](../interfaces/columnsearchstrategy.md)): *[Evaluator](evaluator.md)*

*Defined in [src/Evaluator.ts:64](https://github.com/handsontable/hyperformula/blob/5a8cb26/src/Evaluator.ts#L64)*

**Parameters:**

Name | Type | Description |
------ | ------ | ------ |
`config` | [Config](config.md) | Configuration including iterative calculation settings |
`stats` | [Statistics](statistics.md) | Statistics collector for performance measurement |
`interpreter` | Interpreter | AST interpreter for formula evaluation |
`lazilyTransformingAstService` | [LazilyTransformingAstService](lazilytransformingastservice.md) | Service for lazy AST transformations (address updates) |
`dependencyGraph` | DependencyGraph | Graph of cell/range dependencies |
`columnSearch` | [ColumnSearchStrategy](../interfaces/columnsearchstrategy.md) | Search index for efficient column lookups  |

**Returns:** *[Evaluator](evaluator.md)*

## Properties

### interpreter

• **interpreter**: *Interpreter*

*Defined in [src/Evaluator.ts:76](https://github.com/handsontable/hyperformula/blob/5a8cb26/src/Evaluator.ts#L76)*

AST interpreter for formula evaluation

## Methods

### evaluateSingleFormula 

▸ **evaluateSingleFormula**(`ast`: Ast, `address`: [SimpleCellAddress](../interfaces/simplecelladdress.md), `dependencies`: RelativeDependency[]): *InterpreterValue*

*Defined in [src/Evaluator.ts:172](https://github.com/handsontable/hyperformula/blob/5a8cb26/src/Evaluator.ts#L172)*

Evaluates a formula without persisting the result or modifying the graph.

Used for one-off calculations like conditional formatting or data validation.
Temporarily creates range vertices if needed, then cleans them up.

**Parameters:**

Name | Type | Description |
------ | ------ | ------ |
`ast` | Ast | Parsed formula AST to evaluate |
`address` | [SimpleCellAddress](../interfaces/simplecelladdress.md) | Cell address context for relative references |
`dependencies` | RelativeDependency[] | Relative dependencies extracted from the formula |

**Returns:** *InterpreterValue*

Computed value (number, string, boolean, error, or array)

___

### recomputeSubgraph 

▸ **recomputeSubgraph**(`changedVertices`: Vertex[]): *[ContentChanges](contentchanges.md)*

*Defined in [src/Evaluator.ts:118](https://github.com/handsontable/hyperformula/blob/5a8cb26/src/Evaluator.ts#L118)*

Performs incremental evaluation starting from a set of changed vertices.

More efficient than `recomputeWholeGraph()` when only a subset of cells have changed.
Traverses only the subgraph reachable from the changed vertices.

Algorithm:
1. Traverse subgraph from starting vertices in topological order
2. Collect any cycles encountered during traversal
3. Mark vertices that depend on cycles for deferred processing
4. Process cycles via iterative calculation
5. Cycle dependents are handled inside iterateCircularDependencies

**Parameters:**

Name | Type | Description |
------ | ------ | ------ |
`changedVertices` | Vertex[] | Starting vertices (typically cells that were directly modified) |

**Returns:** *[ContentChanges](contentchanges.md)*

Content changes describing all value updates

___

### recomputeWholeGraph 

▸ **recomputeWholeGraph**(): *void*

*Defined in [src/Evaluator.ts:92](https://github.com/handsontable/hyperformula/blob/5a8cb26/src/Evaluator.ts#L92)*

Performs full evaluation of all formulas in the dependency graph.

Used for initial spreadsheet load or when dependencies have changed significantly.
Performs topological sort to determine evaluation order and handles any cycles.

Complexity: O(V + E) for topological sort + O(I × C) for cycles where
V=vertices, E=edges, I=iterations, C=cycle size

**Returns:** *void*