robometric_frame.trajectory_quality.path_length

Path Length metric for robotics policy trajectory evaluation.

Path Length quantifies the total distance traveled to complete a task, serving as a crucial metric for efficiency evaluation.

Reference:

P. Fankhauser et al., “Kinect v2 for mobile robot navigation: Evaluation and modeling,” in 2015 International Conference on Advanced Robotics (ICAR), IEEE, July 2015.

Classes

PathLength(**kwargs)

Compute Path Length for robotics policy trajectory evaluation.

class robometric_frame.trajectory_quality.path_length.PathLength(**kwargs)

Compute Path Length for robotics policy trajectory evaluation.

Path Length is calculated as:

PL = Σ(i=1 to L-1) |p_{i+1} - p_i|_2

where p_i are trajectory points in D-dimensional space and L is the length of the trajectory. Shorter paths generally indicate more efficient task execution.

This metric accumulates path lengths across multiple trajectories and returns the average path length when compute() is called.

Parameters:

**kwargs (Any) – Additional keyword arguments passed to the base Metric class.

Example

>>> from robometric_frame.trajectory_quality import PathLength
>>> import torch
>>> metric = PathLength()
>>> # 2D trajectory with 5 points
>>> trajectory = torch.tensor([
...     [0.0, 0.0],
...     [1.0, 0.0],
...     [1.0, 1.0],
...     [2.0, 1.0],
...     [2.0, 2.0]
... ])
>>> metric.update(trajectory)
>>> metric.compute()
tensor(4.0000)

Example (batched):

>>> # Batch of trajectories - shape (B, L, D)
>>> metric = PathLength()
>>> batch = torch.tensor([
...     [[0.0, 0.0], [1.0, 0.0], [2.0, 0.0]],  # trajectory 1
...     [[0.0, 0.0], [0.0, 1.0], [0.0, 2.0]]   # trajectory 2
... ])
>>> metric.update(batch)
>>> metric.compute()  # Average of 2.0 and 2.0
tensor(2.0000)

Example (3D trajectories):

>>> # 3D trajectory
>>> metric = PathLength()
>>> trajectory_3d = torch.tensor([
...     [0.0, 0.0, 0.0],
...     [1.0, 0.0, 0.0],
...     [1.0, 1.0, 0.0],
...     [1.0, 1.0, 1.0]
... ])
>>> metric.update(trajectory_3d)
>>> metric.compute()
tensor(3.0000)

Example (distributed):

>>> # In distributed training, metrics are automatically synced
>>> metric = PathLength()
>>> # On GPU 0
>>> traj_gpu0 = torch.tensor([[0.0, 0.0], [1.0, 0.0]])
>>> metric.update(traj_gpu0)
>>> # On GPU 1
>>> traj_gpu1 = torch.tensor([[0.0, 0.0], [0.0, 1.0]])
>>> metric.update(traj_gpu1)
>>> # Final result aggregates across all GPUs
>>> result = metric.compute()  # Returns aggregated average path length

full_state_update: bool = False

total_path_length: Tensor

num_trajectories: Tensor

__init__(**kwargs)

Initialize the PathLength metric.

update(trajectory)

Update metric state with new trajectory or batch of trajectories.

Parameters:

trajectory (Tensor) –

Tensor of shape (…, L, D) where: - … represents any number of batch dimensions (can be empty) - L is the number of points (must be >= 2) - D is the spatial dimensionality (e.g., 2 for 2D, 3 for 3D)

Examples of valid shapes: - (L, D): Single trajectory - (B, L, D): Batch of B trajectories - (B, T, L, D): Batch of B sequences with T slices each

Points should be ordered chronologically along the L dimension.

Raises:

ValueError – If trajectory has invalid shape or insufficient points.

Return type:

None

compute()

Compute the average Path Length across all trajectories.

Return type:

Tensor

Returns:

Average path length as a scalar tensor.

Raises:

RuntimeError – If no trajectories have been recorded.

training: bool