PowerSolver Docs
Back to Wizard
This page belongs to the full documentation. You don't need it to plan: back to the essentials.

PowerSolver 2.0 — User Guide

This guide explains how to use PowerSolver day-to-day: framing problems, working with the wizard, importing and exporting JSON, interpreting solutions, and resolving common surprises.

If you're brand-new to PowerSolver, start with Concepts Guide and the four tutorials in Quick Start, then return here.

1. Choosing the right shape for your problem

Most real-world planning problems fall into one of two shapes.

Sequence mode — order matters

Use sequence mode when entities are scheduled CONSECUTIVELY on a host:

  • Tasks scheduled back-to-back on a machine, day, or developer
  • Customer visits chained along a vehicle route
  • Maintenance jobs sequenced for a crew
  • Shifts ordered through an employee's day

PowerSolver models this with a list variable + the canonical derived shadows (startTime, endTime). One host owns the sequence; entities are placed in order.

Pure assignment — no order

Use pure assignment when each entity gets ONE value and order doesn't matter:

  • Each room assigned to one time-slot (no sequencing within the room)
  • Each meeting assigned to one cohort

PowerSolver models this with a basic variable. No shadows, no derived shadows, just a simple assignment.

When in doubt, ask yourself: "Do I care which thing comes first, second, third on each host?" If yes → sequence mode. If no → pure assignment.

2. Workflow at a glance

From the wizard

  1. Open https://wizard.planningpowertools.com/.
  2. Step 1 — Load a plan from Excel (then Fill all steps now), or pick the problem type and fill each step.
  3. Steps 2–6 — items, resource lists and reference lists, rules, items fixed in advance, time limit.
  4. Step 7 — Can this work? checks the data, then Plan it.
  5. Read the Results page: verdict, Check before you use it, calendar, Rules & score, Changes; Export to Excel.
  6. Keep the downloaded problem and solution files (they are the record of the plan).

From the API directly

  1. Hand-author or generate a §5bis JSON spec (POST /api/solve body shape — see API Reference).
  2. POST to https://api.planningpowertools.com/api/solve.
  3. Inspect the response envelope: score, feasible, assignments, shadows.

The wizard and the API consume the SAME JSON shape. Anything the wizard emits in Step 7 you can POST verbatim. Anything you POST you can paste into the wizard's import.

3. Saving and loading

Saving

Every plan you make with Plan it is kept by PowerSolver, with all its solutions: open Plans in the left menu (see the Wizard Guide). Step 7's Download button still gives you a <problem-type>.json file to keep in version control or share.

Loading (import)

Upload (left menu) accepts any problem JSON file; loading sets every step to match the file. Load a plan from Excel (step 1) loads a plan workbook. Files in the old 1.x format (top-level entities[] + valueRanges{}, chained variables, schedulingPattern: TIME_GRAIN) are refused with an explicit message: re-author them in the wizard.

4. Interpreting a solved solution

A POST /api/solve returns:

{
  "score": "0hard/-6soft",
  "feasible": true,
  "assignments": {"R1": ["T1", "T2", "T3"]},
  "shadows": {
    "T1": {"previous": null, "host": "R1", "startTime": "2026-06-01T08:00", "endTime": "2026-06-01T08:30"},
    "T2": {"previous": "T1", "host": "R1", "startTime": "2026-06-01T08:30", "endTime": "2026-06-01T09:15"},
    "T3": {"previous": "T2", "host": "R1", "startTime": "2026-06-01T09:15", "endTime": "2026-06-01T09:35"}
  }
}

Reading top to bottom:

  • score — 0hard/-6soft means feasible (no hard constraint violated) with a soft optimisation tally of 6 weighted units. The soft tally is only meaningful inside the same problem; comparing soft scores across problems isn't useful.
  • feasible — duplicate of "is hard tally 0". Always check this before consuming assignments.
  • assignments — one ordered list per host. The order is meaningful for sequence-mode problems (R1 does T1, then T2, then T3 in that order).
  • shadows — one entry per entity, keyed by entity id. Each value sub-map holds every shadow declared on the entity collection. Use it for downstream rendering: timetables, Gantt charts, route maps.

5. Common surprises

"Score: 0hard/0soft, but the assignments map is empty / partial"

If you have a list variable with allowsUnassigned: true (or its 1.x equivalent allowsUnassignedValues) but no hard unassigned_count constraint, the solver will satisfy the constraints by leaving everything unassigned — that's trivially 0hard/0soft.

Fix: add the hard unassigned_count constraint that the §5bis vocabulary expects:

{"name": "All entities assigned", "type": "hard", "rule": "unassigned_count",
 "params": {"inverse_field": "host"}, "weight": 100}

This is the most common "why is my solution empty" cause. The validator emits a warning when it detects a list variable without unassigned_count.

"I added a duration property but the supplier crashes"

The expression startTime + this.duration needs this.duration to be a Duration value at solve time, not a string. PowerSolver auto-coerces ISO-8601 strings ("PT45M", "PT1H30M") into Duration at problem-load time. Same for LocalDateTime strings on host properties.

If your duration is a plain number ("45" meaning minutes), either:

  • Convert it in your data prep to "PT45M", or
  • Adjust the expression to multiply: startTime + this.duration * 60. But this is brittle and the standard practice is to use ISO-8601 strings throughout.

"Validation says my expression references an unprefixed property"

The expression DSL requires every property access to be rooted at one of this, previous, next, host, index, or another shadow's name. A bare duration (without this.) is ambiguous and rejected.

Fix: prefix with this.:

"expression": "startTime + this.duration"  // not "startTime + duration"

"Validation says a derived-shadow source is missing"

Every property the expression reads must appear in sources. PowerSolver uses sources to schedule supplier evaluation — missing sources would mean the shadow is stale when read.

Fix: add the path:

{"name": "endTime",
 "sources": ["startTime", "this.duration"],   // both used in expression
 "expression": "startTime + this.duration"}

"Solve takes much longer than the budget"

config.timeoutSeconds caps the solver runtime, but the response is still synchronous over HTTP. Long timeouts (60s+) need a matching HTTP-client timeout on the caller side. The wizard's iframe sets its own progress UI; direct API callers should set timeout: timeoutSeconds + 30 to allow envelope serialisation.

For very large problems (hundreds of entities), expect the first POST per schema to take an extra few seconds for class generation; subsequent POSTs hit the cache. Restarting the container rebuilds the cache.

6. Tips for getting good solutions

Use realistic numbers

PowerSolver's minimize_property rule sums the property across all entities. Wildly different magnitudes between properties (priority 1–5 vs duration in seconds) bias the soft tally. Either keep magnitudes comparable or use different weights per constraint to compensate.

Hard constraints are binary

If unassigned_count is hard with weight 100, ONE unassigned entity makes the score -100hard/... — infeasible. The solver will work hard to clear hard constraints before optimising soft.

Soft weights are relative

weight: 1 vs weight: 10 shifts the solver's attention by 10×. Use this to express "I really care about priority ordering, less so about minor reshuffling."

Longer is not always better

Beyond a problem-specific point, doubling the timeoutSeconds doesn't double the score quality. The construction heuristic finishes quickly; local search saturates. Start at 5s, double until the soft tally stops improving meaningfully.

Pinned assignments freeze entities

Step 5 fixes the decisions of some items in advance (an operation already running, an exam already sat); the solver plans the others around them. A pin fixes all decisions of the item. If a value is never to be decided for any item — a class's teacher, a job's pre-assigned technician — it is not a pin but item data with a reference list: see Concepts guide §5b.

7. Where to go next