Breaking API changes¶

Changes that break existing Python code, newest first, each with what replaces it. 0.35.0.9 removes IfoptQPProblem and IfoptProblem: build a TrajOptQPProblem instead, and expect different results wherever a cost went in without a penalty type. Its convex evaluators take only the QP solution vector. The changelog lists every change; the upgrade guide covers the tesseract upgrades in full.

Unreleased¶

setPairCollisionCoeff and getPairCollisionCoeff removed¶

trajopt_ifopt.CollisionCoeffData bound two copies of its setter and getter under names C++ does not have (#298). Call the C++ names:

trajopt value types compare by value and are unhashable¶

trajopt_ifopt.CollisionCoeffData, trajopt_ifopt.TrajOptCollisionConfig and trajopt_sqp.SQPParameters bind __eq__/__ne__ from their C++ operator== and set __hash__ = None (#261), as the 0.35.0.9 collision, common and environment types did. CollisionCoeffData() == CollisionCoeffData() was False. hash(obj), {obj} and d[obj] = … now raise TypeError: unhashable type:

Collision constraints need a Var in a variable set¶

trajopt's collision constraints key their contact cache on the variable set's hash, which they read through var.getParent().getParent() without a check: a Var outside a NodesVariables dereferenced null on the first update(). DiscreteCollisionConstraint, DiscreteCollisionConstraintD, DiscreteCollisionNumericalConstraint, ContinuousCollisionConstraint, ContinuousCollisionConstraintD and ContinuousCollisionNumericalConstraint now raise VarNotInVariableSetError (a ValueError) at construction (#297). A Var from createNodesVariables always qualifies; one from Node.addVar qualifies once its Node is handed to NodesVariables:

Node.getParent raises for planner-owned nodes¶

A Python TrajOptIfoptCompositeProfile.create receives the planner's Nodes, whose variable set the planner builds in C++ and frees when its solve returns. Node.getParent() on such a Node returned a view of that set, which read freed memory once the solve was over (#297). It now raises NodeParentUnavailableError (a RuntimeError) for every Node of a set C++ owns, during create too. getParent() still returns the set for Nodes of a set built from Python:

OSQPEigenSolver updates check sizes¶

updateGradient, updateLowerBound, updateUpperBound and updateBounds now sit on QPSolver and raise QPSizeError (a ValueError) unless the vector has init()'s num_vars (gradient) or num_cnts (bounds) entries (#283). trajopt checked with assert only and read past a short vector. Call init(num_vars, num_cnts) with the QP's size before the updates.

Command-language types compare by value and are unhashable¶

The command-language waypoints, instructions and Polys compared by identity: two JointWaypoint(["a"], [1.0]) were unequal. They now bind __eq__/__ne__ from the C++ operators and set __hash__ = None, as the collision, common and environment types did in 0.35.0.9 (#261): CartesianWaypoint, JointWaypoint, StateWaypoint, WaypointPoly, CartesianWaypointPoly, JointWaypointPoly, StateWaypointPoly, InstructionPoly, MoveInstructionPoly, MoveInstruction, CompositeInstruction, WaitInstruction, TimerInstruction, SetAnalogInstruction, SetDigitalInstruction, SetToolInstruction.

hash(obj), {obj} and d[obj] = … now raise TypeError: unhashable type. Every instruction has a UUID, which is the natural key; MoveInstruction equality also compares it, so two moves built separately are unequal until the UUIDs match:

Time-parameterization profiles compare by value and are unhashable¶

The four time-parameterization profiles were bound without their C++ operator==, so == compared identity: TOTGCompositeProfile() == TOTGCompositeProfile() was False. They now bind __eq__/__ne__ and set __hash__ = None (#261), as the collision, common and environment value types did in 0.35.0.9. The new RuckigTrajectorySmoothingCompositeProfile behaves the same way.

Simple-planner move profiles compare by value and are unhashable¶

SimplePlannerFixedSize{,Assign,AssignNoIK}MoveProfile and SimplePlannerLVS{,NoIK,Assign,AssignNoIK}MoveProfile bind the C++ operator== (#261): two profiles with the same fields are ==, and hash(), set members and dict keys raise TypeError, as for the value types in 0.35.0.9.

OMPLSolverConfig.getNumPlanners() removed¶

OMPLSolverConfig.planners is bound (#302), so the count is len(cfg.planners). The list is copied on access; its configurators are shared with the config. cfg.planners.append(x) changes the copy, but cfg.planners[0].range = 0.5 edits the config. Assign a new list, or use addPlanner / clearPlanners, which change it in place.

Planner value types compare by value and are unhashable¶

As for collision, common and environment in 0.35.0.9, these classes bind the C++ operator== and set __hash__ = None (#261). hash(), set members and dict keys raise TypeError:

Key on a field, or on id(obj) where identity is meant, as in the 0.35.0.9 entry. OMPLSolverConfig compares planners by count only (upstream ompl_solver_config.cpp), so two configs holding different configurator types of the same number are equal.

create_ompl_planner_configurators rejects unused keywords¶

The helper accepts every OMPLPlannerType name (#301) and sets each keyword on the requested configurators that have that field. It used to ignore a keyword no configurator used; now it raises ValueError naming the keyword. A keyword that fits at least one requested planner is still accepted (goal_bias with ["RRTConnect", "RRTstar"] sets it on the RRTstar ones).

TrajOpt-Ifopt and Descartes profiles compare by value and are unhashable¶

These classes bind __eq__/__ne__ from their C++ operator== and set __hash__ = None, as the 0.35.0.9 value types do (#261):

| tesseract_motion_planners_trajopt_ifopt | TrajOptIfoptCartesianWaypointConfig, TrajOptIfoptJointWaypointConfig, TrajOptIfoptDefaultMoveProfile, TrajOptIfoptDefaultCompositeProfile, TrajOptIfoptOSQPSolverProfile | | tesseract_motion_planners_descartes | DescartesDefaultMoveProfileD, DescartesLadderGraphSolverProfileD |

hash(profile), {profile} and d[profile] = … raise TypeError: unhashable type. Key on the profile's name in the ProfileDictionary, or on id(profile) where identity is what you mean:

| seen = {profile} | seen = {profile_name} | | cache[profile] = result | cache[id(profile)] = result (keep profile alive) |

Overriding a hook on a concrete profile raises¶

Only the abstract profile bases forward the planner's calls to Python. A Python subclass of a concrete profile (the seven simple-planner move profiles, TrajOptIfoptDefaultMoveProfile, TrajOptIfoptDefaultCompositeProfile, TrajOptIfoptOSQPSolverProfile, DescartesDefaultMoveProfileD, DescartesLadderGraphSolverProfileD) that defined generate, create or a create* hook planned with the C++ hook and never ran the override. Such a class statement now raises ProfileOverrideNotDispatchedError, a TypeError (#340):

A subclass that defines no hook (to add fields or helpers) is unaffected.

0.35.0.9¶

ChangeCollisionMarginsCommand(pair_margin_data) defaults to MODIFY¶

The binding defaulted override_type to REPLACE, so leaving it out replaced every pair margin in the environment, where the same C++ call merges the given pairs into the existing ones (#247). Both overloads that take pair_margin_data now default to MODIFY, as upstream. Code that left override_type out and relied on the replace passes it explicitly:

CollisionMarginPairOverrideType is in tesseract_common. The new ChangeCollisionMarginsCommand(default_margin, pairs, override_type) overload defaults to MODIFY too.

The planning API no longer picks a TCP or working frame¶

tesseract_robotics.planning used to fill in frames it could not know (#30): the TCP as the last of getActiveLinkNames(), which is only the tip for a serial chain, and the working frame as the literal "base_link". get_manipulator_info also cached the guess and returned one shared, mutable ManipulatorInfo per key. Now the caller names every frame: a missing one raises TypeError at the call.

For the bundled abb_irb2400 and lbr_iiwa_14_r820 the old guesses were "tool0" and "base_link", so the right-hand column behaves exactly as before. For another robot, pass the link your tool is mounted on and the frame your Cartesian targets are expressed in.

New: MotionProgram and get_manipulator_info take a keyword-only tcp_offset, a named TCP (SRDF group_tcps, #133) or an Isometry3d, and the planner puts tcp_frame * tcp_offset on each Cartesian target. See Frames and the TCP.

PointCloudPoint renamed to PointCloud.Point¶

The point type of PointCloud is nested in C++ (tesseract::geometry::PointCloud::Point) and is now bound nested (#209). The module-level PointCloudPoint is gone: importing it raises ImportError, reading it as an attribute raises AttributeError. addPoint(x, y, z) is unchanged.

SWIG-era JointType_* constants removed¶

tesseract_scene_graph no longer exports a module constant per JointType value. The seven constants were copies kept from the SWIG bindings; C++ has none of them, and JointType is bound as an enum whose members are the same objects (#214, finishing #176). Importing one now raises ImportError: cannot import name 'JointType_FIXED' from 'tesseract_robotics.tesseract_scene_graph'; reading one as an attribute raises AttributeError.

Value types compare by value and are unhashable¶

Every collision, common and environment class whose C++ header declares operator== was bound without it, so == compared identity: ContactRequest() == ContactRequest() was False, and so was env == env.clone(). These classes now bind __eq__/__ne__ from the C++ operators and set __hash__ = None (#169):

They join the classes that already compared by value (JointTrajectory, the plugin-info structs, AddTrajectoryLinkCommand, AddContactManagersPluginInfoCommand and the two SetActive*ContactManagerCommands).

What breaks is hashing. These objects are mutable, and an object that compares by value must not hash by identity, or two equal objects land in different set buckets. So hash(obj), {obj} and d[obj] = … now raise TypeError: unhashable type. Key on a field that identifies the object, or on id(obj) where identity is what you mean:

The equality is the C++ one, unchanged, so it inherits upstream's choices:

• Floating-point fields compare within a tolerance, not exactly: JointState vectors with isApprox(1e-5) after an exact size check (joint_state.cpp), ContactResult and CollisionCheckConfig with almostEqualRelativeAndAbs, the command origins with isApprox(1e-5).
• ContactRequest.is_valid compares the validator object: two requests are equal only while they hold the same validator (types.cpp).
• BytesResource and SimpleLocatedResource compare their parent locators only for presence: ResourceLocator::operator== returns true (resource_locator.cpp).
• A geometry compares by type and its per-instance uuid (geometry.cpp), so commands holding geometry are equal only when they share it: the same URDF parsed twice gives unequal AddSceneGraphCommands.
• Environment compares its revisions, the types of its commands, its current state and both timestamps (environment.cpp). env == env.clone() holds, because clone() copies the timestamps (L442–L444); two environments initialised separately from the same URDF are unequal. Its __eq__ releases the GIL, because the C++ operator takes the environment's lock.

Two classes keep identity equality: ResourceLocator and Resource. Their C++ operator== returns true for any pair (L46, L206), so binding it would make every two Python locators equal. A Python locator subclass stays hashable.

KinematicLimits compares the shapes of its four limit matrices before calling the C++ operator, which calls isApprox without checking them and reads out of bounds when they differ (kinematic_limits.cpp). Limits of different shapes are unequal.

createTaskComposerNode and createTaskComposerExecutor raise¶

Upstream's TaskComposerPluginFactory returns null when it cannot create a node or executor: the name is not configured, the plugin symbol fails to load, or the plugin factory throws. It only logs a console_bridge warning. Python got None, against a stub that promised the object. Both methods now raise TaskComposerPluginError, a RuntimeError (#203). For a name that is not configured, the message lists the configured names.

TaskComposer.plan still returns a failed PlanningResult for an unknown pipeline; its message is now the factory's error.

Pre-0.33 collision-margin aliases removed¶

tesseract 0.33 renamed the collision-margin members; the bindings kept the old names as aliases of the new ones. The eight aliases are gone (#177); each replacement takes the same arguments and does the same thing.

manager is a DiscreteContactManager or ContinuousContactManager, config a ContactManagerConfig, margins a CollisionMarginData. A ContactManagerConfig has no margin_data member (the collision API page used one; that snippet never ran): set its default_margin, pair_margin_data and pair_margin_override_type, then pass it to manager.applyContactManagerConfig(config).

SWIG-era enum constants removed¶

tesseract_collision, tesseract_environment and tesseract_common no longer export a module constant per enum value. The 14 constants were copies kept from the SWIG bindings; C++ has none of them, and every enum is bound as a class whose members are the same objects (#176). Importing one now raises ImportError: cannot import name 'ContactTestType_ALL' from 'tesseract_robotics.tesseract_collision'; reading one as an attribute raises AttributeError.

# before
from tesseract_robotics.tesseract_collision import ContactRequest, ContactTestType_ALL
from tesseract_robotics.tesseract_common import CONSOLE_BRIDGE_LOG_WARN, setLogLevel

request = ContactRequest(ContactTestType_ALL)
setLogLevel(CONSOLE_BRIDGE_LOG_WARN)

# after
from tesseract_robotics.tesseract_collision import ContactRequest, ContactTestType
from tesseract_robotics.tesseract_common import LogLevel, setLogLevel

request = ContactRequest(ContactTestType.ALL)
setLogLevel(LogLevel.CONSOLE_BRIDGE_LOG_WARN)

The CONSOLE_BRIDGE_LOG_* names keep their prefix because they are the C++ enumerator names of console_bridge's unscoped LogLevel; only the module-level copies are gone.

AnyPoly helpers only in tesseract_task_composer¶

tesseract_environment re-exported AnyPoly_wrap_EnvironmentConst, and tesseract_command_language re-exported AnyPoly_wrap_CompositeInstruction, AnyPoly_wrap_ProfileDictionary and AnyPoly_as_CompositeInstruction, from tesseract_task_composer inside a try: … except ImportError: pass. An install whose task-composer extension failed to load lost the names without an error, and importing either package loaded the task composer. The re-exports and tesseract_command_language._HAS_TASK_COMPOSER are removed (#192); the functions are defined in, and imported from, tesseract_task_composer. Code that imports them from the old place now fails with ImportError: cannot import name ….

A str is content, pathlib.Path is a file¶

tesseract_common.FilesystemPath was a str subclass, so Environment.init had to guess whether a string was a path or URDF content, and init(str, str, locator) loaded files where the C++ std::string overload parses content. std::filesystem::path now converts with nanobind's caster (str | os.PathLike in, pathlib.Path out), and Environment.init binds the four native overloads (#165):

The path overloads of Environment.init and the ContactManagersPluginFactory / KinematicsPluginFactory config constructors accept os.PathLike only, never str, because each sits beside a str content overload. Every other std::filesystem::path parameter takes str | os.PathLike.

TaskComposerPluginFactory still takes its config path as str; its path/content pair is not bound yet.

The convex evaluators take the QP solution vector¶

QPProblem.evaluateConvexCosts, evaluateTotalConvexCost and evaluateConvexConstraintViolations read var_vals in the layout of the QP that the last convexify() built: getNumQPVars() entries, the NLP variables followed by the slack variables (L28). trajopt documents that size (L59, L67) but does not check it. The binding now raises ValueError for any other size, and before the first convexify(), while getNumQPVars() is still 0 (L99, L831):

ValueError: evaluateConvexCosts: var_vals has 3 entries; it must be the QP solution vector of getNumQPVars() = 5 entries, the NLP variables followed by the slack variables
ValueError: evaluateConvexCosts: the problem has no convex model yet; call convexify() first

What used to work and now raises: an NLP-sized var_vals on a problem with constraint sets and no hinge or absolute cost. Each constraint row adds one or two slack variables, and trajopt 0.35.0, which every tesseract-robotics-nanobind 0.35.0.x wheel bundles, reads only the NLP block there, so the call returned the right values. Append zeros for the slack variables:

problem.convexify()
n_slack = problem.getNumQPVars() - problem.getNumNLPVars()
model_costs = problem.evaluateConvexCosts(np.concatenate([x, np.zeros(n_slack)]))

A QP solution, such as SQPResults.new_var_vals in a callback, already has the right size. SQPResults.best_var_vals needs it too: on trajopt 0.35.0 it is NLP-sized until the first accepted step and QP-sized after it (always NLP-sized in a wheel built on a trajopt that contains trajopt#592), so take its first getNumNLPVars() entries and pad them as above. A problem with no constraint sets and only squared costs has no slack variables, so its NLP point is a QP point and nothing changes.

Why the binding checks: with a hinge or absolute cost, trajopt 0.35.0 multiplies the cost's full QP rows, slack columns included, into var_vals (L187–L188), so an NLP-sized vector was read past its end. On a one-joint problem whose absolute cost is 0.5, a view of the first three entries of a longer buffer read 3.5 or 0.5, depending on the two entries after the view, and a fresh three-entry array read 14.6. Before the first convexify(), an empty or NLP-sized vector segfaulted on a squared cost. The rule covers all three evaluators, although trajopt 0.35.0 reads only the NLP block in two of them: one contract, the one trajopt documents for all three once trajopt#592 is in.

IfoptQPProblem and IfoptProblem removed¶

tesseract_robotics.trajopt_sqp no longer binds IfoptQPProblem or IfoptProblem. trajopt is removing IfoptQPProblem (trajopt#595), and IfoptProblem was bound only to construct it. Code that uses either now fails with AttributeError: module 'tesseract_robotics.trajopt_sqp' has no attribute 'IfoptQPProblem' (or 'IfoptProblem'). Build a TrajOptQPProblem over the same variables, and add every set to it, each cost with a penalty type (#148):

# before
nlp = tsqp.IfoptProblem(nodes_variables)
nlp.addConstraintSet(joint_constraint)
nlp.addCostSet(vel_cost)                        # no penalty type
problem = tsqp.IfoptQPProblem(nlp)
problem.addConstraintSet(collision_constraint)
problem.setup()

# after
problem = tsqp.TrajOptQPProblem(nodes_variables)
problem.addConstraintSet(joint_constraint)
problem.addConstraintSet(collision_constraint)
problem.addCostSet(vel_cost, tsqp.CostPenaltyType.SQUARED)
problem.setup()

It is not a rename. In trajopt 0.35.0, which every tesseract-robotics-nanobind 0.35.0.x wheel bundles (TrajOptQPProblem first ships in 0.35.0.9; earlier releases bind IfoptQPProblem), the two problems differ in five ways, and the third and fourth change results:

How much the third difference moves a result: this package's online SQP example added its velocity cost with IfoptProblem.addCostSet, so its QP had no cost term and OSQP solved with an empty Hessian. As a squared cost on TrajOptQPProblem, the global solve's summed squared joint steps fell from 23.2 to 3.9, against 3.6 for the straight-line seed, and getTotalExactCost() now reports that sum instead of the first velocity row (0.5).

0.35.0.1¶

Transform removed; Pose is an Isometry3d¶

tesseract_robotics.planning.Pose now subclasses Isometry3d. Its rotation math runs in Eigen, its numpy-property facade is gone, its stored data are properties, and its factories collapse to one name each that accepts both scalar-positional and array-like arguments. The Transform alias is removed: use Pose (#76).

Resource URIs moved¶

tesseract 0.35 folds its support data into the tesseract package, so package://tesseract_support/... is now package://tesseract/support/... in every URDF, SRDF and locateResource call. The rest of that upgrade leaves the Python API unchanged; see the 0.34 → 0.35 guide.

0.34.1.0¶

The tesseract 0.34 upgrade removed the ifopt module (its types moved to trajopt_ifopt) and replaced JointPosition with Var / Node / NodesVariables. It also removed CartPosInfo and CollisionCache, dropped getStaticKey() from profiles, and renamed the cost and constraint evaluation methods. The 0.33 → 0.34 guide has each change with its replacement.