Planning and Validation

Overview

This section explains how workflows are validated, planned, and optimized in the LINQ SDK.

Validation

Validation ensures your workflow is structurally correct and free of configuration errors.
Planning uses the Intelligent Scheduling Engine to generate an optimized execution schedule for a workcell.

Validation must succeed before planning can occur.

Planning may incorporate:

Hard constraints (dependencies and time constraints)
Soft timing preferences (planning_targets)
Optimization configuration (PlannerOptions or sequential Optimization Stages)

Validation

Validation checks structural, deterministic, and configuration-level characteristics of a workflow to ensure it can be planned.

Validation occurs in the LINQ Cloud environment.

Validation does not guarantee successful execution — it guarantees the workflow is structurally plannable.

Warning

Validation does not guarantee a workflow will run without issue.

Validation via Python

workflow = Workflow(...)

result = linq.validate_workflow(workflow)

Optional execution-level validation

result = linq.validate_workflow(workflow, validate_for_execution=True)

Validation via CLI

linq workflow validate <path>

Optional flags:

linq workflow validate <path> --validate-drivers
linq workflow validate <path> --validate-infeasibility

What Is Validated?

Core Workflow Structure

Task dependencies are logically consistent (no circular references)
Time constraints are feasible
Slots are correctly defined and non-conflicting
Required configuration values are present

Timing Targets (`planning_targets`)

If planning_targets are defined:

Referenced task IDs must exist
Anchor edges (start / end) must be valid
Span definitions must conform to schema
TaskEdgeSpan and TaskEdgeReference structures must be valid

Timing Targets are validated structurally but do not affect feasibility — they influence optimization only.

Execution / Driver Validation (Optional)

When validating for execution:

Instrument configurations must match driver requirements
Driver versions must exist
Transport definitions must be valid
Instruments configured with "simulate": true do not require hardware driver initialization for execution-level validation.

Instruments marked with "simulate": true are treated as available without initializing hardware drivers. This affects execution-level validation only. Structural validation, feasibility checks, and planning behavior remain unchanged.

Planning

Planning is the process by which the Intelligent Scheduling Engine converts a validated workflow into a concrete execution plan.

Each planning invocation may produce a different valid schedule depending on:

Optimization objectives
Search behavior
Computation limits
Soft preferences (Timing Targets)

All hard constraints are always satisfied.

Planning produces a single execution plan.

Note

Successful planning guarantees deadlock-free execution by resolving all resource conflicts before deployment.

Workflow Inputs to Planning

The scheduling engine operates on the following workflow-level inputs:

1. Tasks

Executable actions on instruments or transport systems.

2. Dependencies

Hard ordering relationships between tasks.

3. Time Constraints

Hard timing relationships between task edges.

These must always be satisfied.

4. Timing Targets (Soft Preferences)

Defined using planning_targets.

Timing Targets:

Express preferred timing relationships between task edges
Influence optimization without affecting feasibility
Are treated as soft objectives

Example:

workflow = Workflow(
    ...,
    planning_targets={
        "peel_consistency": [
            TaskEdgeSpan(
                anchor_a=TaskEdgeReference(task_id=task_a.id, edge="end"),
                anchor_b=TaskEdgeReference(task_id=task_b.id, edge="start"),
            )
        ]
    },
)

Optimization Configuration

Planning behavior can be configured using either:

PlannerOptions (single-stage optimization), or
Optimization Stages (sequential multi-stage optimization)

These approaches should not be combined for conflicting objective control.

PlannerOptions (Single-Stage Optimization)

PlannerOptions configure a single optimization pass.

options = Options(
    planner=PlannerOptions(
        target_objective=7200,
        max_computation_time=200,
        max_dead_time=5,
        round_robin_load_balancing=True,
        preset="PROD_LARGE",
        optimisation_target="balance_total_plan_duration_and_labware_idle_time",
    )
)

PlannerOptions allow you to control:

Objective targets
Computation time limits
Dead time limits
Load balancing behavior
Preset optimization profiles
Optimization strategy

This configuration performs one optimization stage.

Optimization Stages (Advanced Configuration)

Optimization Stages enable sequential multi-objective optimization.

Each stage defines:

An objective
Stopping conditions
A carry-forward rule

Stages execute in order. Each stage refines the plan produced by the previous stage.

OptimizationStage Schema

class OptimisationStage(BaseModel):
    objective: Objective
    stop_at: StoppingConditions
    carry_forward_rule: ObjectivePreservationTarget

Objective Enum Values

Supported objective values:

"makespan" — Minimize total plan duration
"deadtime" — Minimize idle time
"timing_targets" — Optimize alignment with Timing Targets
"consistency" — Optimize schedule consistency metrics
"slack" — Optimize timing slack

Each stage optimizes one objective.

Stopping Conditions

Control when a stage ends.

class StoppingConditions(BaseModel):
    max_computation_time: Optional[float]
    improvement_timer_limit: int
    target_objective: Optional[float]

max_computation_time

Stop after N seconds.

improvement_timer_limit

Stop if no better solution is found within N seconds.

target_objective

Stop when objective value reaches a specified threshold.

A stage ends when any stopping condition is met.

Carry-Forward Rule

Controls how subsequent stages may affect prior objectives.

class ObjectivePreservationTarget(str, Enum):
    LOCK
    SAME_OR_BETTER
    WITHIN_1_PERCENT
    WITHIN_5_PERCENT
    WITHIN_10_PERCENT

Behavior

LOCK — Objective cannot degrade
SAME_OR_BETTER — Must remain equal or improved
WITHIN_1_PERCENT — May degrade up to 1%
WITHIN_5_PERCENT — May degrade up to 5%
WITHIN_10_PERCENT — May degrade up to 10%

This enables controlled multi-objective tradeoffs.

Interaction Between Timing Targets and Optimization Stages

Timing Targets are soft preferences that influence optimization but do not affect feasibility.

They may be optimized in two ways:

Indirectly, via PlannerOptions optimization targets
Directly, by defining an Optimization Stage with the objective "timing_targets"

Optimization Stages allow you to explicitly control how Timing Targets are prioritized relative to other objectives such as makespan or deadtime.

Example multi-stage strategy:

Minimize makespan (LOCK)
Optimize timing_targets (WITHIN_5_PERCENT)
Reduce deadtime (SAME_OR_BETTER)

In this configuration:

The first stage minimizes total duration and locks it.
The second stage improves alignment with Timing Targets without degrading makespan beyond the allowed threshold.
The third stage reduces idle time while preserving prior objectives.

Hard constraints (dependencies and time constraints) are always enforced.

Timing Targets never invalidate feasibility.

Working with Plans

The lifecycle of initiating a workflow is as follows:

Validate
Create
Plan
Publish
Deploy
Start

Validate Workflow

linq workflow validate --path=quickstart.py --workflow=workflow

Create Workflow

Creating a workflow stages the workflow in the LINQ API, making it available to the planner and other downstream functions.

linq workflow create --path=quickstart.py --workflow=workflow

This returns a workflow ID.

To view staged workflows:

linq workflow list

Start Plan

To start a plan:

linq workflow plan start --workflow-id=<workflow-id>

Check Plan Status

To check the current progress of your plan:

linq workflow plan status --workflow-id=<workflow-id> --plan-id=<plan-id>

Plan statuses are:

PLANNING — the plan is currently being computed.
COMPLETED — the plan was computed successfully.
FAILED — the plan could not be computed.

Retrieve Plan Result

Once the plan is complete, retrieve the task execution details:

linq workflow plan result --workflow-id=<workflow-id> --plan-id=<plan-id>

Optional flags:

--watch
--silent
--metrics

--watch polls for updates.
--silent suppresses terminal output.
--metrics includes detailed performance metrics.

List Plans

To view all running and completed plans:

linq workflow plan list

To filter by workflow:

linq workflow plan list --workflow-id <workflow-id>

Plan Metrics

When using the --metrics flag with:

linq workflow plan result --workflow-id=<workflow-id> --plan-id=<plan-id> --metrics

Available metrics include:

total_plan_duration
plan_solve_duration
create_model_duration
search_duration
time_to_feasible
total_deadtime
batches_requested
instrument_utilization
times
solutions

These metrics provide insight into model build time, search time, solution quality progression, and overall workflow efficiency.

Visualizations

To visualize a plan’s output in instrument-centric or labware-centric utilization Gantt chart views, use:

--visualize instrument
--visualize labware

These views help you analyze resource utilization and workflow timing.

Scheduler Versioning

Every workflow can be pinned to a specific scheduler version.

To view available scheduler versions:

linq scheduler-versions

Pin a workflow to a specific scheduler version using the appropriate CLI option during workflow creation or planning.

Pinning a scheduler version allows you to freeze behavior for reproducibility while still allowing new workflows to use the latest scheduler improvements.

Replanning

Replanning occurs when the original plan no longer aligns with real-time execution.

Replanning may be triggered by:

Inaccurate task duration estimates
Runtime errors
Conditional branch outcomes that differ from expectations

Replanning happens locally on the workcell and leverages prior solve information to compute updates efficiently.

To reduce replanning, ensure accurate task time estimates.

Summary

Planning in LINQ:

Enforces all hard constraints (dependencies and time constraints)
Supports soft timing preferences via planning_targets
Enables advanced staged optimization with controlled tradeoffs
Produces a single executable plan
Guarantees deadlock-free scheduling

Planning and Validation

Overview

Validation

Validation

Validation via Python

Optional execution-level validation

Validation via CLI

What Is Validated?

Core Workflow Structure

Timing Targets (planning_targets)

Execution / Driver Validation (Optional)

Planning

Workflow Inputs to Planning

1. Tasks

2. Dependencies

3. Time Constraints

4. Timing Targets (Soft Preferences)

Optimization Configuration

PlannerOptions (Single-Stage Optimization)

Optimization Stages (Advanced Configuration)

OptimizationStage Schema

Objective Enum Values

Stopping Conditions

max_computation_time

improvement_timer_limit

target_objective

Carry-Forward Rule

Behavior

Interaction Between Timing Targets and Optimization Stages

Working with Plans

Validate Workflow

Create Workflow

Start Plan

Check Plan Status

Retrieve Plan Result

List Plans

Plan Metrics

Visualizations

Scheduler Versioning

Replanning

Summary

Timing Targets (`planning_targets`)