TaskBase

TaskBase is the root class for every problem type in ML4CO-Kit (routing, graph, SAT, portfolio, etc.). It defines the common lifecycle:

1. Load / construct instance data (from_pickle, from_data in subclasses).

2. Evaluate a solution with TaskBase.evaluate().

3. Compare against a reference with TaskBase.evaluate_w_gap().

4. Visualize with TaskBase.render() (implemented in subclasses).

Core attributes

Attribute	Description
task_type	Problem identifier (TASK_TYPE).
minimize	True if the objective is minimized (e.g. route length); False if maximized.
precision	Floating dtype, np.float32 or np.float64.
sol	Current solution encoding (problem-specific).
ref_sol	Reference / ground-truth solution for benchmarking.
name	Unique instance id (UUID hex by default).

Quick example

Load a CVRP task from pickle and evaluate the reference tour (cp311_base environment, test_dataset/routing/vrp/cvrp/task/cvrp50_uniform_task.pkl):

import pathlib
from ml4co_kit import CVRPTask

task = CVRPTask()
task.from_pickle(pathlib.Path(
    "test_dataset/routing/vrp/cvrp/task/cvrp50_uniform_task.pkl"
))
print(task)
# CVRPTask(2fb389cdafdb4e79a94572f01edf0b95)

cost = task.evaluate(task.ref_sol)
print(cost)
# 10.973381996154785

Serialization

• TaskBase.from_pickle() — restore a full task object from .pkl.

• TaskBase.to_pickle() — persist the task (used in tests for round-trip checks).

• TaskBase.get_data_md5() — content hash for verifying data integrity (independent of pickle object identity).

print(task.get_data_md5())
# 794ee6f7389c675300bddbe63453c4aa

Gap evaluation

TaskBase.evaluate_w_gap() compares sol and ref_sol under the same objective. For minimization problems the gap (%) is (sol_cost - ref_cost) / ref_cost * 100.

task.sol = task.ref_sol.copy()
sol_cost, ref_cost, gap = task.evaluate_w_gap()
print(sol_cost, ref_cost, gap)
# 10.973381996154785 10.973381996154785 0.0

API reference

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

Bases: str, Enum

Define the task types as an enumeration.

ATSP = 'ATSP'

CVRP = 'CVRP'

CVRPB = 'CVRPB'

CVRPBL = 'CVRPBL'

CVRPBLTW = 'CVRPBLTW'

CVRPBTW = 'CVRPBTW'

CVRPL = 'CVRPL'

CVRPLTW = 'CVRPLTW'

CVRPTW = 'CVRPTW'

EDAP = 'EDA-P'

EDAR = 'EDA-R'

EDATDP = 'EDA-TDP'

GED = 'GED'

GM = 'GM'

KQAP = 'KQAP'

LP = 'LP'

LQAP = 'LQAP'

MAXRETPO = 'MaxRetPO'

MCL = 'MCl'

MCUT = 'MCut'

MILP = 'MILP'

MINVARPO = 'MinVarPO'

MIP = 'MIP'

MIS = 'MIS'

MOPO = 'MOPO'

MTVRP = 'MTVRP'

MVC = 'MVC'

OP = 'OP'

PCTSP = 'PCTSP'

SATA = 'SAT-A'

SATP = 'SAT-P'

SPCTSP = 'SPCTSP'

TSP = 'TSP'

class ml4co_kit.task.base.TaskBase(task_type: ~ml4co_kit.task.base.TASK_TYPE, minimize: bool, precision: ~numpy.float32 | ~numpy.float64 = <class 'numpy.float32'>)

Bases: object

Base class for a single combinatorial optimization instance.

Parameters

task_typeTASK_TYPE

Problem identifier.

minimizebool

Whether the objective is minimized (True) or maximized (False).

precisionnp.float32 or np.float64, optional

Floating-point dtype for coordinates and costs. Default is np.float32.

Attributes

solnp.ndarray or None

Current solution encoding (subclass-specific).

ref_solnp.ndarray or None

Reference solution for benchmarking.

namestr

Unique instance name (UUID hex by default).

cachedict

Optional cache used by solvers / optimizers.

Examples

>>> import pathlib
>>> from ml4co_kit import CVRPTask
>>> task = CVRPTask()
>>> task.from_pickle(
...     pathlib.Path("test_dataset/routing/vrp/cvrp/task/cvrp50_uniform_task.pkl")
... )
>>> task.evaluate(task.ref_sol)
10.973...

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).