metacsp

The subset of the meta-CSP framework that coordination_oru exercises at runtime: poses, trajectories, trajectory envelopes, and a Simple Temporal Problem solver.

coordination_oru.metacsp.spatial.pose

Spatial primitives: Pose and PoseSteering.

Mirrors the metaCSP Pose/PoseSteering classes. Java-named accessors (getX(), distanceTo(), interpolate(), ...) are provided so ported coordinator code reads like the Java original; the pythonic attribute access (pose.x) remains available.

Pose dataclass

x instance-attribute

y instance-attribute

theta instance-attribute

z = math.nan class-attribute instance-attribute

roll = math.nan class-attribute instance-attribute

pitch = math.nan class-attribute instance-attribute

is_3d()

distance_xy(other)

getX()

getY()

getTheta()

distanceTo(other)

interpolate(other, ratio)

Linear interpolation towards other; theta via shortest arc.

PoseSteering dataclass

A pose with the steering angle the robot should apply at that pose.

pose instance-attribute

steering = 0.0 class-attribute instance-attribute

getPose()

getSteering()

getX()

getY()

getTheta()

_lerp_angle(a, b, t)

Shortest-arc interpolation between two angles in radians.

coordination_oru.metacsp.spatial.trajectory

Trajectory: the path view of a trajectory envelope.

Mirrors the metaCSP Trajectory class just enough for the coordinator code, which accesses paths via te.getTrajectory().getPose()[i] and te.getTrajectory().getPoseSteering().

Pose dataclass

x instance-attribute

y instance-attribute

theta instance-attribute

z = math.nan class-attribute instance-attribute

roll = math.nan class-attribute instance-attribute

pitch = math.nan class-attribute instance-attribute

is_3d()

distance_xy(other)

getX()

getY()

getTheta()

distanceTo(other)

interpolate(other, ratio)

Linear interpolation towards other; theta via shortest arc.

PoseSteering dataclass

A pose with the steering angle the robot should apply at that pose.

pose instance-attribute

steering = 0.0 class-attribute instance-attribute

getPose()

getSteering()

getX()

getY()

getTheta()

Trajectory

getPoseSteering()

getPose()

coordination_oru.metacsp.spatial.trajectory_envelope

Trajectory envelope: a swept-area polygon plus its STP timing variables.

A :class:TrajectoryEnvelope is the runtime unit the coordinator reasons over. It bundles:

• The full path the robot intends to follow (tuple[PoseSteering, ...]).
• The robot id that owns it.
• Two STP node indices (start_node and end_node) that participate in the all-pairs distance matrix.
• The :class:SpatialEnvelope — the union of per-waypoint footprints, plus the per-waypoint footprints themselves so we can localise where two envelopes start to interfere.

Java-named accessors (getRobotID(), getTrajectory(), makeFootprint(), ...) are provided so the ported coordinator code reads like the Java original. Envelope identity (__eq__/__hash__) is by envelope_id, matching Java object identity of metaCSP variables.

Pose dataclass

x instance-attribute

y instance-attribute

theta instance-attribute

z = math.nan class-attribute instance-attribute

roll = math.nan class-attribute instance-attribute

pitch = math.nan class-attribute instance-attribute

is_3d()

distance_xy(other)

getX()

getY()

getTheta()

distanceTo(other)

interpolate(other, ratio)

Linear interpolation towards other; theta via shortest arc.

PoseSteering dataclass

A pose with the steering angle the robot should apply at that pose.

pose instance-attribute

steering = 0.0 class-attribute instance-attribute

getPose()

getSteering()

getX()

getY()

getTheta()

Trajectory

getPoseSteering()

getPose()

SpatialEnvelope dataclass

Pre-computed swept geometry of an envelope's path.

Mirrors Java's TrajectoryEnvelope.SpatialEnvelope (polygon + path + footprint), with the per-waypoint footprints cached in addition.

geometry instance-attribute

footprints instance-attribute

path instance-attribute

footprint instance-attribute

getPolygon()

getPath()

getFootprint()

TrajectoryEnvelope dataclass

A robot's planned trajectory expressed as an STP-aware swept envelope.

envelope_id is assigned by the :class:~coordination_oru.metacsp.spatial.trajectory_envelope_solver.TrajectoryEnvelopeSolver that creates it; start_node / end_node are the STP variable indices for this envelope's start and end times.

envelope_id instance-attribute

robot_id instance-attribute

path instance-attribute

start_node instance-attribute

end_node instance-attribute

spatial_envelope instance-attribute

footprint instance-attribute

component = 'Driving' class-attribute instance-attribute

nominal_duration = 0.0 class-attribute instance-attribute

completed = False class-attribute instance-attribute

metadata = field(default_factory=dict) class-attribute instance-attribute

length property

pose_at(index)

waypoint_footprint(index)

getID()

getRobotID()

getPathLength()

getSpatialEnvelope()

getFootprint()

getTrajectory()

makeFootprint(ps)

getComponent()

getSequenceNumberStart()

getSequenceNumberEnd()

getSequenceNumber(x, y)

Index of the path point closest to (x, y).

Mirrors Java's getSequenceNumber(Coordinate) used to locate stopping points along the path.

place_footprint(footprint, pose)

Rotate footprint (centered at origin) by theta then translate to pose.

compute_spatial_envelope(path, footprint)

Sweep footprint along path and union the result.

coordination_oru.metacsp.spatial.trajectory_envelope_solver

Registry that owns trajectory envelopes and wires them to the STP network.

This is the surface the coordinator uses to:

• Create a new envelope from a path + footprint.
• Add ordering constraints between two envelopes (A BEFORE B, etc).
• Query the earliest/latest start/end of any envelope.
• Mark an envelope as completed (releases its STP variables in spirit; we keep the matrix nodes but flag the envelope as inactive so the coordination loop ignores it).

The original Java TrajectoryEnvelopeSolver also exposes Allen-relation metaprogramming. We expose a thin add_allen_constraint helper for the small subset the coordinator actually exercises.

Pose dataclass

x instance-attribute

y instance-attribute

theta instance-attribute

z = math.nan class-attribute instance-attribute

roll = math.nan class-attribute instance-attribute

pitch = math.nan class-attribute instance-attribute

is_3d()

distance_xy(other)

getX()

getY()

getTheta()

distanceTo(other)

interpolate(other, ratio)

Linear interpolation towards other; theta via shortest arc.

PoseSteering dataclass

A pose with the steering angle the robot should apply at that pose.

pose instance-attribute

steering = 0.0 class-attribute instance-attribute

getPose()

getSteering()

getX()

getY()

getTheta()

TrajectoryEnvelope dataclass

A robot's planned trajectory expressed as an STP-aware swept envelope.

envelope_id is assigned by the :class:~coordination_oru.metacsp.spatial.trajectory_envelope_solver.TrajectoryEnvelopeSolver that creates it; start_node / end_node are the STP variable indices for this envelope's start and end times.

envelope_id instance-attribute

robot_id instance-attribute

path instance-attribute

start_node instance-attribute

end_node instance-attribute

spatial_envelope instance-attribute

footprint instance-attribute

component = 'Driving' class-attribute instance-attribute

nominal_duration = 0.0 class-attribute instance-attribute

completed = False class-attribute instance-attribute

metadata = field(default_factory=dict) class-attribute instance-attribute

length property

pose_at(index)

waypoint_footprint(index)

getID()

getRobotID()

getPathLength()

getSpatialEnvelope()

getFootprint()

getTrajectory()

makeFootprint(ps)

getComponent()

getSequenceNumberStart()

getSequenceNumberEnd()

getSequenceNumber(x, y)

Index of the path point closest to (x, y).

Mirrors Java's getSequenceNumber(Coordinate) used to locate stopping points along the path.

AllenType

Bases: Enum

BEFORE = auto() class-attribute instance-attribute

MEETS = auto() class-attribute instance-attribute

OVERLAPS = auto() class-attribute instance-attribute

STARTS = auto() class-attribute instance-attribute

DURING = auto() class-attribute instance-attribute

FINISHES = auto() class-attribute instance-attribute

EQUALS = auto() class-attribute instance-attribute

AFTER = auto() class-attribute instance-attribute

MET_BY = auto() class-attribute instance-attribute

OVERLAPPED_BY = auto() class-attribute instance-attribute

STARTED_BY = auto() class-attribute instance-attribute

CONTAINS = auto() class-attribute instance-attribute

FINISHED_BY = auto() class-attribute instance-attribute

Bounds

Bases: NamedTuple

Closed temporal interval. ub may be math.inf for unbounded.

lb instance-attribute

ub instance-attribute

intersect(other)

is_singleton()

STPSolver

All-pairs-shortest-path STP solver.

The distance matrix _d has shape (max_nodes, max_nodes); only the top-left (_n, _n) block is meaningful. _d[i, j] is the tightest known upper bound on x_j - x_i.

num_variables property

new_variable()

add_constraint(src, dst, weight)

Add x_dst - x_src <= weight.

Performs an incremental tightening: for any pair (u, v), the new edge can only shorten d[u, v] via the path u -> src -> dst -> v. Raises :class:STPInconsistent if the result has a negative cycle.

add_interval(src, dst, lb, ub)

Encode lb <= x_dst - x_src <= ub as two difference constraints.

add_release_time(node, earliest)

Constrain earliest <= x_node (relative to the origin).

add_deadline(node, latest)

Constrain x_node <= latest (relative to the origin).

is_consistent()

get_earliest(node)

Earliest feasible time of node relative to the origin.

get_latest(node)

Latest feasible time of node relative to the origin.

get_distance(src, dst)

Tightest known upper bound on x_dst - x_src.

rebuild()

Recompute the distance matrix from scratch — used after removals.

TrajectoryEnvelopeSolver dataclass

Tracks envelopes and exposes timing queries through an STP network.

max_envelopes = 64 class-attribute instance-attribute

stp = field(init=False) class-attribute instance-attribute

create_envelope(robot_id, path, footprint, *, nominal_duration=math.nan, earliest_start=None, latest_start=None)

createEnvelopeNoParking(robotID, path, component, footprint)

createParkingEnvelope(robotID, duration, pose, location, footprint)

envelopes()

all_envelopes()

get(envelope_id)

mark_completed(envelope_id)

add_ordering(first, second, *, gap_lb=0.0, gap_ub=math.inf)

Constrain first to finish before second starts.

gap_lb / gap_ub define the allowed gap between end(first) and start(second). Defaults to "any non-negative gap" — the most common case for critical-section serialisation.

add_allen_constraint(rel, a, b, bounds=None)

earliest_start(envelope)

latest_start(envelope)

earliest_end(envelope)

latest_end(envelope)

is_consistent()

compute_spatial_envelope(path, footprint)

Sweep footprint along path and union the result.

to_diff_constraints(rel, a_start, a_end, b_start, b_end, bounds=None)

Translate A REL B into the STP edges that encode it.

Some relations admit an optional gap or overlap interval bounds: e.g. BEFORE with bounds (2, 5) means there is a gap of at least 2 and at most 5 between end(A) and start(B). When bounds is None we use [0, inf) for the gap-bearing relations.

Bounds use a closed interval [lb, ub]. ub may be math.inf.

coordination_oru.metacsp.temporal.stp

Simple Temporal Problem solver (Floyd-Warshall on a numpy distance matrix).

Replaces the meta-csp APSPSolver. Constraints are difference constraints of the form x_dst - x_src <= weight. Consistency is the absence of any negative-weight cycle, equivalently d[i, i] >= 0 for every node.

Node 0 is reserved as the temporal origin (t = 0). The solver allocates it in the constructor so that get_earliest / get_latest always have a reference frame.

The Java implementation supports incremental constraint removal via a kept copy of the original constraint graph. We start with that pattern: every add_constraint records the edge and runs an incremental update; a removal or backtrack triggers a full rebuild.

INF = math.inf module-attribute

ORIGIN = 0 module-attribute

_Edge dataclass

src instance-attribute

dst instance-attribute

weight instance-attribute

STPInconsistent

Bases: RuntimeError

Raised when a constraint addition produces a negative-weight cycle.

STPSolver

All-pairs-shortest-path STP solver.

The distance matrix _d has shape (max_nodes, max_nodes); only the top-left (_n, _n) block is meaningful. _d[i, j] is the tightest known upper bound on x_j - x_i.

num_variables property

new_variable()

add_constraint(src, dst, weight)

Add x_dst - x_src <= weight.

Performs an incremental tightening: for any pair (u, v), the new edge can only shorten d[u, v] via the path u -> src -> dst -> v. Raises :class:STPInconsistent if the result has a negative cycle.

add_interval(src, dst, lb, ub)

Encode lb <= x_dst - x_src <= ub as two difference constraints.

add_release_time(node, earliest)

Constrain earliest <= x_node (relative to the origin).

add_deadline(node, latest)

Constrain x_node <= latest (relative to the origin).

is_consistent()

get_earliest(node)

Earliest feasible time of node relative to the origin.

get_latest(node)

Latest feasible time of node relative to the origin.

get_distance(src, dst)

Tightest known upper bound on x_dst - x_src.

rebuild()

Recompute the distance matrix from scratch — used after removals.

coordination_oru.metacsp.temporal.allen

Allen interval-algebra relations.

The Java meta-csp framework exposes AllenIntervalConstraint.Type with the 13 jointly-exhaustive, pairwise-disjoint relations between two intervals plus a few syntactic-sugar variants. We port only the 13 base relations and a helper that converts each to the difference constraints needed by the STP layer.

Naming convention: the relation is read A REL B. So BEFORE means A ends before B starts, MET_BY means B ends exactly when A starts, etc.

Bounds

Bases: NamedTuple

Closed temporal interval. ub may be math.inf for unbounded.

lb instance-attribute

ub instance-attribute

intersect(other)

is_singleton()

AllenType

Bases: Enum

BEFORE = auto() class-attribute instance-attribute

MEETS = auto() class-attribute instance-attribute

OVERLAPS = auto() class-attribute instance-attribute

STARTS = auto() class-attribute instance-attribute

DURING = auto() class-attribute instance-attribute

FINISHES = auto() class-attribute instance-attribute

EQUALS = auto() class-attribute instance-attribute

AFTER = auto() class-attribute instance-attribute

MET_BY = auto() class-attribute instance-attribute

OVERLAPPED_BY = auto() class-attribute instance-attribute

STARTED_BY = auto() class-attribute instance-attribute

CONTAINS = auto() class-attribute instance-attribute

FINISHED_BY = auto() class-attribute instance-attribute

DiffConstraint dataclass

A single x_dst - x_src <= weight STP edge.

src instance-attribute

dst instance-attribute

weight instance-attribute

to_diff_constraints(rel, a_start, a_end, b_start, b_end, bounds=None)

Translate A REL B into the STP edges that encode it.

Some relations admit an optional gap or overlap interval bounds: e.g. BEFORE with bounds (2, 5) means there is a gap of at least 2 and at most 5 between end(A) and start(B). When bounds is None we use [0, inf) for the gap-bearing relations.

Bounds use a closed interval [lb, ub]. ub may be math.inf.

coordination_oru.metacsp.temporal.bounds

Closed temporal interval [lb, ub] (seconds).

Mirrors the Java meta-csp Bounds value type: a flyweight pair used by the STP layer and trajectory-envelope plumbing whenever a temporal interval needs to be passed around (durations, release times, deadlines, etc.).

UNBOUNDED = Bounds(0.0, math.inf) module-attribute

Bounds

Bases: NamedTuple

Closed temporal interval. ub may be math.inf for unbounded.

lb instance-attribute

ub instance-attribute

intersect(other)

is_singleton()