RoutingTaskBase

RoutingTaskBase extends TaskBase for problems defined on a set of nodes with pairwise travel costs (TSP, VRP, etc.).

Compared to TaskBase, it adds:

• distance_type — how edge lengths are computed (DISTANCE_TYPE).

• dist_eval — a DistanceEvaluator used by subclasses for DistanceEvaluator.cal_distance() and DistanceEvaluator.cal_dist_matrix().

Distance types

DISTANCE_TYPE	Meaning
EUC_2D / EUC_3D	Euclidean distance (default for synthetic datasets).
MAN_2D / MAN_3D	Manhattan (L1) distance.
MAX_2D / MAX_3D	Chebyshev (L∞) distance.
GEO	Great-circle distance on a sphere (TSPLIB GEO format).
ATT	ATT pseudo-Euclidean metric (TSPLIB).

Rounding

ROUND_TYPE controls integer rounding of computed distances (NO, CEIL, FLOOR, ROUND), matching TSPLIB / VRPLIB conventions.

DistanceEvaluator

DistanceEvaluator centralizes metric logic so TSP and VRP tasks share the same distance semantics:

import numpy as np
from ml4co_kit.task.routing.base import (
    DistanceEvaluator, DISTANCE_TYPE, ROUND_TYPE,
)

dist_eval = DistanceEvaluator(
    distance_type=DISTANCE_TYPE.EUC_2D,
    round_type=ROUND_TYPE.NO,
)
a = np.array([0.0, 0.0])
b = np.array([3.0, 4.0])
print(dist_eval.cal_distance(a, b))
# 5.0

coords = np.array([[0.0, 0.0], [1.0, 0.0], [0.0, 1.0]], dtype=np.float32)
print(dist_eval.cal_dist_matrix(coords))
# [[0. 1. 1.]
#  [1. 0. 1.4142135]
#  [1. 1.4142135 0. ]]

Subclass contract

Concrete routing tasks (e.g. CVRPTask) must implement:

• from_data() — populate coordinates and problem fields.

• check_constraints() — feasibility check.

• evaluate() — tour / route cost.

• render() — matplotlib visualization.

API reference

class ml4co_kit.task.routing.base.DISTANCE_TYPE(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

Define the distance types as an enumeration.

ATT = 'ATT'

EUC_2D = 'EUC_2D'

EUC_3D = 'EUC_3D'

GEO = 'GEO'

MAN_2D = 'MAN_2D'

MAN_3D = 'MAN_3D'

MAX_2D = 'MAX_2D'

MAX_3D = 'MAX_3D'

class ml4co_kit.task.routing.base.ROUND_TYPE(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

Define the rounding types as an enumeration.

CEIL = 'ceil'

FLOOR = 'floor'

NO = 'no'

ROUND = 'round'

class ml4co_kit.task.routing.base.DistanceEvaluator(distance_type: DISTANCE_TYPE, round_type: ROUND_TYPE, geo_radius: float = 6371.393)

Bases: object

Distance evaluator for different distance types.

static att(start: ndarray, end: ndarray)

Return the Att distance between start and end points.

cal_dist_matrix(coords: ndarray) → ndarray

Calculate the distance matrix for the given coordinates.

cal_distance(start: ndarray, end: ndarray) → float

Return the distance based on the specified distance type.

static euclidean(start: ndarray, end: ndarray)

Return the Euclidean distance between start and end points.

geographical(start: ndarray, end: ndarray)

Return the Geographical distance between start and end points.

static manhattan(start: ndarray, end: ndarray)

Return the Manhattan distance between start and end points.

static maximum(start: ndarray, end: ndarray)

Return the Maximum distance between start and end points.

round_result(distance: float) → int

Return the rounded distance based on the specified rounding type.

class ml4co_kit.task.routing.base.RoutingTaskBase(task_type: ~ml4co_kit.task.base.TASK_TYPE, minimize: bool, distance_type: ~ml4co_kit.task.routing.base.DISTANCE_TYPE, round_type: ~ml4co_kit.task.routing.base.ROUND_TYPE, precision: ~numpy.float32 | ~numpy.float64 = <class 'numpy.float32'>)

Bases: TaskBase

Base class for routing tasks defined on node coordinates.

Parameters

task_typeTASK_TYPE

Routing problem type.

minimizebool

Whether route cost is minimized.

distance_typeDISTANCE_TYPE

Edge weight metric (e.g. EUC_2D).

round_typeROUND_TYPE

Rounding applied to computed distances.

precisionnp.float32 or np.float64, optional

Floating dtype. Default is np.float32.

Attributes

distance_typeDISTANCE_TYPE

Selected distance metric.

dist_evalDistanceEvaluator

Callable distance engine shared by subclasses.

check_constraints(sol: ndarray) → bool

Check if the given solution satisfies all problem constraints. To be implemented by subclasses.

evaluate(sol: ndarray, check_constr: bool = True) → floating

Evaluate the given solution. To be implemented by subclasses.

evaluate_w_gap(check_constr: bool = True) → Sequence[floating]

Compare sol and ref_sol and return the optimality gap (%).

Parameters

check_constrbool, optional

If True, validate solutions before evaluation.

Returns

tuple of (sol_cost, ref_cost, gap)

gap is None when ref_cost is near zero. For minimization, gap = (sol_cost - ref_cost) / ref_cost * 100.

from_data()

Create a problem instance from raw data. To be implemented by subclasses.

from_pickle(file_path: Path)

Restore a task from a pickle file.

Parameters

file_pathpathlib.Path

Path to a .pkl file produced by to_pickle() or the toolkit.

get_data_md5() → str

Calculate MD5 hash of the task’s data content.

This method computes the MD5 hash based on the actual data content rather than the file content, which is useful for verifying data integrity when pickle files may have different object references.

Returns:

str: MD5 hash of the task’s data content

render()

Render the problem instance. To be implemented by subclasses.

to_pickle(file_path: Path)

Serialize this task to a pickle file.

Parameters

file_pathpathlib.Path

Output .pkl path (parent directories are created if needed).