DHTMLX Planning Engine Documentation

Resource Load#

This guide shows how to measure how busy each resource is over a date range. That's the data behind a resource histogram. It covers the profile query, how capacity follows resource calendars, which tasks fill each bucket, and how to get the load for dates you haven't committed yet.

How a load profile works#

Project::load_profile reads the solved baseline and cuts the date range into buckets, either hours or days. For every resource it reports each bucket's load and capacity. It's read-only (&self). It never schedules and never changes the project.

The parts fit together like this:

  • A ProfileQuery says what to measure: the range from..to, which resources, the bucket size (basis) and whether to list tasks. ProfileQuery::new(from, to) gives you every resource, the default basis and no task lists.
  • LoadProfileOptions wraps the query and adds an optional baseline_id. From<ProfileQuery> is implemented, so project.load_profile(&query.into()) is the short form.
  • The result is a LoadProfile: the basis it used and one ResourceLoad per resource. Each ResourceLoad has the resource id, its capacity_mode and a list of LoadBucket { start, load, capacity, tasks }.

A few rules decide what ends up in the buckets:

  • Range. A bucket is included when its start lies in [from, to). A day bucket starts at midnight, so a from of Monday 12:00 skips Monday and starts on Tuesday. to is exclusive.
  • Dense output. Every bucket in the range appears, including empty ones with load 0. That's why the range is capped at 100 000 buckets per resource, about 11 years at hour basis.
  • Basis. By default the basis follows config.duration_unit: Day for days, Hour for hours and minutes. Set basis to override it.
  • Load units. Load is in assignment value units, where 1 is 100 %. Nothing is converted to hours. An assignment that works in a bucket books its value there. Two full-time tasks on the same day give a load of 2.0.
  • Same load as leveling. The profile uses the same sweep as the leveler and the overallocations in ScheduleResult: only real work segments, each assignment on its own calendar, cut to its slice. A bucket overallocates when load > capacity.
  • Order. Resources come back in input order, and task ids in a bucket too.

The profile always describes the accepted baseline, so the project has to be solved and clean.

Failure Error
Project not solved yet, or edited with apply since the last solve Error::Project(ProjectError::NoBaseline)
baseline_id doesn't name the current baseline Error::Project(ProjectError::StaleBaseline)
to <= from, or more than 100 000 buckets Error::Input, path to
Unknown id in resources Error::Input, path resources

See Handling errors for the error types and the LoadProfile reference for every field.

Querying a profile#

Solve the project, build a ProfileQuery and pass it to load_profile.

use plen_core::{
    AssignmentData, DateTime, ProfileQuery, Project, ProjectData, ResourceData, SolveOptions,
    TaskData,
};

fn at(day: u32, hour: u32) -> Result<DateTime, Box<dyn std::error::Error>> {
    Ok(DateTime::from_ymd_hm(2026, 8, day, hour, 0).ok_or("invalid date")?)
}

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 assign(task: &str, resource: &str, value: f64) -> AssignmentData {
    AssignmentData {
        id: Some(format!("{task}:{resource}").into()),
        task: task.into(),
        resource: resource.into(),
        value,
        offset: None,
        duration: None,
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 2026-08-10 is a Monday.
    let data = ProjectData {
        tasks: vec![
            task("a", at(10, 8)?, 2.0),
            task("b", at(10, 8)?, 1.0),
            task("c", at(11, 8)?, 1.0),
            task("d", at(12, 8)?, 1.0),
        ],
        resources: vec![ResourceData {
            id: "dev".into(),
            capacity: None,
            calendar_id: None,
        }],
        assignments: vec![
            assign("a", "dev", 1.0),
            assign("b", "dev", 1.0),
            assign("c", "dev", 0.5),
            assign("d", "dev", 1.0),
        ],
        ..Default::default()
    };

    let mut project = Project::default();
    project.solve(Some(data), &SolveOptions::default())?;

    // Sunday 9 up to Friday 14; `to` is exclusive.
    let query = ProfileQuery::new(at(9, 0)?, at(14, 0)?);
    let profile = project.load_profile(&query.into())?;

    println!("basis: {:?}", profile.basis);
    for row in &profile.resources {
        for bucket in &row.buckets {
            println!(
                "{} {}: load {} of {}",
                row.resource, bucket.start, bucket.load, bucket.capacity
            );
        }
    }
    Ok(())
}

The project uses day units, so the basis is Day and you get five buckets, Sunday to Thursday. The loads are 0, 2.0 (a and b), 1.5 (a plus c at half time), 1.0 (d) and 0. Capacity is 1.0 in every bucket: dev has no capacity of its own, so it takes config.default_resource_capacity.

Narrowing the query#

Set resources to measure only some resources, and basis to change the bucket size. ProfileQuery is a plain struct, so start from ProfileQuery::new and override fields with struct update syntax.

use plen_core::{
    AssignmentData, Basis, DateTime, ProfileQuery, Project, ProjectData, ResourceData,
    SolveOptions, TaskData,
};

fn at(day: u32, hour: u32) -> Result<DateTime, Box<dyn std::error::Error>> {
    Ok(DateTime::from_ymd_hm(2026, 8, day, hour, 0).ok_or("invalid date")?)
}

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 assign(task: &str, resource: &str) -> AssignmentData {
    AssignmentData {
        id: None,
        task: task.into(),
        resource: resource.into(),
        value: 1.0,
        offset: None,
        duration: None,
    }
}

fn resource(id: &str) -> ResourceData {
    ResourceData {
        id: id.into(),
        capacity: None,
        calendar_id: None,
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let data = ProjectData {
        tasks: vec![task("a", at(10, 8)?, 2.0), task("b", at(10, 8)?, 1.0)],
        resources: vec![resource("dev"), resource("qa")],
        assignments: vec![assign("a", "dev"), assign("b", "dev")],
        ..Default::default()
    };

    let mut project = Project::default();
    project.solve(Some(data), &SolveOptions::default())?;

    // Monday 07:00 to 10:00, hour buckets, `dev` only.
    let query = ProfileQuery {
        resources: Some(vec!["dev".into()]),
        basis: Some(Basis::Hour),
        ..ProfileQuery::new(at(10, 7)?, at(10, 10)?)
    };
    let profile = project.load_profile(&query.into())?;

    for row in &profile.resources {
        let loads: Vec<f64> = row.buckets.iter().map(|b| b.load).collect();
        println!("{}: {:?}", row.resource, loads);
    }
    Ok(())
}

Only dev comes back, with three hour buckets: 07:00 is before work starts (0.0), and 08:00 and 09:00 carry both tasks (2.0 each). An id in resources that isn't in the project fails with Error::Input at path resources.

Pinning the profile to a baseline#

A UI often fetches the profile some time after the solve. To make sure the profile matches the dates on screen, pass the token from the solve result as LoadProfileOptions.baseline_id. If the project was solved again in the meantime, the call fails with ProjectError::StaleBaseline instead of returning load for other dates.

use plen_core::{
    AssignmentData, DateTime, LoadProfileOptions, ProfileQuery, Project, ProjectData,
    ResourceData, SolveOptions, TaskData,
};

fn at(day: u32, hour: u32) -> Result<DateTime, Box<dyn std::error::Error>> {
    Ok(DateTime::from_ymd_hm(2026, 8, day, hour, 0).ok_or("invalid date")?)
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut task = TaskData::new("a");
    task.start_date = Some(at(10, 8)?);
    task.duration = Some(2.0);

    let data = ProjectData {
        tasks: vec![task],
        resources: vec![ResourceData {
            id: "dev".into(),
            capacity: None,
            calendar_id: None,
        }],
        assignments: vec![AssignmentData {
            id: None,
            task: "a".into(),
            resource: "dev".into(),
            value: 1.0,
            offset: None,
            duration: None,
        }],
        ..Default::default()
    };

    let mut project = Project::default();
    let solved = project.solve(Some(data), &SolveOptions::default())?;

    let options = LoadProfileOptions {
        query: ProfileQuery::new(at(10, 0)?, at(15, 0)?),
        baseline_id: solved.baseline_id.clone(),
    };
    let profile = project.load_profile(&options)?;
    println!("{} resource(s) measured", profile.resources.len());
    Ok(())
}

Take the token from the latest solve result. Tokens are opaque, and the same data solved twice can get a different one, so don't store them or compare them across runs.

Capacity modes#

Capacity is the resource's capacity (default config.default_resource_capacity, 1.0). The capacity_mode of each ResourceLoad tells you how it's spread over the buckets:

  • CapacityMode::Calendar - the resource has its own calendar, config.calendar_mode is Resource (the default) and config.use_calendars is on. Buckets with working time on that calendar get the full capacity, all others get 0.
  • CapacityMode::Flat - every bucket gets the full capacity, weekends and nights included. This applies when the resource has no calendar, when calendar_mode is a task mode (the one the dhtmlxGantt adapter uses), or when use_calendars is false.

In calendar mode an assignment always works on the resource's calendar, or on the overlap of the task's and the resource's calendars. So a bucket with capacity 0 never gets load, and a bucket overallocates in the profile exactly when leveling sees it as overallocated.

use plen_core::{
    AssignmentData, Basis, CalendarData, DateTime, ProfileQuery, Project, ProjectData,
    ResourceData, SolveOptions, TaskData, TimeRange, Worktime,
};

fn at(day: u32, hour: u32) -> Result<DateTime, Box<dyn std::error::Error>> {
    Ok(DateTime::from_ymd_hm(2026, 8, day, hour, 0).ok_or("invalid date")?)
}

// Days run Sunday..Saturday.
fn calendar(id: &str, days: [bool; 7], hours: (u16, u16)) -> CalendarData {
    CalendarData {
        id: id.into(),
        worktime: Some(Worktime {
            hours: Some(vec![TimeRange {
                start: hours.0 * 60,
                end: hours.1 * 60,
            }]),
            days: Some(days),
            ..Default::default()
        }),
    }
}

fn resource(id: &str, calendar: Option<&str>) -> ResourceData {
    ResourceData {
        id: id.into(),
        capacity: None,
        calendar_id: calendar.map(Into::into),
    }
}

const MON_FRI: [bool; 7] = [false, true, true, true, true, true, false];
const TUE_SAT: [bool; 7] = [false, false, true, true, true, true, true];

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut task = TaskData::new("a");
    task.start_date = Some(at(11, 8)?); // Tuesday
    task.duration = Some(2.0);

    let data = ProjectData {
        tasks: vec![task],
        calendars: vec![
            calendar("global", MON_FRI, (8, 16)),
            calendar("tue_sat", TUE_SAT, (8, 16)),
            calendar("mornings", MON_FRI, (8, 12)),
        ],
        resources: vec![
            resource("office", None),
            resource("shop", Some("tue_sat")),
            resource("part_time", Some("mornings")),
        ],
        assignments: vec![AssignmentData {
            id: None,
            task: "a".into(),
            resource: "shop".into(),
            value: 1.0,
            offset: None,
            duration: None,
        }],
        ..Default::default()
    };

    let mut project = Project::default();
    project.solve(Some(data), &SolveOptions::default())?;

    // One week in day buckets, Sunday 9 to Saturday 15.
    let week = project.load_profile(&ProfileQuery::new(at(9, 0)?, at(16, 0)?).into())?;
    for row in &week.resources {
        let capacity: Vec<f64> = row.buckets.iter().map(|b| b.capacity).collect();
        let load: Vec<f64> = row.buckets.iter().map(|b| b.load).collect();
        println!(
            "{} ({:?}): capacity {:?}, load {:?}",
            row.resource, row.capacity_mode, capacity, load
        );
    }

    // Tuesday 06:00 to 18:00 in hour buckets, for the part-time resource.
    let day = ProfileQuery {
        resources: Some(vec!["part_time".into()]),
        basis: Some(Basis::Hour),
        ..ProfileQuery::new(at(11, 6)?, at(11, 18)?)
    };
    let hours = project.load_profile(&day.into())?;
    let capacity: Vec<f64> = hours.resources[0].buckets.iter().map(|b| b.capacity).collect();
    println!("part_time hourly capacity: {:?}", capacity);
    Ok(())
}

What the week shows:

  • office has no calendar, so it's Flat with capacity 1.0 on all seven days, Sunday and Saturday included.
  • shop is Calendar. Its capacity is 0 on Sunday and Monday and 1.0 from Tuesday to Saturday. Task a runs Tuesday and Wednesday, so those two buckets have load 1.0.
  • At hour basis, part_time has capacity only in the four hour buckets between 08:00 and 12:00. The other eight hours are 0.

Set data.config.calendar_mode = CalendarMode::Task (or use_calendars = false) and all three resources become Flat, with capacity 1.0 in every bucket. See Working time and calendars for calendar setup and the CapacityMode reference.

Task lists per bucket#

A histogram usually needs to say who is overloading a resource. Set ProfileQuery.tasks to fill LoadBucket.tasks:

ProfileTasks LoadBucket.tasks
None (default) None in every bucket
Over Some(ids) in buckets where load > capacity, Some(vec![]) elsewhere
All Some(ids) of every task booked in the bucket 
use plen_core::{
    AssignmentData, DateTime, ProfileQuery, ProfileTasks, Project, ProjectData, ResourceData,
    SolveOptions, TaskData,
};

fn at(day: u32, hour: u32) -> Result<DateTime, Box<dyn std::error::Error>> {
    Ok(DateTime::from_ymd_hm(2026, 8, day, hour, 0).ok_or("invalid date")?)
}

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 assign(task: &str, value: f64) -> AssignmentData {
    AssignmentData {
        id: None,
        task: task.into(),
        resource: "dev".into(),
        value,
        offset: None,
        duration: None,
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let data = ProjectData {
        tasks: vec![
            task("a", at(10, 8)?, 2.0),
            task("b", at(10, 8)?, 1.0),
            task("c", at(11, 8)?, 1.0),
            task("d", at(12, 8)?, 1.0),
        ],
        resources: vec![ResourceData {
            id: "dev".into(),
            capacity: None,
            calendar_id: None,
        }],
        assignments: vec![
            assign("a", 1.0),
            assign("b", 1.0),
            assign("c", 0.5),
            assign("d", 1.0),
        ],
        ..Default::default()
    };

    let mut project = Project::default();
    project.solve(Some(data), &SolveOptions::default())?;

    // Monday 10 to Thursday 13.
    let query = ProfileQuery {
        tasks: ProfileTasks::Over,
        ..ProfileQuery::new(at(10, 0)?, at(14, 0)?)
    };
    let profile = project.load_profile(&query.into())?;

    for bucket in &profile.resources[0].buckets {
        println!("{}: load {}, tasks {:?}", bucket.start, bucket.load, bucket.tasks);
    }
    Ok(())
}

With Over, Monday lists a and b, and Tuesday lists a and c. Wednesday and Thursday aren't overloaded, so they get empty lists. Switch to ProfileTasks::All and Wednesday lists d too, because All reports every booked task regardless of capacity.

If you need only the overloaded periods, not the full histogram, skip the profile. Every ScheduleResult of a project with assignments carries overallocations: per-resource windows with peak, overload and the contending tasks. See Leveling resources for how to remove the overload.

Load of hypothetical dates#

load_profile only reads the baseline. To see the load an edit would cause, set PreviewOptions.profile to a ProfileQuery and call preview. The result's profile is computed on the previewed dates, and the project is left untouched.

use plen_core::{
    AssignmentData, AssignmentUpdate, DateTime, Patch, PreviewOptions, ProfileQuery, Project,
    ProjectData, ResourceData, SchedulingChanges, SolveOptions, TaskData,
};

fn at(day: u32, hour: u32) -> Result<DateTime, Box<dyn std::error::Error>> {
    Ok(DateTime::from_ymd_hm(2026, 8, day, hour, 0).ok_or("invalid date")?)
}

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 assign(task: &str, resource: &str, value: f64) -> AssignmentData {
    AssignmentData {
        id: Some(format!("{task}:{resource}").into()),
        task: task.into(),
        resource: resource.into(),
        value,
        offset: None,
        duration: None,
    }
}

fn resource(id: &str) -> ResourceData {
    ResourceData {
        id: id.into(),
        capacity: None,
        calendar_id: None,
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let data = ProjectData {
        tasks: vec![
            task("a", at(10, 8)?, 2.0),
            task("b", at(10, 8)?, 1.0),
            task("c", at(11, 8)?, 1.0),
        ],
        resources: vec![resource("dev"), resource("qa")],
        assignments: vec![
            assign("a", "dev", 1.0),
            assign("b", "dev", 1.0),
            assign("c", "dev", 0.5),
        ],
        ..Default::default()
    };

    let mut project = Project::default();
    project.solve(Some(data), &SolveOptions::default())?;

    // What if `b` moves from `dev` to `qa`?
    let mut changes = SchedulingChanges::default();
    let mut update = AssignmentUpdate::new("b:dev");
    update.resource = Patch::Value("qa".into());
    changes.assignments.update.push(update);

    let options = PreviewOptions {
        profile: Some(ProfileQuery::new(at(10, 0)?, at(12, 0)?)),
        ..Default::default()
    };
    let preview = project.preview(&changes, &options)?;

    if let Some(profile) = &preview.profile {
        for row in &profile.resources {
            let loads: Vec<f64> = row.buckets.iter().map(|b| b.load).collect();
            println!("previewed {}: {:?}", row.resource, loads);
        }
    }

    // The baseline still has both tasks on `dev`.
    let base = project.load_profile(&ProfileQuery::new(at(10, 0)?, at(12, 0)?).into())?;
    let loads: Vec<f64> = base.resources[0].buckets.iter().map(|b| b.load).collect();
    println!("baseline dev: {:?}", loads);
    Ok(())
}

In the preview, dev drops to 1.0 on Monday and keeps 1.5 on Tuesday, and qa gets 1.0 on Monday. The baseline profile still shows 2.0 and 1.5 for dev. Without PreviewOptions.profile, preview.profile is None.

PreviewOptions.profile takes a bare ProfileQuery, not LoadProfileOptions, so it has no baseline_id of its own. To guard a preview against a stale baseline, set PreviewOptions.baseline_id. An invalid query fails the whole preview with Error::Input.

To profile a multi-step edit or a leveling run, clone the project, edit or level the clone, and call load_profile on it. The clone is cheap and the original stays as it was. See Previewing changes for both approaches.