[Canonical page](<https://docs.dhtmlx.com/planning-engine/java/api/evaluate/leveled-metrics/>)
[Full documentation index](<https://docs.dhtmlx.com/planning-engine/llms.txt>)


# LeveledMetrics

Metrics of a leveled stage, plus a summary of the leveling run. It's found in [`CandidateResult.leveled`](<https://docs.dhtmlx.com/planning-engine/java/api/evaluate/candidate-result.md>) and [`SuggestProposal.leveled`](<https://docs.dhtmlx.com/planning-engine/java/api/suggest/suggest-result.md#suggestproposal>), and only when the call's options set `level`. It's `null` when the scheduled stage is cyclic, because then there's no leveled stage.

## Declaration

```java
package org.dhtmlx.plen;

public class LeveledMetrics extends ValueRecord implements DeepCloneable<LeveledMetrics>
```

## Constructors

### LeveledMetrics()

```java
public LeveledMetrics()
```

Creates an instance with `metrics = null`, `converged = false`, `rounds = 0` and `windows = 0`. `Project#evaluate` and `Project#suggestAssignments` build these values; creating one by hand is mainly useful in tests.

## Fields

| Field | Type | Default | Description |
|---|---|---|---|
| `metrics` | [`Metrics`](<https://docs.dhtmlx.com/planning-engine/java/api/evaluate/metrics.md>) | `null` | Finish, overload, conflicts, cycles and cost of the leveled stage, against the baseline. |
| `converged` | `boolean` | `false` | `converged` of the leveled schedule. |
| `rounds` | `int` | `0` | Leveling rounds run. |
| `windows` | `int` | `0` | Overallocation windows left after leveling, for every reason. |

### metrics

```java
public Metrics metrics
```

The leveled stage, measured against the same baseline as the scheduled stage. `metrics.cost` is the stage's cost. A candidate's [`CandidateResult.cost`](<https://docs.dhtmlx.com/planning-engine/java/api/evaluate/candidate-result.md>) equals it whenever `leveled` is set.

### converged

```java
public boolean converged
```

[`ScheduleResult.converged`](<https://docs.dhtmlx.com/planning-engine/java/api/results/schedule-result.md#converged>) of the schedule the leveling run returned.

### rounds

```java
public int rounds
```

[`LevelingResult.rounds`](<https://docs.dhtmlx.com/planning-engine/java/api/resources/leveling-result.md#rounds>) of the leveling run.

### windows

```java
public int windows
```

The number of overallocation windows still left in the leveled schedule, summed over all resources, whatever the reason each one remained. `0` means leveling resolved every overallocation. The windows themselves aren't in the result. For what a window is, see [`ResourceOverallocation`](<https://docs.dhtmlx.com/planning-engine/java/api/resources/resource-overallocation.md>).

## Methods

### withMetrics, withConverged, withRounds, withWindows

```java
public LeveledMetrics withMetrics(Metrics value)
public LeveledMetrics withConverged(boolean value)
public LeveledMetrics withRounds(int value)
public LeveledMetrics withWindows(int value)
```

Each setter assigns its field and returns this instance.

**Returns**: this `LeveledMetrics`.

### deepClone

```java
public LeveledMetrics deepClone()
```

Returns a copy with a deep copy of `metrics`. No nested object is shared with the original.

**Returns**: a new `LeveledMetrics`.

**Errors**: `NullPointerException` when `metrics` is `null`.

### copy

```java
public LeveledMetrics copy()
```

Returns a shallow copy: the new instance holds the same `metrics` object.

**Returns**: a new `LeveledMetrics`.

### equals, hashCode, toString

```java
public boolean equals(Object other)
public int hashCode()
public String toString()
```

Inherited from [`ValueRecord`](<https://docs.dhtmlx.com/planning-engine/java/api/support/value-record.md>). Two instances are equal when `metrics` is equal and `converged`, `rounds` and `windows` match. `toString()` prints every field, for logging.

## Example

Score one candidate with leveling and read its leveled stage.

```java
import java.util.List;
import org.dhtmlx.plen.*;

public class LeveledMetricsExample {
  public static void main(String[] args) throws Exception {
    Moment monday = Moment.fromYmdHm(2026, 8, 10, 8, 0);
    ProjectData data = new ProjectData()
        .withTasks(List.of(
            new TaskData(Id.num(1)).withStartDate(monday).withDuration(2.0),
            new TaskData(Id.num(2)).withStartDate(monday).withDuration(2.0)))
        .withResources(List.of(new ResourceData().withId(Id.str("dev1"))))
        .withAssignments(List.of(new AssignmentData()
            .withId(Id.str("a1"))
            .withTask(Id.num(1))
            .withResource(Id.str("dev1"))
            .withValue(1.0)));

    Project project = new Project();
    project.solve(data, new SolveOptions());

    SchedulingChanges changes = new SchedulingChanges();
    changes.assignments.add.add(new AssignmentData()
        .withId(Id.str("a2"))
        .withTask(Id.num(2))
        .withResource(Id.str("dev1"))
        .withValue(1.0));

    EvaluateResult result = project.evaluate(
        List.of(new Candidate().withId(Id.str("dev1-on-2")).withChanges(changes)),
        new EvaluateOptions().withLevel(new LevelingOptions()));

    LeveledMetrics leveled = result.candidates.get(0).leveled;
    if (leveled != null) {
      System.out.println("cost: " + leveled.metrics.cost);
      System.out.println("rounds: " + leveled.rounds + ", windows left: " + leveled.windows);
    }
  }
}
```

## Related

- [`Metrics`](<https://docs.dhtmlx.com/planning-engine/java/api/evaluate/metrics.md>) - the type of `metrics`
- [`CandidateResult`](<https://docs.dhtmlx.com/planning-engine/java/api/evaluate/candidate-result.md>) - holds the leveled stage of a candidate
- [`LevelingOptions`](<https://docs.dhtmlx.com/planning-engine/java/api/resources/leveling-options.md>) - the options that turn the leveled stage on
- [`LevelingResult`](<https://docs.dhtmlx.com/planning-engine/java/api/resources/leveling-result.md>) - the result of a committed leveling run
- [Evaluating alternatives](<https://docs.dhtmlx.com/planning-engine/java/resources-and-assignment/evaluating-alternatives.md#metrics-and-cost>) - reading metrics and cost