PowerSolver Wizard User Guide

This guide walks you through every screen of the Planning Wizard with detailed explanations, tips, and troubleshooting.

Overview

The Planning Wizard guides you through 7 steps to define and solve your planning problem:

┌─────────────────────────────────────────────────────────────────────────┐
│  Step 1    Step 2    Step 3    Step 4    Step 5    Step 6    Step 7    │
│  Define    List      Define    Define    Pinned    Solver    Review    │
│  Problem   Entities  Values    Rules     Assign    Settings  & Solve   │
└─────────────────────────────────────────────────────────────────────────┘

Getting Started

Login Screen

After logging in, you'll see the main dashboard.

Main Dashboard

The dashboard shows:

Sidebar Controls

Step 1: Define Your Problem

Purpose

Tell PowerSolver what kind of problem you're solving. This step configures the wizard for your specific use case.

Fields

Problem Type Options

Problem Type Info Card

When you select a problem type, an info card appears showing:

• Description of the problem type
• Examples of typical use cases
• Entity label (what you'll call your entities)
• Value label (what you'll call your values)

Buttons

Tips

• Be specific in your problem statement — the AI advisor uses this to give better suggestions
• If unsure which problem type to choose, start with "Generic (Custom)"
• Your problem statement and success criteria are saved but don't affect the solver directly

Common Issues

Step 2: What Needs Scheduling? (Entities)

Purpose

Enter the items that need to be assigned or scheduled. These are your planning entities.

Understanding Entities

The Entity Cards Interface

Each entity appears as a card with:

• ID (required) — Unique identifier
• Name (required) — Human-readable description
• Properties — Additional fields based on problem type

Adding Entities

Method 1: Add One at a Time

1. Click "Add Item" button
2. Fill in the card fields
3. Click ✓ to save or ✗ to cancel

Method 2: Import from File

1. Click "Import from File" button
2. Select Excel (.xlsx), CSV, or JSON file
3. Map your columns to PowerSolver fields
4. Review preview and click "Import Items"

Entity Properties

Custom Properties

In addition to standard properties, PowerSolver supports custom properties for domain-specific data.

How Custom Properties Work

1. Detection: Custom properties in your JSON are auto-detected
2. Display: New fields are created for each custom property
3. Editing: Edit custom property values just like standard fields
4. Preservation: Custom properties are saved and exported correctly

Examples by Domain

Card Actions

Pinned Assignments (Preview)

Check the 🔒 Pinned checkbox and select a value in "Pre-Assign To" to lock an assignment. The solver will not change pinned assignments.

Common Issues

Step 3: Who or What Can Do It? (Values)

Purpose

Enter the resources that entities can be assigned to. These are your planning values.

Understanding Values and Variables

PowerSolver supports 1-4 value ranges (planning variables):

Each value range appears as a separate tab or section.

Value Properties

Custom Properties on Values

Values also support custom properties that define their capabilities:

Matching Entity and Value Properties

Custom properties create a matching relationship:

Entity (Workload):                    Value (Server):
├── requiredResourceType: "gpu"  ←→  resourceTypes: ["gpu", "cpu"]
├── cpuRequired: 16              ←→  cpuCores: 32
└── memoryRequired: 64           ←→  memoryGB: 128

Tips

• Ensure value skills cover all entity requirements
• Set realistic capacity values
• For time slots, ensure you have enough to cover all entities

Common Issues

Step 4: What Are Your Rules? (Constraints)

Purpose

Define the rules your solution must follow. These are your constraints.

Constraint Levels

Adding Constraints

1. Click the appropriate tab (Hard/Medium/Soft)
2. Click "Add Constraint"
3. Fill in the constraint form:

Available Constraint Rules

Configuring Constraints with Custom Properties

When using custom properties (defined in Steps 2 and 3), you need to tell the constraint which property names to use:

Skill Constraint with Custom Properties

For the skill rule, expand the constraint card to see additional fields:

Example Configuration

Name: Resource Type Match
Rule: skill
Target Variable: server
Entity Skills Property: requiredResourceType
Value Skills Property: resourceTypes
Weight: 10

This constraint ensures entities with requiredResourceType: "gpu" are only assigned to values where resourceTypes contains "gpu".

Constraint Property Reference

Weight Guidelines

Tips

• Start with hard constraints (must-haves)
• Add unassigned constraint to ensure all entities get assigned
• Use weights to prioritize within the same level
• Test with fewer constraints first, then add more

Common Issues

Step 5: Any Pre-Decisions? (Pinned Assignments)

Purpose

Review and manage pinned assignments — entities that are already assigned and should not be changed by the solver.

When to Use Pinning

How Pinning Works

1. In Step 2: Check the 🔒 Pinned checkbox on an entity card
2. In Step 2: Select the pre-assigned value
3. In Step 5: Review all pinned assignments

The solver will never change a pinned assignment.

Tips

• Only pin what's truly fixed
• Too many pins limit solver flexibility
• Check that pins don't conflict with hard constraints

Common Issues

Step 6: How Long Should We Search? (Solver Settings)

Purpose

Configure how long the solver should run and other optimization settings.

Time Presets

Problem Size Summary

The wizard shows a summary of your problem:

Entities: 20 tasks
Values: 6 developers × 10 timeslots
Constraints: 5 hard, 3 soft
Recommended timeout: 120 seconds

Custom Time Setting

If you select Custom:

1. Use the slider to set timeout (10-600 seconds)
2. Or type a specific value in the input box
3. Maximum: 3600 seconds (1 hour)

Timeout Guidelines

Tips

• Longer timeouts generally produce better solutions
• Diminishing returns after a certain point
• Start with Standard, adjust based on results
• For testing, use Quick to verify setup

Common Issues

Step 7: Review & Validate JSON

Purpose

Final review of your problem configuration. Validate, optionally improve with AI, and solve.

The JSON Editor

The large text area shows your complete problem as JSON. You can:

• Review the configuration
• Make manual edits if needed
• Copy the JSON for external use

Validation

Click "Validate JSON" to check for errors:

Common Validation Errors

AI Improvement Feature

Click "Improve with AI" to get AI-powered suggestions:

1. AI analyzes your problem
2. Shows loading indicator while processing
3. Displays improvement suggestions
4. Shows improved JSON for comparison

Solving from Step 7

After validation succeeds, you can:

1. Click "Done" to close the wizard
2. On the main dashboard, click "Solve" button
3. Or use the API to submit the problem

Solution View

After solving, view your results:

Solution Summary

Score Interpretation

Score: 0hard / -2medium / -450soft
       │        │          │
       │        │          └── Soft penalties (lower is better)
       │        └── Medium violations
       └── Hard violations (must be 0!)

Export Options

Domain Attributes Registry

What is the Domain Attributes Registry?

The Domain Attributes Registry is a central panel that appears in Steps 2 and 3 of the wizard. It allows you to:

• Define custom attributes for entities and values
• Select attributes from dropdowns when configuring constraints
• Validate that your data has the required properties
• Track which attributes are used in constraints

Why Use Domain Attributes?

The Three-Step Connection

Domain Attributes create a powerful link between Steps 2, 3, and 4:

┌─────────────────────────────────────────────────────────────────────┐
│                                                                     │
│  STEP 2: Entities        STEP 3: Values        STEP 4: Constraints │
│                                                                     │
│  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐ │
│  │ Entity          │    │ Value           │    │ Constraint      │ │
│  │ Attributes      │    │ Attributes      │    │ Properties      │ │
│  │                 │    │                 │    │                 │ │
│  │ • cpuRequired   │───▶│ • cpuCapacity   │───▶│ demandProperty: │ │
│  │ • memoryReq     │───▶│ • memoryCapacity│    │   cpuRequired   │ │
│  │ • requiredType  │───▶│ • resourceTypes │    │ capacityProp:   │ │
│  └─────────────────┘    └─────────────────┘    │   cpuCapacity   │ │
│                                                 └─────────────────┘ │
│  Requirements           Capabilities           Rules               │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Using the Domain Attributes Panel

Location

The Domain Attributes panel appears at the top of:

• Step 2 (What Needs Scheduling?) — For entity attributes
• Step 3 (Who or What Can Do It?) — For value attributes

[Screenshot: Domain Attributes Panel]

Panel Structure

┌─────────────────────────────────────────────────────────────────────┐
│ ⚙️ Domain Attributes (8)                                      ▼    │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│ 📦 Entity Attributes                                      [+ Add]  │
│ ─────────────────────────────────────────────────────────────────  │
│ cpuRequired         Number (cores)       🔗1  ✓4/4   [✏️] [🗑️]   │
│ memoryRequired      Number (GB)          🔗1  ✓4/4   [✏️] [🗑️]   │
│ gpuRequired         Number (units)            ✓4/4   [✏️] [🗑️]   │
│ requiredResourceType Text                🔗1  ✓4/4   [✏️] [🗑️]   │
│                                                                     │
│ 🖥️ Value Attributes                                       [+ Add]  │
│ ─────────────────────────────────────────────────────────────────  │
│ cpuCapacity         Number (cores)       🔗1  ✓3/3   [✏️] [🗑️]   │
│ memoryCapacity      Number (GB)          🔗1  ✓3/3   [✏️] [🗑️]   │
│ gpuCount            Number (units)            ✓3/3   [✏️] [🗑️]   │
│ resourceTypes       List                 🔗1  ✓3/3   [✏️] [🗑️]   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Status Badges

Adding an Attribute

1. Click + Add next to "Entity Attributes" or "Value Attributes"
2. Fill in the modal form:

3. Click Save

[Screenshot: Add Attribute Modal]

Attribute Types

Using Attributes in Constraints (Step 4)

When you configure a constraint that uses property fields:

1. Dropdowns appear instead of text inputs
2. All defined attributes are shown as options
3. Type labels help you select the right one
4. Empty warning prompts you to define attributes first

[Screenshot: Constraint Dropdown Selection]

Constraint Fields That Use Domain Attributes

Best Practices

Naming Conventions

Migration from Existing JSON

When you import a JSON file created before Domain Attributes:

1. Auto-detection: Custom properties are automatically detected
2. Migration: Properties are added to the registry
3. No action needed: Your existing files work seamlessly

Troubleshooting Domain Attributes

Navigation Tips

Progress Indicator

The step indicator at the top of each modal shows your progress:

[Step 1] ─ [Step 2] ─ [Step 3] ─ [Step 4] ─ [Step 5] ─ [Step 6] ─ [Step 7]
   ●          ●          ○          ○          ○          ○          ○
completed  active    upcoming

Saving Your Work

Your work is saved when you:

• Click "Save" on any step
• Click "Next" to proceed
• The wizard auto-saves periodically

Going Back

You can always go back to previous steps:

• Click "Previous" button
• Click on a completed step in the progress indicator

Keyboard Shortcuts

Custom Properties Reference

This section provides a complete reference for using custom properties throughout the Planning Wizard.

What Are Custom Properties?

Custom properties are domain-specific attributes that go beyond standard fields. They allow you to model any type of planning problem with your own terminology and data structures.

Automatic Detection

When you load a JSON file or import data, the wizard automatically detects custom properties:

1. Scans all entities and values for non-standard property names
2. Determines the appropriate field type based on data
3. Creates editable fields in the card UI
4. Preserves all properties during save/export

Field Type Detection

Property Naming Best Practices

Complete Constraint Properties Reference

Each constraint type can reference custom properties. Here's the complete reference:

Skill Constraints

Default: skills ↔ skills | Example: requiredResourceType ↔ resourceTypes

Capacity Constraints

Defaults: capacity, demand (or count if null)

Cost Constraints

Defaults: duration, hourlyRate

Time Constraints

Location Constraints

Defaults: location, location

Dependency Constraints

Default: dependsOn

Preference Constraints

Defaults: preferredValues, unavailableValues

Group Constraints

Default: groupId

Conditional Constraints

Pairing Constraints

Default: compatibleWith

List Variable Constraints

End-to-End Example: Cloud Capacity Planning

{
  "id": "WL-ML",
  "properties": {
    "name": "ML Training Pipeline",
    "requiredResourceType": "gpu",
    "cpuRequired": 16,
    "memoryRequired": 64,
    "gpuRequired": 2
  }
}

{
  "id": "SRV-GPU",
  "properties": {
    "name": "GPU Server",
    "resourceTypes": ["gpu"],
    "cpuCores": 32,
    "memoryGB": 128,
    "gpuCount": 4
  }
}

Step 4 - Constraint

{
  "name": "Resource Type Match",
  "type": "hard",
  "rule": "skill",
  "targetVariableId": "server",
  "entitySkillsProperty": "requiredResourceType",
  "valueSkillsProperty": "resourceTypes",
  "weight": 10
}

Custom Properties Troubleshooting

Data Flow Diagram

┌─────────────────────────────────────────────────────────────────────────────┐
│                        CUSTOM PROPERTIES DATA FLOW                          │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐                  │
│  │  JSON File   │───▶│ Wizard State │───▶│  Card UI     │                  │
│  │  (Import)    │    │ (Memory)     │    │  (Display)   │                  │
│  └──────────────┘    └──────────────┘    └──────────────┘                  │
│         │                   │                   │                           │
│         ▼                   ▼                   ▼                           │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐                  │
│  │ Auto-Detect  │    │  Preserve    │    │  Edit & Save │                  │
│  │ Properties   │    │  All Props   │    │  Properties  │                  │
│  └──────────────┘    └──────────────┘    └──────────────┘                  │
│         │                   │                   │                           │
│         └───────────────────┼───────────────────┘                           │
│                             ▼                                               │
│                    ┌──────────────┐                                         │
│                    │ Export JSON  │───▶ Solver (Uses Constraints)           │
│                    │ (All Props)  │                                         │
│                    └──────────────┘                                         │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Troubleshooting

Wizard Won't Open

Lost My Work

AI Features Not Working

Validation Keeps Failing

Quick Reference

Step Summary

Button Reference

Next Steps

• Quick Start Guide — Step-by-step tutorials
• Concepts Guide — Understanding planning concepts
• User Guide — Complete reference

Support

• Click the ? icon in any step for context help
• Use the AI Advisor panel for suggestions
• Email: support@planningpowertools.com