---
title: "Iterative Calculations in Pigment"
slug: "iterative-calculations-in-pigment"
description: "Learn how to handle iterative calculations in Pigment without causing circular dependency errors. This section explains how Pigment evaluates formulas, how to identify and debug circular references, and when to use PREVIOUS and PREVIOUSOF functions to safely model time-based and dependent calculations."
updated: 2025-12-02T16:13:49Z
published: 2025-12-02T16:13:49Z
canonical: "kb.pigment.com/iterative-calculations-in-pigment"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://kb.pigment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Iterative Calculations in Pigment

A common modeling need when building a Pigment Application is to have a formula iterate over all the Items in a Dimension, using a calculation from one Item to calculate the next. This section sets out the tools available in Pigment to handle iterative calculations, while detailing which formulations may lead to errors.

## Before you begin

### About circular dependencies

The formula below is an example of a circular dependency within a single Block:

`'Metric A' = 'Metric A'[SELECT: Month - 1] + 1`

It attempts to increase Metric A by one, month-on-month, but would result in an error message, as Metric A cannot reference itself in the formula.

The Pigment modeling engine computes formulas in sequence. Each time a formula in a Block is created or edited, all of the Blocks using the original Block in their formulas are automatically recalculated. Creating a circular dependency could lead to an infinite loop of calculations.

For that reason, each time a formula is created or edited, the Pigment engine checks if the new formula would create a circular dependency, flagging errors such as the below when circular referencing cannot be resolved:

![](https://cdn.document360.io/e47cfe35-dc28-40c7-a083-6cf003073d8e/Images/Documentation/image(218).png)

![](https://cdn.document360.io/e47cfe35-dc28-40c7-a083-6cf003073d8e/Images/Documentation/image(217).png)

![](https://cdn.document360.io/e47cfe35-dc28-40c7-a083-6cf003073d8e/Images/Documentation/image(216).png)

## Debug circular dependency errors

When an error occurs, Pigment lists the Metrics involved in the circular dependency, helping you trace the issue. To debug, first check that your formulas do not have a circular dependency at cell-level, for example:

`'Metric A' = 'Metric A' + 1`

Pigment does not support these types of circular reference, and it will always fail because the Metric is asking for its own value.

If you need a Metric to “build on itself” over time (for example, month-over-month growth), use the [function for iterative calculations](/v1/docs/troubleshoot-circular-dependencies#functions-for-models-requiring-circular-reference) for single Blocks instead of direct self-reference.

Circular dependencies can also occur between Metrics. Pigment allows these only through the iterative calculation feature (see [Iterative Calculations across multiple Blocks using PREVIOUSOF](/v1/docs/iterative-calculations-using-previousof)). In this setup, formulas can safely reference each other as long as:

- They are all included in the configuration, and
- They do not make cell-level self-references.

If you see an error in this case, check that **all listed Metrics** are properly included in the configuration.

## Functions for models requiring a circular reference

If a model requires a circular reference, Pigment offers two functions that unblock this capability. Find guidance in the articles provided.

|  | Description | Solution | Article |
| --- | --- | --- | --- |
| **Single-Block** | The Metrics containing circular-referencing formulas exist within one Block | `PREVIOUS()` | [Iterative calculations within a Block using PREVIOUS](/v1/docs/iterative-calculations-using-previous) |
| **Multiple-Block** | The Metrics containing circular-referencing formulas exist within different Blocks | `PREVIOUSOF()` | [Iterative Calculations across multiple Blocks using PREVIOUSOF](/v1/docs/iterative-calculations-using-previousof) |