ml4co_kit.task.base

Base classes for all combinatorial optimization tasks in ML4CO-Kit.

A task represents a single problem instance: input data, an optional candidate solution (sol), and an optional reference solution (ref_sol). Subclasses implement problem-specific encodings, constraint checking, and objective evaluation.

Classes

TASK_TYPE(value[, names, module, qualname, ...])	Define the task types as an enumeration.
TaskBase(task_type, minimize, precision)	Base class for a single combinatorial optimization instance.

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