Scheduling a Project#

This guide covers how to run the scheduler. It explains when to use the one-shot schedule function and when to keep a Project. It also covers what the solve options change, how forward and backward planning place tasks, and what "converged" means in a result.

How scheduling works#

There are two entry points, and they run the same planner:

schedule(data, &options) takes a ProjectData snapshot, schedules it once and returns a ScheduleResult. Nothing is kept after the call. It's a shortcut for Project::default().solve(Some(data), &options).
Project::solve(data, &options) does the same work on a long-lived Project. The project keeps the scheduled dates as its accepted baseline, so later calls can edit, preview, level and evaluate against it.

Every solve follows the same steps. The engine imports the snapshot into its own normalized model and validates it. It builds the scheduling graph from links and summaries, checks for dependency cycles and resolves the scope (the whole project, or one branch with subtree). Then it runs the planner until the dates stop changing. The result lists only what moved.

A few rules shape what you get back:

Updates are sparse. result.updates holds one Mutation per task whose dates changed, with only the changed fields set. Write them back into your own model. To get every task's dates, set include_unchanged.
Problems are data, not errors. Conflicts, cycles, dropped input and non-convergence come back inside ScheduleResult. Err means invalid input (Error::Input) or a call that doesn't fit the project's state (Error::Project). See Error handling.
Some tasks never move. Tasks with auto_scheduling: false, unscheduled tasks and completed tasks (use_progress with progress == 1) stay where they are. That's how you lock work in place. There are no cancellation hooks.
Calls are synchronous and CPU-only. There's no I/O, clock or async runtime. In an async server, run large solves on a worker thread or in spawn_blocking.

One-shot scheduling#

Use schedule in batch jobs, request handlers and scripts that schedule a snapshot and throw it away.

use plen_core::{schedule, DateTime, LinkData, LinkType, ProjectData, SolveOptions, TaskData};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let monday = DateTime::from_ymd_hm(2026, 8, 10, 8, 0).ok_or("invalid date")?;

    let mut design = TaskData::new(1);
    design.start_date = Some(monday);
    design.duration = Some(2.0);

    let mut build = TaskData::new(2);
    build.start_date = Some(monday);
    build.duration = Some(3.0);

    let data = ProjectData {
        tasks: vec![design, build],
        links: vec![LinkData {
            id: 1.into(),
            source: 1.into(),
            target: 2.into(),
            link_type: LinkType::Fs,
            lag: 0.0,
            lag_unit: None,
        }],
        ..Default::default()
    };

    let result = schedule(data, &SolveOptions::default())?;
    for update in &result.updates {
        if let (Some(start), Some(end)) = (update.start_date, update.end_date) {
            println!("task {}: {start} .. {end}", update.id);
        }
    }
    Ok(())
}

Task 2 has to wait for task 1, so it's the only update: task 2: 2026-08-12 08:00 .. 2026-08-17 08:00. Task 1 is already where it belongs and isn't reported. The default "global" calendar works Mon-Fri, 08:00-12:00 and 13:00-17:00, which is why the dates skip the weekend.

schedule takes the data by value and returns a plain ScheduleResult, not an Arc. It fails only with Error::Input, when validation rejects the snapshot.

Solving a project#

Keep a Project when the plan lives on: an editor backend with one project per open document, or a service that applies edits over time.

use std::sync::Arc;
use plen_core::{
    DateTime, LinkData, LinkType, Patch, Project, ProjectData, ProjectOptions, SchedulingChanges,
    SolveOptions, TaskData, TaskUpdate,
};

fn task(id: i32, start: DateTime, duration: f64) -> TaskData {
    let mut task = TaskData::new(id);
    task.start_date = Some(start);
    task.duration = Some(duration);
    task
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let monday = DateTime::from_ymd_hm(2026, 8, 10, 8, 0).ok_or("invalid date")?;
    let data = ProjectData {
        tasks: vec![task(1, monday, 2.0), task(2, monday, 3.0)],
        links: vec![LinkData {
            id: 1.into(),
            source: 1.into(),
            target: 2.into(),
            link_type: LinkType::Fs,
            lag: 0.0,
            lag_unit: None,
        }],
        ..Default::default()
    };

    let mut project = Project::new(ProjectOptions::default());
    let options = SolveOptions::default();

    // Install the data, schedule it and accept the dates as the baseline.
    let loaded = project.solve(Some(data), &options)?;

    // Nothing changed since: the cached result comes back.
    let cached = project.solve(None, &options)?;
    assert!(Arc::ptr_eq(&loaded, &cached));

    // Edit, then reschedule.
    let mut changes = SchedulingChanges::default();
    let mut longer = TaskUpdate::new(1);
    longer.duration = Patch::Value(4.0);
    changes.tasks.update.push(longer);
    project.apply(&changes)?;

    let after = project.solve(None, &options)?;
    for update in &after.updates {
        if let (Some(start), Some(end)) = (update.start_date, update.end_date) {
            println!("task {}: {start} .. {end}", update.id);
        }
    }
    Ok(())
}

The two forms of solve do different jobs:

solve(Some(data), ..) validates the replacement data, installs it, schedules it and accepts the dates as the new baseline. Use it on the first load and to resync the whole project. If validation fails, you get Error::Input and the previous state and cached result stay as they were.
solve(None, ..) schedules the current state. After an apply it plans the edits. Tasks the edit touched (task 1 above) are reported too, even when the planner leaves them where the edit put them. On a clean project with the same options it returns the cached result without planning again.

The cache key is the whole SolveOptions value. Calling solve(None, ..) with different options replans from the accepted dates. That doesn't change the data, so the baseline_id stays the same unless a task moves.

solve returns Arc<ScheduleResult> because the project keeps the same result in its cache. After a rejected apply operation, solve(None, ..) fails with ProjectError::NeedsResync until you send the full data again with solve(Some(data), ..). Editing is covered in Data Updates.

Solve options#

SolveOptions changes what a solve schedules and what it reports. The defaults schedule the whole project and return only the moves.

use plen_core::{
    AnalyticsOptions, DateTime, LinkData, LinkType, Project, ProjectData, SolveOptions, Subtree,
    TaskData,
};

fn task(id: i32, start: DateTime, duration: f64) -> TaskData {
    let mut task = TaskData::new(id);
    task.start_date = Some(start);
    task.duration = Some(duration);
    task
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let monday = DateTime::from_ymd_hm(2026, 8, 10, 8, 0).ok_or("invalid date")?;
    let data = ProjectData {
        tasks: vec![task(1, monday, 2.0), task(2, monday, 3.0), task(3, monday, 1.0)],
        links: vec![LinkData {
            id: 1.into(),
            source: 2.into(),
            target: 3.into(),
            link_type: LinkType::Fs,
            lag: 0.0,
            lag_unit: None,
        }],
        ..Default::default()
    };
    let mut project = Project::default();

    // Initial load: every task's dates, why each one sits where it does,
    // plus the critical path and slack.
    let options = SolveOptions {
        include_unchanged: true,
        reasons: true,
        analytics: AnalyticsOptions {
            critical_path: true,
            slack: true,
        },
        ..Default::default()
    };
    let result = project.solve(Some(data), &options)?;
    for update in &result.updates {
        println!("{} {:?}", update.id, update.reason);
    }

    // Later: reschedule only task 2 and what depends on it.
    let branch = SolveOptions {
        subtree: Some(Subtree::new(2)),
        ..Default::default()
    };
    project.solve(None, &branch)?;
    Ok(())
}

include_unchanged also reports tasks that didn't move, each with start_date, end_date and duration set. The result alone is then the full normalized date list, which is what an editor needs on first load. Unscheduled tasks are never reported. See Load all task dates.
reasons adds a Reason to each update: pushed by a predecessor link (Asap), pulled by a successor (Alap), moved with its summary block (SummaryTranslation), placed by its constraint (Constraint) or kept at its preferred date (Preferred).
analytics asks for the critical path, slack, or both. They're off by default. See Critical path and slack.
subtree limits the run to one task and what depends on it, like gantt.autoSchedule(id, inclusive). Subtree::new(id) sets inclusive: true, so the root task is scheduled too. The subtree applies to this call only. A scoped solve accepts only its own moves, and a later unscoped solve picks up the rest. An unknown or unscheduled subtree task is an Error::Input at subtree.task, and the cached result is kept. See Reschedule a branch.

With subtree and include_unchanged together, the result holds every task in the subtree (with their ancestors) plus the out-of-subtree tasks that changed or were touched by an edit.

level and preview don't inherit these options: level solves with defaults first, and preview takes its own PreviewOptions.

Forward and backward planning#

By default the planner works forward: each task starts as early as its links allow. Set config.schedule_from_end to plan backward instead: each task ends as late as its successors allow, and the project is anchored at its end.

use plen_core::{
    schedule, DateTime, GapBehavior, LinkData, LinkType, ProjectData, SolveOptions, TaskData,
};

fn task(id: i32, start: DateTime, duration: f64) -> TaskData {
    let mut task = TaskData::new(id);
    task.start_date = Some(start);
    task.duration = Some(duration);
    task
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let date = |d, h| DateTime::from_ymd_hm(2026, 8, d, h, 0).ok_or("invalid date");

    let mut data = ProjectData {
        tasks: vec![task(1, date(10, 8)?, 2.0), task(2, date(12, 8)?, 3.0)],
        links: vec![LinkData {
            id: 1.into(),
            source: 1.into(),
            target: 2.into(),
            link_type: LinkType::Fs,
            lag: 0.0,
            lag_unit: None,
        }],
        ..Default::default()
    };
    data.config.schedule_from_end = true;
    data.config.gap_behavior = GapBehavior::Compress;
    data.config.project_end = Some(date(28, 17)?);

    let result = schedule(data, &SolveOptions::default())?;
    for update in &result.updates {
        if let (Some(start), Some(end)) = (update.start_date, update.end_date) {
            println!("task {}: {start} .. {end}", update.id);
        }
    }
    Ok(())
}

Task 2 has no successor, so project_end caps it and it ends at 2026-08-28 17:00. Task 1 ends where task 2 starts, on 2026-08-25 17:00.

The project bounds act only on tasks at the open ends of the graph:

project_start (forward) applies to tasks without predecessors. With GapBehavior::Compress it pulls them onto the project start. With GapBehavior::Preserve it only raises tasks that start earlier and leaves later ones at their dates. For a task with predecessors it's a hard floor only when apply_constraints is on.
project_end (backward) caps tasks without successors, in either gap mode. Without it, such a task keeps its current end.

A task whose constraint points the other way gets a secondary pass in the opposite direction. In a forward project with apply_constraints, an Alap task moves as late as its successors allow:

use plen_core::{
    schedule, ConstraintType, DateTime, LinkData, LinkType, ProjectData, SolveOptions, TaskData,
};

fn task(id: &str, start: DateTime, duration: f64) -> TaskData {
    let mut task = TaskData::new(id);
    task.start_date = Some(start);
    task.duration = Some(duration);
    task
}

fn fs(id: &str, source: &str, target: &str) -> LinkData {
    LinkData {
        id: id.into(),
        source: source.into(),
        target: target.into(),
        link_type: LinkType::Fs,
        lag: 0.0,
        lag_unit: None,
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let monday = DateTime::from_ymd_hm(2026, 8, 10, 8, 0).ok_or("invalid date")?;

    // "order" can happen any time before "install"; "build" sets the pace.
    let mut order = task("order", monday, 1.0);
    order.constraint_type = Some(ConstraintType::Alap);

    let mut data = ProjectData {
        tasks: vec![task("build", monday, 4.0), order, task("install", monday, 1.0)],
        links: vec![fs("l1", "build", "install"), fs("l2", "order", "install")],
        ..Default::default()
    };
    data.config.apply_constraints = true;

    let result = schedule(data, &SolveOptions::default())?;
    for update in &result.updates {
        if let (Some(start), Some(end)) = (update.start_date, update.end_date) {
            println!("{}: {start} .. {end}", update.id);
        }
    }
    Ok(())
}

install waits for build and starts on 2026-08-14 08:00. order moves from Monday to 2026-08-13 08:00, so it ends right when install starts.

Leveling is forward-only: Project::level rejects a project with schedule_from_end: true (Error::Input at config.schedule_from_end). Constraint types and summary behavior are covered in Links, constraints and summaries.

Determinism and convergence#

The same input and options always give the same result. The engine reads no clock and uses no randomness. It iterates in input order and topological order, never in hash order. That makes results safe to cache, diff and compare in tests.

The one exception is baseline_id. Tokens are opaque and may differ between runs for the same data, so never compare them across runs or store them. Take the current one from the latest solve result.

The planner runs passes until the dates stop changing. result.converged tells you whether it reached that point within config.max_iterations passes:

An unscoped run converges in two passes by design. The second pass reproduces the first.
A scoped run (subtree) can need more passes, because tasks outside the scope feed into it.
max_iterations defaults to 8 and must be at least 1. 0 is rejected as an Error::Input.

use plen_core::{schedule, DateTime, ProjectData, SolveOptions, TaskData};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let monday = DateTime::from_ymd_hm(2026, 8, 10, 8, 0).ok_or("invalid date")?;
    let mut only = TaskData::new(1);
    only.start_date = Some(monday);
    only.duration = Some(1.0);

    let mut data = ProjectData {
        tasks: vec![only],
        ..Default::default()
    };
    data.config.max_iterations = 4;

    let result = schedule(data, &SolveOptions::default())?;
    if !result.cycles.is_empty() {
        println!("dependency cycles: {}", result.cycles.len());
    } else if !result.converged {
        println!("planner stopped after max_iterations");
    }
    Ok(())
}

converged: false isn't an error, and the result is still valid.

A dependency cycle stops the run before planning. Dates stay unchanged, updates is empty and cycles lists each unique cycle. For everything else a result carries, see Reading results.