[Canonical page]() [Full documentation index]() # Scheduling a Project This guide shows how to run the scheduler from .NET. It explains when to call the one-shot [`Engine.Schedule`]() 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 both run the same planner: - [`Engine.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 `new Project().Solve(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 goes through the same steps. The engine copies the snapshot into its own normalized model and validates it. Next, it builds the scheduling graph from links and summaries, checks for dependency cycles and works out the scope: the whole project, or one branch with [`Subtree`](). Then the planner runs 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. Set [`IncludeUnchanged`]() to get every task's dates. - **Problems are data, not exceptions.** Conflicts, cycles, dropped input and non-convergence come back inside `ScheduleResult`. A call throws [`InputException`]() for invalid input and [`ProjectException`]() for a call that doesn't fit the project's state. See [Error handling](). - **Some tasks never move.** Tasks with `AutoScheduling = false`, unscheduled tasks and completed tasks ([`UseProgress`]() with `Progress == 1`) stay where they are. That's how you lock work in place. There are no cancellation events. - **Calls are synchronous and CPU-only.** There's no I/O, no clock and no async API. See [Blocking calls](). ## One-shot scheduling Use [`Engine.Schedule`]() in batch jobs, request handlers and tools that schedule a snapshot and then throw it away. ```csharp using Plen; var monday = Moment.FromYmdHm(2026, 8, 10, 8, 0) ?? throw new InvalidOperationException("invalid date"); var data = new ProjectData { Tasks = [ new TaskData(1) { StartDate = monday, Duration = 2.0 }, new TaskData(2) { StartDate = monday, Duration = 3.0 }, ], Links = [new LinkData { Id = 1, Source = 1, Target = 2 }], }; var result = Engine.Schedule(data, new SolveOptions()); foreach (var update in result.Updates) Console.WriteLine($"task {update.Id}: {update.StartDate} .. {update.EndDate}"); ``` 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, so it isn't reported. The dates skip the weekend because the default `"global"` calendar works Mon-Fri, 08:00-12:00 and 13:00-17:00. `Engine.Schedule` never changes the `data` you pass in, and the result it returns is yours alone, so you can modify it freely. It throws only when validation rejects the snapshot, and the exception is always [`InputException`](). ## Solving a project Keep a [`Project`]() when the plan lives on. Typical cases are an editor backend with one project per open document, or a service that applies edits over time. ```csharp using Plen; var monday = Moment.FromYmdHm(2026, 8, 10, 8, 0) ?? throw new InvalidOperationException("invalid date"); var data = new ProjectData { Tasks = [ new TaskData(1) { StartDate = monday, Duration = 2.0 }, new TaskData(2) { StartDate = monday, Duration = 3.0 }, ], Links = [new LinkData { Id = 1, Source = 1, Target = 2 }], }; var project = new Project(); var options = new SolveOptions(); // Install the data, schedule it and accept the dates as the baseline. var loaded = project.Solve(data, options); // Nothing changed since: the cached result comes back. var cached = project.Solve(null, options); Console.WriteLine(ReferenceEquals(loaded, cached)); // True // Edit, then reschedule. var changes = new SchedulingChanges(); changes.Tasks.Update.Add(new TaskUpdate(1) { Duration = 4.0 }); project.Apply(changes); var after = project.Solve(null, options); foreach (var update in after.Updates) Console.WriteLine($"task {update.Id}: {update.StartDate} .. {update.EndDate}"); ``` The edit makes task 1 four days long. Task 2 moves to `2026-08-14 08:00 .. 2026-08-19 08:00`, and task 1 is reported as well. The two forms of [`Solve`]() do different jobs: - `Solve(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. The project works on its own deep copy, so later changes to your [`ProjectData`]() don't leak into it. If validation fails, `Solve` throws [`InputException`]() and the previous state and cached result stay as they were. - `Solve(null, …)` 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 equal options it returns the cached result, the same object, without planning again. The cache key is the whole [`SolveOptions`]() value, compared by value. Calling `Solve(null, …)` with different options replans from the accepted dates. The data doesn't change, so [`BaselineId`]() stays the same unless a task moves. Treat every result as read-only. The project keeps it as its baseline, can return the same object from a later `Solve`, and shares it with its clones. Call [`DeepClone()`]() before you modify one. After an `Apply` rejects an operation, `Solve(null, …)` throws [`ProjectException`]() with `Code == ProjectError.NeedsResync` until you send the full data again with `Solve(data, …)`. Editing is covered in [Editing a project](). ## Solve options [`SolveOptions`]() controls what a solve schedules and what it reports. With the defaults it schedules the whole project and returns only the moves. ```csharp using Plen; var monday = Moment.FromYmdHm(2026, 8, 10, 8, 0) ?? throw new InvalidOperationException("invalid date"); var data = new ProjectData { Tasks = [ new TaskData(1) { StartDate = monday, Duration = 2.0 }, new TaskData(2) { StartDate = monday, Duration = 3.0 }, new TaskData(3) { StartDate = monday, Duration = 1.0 }, ], Links = [new LinkData { Id = 1, Source = 2, Target = 3 }], }; var project = new Project(); // Initial load: every task's dates, why each one sits where it does, // plus the critical path and slack. var options = new SolveOptions { IncludeUnchanged = true, Reasons = true, Analytics = new AnalyticsOptions { CriticalPath = true, Slack = true }, }; var result = project.Solve(data, options); foreach (var update in result.Updates) Console.WriteLine($"{update.Id} {update.Reason}"); // Later: reschedule only task 2 and what depends on it. project.Solve(null, new SolveOptions { Subtree = new Subtree(2) }); ``` - [`IncludeUnchanged`]() also reports tasks that didn't move, each with `StartDate`, `EndDate` 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 (`Reason.Asap`), pulled by a successor (`Reason.Alap`), moved with its summary block (`Reason.SummaryTranslation`), placed by its constraint (`Reason.Constraint`) or kept at its preferred date (`Reason.Preferred`). Read it with a `switch` on the nested types. - [`Analytics`]() asks for the critical path, slack, or both. Both are off by default. See [Critical path and slack](). - [`Subtree`]() limits the run to one task and what depends on it. [`new Subtree(id)`]() sets `Inclusive = true`, so the scope also takes in the task's predecessors. 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 throws [`InputException`]() with `Path == "subtree.task"`, and the cached result is kept. See [Reschedule a branch](). With `Subtree` and `IncludeUnchanged` 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 default options 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.ScheduleFromEnd`]() to plan backward instead. Then each task ends as late as its successors allow, and the project is anchored at its end. ```csharp using Plen; static Moment Date(int day, int hour) => Moment.FromYmdHm(2026, 8, day, hour, 0) ?? throw new InvalidOperationException("invalid date"); var data = new ProjectData { Tasks = [ new TaskData(1) { StartDate = Date(10, 8), Duration = 2.0 }, new TaskData(2) { StartDate = Date(12, 8), Duration = 3.0 }, ], Links = [new LinkData { Id = 1, Source = 1, Target = 2 }], }; data.Config.ScheduleFromEnd = true; data.Config.GapBehavior = GapBehavior.Compress; data.Config.ProjectEnd = Date(28, 17); var result = Engine.Schedule(data, new SolveOptions()); foreach (var update in result.Updates) Console.WriteLine($"task {update.Id}: {update.StartDate} .. {update.EndDate}"); ``` Task 2 has no successor, so [`ProjectEnd`]() 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: - [`ProjectStart`]() (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 [`ApplyConstraints`]() is on. - `ProjectEnd` (backward) caps tasks without successors, in either gap mode. Without it, such a task keeps its current end. All of these settings live on [`SchedulingConfig`](). A task whose constraint points the other way gets a secondary pass in the opposite direction. In a forward project with `ApplyConstraints`, an `Alap` task moves as late as its successors allow: ```csharp using Plen; var monday = Moment.FromYmdHm(2026, 8, 10, 8, 0) ?? throw new InvalidOperationException("invalid date"); // "order" can happen any time before "install"; "build" sets the pace. var data = new ProjectData { Tasks = [ new TaskData("build") { StartDate = monday, Duration = 4.0 }, new TaskData("order") { StartDate = monday, Duration = 1.0, ConstraintType = ConstraintType.Alap }, new TaskData("install") { StartDate = monday, Duration = 1.0 }, ], Links = [ new LinkData { Id = "l1", Source = "build", Target = "install" }, new LinkData { Id = "l2", Source = "order", Target = "install" }, ], }; data.Config.ApplyConstraints = true; var result = Engine.Schedule(data, new SolveOptions()); foreach (var update in result.Updates) Console.WriteLine($"{update.Id}: {update.StartDate} .. {update.EndDate}"); ``` `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 `ScheduleFromEnd = true` and throws [`InputException`]() 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. [`BaselineId`]() is the one exception. Tokens are opaque and unique to the process, and they can differ between runs for the same data. 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 got there within [`Config.MaxIterations`]() 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. - `MaxIterations` defaults to 8 and must be at least 1. `0` throws [`InputException`](). ```csharp using Plen; var monday = Moment.FromYmdHm(2026, 8, 10, 8, 0) ?? throw new InvalidOperationException("invalid date"); var data = new ProjectData { Tasks = [new TaskData(1) { StartDate = monday, Duration = 1.0 }], }; data.Config.MaxIterations = 4; var result = Engine.Schedule(data, new SolveOptions()); if (result.Cycles.Count > 0) Console.WriteLine($"dependency cycles: {result.Cycles.Count}"); else if (!result.Converged) Console.WriteLine("planner stopped after MaxIterations"); ``` `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. With `IncludeUnchanged`, `Updates` lists every scheduled task with its stored dates instead. For everything else a result carries, see [Reading results](). ## Blocking calls Every method runs on the calling thread and returns when the work is done. There are no `Async` methods and no `CancellationToken` parameters. In ASP.NET Core or another async host, move large solves and long calls such as [`Level`](), [`Evaluate`]() and [`SuggestAssignments`]() off the request thread with `Task.Run`. A [`Project`]() isn't thread-safe. Even read-only calls such as [`Clone()`]() update its internal state, so let only one thread use a shared instance at a time. ```csharp using Plen; var monday = Moment.FromYmdHm(2026, 8, 10, 8, 0) ?? throw new InvalidOperationException("invalid date"); var data = new ProjectData { Tasks = [new TaskData(1) { StartDate = monday, Duration = 2.0 }], }; // One-shot: the snapshot belongs to this call alone. var result = await Task.Run(() => Engine.Schedule(data, new SolveOptions())); // A long-lived project shared by request handlers: one call at a time. var project = new Project(); var gate = new object(); var loaded = await Task.Run(() => { lock (gate) return project.Solve(data, new SolveOptions()); }); ``` [`Engine.Schedule`]() builds a fresh project on every call, so parallel one-shot calls need no lock. To work on one plan from several threads, give each thread its own `Clone()`, made on one thread first. See [Call from async code]() and [Share a project between threads]().