Interop

Helper functions for bridging pycsp3-scheduling with pycsp3.

Functions

start_time

pycsp3_scheduling.interop.start_time(interval)

Return a pycsp3 variable representing the start time.

end_time

pycsp3_scheduling.interop.end_time(interval)

Return a pycsp3 expression representing the end time (start + length).

presence_time

pycsp3_scheduling.interop.presence_time(interval)

Return a pycsp3 variable representing presence (0/1) for optional intervals.

interval_value

pycsp3_scheduling.interop.interval_value(interval)

Extract the solution values for an interval after solving.

Returns an IntervalValue with ‘start’, ‘end’, ‘length’, ‘present’ fields, or None if the interval is absent (for optional intervals).

Parameters:

interval (IntervalVar) – The interval variable to extract values from.

Returns:

IntervalValue with start/end/length/present values, or None if absent.

Return type:

IntervalValue | None

Example

>>> task = IntervalVar(size=10, name="task")
>>> # ... add constraints and solve ...
>>> vals = interval_value(task)
>>> print(f"start={vals.start}, end={vals.end}")

model_statistics

pycsp3_scheduling.interop.model_statistics()

Return statistics about the current scheduling model.

solution_statistics

pycsp3_scheduling.interop.solution_statistics(intervals=None, *, status=None, objective=None, solve_time=None)

Return statistics about the current solution.

Parameters:

• intervals (Sequence[IntervalVar] | None) – Optional list of intervals to analyze. Defaults to the registered intervals.

• status (object | None) – Optional solve status from pycsp3 (SAT, OPTIMUM, UNSAT, etc.).

• objective (Any | None) – Optional objective expression or value to evaluate.

• solve_time (float | None) – Optional elapsed solve time in seconds.

Classes

IntervalValue

class pycsp3_scheduling.interop.IntervalValue(start, length, present=True, name=None)

Solved interval values with dict-like and attribute access.

start: int

length: int

present: bool = True

name: str | None = None

property end: int

End time of the interval.

to_dict()

Return a plain dict representation.

__init__(start, length, present=True, name=None)

ModelStatistics

class pycsp3_scheduling.interop.ModelStatistics(nb_interval_vars, nb_optional_interval_vars, nb_sequences, nb_sequences_with_types, nb_cumul_functions, nb_state_functions)

Statistics about the scheduling model.

nb_interval_vars: int

nb_optional_interval_vars: int

nb_sequences: int

nb_sequences_with_types: int

nb_cumul_functions: int

nb_state_functions: int

to_dict()

Return a plain dict representation.

__init__(nb_interval_vars, nb_optional_interval_vars, nb_sequences, nb_sequences_with_types, nb_cumul_functions, nb_state_functions)

SolutionStatistics

class pycsp3_scheduling.interop.SolutionStatistics(status, objective_value, solve_time, nb_interval_vars, nb_intervals_present, nb_intervals_absent, min_start, max_end, makespan, span)

Statistics about the solved schedule.

status: object | None

objective_value: int | float | None

solve_time: float | None

nb_interval_vars: int

nb_intervals_present: int

nb_intervals_absent: int

min_start: int | None

max_end: int | None

makespan: int | None

span: int | None

to_dict()

Return a plain dict representation.

__init__(status, objective_value, solve_time, nb_interval_vars, nb_intervals_present, nb_intervals_absent, min_start, max_end, makespan, span)

Function Reference

Function	Returns	Description
start_time(interval)	pycsp3 Variable	Start time variable for pycsp3 constraints
end_time(interval)	pycsp3 Expression	End time expression (start + length)
presence_time(interval)	pycsp3 Variable	Presence variable (0/1) for optional intervals
interval_value(interval)	IntervalValue or None	Solution values after solving
model_statistics()	ModelStatistics	Counts for registered scheduling objects
solution_statistics(...)	SolutionStatistics	Summary stats for solved intervals

Usage Examples

Using in pycsp3 Constraints

from pycsp3 import satisfy, minimize, Maximum
from pycsp3_scheduling import IntervalVar, start_time, end_time

tasks = [IntervalVar(size=10, name=f"task{i}") for i in range(3)]

# Use start_time/end_time in pycsp3 expressions
# Minimize makespan
minimize(Maximum(end_time(task) for task in tasks))

# Custom constraint: all tasks must start before time 100
for task in tasks:
    satisfy(start_time(task) <= 100)

Extracting Solution Values

from pycsp3 import solve, SAT, OPTIMUM
from pycsp3_scheduling import IntervalVar, interval_value

task = IntervalVar(size=10, name="task")
optional_task = IntervalVar(size=10, optional=True, name="optional")

# ... add constraints ...

if solve() in (SAT, OPTIMUM):
    # Regular task
    result = interval_value(task)
    print(f"Task: start={result.start}, end={result.end}, length={result.length}")
    
    # Optional task (may be absent)
    result = interval_value(optional_task)
    if result is None:
        print("Optional task was not scheduled (absent)")
    else:
        print(f"Optional task: start={result.start}, end={result.end}")

Working with Presence Variables

from pycsp3 import satisfy, Sum
from pycsp3_scheduling import IntervalVar, presence_time

optional_tasks = [IntervalVar(size=10, optional=True, name=f"opt{i}") 
                  for i in range(5)]

# At least 3 optional tasks must be scheduled
satisfy(Sum(presence_time(task) for task in optional_tasks) >= 3)

# Two optional tasks must be scheduled together or not at all
task_a, task_b = optional_tasks[0], optional_tasks[1]
satisfy(presence_time(task_a) == presence_time(task_b))

Return Value Format

The interval_value() function returns an IntervalValue with the following fields:

{
    'start': int,     # Start time of the interval
    'end': int,       # End time of the interval
    'length': int,    # Duration/length of the interval
    'present': bool,  # True if interval is present (always True for non-optional)
}

IntervalValue supports attribute access (result.start) and dict-like access (result['start']) for compatibility.

For optional intervals that are absent, interval_value() returns None.

Statistics Examples

from pycsp3 import solve, SAT, OPTIMUM, Maximum, minimize
from pycsp3_scheduling import (
    IntervalVar,
    end_time,
    interval_value,
    model_statistics,
    solution_statistics,
)

tasks = [IntervalVar(size=10, name=f"task{i}") for i in range(3)]
objective = Maximum(end_time(t) for t in tasks)
minimize(objective)

print(model_statistics())

if solve() in (SAT, OPTIMUM):
    stats = solution_statistics(objective=objective)
    print(stats)

Notes:

• model_statistics() reports registered scheduling objects. Interval variables and state functions are registered automatically; cumulative functions can be registered explicitly with register_cumul() when needed.

• solution_statistics() evaluates interval values, so call it after a successful solve.

Important Notes

1. Use start_time()/end_time() for pycsp3 expressions (objectives, custom constraints)

2. Use start_of()/end_of() for internal IntervalExpr objects (scheduling expressions)

3. Always check for None when reading optional intervals with interval_value()

4. Call interval_value() only after solving (after solve() returns SAT/OPTIMUM)