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


# EvaluateOptions

Options for [`Project#evaluate`](<https://docs.dhtmlx.com/planning-engine/java/api/project-evaluate.md>) and [`Project#evaluateWith`](<https://docs.dhtmlx.com/planning-engine/java/api/project-evaluate.md#evaluatewith>). They set the baseline the call expects, whether each candidate also gets a leveled stage, which tasks get per-task finish and overload figures, and whether candidates are scored against a cleared copy of the baseline. `new EvaluateOptions()` scores the scheduled stage only, with no focus tasks.

## Declaration

```java
public class EvaluateOptions extends ValueRecord implements DeepCloneable<EvaluateOptions>
```

Set fields with the fluent `withX` setters: `new EvaluateOptions().withLevel(new LevelingOptions())`.

## Constructors

### EvaluateOptions()

```java
public EvaluateOptions()
```

Creates options with every field at its default.

## Fields

| Field | Type | Default | Description |
|---|---|---|---|
| `baselineId` | `String` | `null` | The baseline the call expects. `null` skips the check. |
| `level` | [`LevelingOptions`](<https://docs.dhtmlx.com/planning-engine/java/api/resources/leveling-options.md>) | `null` | Adds a leveled stage to each candidate. `null` scores the scheduled stage only. |
| `focus` | [`Vec`](<https://docs.dhtmlx.com/planning-engine/java/api/support/vec.md>)`<`[`Id`](<https://docs.dhtmlx.com/planning-engine/java/api/data/id.md>)`>` | empty | Tasks to report finish and overload for. Must not be `null`. |
| `clearFirst` | `boolean` | `false` | Scores against a copy of the baseline with leveling delays and pauses cleared. |

### baselineId

```java
public String baselineId = null;
```

A baseline token taken from the latest [`ScheduleResult.baselineId`](<https://docs.dhtmlx.com/planning-engine/java/api/results/schedule-result.md#baselineid>). When it isn't `null` and doesn't name the project's current baseline, `Project#evaluate` throws a [`ProjectException`](<https://docs.dhtmlx.com/planning-engine/java/api/errors/project-exception.md>) with code `STALE_BASELINE`.

Each candidate's [`SchedulingChanges.baselineId`](<https://docs.dhtmlx.com/planning-engine/java/api/changes/scheduling-changes.md#baselineid>) is checked the same way, independently of this field.

### level

```java
public LevelingOptions level = null;
```

When set, every candidate is leveled with these options after it's solved, and [`CandidateResult.leveled`](<https://docs.dhtmlx.com/planning-engine/java/api/evaluate/candidate-result.md>) holds the [`LeveledMetrics`](<https://docs.dhtmlx.com/planning-engine/java/api/evaluate/leveled-metrics.md>) of that stage. The options are used unchanged, so `level.clearFirst` (default `true`) applies. When `null`, `CandidateResult.leveled` is always `null`.

`level.basis`, when given, is the bucket basis for every overload figure in the result, baseline included. Without it, the basis is derived from the project.

Options that are invalid for the baseline make `Project#evaluate` throw an [`InputException`](<https://docs.dhtmlx.com/planning-engine/java/api/errors/input-exception.md>). To commit a scored candidate with [`Project#level`](<https://docs.dhtmlx.com/planning-engine/java/api/project-level.md>), pass the same `LevelingOptions`, `step` included, so the committed plan matches the scored one.

### focus

```java
public Vec<Id> focus = new Vec<Id>();
```

Task ids that get per-task figures in every [`Metrics`](<https://docs.dhtmlx.com/planning-engine/java/api/evaluate/metrics.md>) value of the result: one [`TaskFinish`](<https://docs.dhtmlx.com/planning-engine/java/api/evaluate/metrics.md#taskfinish>) entry in `finish.tasks` and one [`FocusOverload`](<https://docs.dhtmlx.com/planning-engine/java/api/evaluate/overload.md#focusoverload>) entry in `overload.focus` per id, in this order. An empty list adds no per-task figures.

Every id must name a task in the baseline. An unknown id makes `Project#evaluate` throw an [`InputException`](<https://docs.dhtmlx.com/planning-engine/java/api/errors/input-exception.md>) with path `focus[i]`. A focus task that a candidate removes reports `null` for its finish and focus overload in that candidate's metrics.

### clearFirst

```java
public boolean clearFirst = false;
```

When `true`, the reference state is a copy of the baseline with `levelingDelay` and `pauses` cleared on the tasks in scope, then solved. The scope is `level.scope.tasks` when `level` gives it, otherwise every task, also when `level` is `null`. [`EvaluateResult.baseline`](<https://docs.dhtmlx.com/planning-engine/java/api/evaluate/evaluate-result.md#baseline>) and every candidate are measured on that copy.

- `clearFirst` is independent of `level.clearFirst`, so it also applies when only the scheduled stage is scored.
- `baselineId`, candidate tokens, `level` and `focus` are checked against the accepted baseline before anything is cleared. A valid candidate `baselineId` is dropped before that candidate's changes are applied to the copy.
- [`EvaluateResult.baselineId`](<https://docs.dhtmlx.com/planning-engine/java/api/evaluate/evaluate-result.md#baselineid>) stays the accepted baseline's id.
- When nothing in scope has a delay or pause to clear, the result is identical to `clearFirst = false`.

## Methods

### withBaselineId, withLevel, withFocus, withClearFirst

```java
public EvaluateOptions withBaselineId(String value)
public EvaluateOptions withLevel(LevelingOptions value)
public EvaluateOptions withFocus(Vec<Id> value)
public EvaluateOptions withFocus(Collection<? extends Id> value)
public EvaluateOptions withClearFirst(boolean value)
```

Each setter assigns its field and returns this instance for chaining. The `Collection` overload of `withFocus` copies the ids into a new `Vec`, so `List.of(...)` works. Passing `null` to either `withFocus` overload sets `focus` to `null`, which `Project#evaluate` rejects with a `NullPointerException`.

**Returns** - this `EvaluateOptions`.

### deepClone

```java
public EvaluateOptions deepClone()
```

Returns a copy that shares no nested object (`level`, the `focus` list) with this instance.

**Returns** - a new `EvaluateOptions` with the same values.

### copy

```java
public EvaluateOptions copy()
```

Returns a shallow copy. The copy shares the `level` object and the `focus` list with this instance.

**Returns** - a new `EvaluateOptions` with the same field values.

### 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 `EvaluateOptions` are equal when their public fields are equal, nested records compared by value. `toString()` lists the fields.

## Example

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

public class EvaluateOptionsExample {
  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.str("A")).withStartDate(monday).withDuration(2.0),
            new TaskData(Id.str("B")).withStartDate(monday).withDuration(2.0)))
        .withResources(List.of(
            new ResourceData().withId(Id.str("dev1")),
            new ResourceData().withId(Id.str("dev2"))))
        .withAssignments(List.of(
            new AssignmentData().withId(Id.str("aA")).withTask(Id.str("A"))
                .withResource(Id.str("dev1")).withValue(1.0),
            new AssignmentData().withId(Id.str("aB")).withTask(Id.str("B"))
                .withResource(Id.str("dev1")).withValue(1.0)));

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

    SchedulingChanges toDev2 = new SchedulingChanges();
    toDev2.assignments.update.add(
        new AssignmentUpdate(Id.str("aB")).withResource(Patch.of(Id.str("dev2"))));

    EvaluateOptions options = new EvaluateOptions()
        .withBaselineId(solved.baselineId)
        .withLevel(new LevelingOptions())
        .withFocus(List.of(Id.str("B")));

    EvaluateResult result = project.evaluate(
        List.of(
            new Candidate().withId(Id.str("stay")).withChanges(new SchedulingChanges()),
            new Candidate().withId(Id.str("dev2")).withChanges(toDev2)),
        options);

    for (CandidateResult candidate : result.candidates) {
      if (candidate.leveled == null) continue;
      TaskFinish finishB = candidate.leveled.metrics.finish.tasks.get(0);
      System.out.println(candidate.id + ": B finishes " + finishB.finish.date
          + ", leveled cost " + candidate.cost);
    }
  }
}
```

## Related

- [`Project#evaluate`](<https://docs.dhtmlx.com/planning-engine/java/api/project-evaluate.md>) - the call these options configure
- [`LevelingOptions`](<https://docs.dhtmlx.com/planning-engine/java/api/resources/leveling-options.md>) - the options of the leveled stage
- [`EvaluateResult`](<https://docs.dhtmlx.com/planning-engine/java/api/evaluate/evaluate-result.md>) - the result the options shape
- [`ProjectException`](<https://docs.dhtmlx.com/planning-engine/java/api/errors/project-exception.md>) - thrown with `STALE_BASELINE` for an outdated `baselineId`
- [Evaluating alternatives](<https://docs.dhtmlx.com/planning-engine/java/resources-and-assignment/evaluating-alternatives.md#options>) - choosing focus tasks and a leveled stage