Python API reference¶

This reference is generated from the docstrings of the compiled blast extension. The module must be importable at build time — install it first with pip install . (see Installation).

blast — Python bindings for the Blast trajectory optimization library.

Quick start¶

>>> import numpy as np
>>> import blast
>>>
>>> limits = blast.ManipulatorLimits()
>>> limits.position_max = np.deg2rad([360, 360, 180, 360, 360, 360])
>>> limits.position_min = -limits.position_max
>>> limits.velocity_max = np.full(6, np.pi)
>>> limits.acceleration_max = np.full(6, 13.96)
>>> limits.torque_max = np.array([150., 150., 150., 28., 28., 28.])
>>> limits.tool_speed_max = 2.0
>>>
>>> # ... set up kinematics, dynamics, capsules ...
>>> # manip = blast.Manipulator(6, limits, kinematics, dynamics, capsules)
>>> # task  = blast.Task.stop_to_stop(start_q, goal_q)
>>> # opt   = blast.Optimization(manip, task)
>>> # result = blast.optimize(opt)
>>> # print(result.success, result.trajectory.pos.shape)

Note on array layouts¶

Trajectory.pos, .vel, .acc are returned as Fortran-contiguous numpy arrays of shape (n_joints, n_points). Index them as traj.pos[joint_idx, time_step]. Call np.ascontiguousarray(traj.pos) if you need a C-contiguous copy.

REAL_DTYPE is np.float64 (default build) or np.float32. Always construct input arrays with blast.array(values) or np.asarray(values, dtype=blast.REAL_DTYPE) to avoid silent dtype mismatches.

class blast.Box(*args, **kwargs)¶

Bases: object

property center¶: Center point of the box (Vec3).

property extents¶: Positive half-width extents along each axis (Vec3).

property rotation¶

local x/y/z-axes (Mat3).

Type:: Rotation matrix

class blast.Bspline(*args, **kwargs)¶

Bases: object

property degree¶: Spline degree.

property n_ctrl¶: Number of control points.

property n_joints¶: Number of joints.

property n_points¶: Number of evaluation points.

property traj¶: Trajectory computed from the last optimize() call.

class blast.Capsule(*args, **kwargs)¶

Bases: object

property p1¶: First endpoint (Vec3).

property p2¶: Second endpoint (Vec3).

property radius¶: Radius of the capsule.

class blast.CollisionModelCapsule(*args, **kwargs)¶

Bases: object

property joint_frame¶: Index of the joint frame this capsule is attached to.

property p1¶: First endpoint of the capsule (Vec3).

property p2¶: Second endpoint of the capsule (Vec3).

property radius¶: Radius of the capsule.

class blast.ConstraintSelection(*args, **kwargs)¶

Bases: object

property acceleration¶: Enforce joint acceleration limits.

property external_collisions¶: Enforce collision avoidance with world obstacles.

property n_collision_constraints¶: (self) -> int

property n_collision_skip¶: (self) -> int

property position¶: Enforce joint position limits.

property self_collisions¶: Enforce self-collision avoidance (requires capsule model).

property tool_speed¶: Enforce maximum tool-center-point speed.

property torque¶: Enforce joint torque limits (requires dynamics).

property velocity¶: Enforce joint velocity limits.

class blast.DynamicBox(*args, **kwargs)¶

Bases: object

lookup(self, time: float) → blast._blast_core.Box¶: Interpolate the box pose at the given time.

property end_time¶: (self) -> float

property n_points¶: (self) -> int

property start_time¶: (self) -> float

property trajectory¶: List of Box poses, one per interpolation point.

class blast.DynamicCapsule(*args, **kwargs)¶

Bases: object

lookup(self, time: float) → blast._blast_core.Capsule¶

property end_time¶: (self) -> float

property n_points¶: (self) -> int

property start_time¶: (self) -> float

property trajectory¶: (self) -> list[blast._blast_core.Capsule]

class blast.DynamicSphere(*args, **kwargs)¶

Bases: object

lookup(self, time: float) → blast._blast_core.Sphere¶

property end_time¶: (self) -> float

property n_points¶: (self) -> int

property start_time¶: (self) -> float

property trajectory¶: (self) -> list[blast._blast_core.Sphere]

class blast.Guess(*args, **kwargs)¶

Bases: object

property initial_x¶: Initial solution vector for GuessType.custom (float64 view).

property n_random_shots¶: Number of random initial guesses to try (GuessType.random).

property parameter¶: Scalar parameter (interpretation depends on GuessType).

property type¶: Strategy for generating the initial solution (GuessType).

class blast.GuessType(*values)¶

Bases: Enum

custom = 0¶

from_list = 3¶

random = 1¶

shotgun = 2¶

class blast.Manipulator(*args, **kwargs)¶

Bases: object

add_tool(self, tool: blast._blast_core.Tool) → None¶

set_capsules(self, capsules: blast._blast_core.ManipulatorCapsules) → None¶

set_dynamics(self, dynamics: blast._blast_core.ManipulatorDynamics) → None¶

set_kinematics(self, kinematics: blast._blast_core.ManipulatorKinematics) → None¶

set_limits(self, limits: blast._blast_core.ManipulatorLimits) → None¶

set_payload(self, mass: float, cog: blast._blast_core.Vec3, inertia: blast._blast_core.Mat3) → None¶

property base_position¶: (self) -> blast._blast_core.Vec3

property base_rotation¶: (self) -> blast._blast_core.Mat3

property has_tool¶: (self) -> bool

property n_joints¶: Number of joints.

class blast.ManipulatorCapsules(*args, **kwargs)¶

Bases: object

property base_sphere¶: Collision sphere around the robot base.

property capsule_list¶: List of CollisionModelCapsule objects.

property collision_base¶

1 if capsule[i] can collide with the base sphere.

Type:: Boolean-like array

property collision_matrix¶

collision_matrix[i,j]=1 means capsule i and j can collide.

Type:: Symmetric adjacency matrix (uint8)

class blast.ManipulatorDynamics(*args, **kwargs)¶

Bases: object

property cog_offsets¶: Center-of-gravity offset for each link (list of Vec3).

property inertia_tensors¶: Inertia tensor for each link (list of Mat3).

property link_masses¶: Mass of each link (kg). Length must be <= MAX_JOINTS.

class blast.ManipulatorKinematics(*args, **kwargs)¶

Bases: object

property base_position¶: Base position in the world frame (Vec3).

property base_rotation¶: Base orientation in the world frame (Mat3).

property first_joint_position¶: Position of the first joint relative to the base (Vec3).

property joint_axes¶: Unit rotation axes for each joint (list of Vec3).

property joint_offsets¶: Vectors from each joint to the next, in the joint frame (list of Vec3).

property static_rotations¶: Static rotation matrices between consecutive joint frames (list of Mat3, length MAX_JOINTS+1).

class blast.ManipulatorLimits(*args, **kwargs)¶

Bases: object

property acceleration_max¶: Maximum joint accelerations (rad/s²).

property position_max¶: Maximum joint positions (rad).

property position_min¶: Minimum joint positions (rad).

property tool_speed_max¶: Maximum tool-center-point speed (m/s).

property torque_max¶: Maximum joint torques (N·m).

property velocity_max¶: Maximum joint velocities (rad/s).

class blast.Mat3(*args, **kwargs)¶

Bases: object

to_numpy(self) → numpy.ndarray[dtype=float64]¶: Return a copy as a C-order (3,3) numpy array.

from_numpy = <nanobind.nb_func object>¶

class blast.Objective(*args, **kwargs)¶

Bases: object

property time_weight¶: Weight for the trajectory time objective (default 1.0).

class blast.Optimization(*args, **kwargs)¶

Bases: object

set_task(self, task: blast._blast_core.Task) → None¶

set_world(self, world: blast._blast_core.World) → None¶

x_len(self) → int¶: Total number of decision variables (B-spline control points + time).

property bspline¶: (self) -> blast._blast_core.Bspline

property constraints¶: (self) -> blast._blast_core.ConstraintSelection

property guess¶: (self) -> blast._blast_core.Guess

property max_eval¶: Maximum NLopt function evaluations per try (default 1000).

property max_time¶: Maximum wall time per NLopt call in seconds (default 30).

property max_tries¶: Maximum number of optimization retries (default 1).

property objective¶: (self) -> blast._blast_core.Objective

property success_tolerance¶: Fraction of constraint violation still considered a success (default 0.0).

property trajectory_start_time¶: Trajectory start time for dynamic obstacle synchronisation.

property world¶: (self) -> blast._blast_core.World

class blast.OptimizationMethod(*values)¶

Bases: Enum

baseline = 1¶

with_analytical_dynamics = 3¶

with_analytical_pva = 2¶

with_segments = 0¶

blast.REAL_DTYPE¶: alias of float64

class blast.Result¶

Bases: object

property compute_time¶: Wall time for the optimization (milliseconds).

property max_constraint_idx¶: Index of the most-violated constraint.

property max_constraint_value¶: Maximum constraint violation in the final solution.

property num_eval¶: Number of NLopt function evaluations.

property num_tries¶: Number of optimization retries performed.

property success¶: True if the optimizer found a feasible trajectory.

property trajectory¶: Computed Trajectory (pos/vel/acc/t). The views it returns keep the Result alive.

property x¶: Optimized B-spline control vector (float64 view).

property x0¶: Initial guess vector that was used (float64 view).

class blast.Sphere(*args, **kwargs)¶

Bases: object

property center¶: Center of the sphere (Vec3).

property radius¶: Radius of the sphere.

class blast.Task(*args, **kwargs)¶

Bases: object

property goal¶: Goal boundary condition (TaskBoundary).

property start¶: Start boundary condition (TaskBoundary).

stop_to_stop = <nanobind.nb_func object>¶

class blast.TaskBoundary(*args, **kwargs)¶

Bases: object

property acceleration¶: Joint accelerations (rad/s²).

property position¶: Joint positions (rad).

property velocity¶: Joint velocities (rad/s).

class blast.Tool(*args, **kwargs)¶

Bases: object

property capsule_list¶: Collision capsules for the tool.

property cog_offset¶: Tool center-of-gravity offset (Vec3).

property collision_matrix¶: (self) -> numpy.ndarray[dtype=uint8]

property inertia_tensor¶: Tool inertia tensor (Mat3).

property mass¶: Tool mass (kg).

property tool_offset¶: Offset vector to the tool (Vec3).

property tool_rotation¶: Rotation to the tool frame (Mat3).

class blast.Trajectory(*args, **kwargs)¶

Bases: object

property acc¶: Joint accelerations, shape (n_joints, n_points), Fortran-contiguous float64 array.

property pos¶: Joint positions, shape (n_joints, n_points), Fortran-contiguous float64 array.

property t¶: Time samples, shape (n_points,), float64 array.

property vel¶: Joint velocities, shape (n_joints, n_points), Fortran-contiguous float64 array.

class blast.Vec3(*args, **kwargs)¶

Bases: object

to_numpy(self) → numpy.ndarray[dtype=float64]¶: Return a copy as a (3,) numpy array.

from_numpy = <nanobind.nb_func object>¶

property x¶: (self) -> float

property y¶: (self) -> float

property z¶: (self) -> float

class blast.World(*args, **kwargs)¶

Bases: object

add_box(self, box: blast._blast_core.Box) → None¶

add_box(self, center: blast._blast_core.Vec3, half_extents: blast._blast_core.Vec3, rotation: blast._blast_core.Mat3) → None

Overloaded function.

add_box(self, box: blast._blast_core.Box) -> None

Add a Box obstacle.

add_box(self, center: blast._blast_core.Vec3, half_extents: blast._blast_core.Vec3, rotation: blast._blast_core.Mat3) -> None

Add a box specified by center, half-extents and rotation matrix.

add_capsule(self, capsule: blast._blast_core.Capsule) → None¶

add_capsule(self, p1: blast._blast_core.Vec3, p2: blast._blast_core.Vec3, radius: float) → None

Overloaded function.

add_capsule(self, capsule: blast._blast_core.Capsule) -> None

Add a Capsule obstacle.

add_capsule(self, p1: blast._blast_core.Vec3, p2: blast._blast_core.Vec3, radius: float) -> None

Add a capsule specified by two endpoints and radius.

add_dynamic_box(self, box: blast._blast_core.DynamicBox) → None¶

add_dynamic_capsule(self, capsule: blast._blast_core.DynamicCapsule) → None¶

add_dynamic_sphere(self, sphere: blast._blast_core.DynamicSphere) → None¶

add_sphere(self, sphere: blast._blast_core.Sphere) → None¶

add_sphere(self, center: blast._blast_core.Vec3, radius: float) → None

Overloaded function.

add_sphere(self, sphere: blast._blast_core.Sphere) -> None

Add a Sphere obstacle.

add_sphere(self, center: blast._blast_core.Vec3, radius: float) -> None

Add a sphere specified by center and radius.

property boxes¶: List of static Box obstacles.

property capsules¶: List of static Capsule obstacles.

property size¶: Total number of static obstacle primitives.

property spheres¶: List of static Sphere obstacles.

blast.array(values) → ndarray[source]¶

Return a numpy array with the correct dtype for Blast (REAL_DTYPE).

Use this helper whenever you need to pass numeric data to Blast functions to avoid silent float32/float64 mismatches.

Parameters:: values (array-like) – Any sequence or array that numpy can convert.
Returns:: 1-D or N-D array with dtype == blast.REAL_DTYPE.
Return type:: np.ndarray

Note

Class and method docstrings come from the nanobind .def(...) strings in python/src/ and from python/blast/__init__.py. Bindings without docstrings still appear (signatures only); add a docstring to the corresponding .def(...) to enrich this page.