[Canonical page]() [Full documentation index]() # 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.LoadProfile`]() reads the solved baseline and cuts the date range into **buckets** of one hour or one day. For every resource it reports each bucket's `Load` and `Capacity`. It's read-only: 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`. `new ProfileQuery(from, to)` gives you every resource, the default basis and no task lists. Set the other properties with an object initializer. - [`LoadProfileOptions`]() wraps the query and adds an optional [`BaselineId`](). A `ProfileQuery` converts to `LoadProfileOptions` implicitly, so `project.LoadProfile(query)` 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 [`CapacityMode`]() and a list of [`LoadBucket`]() records with `Start`, `Load`, `Capacity` and `Tasks`. These 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.DurationUnit`](): [`Basis.Day`]() for days, `Basis.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, so 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. Task ids in a bucket do too. The profile always describes the accepted baseline, so the project has to be solved and clean. | Failure | Exception | |---|---| | Project not solved yet, or edited with [`Apply`]() since the last solve | [`ProjectException`](), `Code` = [`ProjectError.NoBaseline`]() | | `BaselineId` doesn't name the current baseline | `ProjectException`, `Code` = `ProjectError.StaleBaseline` | | `To <= From`, or more than 100 000 buckets | [`InputException`](), `Path` = `"to"` | | Unknown id in `Resources` | `InputException`, `Path` = `"resources"` | See [Error handling]() for the exception types and the [`LoadProfile` reference]() for every property. ## Querying a profile Solve the project, build a [`ProfileQuery`]() and pass it to [`LoadProfile`](). ```csharp using Plen; static Moment At(int day, int hour) => Moment.FromYmdHm(2026, 8, day, hour, 0) ?? throw new InvalidOperationException("invalid date"); static TaskData Task(string id, Moment start, double duration) => new(id) { StartDate = start, Duration = duration }; static AssignmentData Assign(string task, string resource, double value) => new() { Id = $"{task}:{resource}", Task = task, Resource = resource, Value = value }; // 2026-08-10 is a Monday. var data = new ProjectData { Tasks = [ 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 = [new ResourceData { Id = "dev" }], Assignments = [ Assign("a", "dev", 1.0), Assign("b", "dev", 1.0), Assign("c", "dev", 0.5), Assign("d", "dev", 1.0), ], }; var project = new Project(); project.Solve(data, new SolveOptions()); // Sunday 9 up to Friday 14; `To` is exclusive. var profile = project.LoadProfile(new ProfileQuery(At(9, 0), At(14, 0))); Console.WriteLine($"basis: {profile.Basis}"); foreach (var row in profile.Resources) { foreach (var bucket in row.Buckets) Console.WriteLine($"{row.Resource} {bucket.Start}: load {bucket.Load} of {bucket.Capacity}"); } ``` Output: ``` basis: Day dev 2026-08-09 00:00: load 0 of 1 dev 2026-08-10 00:00: load 2 of 1 dev 2026-08-11 00:00: load 1.5 of 1 dev 2026-08-12 00:00: load 1 of 1 dev 2026-08-13 00:00: load 0 of 1 ``` The project uses day units, so the basis is `Day` and you get five buckets, Sunday to Thursday. Monday carries `a` and `b`, and Tuesday carries `a` plus `c` at half time. Capacity is 1.0 in every bucket: `dev` has no capacity of its own, so it takes [`config.DefaultResourceCapacity`](). ### Narrowing the query Set `Resources` to measure only some resources, and [`Basis`]() to change the bucket size. ```csharp using Plen; static Moment At(int day, int hour) => Moment.FromYmdHm(2026, 8, day, hour, 0) ?? throw new InvalidOperationException("invalid date"); static TaskData Task(string id, Moment start, double duration) => new(id) { StartDate = start, Duration = duration }; var data = new ProjectData { Tasks = [Task("a", At(10, 8), 2.0), Task("b", At(10, 8), 1.0)], Resources = [new ResourceData { Id = "dev" }, new ResourceData { Id = "qa" }], Assignments = [ new AssignmentData { Task = "a", Resource = "dev", Value = 1.0 }, new AssignmentData { Task = "b", Resource = "dev", Value = 1.0 }, ], }; var project = new Project(); project.Solve(data, new SolveOptions()); // Monday 07:00 to 10:00, hour buckets, `dev` only. var query = new ProfileQuery(At(10, 7), At(10, 10)) { Resources = ["dev"], Basis = Basis.Hour, }; var profile = project.LoadProfile(query); foreach (var row in profile.Resources) Console.WriteLine($"{row.Resource}: [{string.Join(", ", row.Buckets.Select(b => b.Load))}]"); ``` Output: ``` dev: [0, 2, 2] ``` Only `dev` comes back, with three hour buckets. At 07:00 work hasn't started yet, and the 08:00 and 09:00 buckets carry both tasks. An id in `Resources` that isn't in the project throws [`InputException`]() with `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.BaselineId`](). If the project was solved again in the meantime, the call throws [`ProjectException`]() with [`ProjectError.StaleBaseline`]() instead of returning load for other dates. ```csharp using Plen; static Moment At(int day, int hour) => Moment.FromYmdHm(2026, 8, day, hour, 0) ?? throw new InvalidOperationException("invalid date"); var data = new ProjectData { Tasks = [new TaskData("a") { StartDate = At(10, 8), Duration = 2.0 }], Resources = [new ResourceData { Id = "dev" }], Assignments = [new AssignmentData { Task = "a", Resource = "dev", Value = 1.0 }], }; var project = new Project(); var solved = project.Solve(data, new SolveOptions()); var options = new LoadProfileOptions(new ProfileQuery(At(10, 0), At(15, 0))) { BaselineId = solved.BaselineId, }; var profile = project.LoadProfile(options); Console.WriteLine($"{profile.Resources.Count} resource(s) measured"); ``` 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`, or [`config.DefaultResourceCapacity`]() (1.0) when it's `null`. The [`CapacityMode`]() of each [`ResourceLoad`]() tells you how that capacity is spread over the buckets: - `CapacityMode.Calendar`: the resource has its own calendar, [`config.CalendarMode`]() is [`CalendarMode.Resource`]() (the default) and [`config.UseCalendars`]() is `true`. 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 `CalendarMode` is a task mode, or when `UseCalendars` 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. A bucket with capacity 0 never gets load. A bucket overallocates in the profile exactly when leveling sees it as overallocated. ```csharp using Plen; static Moment At(int day, int hour) => Moment.FromYmdHm(2026, 8, day, hour, 0) ?? throw new InvalidOperationException("invalid date"); // Days run Sunday..Saturday; hours are whole hours. static CalendarData Calendar(string id, bool[] days, int from, int to) => new() { Id = id, Worktime = new Worktime { Hours = [new TimeRange((ushort)(from * 60), (ushort)(to * 60))], Days = days, }, }; bool[] monFri = [false, true, true, true, true, true, false]; bool[] tueSat = [false, false, true, true, true, true, true]; var data = new ProjectData { // Tuesday, two days. Tasks = [new TaskData("a") { StartDate = At(11, 8), Duration = 2.0 }], Calendars = [ Calendar("global", monFri, 8, 16), Calendar("tue_sat", tueSat, 8, 16), Calendar("mornings", monFri, 8, 12), ], Resources = [ new ResourceData { Id = "office" }, new ResourceData { Id = "shop", CalendarId = "tue_sat" }, new ResourceData { Id = "part_time", CalendarId = "mornings" }, ], Assignments = [new AssignmentData { Task = "a", Resource = "shop", Value = 1.0 }], }; var project = new Project(); project.Solve(data, new SolveOptions()); // One week in day buckets, Sunday 9 to Saturday 15. var week = project.LoadProfile(new ProfileQuery(At(9, 0), At(16, 0))); foreach (var row in week.Resources) { var capacity = string.Join(", ", row.Buckets.Select(b => b.Capacity)); var load = string.Join(", ", row.Buckets.Select(b => b.Load)); Console.WriteLine($"{row.Resource} ({row.CapacityMode}): capacity [{capacity}], load [{load}]"); } // Tuesday 06:00 to 18:00 in hour buckets, for the part-time resource. var day = new ProfileQuery(At(11, 6), At(11, 18)) { Resources = ["part_time"], Basis = Basis.Hour, }; var hours = project.LoadProfile(day); Console.WriteLine($"part_time hourly capacity: [{string.Join(", ", hours.Resources[0].Buckets.Select(b => b.Capacity))}]"); ``` Output: ``` office (Flat): capacity [1, 1, 1, 1, 1, 1, 1], load [0, 0, 0, 0, 0, 0, 0] shop (Calendar): capacity [0, 0, 1, 1, 1, 1, 1], load [0, 0, 1, 1, 0, 0, 0] part_time (Calendar): capacity [0, 1, 1, 1, 1, 1, 0], load [0, 0, 0, 0, 0, 0, 0] part_time hourly capacity: [0, 0, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0] ``` 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.CalendarMode = CalendarMode.Task` (or `UseCalendars = false`) and all three resources become `Flat`, with capacity 1.0 in every bucket. See [Working time and calendars]() for calendar setup and the [`LoadProfile` reference]() for `CapacityMode`. ## 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) | `null` in every bucket | | `Over` | the task ids in buckets where `Load > Capacity`, an empty list elsewhere | | `All` | the ids of every task booked in the bucket | ```csharp using Plen; static Moment At(int day, int hour) => Moment.FromYmdHm(2026, 8, day, hour, 0) ?? throw new InvalidOperationException("invalid date"); static TaskData Task(string id, Moment start, double duration) => new(id) { StartDate = start, Duration = duration }; static AssignmentData Assign(string task, double value) => new() { Task = task, Resource = "dev", Value = value }; var data = new ProjectData { Tasks = [ 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 = [new ResourceData { Id = "dev" }], Assignments = [Assign("a", 1.0), Assign("b", 1.0), Assign("c", 0.5), Assign("d", 1.0)], }; var project = new Project(); project.Solve(data, new SolveOptions()); // Monday 10 to Thursday 13. var query = new ProfileQuery(At(10, 0), At(14, 0)) { Tasks = ProfileTasks.Over }; var profile = project.LoadProfile(query); foreach (var bucket in profile.Resources[0].Buckets) { var tasks = bucket.Tasks is null ? "null" : $"[{string.Join(", ", bucket.Tasks)}]"; Console.WriteLine($"{bucket.Start}: load {bucket.Load}, tasks {tasks}"); } ``` Output: ``` 2026-08-10 00:00: load 2, tasks [a, b] 2026-08-11 00:00: load 1.5, tasks [a, c] 2026-08-12 00:00: load 1, tasks [] 2026-08-13 00:00: load 0, tasks [] ``` With `Over`, Monday lists `a` and `b`, and Tuesday lists `a` and `c`. Wednesday and Thursday aren't overloaded, so their lists are empty. 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 and 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 [`LoadProfile`]() only reads the baseline. To see the load an edit *would* cause, set [`PreviewOptions.Profile`]() to a [`ProfileQuery`]() and call [`Project.Preview`](). The result's [`Profile`]() is computed on the previewed dates, and the project stays as it was. ```csharp using Plen; static Moment At(int day, int hour) => Moment.FromYmdHm(2026, 8, day, hour, 0) ?? throw new InvalidOperationException("invalid date"); static TaskData Task(string id, Moment start, double duration) => new(id) { StartDate = start, Duration = duration }; static AssignmentData Assign(string task, string resource, double value) => new() { Id = $"{task}:{resource}", Task = task, Resource = resource, Value = value }; var data = new ProjectData { Tasks = [ Task("a", At(10, 8), 2.0), Task("b", At(10, 8), 1.0), Task("c", At(11, 8), 1.0), ], Resources = [new ResourceData { Id = "dev" }, new ResourceData { Id = "qa" }], Assignments = [ Assign("a", "dev", 1.0), Assign("b", "dev", 1.0), Assign("c", "dev", 0.5), ], }; var project = new Project(); project.Solve(data, new SolveOptions()); // What if `b` moves from `dev` to `qa`? var changes = new SchedulingChanges(); changes.Assignments.Update.Add(new AssignmentUpdate("b:dev") { Resource = Patch.Of("qa") }); var options = new PreviewOptions { Profile = new ProfileQuery(At(10, 0), At(12, 0)) }; var preview = project.Preview(changes, options); if (preview.Profile is { } profile) { foreach (var row in profile.Resources) Console.WriteLine($"previewed {row.Resource}: [{string.Join(", ", row.Buckets.Select(b => b.Load))}]"); } // The baseline still has both tasks on `dev`. var baseline = project.LoadProfile(new ProfileQuery(At(10, 0), At(12, 0))); Console.WriteLine($"baseline dev: [{string.Join(", ", baseline.Resources[0].Buckets.Select(b => b.Load))}]"); ``` Output: ``` previewed dev: [1, 1.5] previewed qa: [1, 0] baseline dev: [2, 1.5] ``` 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 `null`. `PreviewOptions.Profile` takes a bare `ProfileQuery`, not [`LoadProfileOptions`](), so it has no `BaselineId` of its own. To guard a preview against a stale baseline, set [`PreviewOptions.BaselineId`](). An invalid query fails the whole preview with [`InputException`](). To profile a multi-step edit or a leveling run, call [`Clone()`]() on the project, edit or [`Level`]() the clone, and call `LoadProfile` on it. The clone is cheap, and the original doesn't change. See [Previewing changes]() for both approaches.