program_functions_csp.py

# This file is loaded with two different global scopes.
# The first scope is the one when this file is imported by another file. This will provide a list of available functions to be added to the LLM prompts.
# The second scope is created when this file is loaded and run by the exec() function. This will provide a valid scope to run the program generated by LLM.
# We can't have only one scope, because some predefined functions use global variables that are statically (lexically) binded.

from abc import abstractmethod
from typing import Callable

import numpy as np

import csp_func_control as cfc
from csp_solver import CSPConstraint, CSPSolver, CSPVar, Solution, reset_var_counter
from misc_utils import (
    check,
    check_list_of_type,
    check_set_of_type,
    is_list_of_type,
    is_set_of_type,
    lookat_matrix,
)
from scannet_utils import ObjInstance
from scope_env import GlobalState, register_handler
from score_funcs import SCORE_FUNCTIONS

CSP_SOLVER: CSPSolver | None = None
TARGET_VARIABLE: CSPVar | None = None


# set far_distance to 0 and others to 20 to get the evaluation results in paper
class Configs:
    near_distance = 2
    far_distance = 0
    between_distance = 1
    center_distance = 1
    above_below_horizontal_distance = 1


def reset_target():
    global TARGET_VARIABLE
    TARGET_VARIABLE = None


def check_target() -> bool:
    return TARGET_VARIABLE is not None


def reset_csp_solver():
    """
    reset the csp solver. always call this before executing the generated program.
    no need to call it for type checking.
    """
    global CSP_SOLVER
    CSP_SOLVER = CSPSolver()
    reset_var_counter()


def run_csp_solver(
    query: str,
    solver_type: str = "default",
    select_solution: str = "min_dist",
):
    """
    solve the csp problem. call this after executing the generated program to get solutions.
    """
    if solver_type == "naive":
        CSP_SOLVER.solve_naive()
    elif solver_type == "non_csp":
        CSP_SOLVER.solve_non_csp()
    elif solver_type == "default":
        CSP_SOLVER.solve(query=query, select_solution=select_solution)
    else:
        raise SystemError(f"invalid csp solver type: {solver_type}.")


def get_var_identifier(csp_var: CSPVar | list[CSPVar] | set[CSPVar] | None) -> str:
    if csp_var is None:
        return "(none)"
    if isinstance(csp_var, CSPVar):
        return csp_var.get_identifier()
    if is_list_of_type(csp_var, CSPVar):
        return f"[{', '.join(var.get_identifier() for var in csp_var)}]"
    raise SystemError(f"invalid variable: {csp_var}")


@register_handler()
class DefineVariable:
    FUNC_NAME = "DEFINE_VARIABLE"
    SIG_STR = "(labels: list[str]) -> CSPVar"

    def call_type_check(self, labels: list[str]) -> CSPVar:
        check(
            isinstance(labels, list),
            f"parameter @labels has wrong type: {type(labels)}.",
        )
        check(
            all(isinstance(x, str) for x in labels),
            "parameter @labels must only contain str!",
        )
        check(len(labels) > 0, "parameter @labels must not be empty!")

        for label in labels:
            check(
                label in GlobalState.relevant_obj_set,
                f"label ({label}) not in the given list of object labels.",
            )

        return CSPVar()

    def call(self, labels: list[str]) -> CSPVar:
        global CSP_SOLVER
        check(all(x in GlobalState.relevant_obj_instances for x in labels))
        return CSP_SOLVER.create_var(labels=labels)


@register_handler(cfc.DISABLE_NEGATION)
class DefineNegativeVariable:
    FUNC_NAME = "DEFINE_NEGATIVE_VARIABLE"
    SIG_STR = "(labels: list[str]) -> CSPVar"

    def call_type_check(self, labels: list[str]) -> CSPVar:
        check(
            isinstance(labels, list),
            f"parameter @labels has wrong type: {type(labels)}.",
        )
        check(
            all(isinstance(x, str) for x in labels),
            "parameter @labels must only contain str!",
        )
        check(len(labels) > 0, "parameter @labels must not be empty!")

        for label in labels:
            check(
                label in GlobalState.relevant_obj_set,
                f"label ({label}) not in the given list of object labels.",
            )

        csp_var = CSPVar()
        csp_var.negative = True
        return csp_var

    def call(self, labels: list[str]) -> CSPVar:
        global CSP_SOLVER
        check(all(x in GlobalState.relevant_obj_instances for x in labels))
        return CSP_SOLVER.create_var(labels=labels, negative=True)


@register_handler()
class SetTarget:
    FUNC_NAME = "SET_TARGET"
    SIG_STR = "(obj: CSPVar) -> None"

    def call_type_check(self, obj: CSPVar) -> None:
        global TARGET_VARIABLE

        check(not obj.negative, "negative variables cannot be set as target.")

        check(isinstance(obj, CSPVar), f"parameter @obj has wrong type: {type(obj)}.")
        check(
            TARGET_VARIABLE is None,
            "there is only one target and you can only call SetTarget once!",
        )

        TARGET_VARIABLE = obj

    def call(self, obj: CSPVar) -> None:
        obj.set_as_target()


def build_check_func(
    target: CSPVar,
    anchor: CSPVar,
    check_func_1_1: Callable[[ObjInstance, ObjInstance], bool],
) -> Callable[[Solution], bool]:
    check(isinstance(target, CSPVar))
    check(isinstance(anchor, CSPVar))

    check(target != anchor)

    def check_func(
        solution_dict: Solution,
    ) -> bool:
        inst_a = solution_dict[target]
        inst_b = solution_dict[anchor]

        if inst_a == inst_b:
            return False

        return check_func_1_1(inst_a, inst_b)

    return check_func


class ConstraintSimple(CSPConstraint):
    SIG_STR = "(target: CSPVar, anchor: CSPVar) -> CSPConstraint"

    def get_desc_str(self) -> str:
        return f"[target: {get_var_identifier(self.target)}] [anchor: {get_var_identifier(self.anchor)}]"

    def call_type_check(self, target: CSPVar, anchor: CSPVar) -> CSPConstraint:
        check(
            isinstance(target, CSPVar),
            f"parameter @target has wrong type: {type(target)}.",
        )
        check(
            isinstance(anchor, CSPVar),
            f"parameter @anchor has wrong type: {type(target)}.",
        )

        check(target != anchor, "parameter @target and @anchor should not be the same.")

        check(
            not target.negative or not anchor.negative,
            "at least one of @target and @anchor must be non-negative.",
        )

        con = self.__class__()
        con.target = target
        return con

    def call(self, target: CSPVar, anchor: CSPVar) -> CSPConstraint:
        con = self.__class__(target=target, anchor=anchor)
        CSP_SOLVER.add_constraint(constraint=con)
        return con

    @staticmethod
    @abstractmethod
    def check_func_1_1(inst_0: ObjInstance, inst_1: ObjInstance) -> bool:
        """implement this method to check the relation between two single instances"""

    def __init__(
        self,
        target: CSPVar | None = None,
        anchor: CSPVar | None = None,
    ):
        if target is None or anchor is None:
            return

        super().__init__()
        self.target = target
        self.anchor = anchor
        self.check_func: Callable | None = None

        # this is a dependency if the target is a CSPSetVar
        self.check_func = build_check_func(
            target=self.target,
            anchor=self.anchor,
            check_func_1_1=self.check_func_1_1,
        )

    def get_target_var(self) -> CSPVar:
        return self.target

    def get_vars(self) -> set[CSPVar]:
        return {self.target, self.anchor}

    def check_solution(self, solution_dict: Solution) -> bool:
        check(self.target in solution_dict)
        check(self.anchor in solution_dict)
        return self.check_func(solution_dict)


@register_handler()
class ConstraintLeft(ConstraintSimple):
    FUNC_NAME = "CONSTRAINT_LEFT"

    @staticmethod
    def check_func_1_1(inst_0: ObjInstance, inst_1: ObjInstance) -> bool:
        if inst_1.label == "room center":
            return True

        # when looking at inst_1, inst_0 is on the left
        world_to_local = lookat_matrix(
            eye=inst_1.bbox.center, target=GlobalState.room_center
        )
        center_0_local = world_to_local @ np.hstack([inst_0.bbox.center, 1])
        center_0_local = center_0_local[:3]

        # return center_0_local[0] < 0 and ConstraintNear.check_func_1_1(inst_0, inst_1)
        return center_0_local[0] < 0


@register_handler()
class ConstraintRight(ConstraintSimple):
    FUNC_NAME = "CONSTRAINT_RIGHT"

    @staticmethod
    def check_func_1_1(inst_0: ObjInstance, inst_1: ObjInstance) -> bool:
        if inst_1.label == "room center":
            return True

        # when looking at inst_1, inst_0 is on the right
        world_to_local = lookat_matrix(
            eye=inst_1.bbox.center, target=GlobalState.room_center
        )
        center_0_local = world_to_local @ np.hstack([inst_0.bbox.center, 1])
        center_0_local = center_0_local[:3]

        # return center_0_local[0] > 0 and ConstraintNear.check_func_1_1(inst_0, inst_1)
        return center_0_local[0] > 0


@register_handler()
class ConstraintNear(ConstraintSimple):
    FUNC_NAME = [
        "CONSTRAINT_NEAR",
        "CONSTRAINT_FRONT",
        "CONSTRAINT_BEHIND",
        "CONSTRAINT_CLOSE",
        "CONSTRAINT_BESIDE",
    ]

    @staticmethod
    def check_func_1_1(inst_0: ObjInstance, inst_1: ObjInstance) -> bool:
        # # max_extent = inst_1.bbox.max_extent
        # max_extent = max(inst_0.bbox.max_extent, inst_1.bbox.max_extent)
        # threshold = get_config("near_distance_ratio") * max_extent
        threshold = Configs.near_distance
        return np.linalg.norm(inst_0.bbox.center - inst_1.bbox.center) < threshold


@register_handler()
class ConstraintFar(ConstraintSimple):
    FUNC_NAME = [
        "CONSTRAINT_FAR",
        "CONSTRAINT_AWAY",
        "CONSTRAINT_ACROSS",
        "CONSTRAINT_OPPOSITE",
    ]

    @staticmethod
    def check_func_1_1(inst_0: ObjInstance, inst_1: ObjInstance) -> bool:
        # max_extent = inst_1.bbox.max_extent
        # # max_extent = max(inst_0.bbox.max_extent, inst_1.bbox.max_extent)
        # threshold = get_config("far_distance_ratio") * max_extent
        threshold = Configs.far_distance
        return np.linalg.norm(inst_0.bbox.center - inst_1.bbox.center) > threshold


@register_handler()
class ConstraintAbove(ConstraintSimple):
    FUNC_NAME = [
        "CONSTRAINT_ABOVE",
        "CONSTRAINT_ON",
    ]

    @staticmethod
    def check_func_1_1(inst_0: ObjInstance, inst_1: ObjInstance) -> bool:
        is_above = inst_0.bbox.center[2] > inst_1.bbox.center[2] + 1e-3
        dist_h = np.linalg.norm(inst_0.bbox.center[:2] - inst_1.bbox.center[:2])

        # max_extent = min(
        #     max(inst_0.bbox.extents["x"], inst_0.bbox.extents["y"]),
        #     max(inst_1.bbox.extents["x"], inst_1.bbox.extents["y"]),
        # )
        # threshold = get_config("above_below_horizontal_distance_ratio") * max_extent
        threshold = Configs.above_below_horizontal_distance

        return is_above and dist_h < threshold


@register_handler()
class ConstraintBelow(ConstraintSimple):
    FUNC_NAME = [
        "CONSTRAINT_BELOW",
        "CONSTRAINT_UNDER",
    ]

    @staticmethod
    def check_func_1_1(inst_0: ObjInstance, inst_1: ObjInstance) -> bool:
        is_below = inst_0.bbox.center[2] < inst_1.bbox.center[2] - 1e-3
        dist_h = np.linalg.norm(inst_0.bbox.center[:2] - inst_1.bbox.center[:2])

        # max_extent = min(
        #     max(inst_0.bbox.extents["x"], inst_0.bbox.extents["y"]),
        #     max(inst_1.bbox.extents["x"], inst_1.bbox.extents["y"]),
        # )
        # threshold = get_config("above_below_horizontal_distance_ratio") * max_extent
        threshold = Configs.above_below_horizontal_distance

        return is_below and dist_h < threshold


@register_handler()
class ConstraintInside(ConstraintSimple):
    FUNC_NAME = [
        "CONSTRAINT_INSIDE",
        "CONSTRAINT_IN",
    ]
    SIG_STR = "(target: CSPVar, anchor: CSPVar) -> CSPConstraint"

    def call_type_check(self, target: CSPVar, anchor: CSPVar) -> CSPConstraint:
        check(
            isinstance(target, CSPVar),
            f"parameter @target has wrong type: {type(target)}.",
        )
        check(
            isinstance(anchor, CSPVar),
            f"parameter @anchor has wrong type: {type(anchor)}.",
        )

        check(target != anchor, "parameter @target and @anchor should not be the same.")

        con = self.__class__()
        con.target = target
        return con

    def call(self, target: CSPVar, anchor: CSPVar) -> CSPConstraint:
        check(isinstance(target, CSPVar))
        check(isinstance(anchor, CSPVar))
        con = self.__class__(target=target, anchor=anchor)
        CSP_SOLVER.add_constraint(constraint=con)
        return con

    @staticmethod
    def check_func_1_1(inst_0: ObjInstance, inst_1: ObjInstance) -> bool:
        return inst_1.bbox.contains(inst_0.bbox.center)


@register_handler()
class ConstraintCenter(ConstraintSimple):
    FUNC_NAME = [
        "CONSTRAINT_CENTER",
        "CONSTRAINT_MIDDLE",
    ]

    @staticmethod
    def check_func_1_1(inst_0: ObjInstance, inst_1: ObjInstance) -> bool:
        return inst_1.bbox.contains(inst_0.bbox.center)

    @staticmethod
    def check_func_1_n(inst_0: ObjInstance, inst_1: list[ObjInstance]) -> bool:
        if len(inst_1) == 0:
            return False

        centers = [inst.bbox.center for inst in inst_1]
        group_center = np.mean(centers, axis=0)
        if inst_0 in inst_1:
            # if the target is one of the anchors, it must be the instance in the middle
            min_idx = np.argmin([np.linalg.norm(c - group_center) for c in centers])
            return inst_0 == inst_1[min_idx]
        else:
            # otherwise, the target must be close enough to the center of the anchors
            # max_extent = np.mean([inst.bbox.max_extent for inst in inst_1])
            # threshold = get_config("center_distance_ratio") * max_extent
            threshold = Configs.center_distance
            return np.linalg.norm(inst_0.bbox.center - group_center) < threshold


def build_check_func_between(
    target: CSPVar,
    anchors: set[CSPVar],
    check_func_between: Callable[[ObjInstance, list[ObjInstance]], bool],
) -> Callable[[Solution], bool]:
    check(
        isinstance(target, CSPVar),
        f"invalid argument type: {type(target)}; {type(anchors)}",
    )
    check_set_of_type(
        anchors,
        CSPVar,
        f"invalid argument type: {type(target)}; {type(anchors)}",
    )

    def check_func(
        solution_dict: Solution,
    ) -> bool:
        inst_a = solution_dict[target]
        sol_b = [solution_dict[anchor] for anchor in anchors]

        # ignore the target instance in the set of anchor instances
        if inst_a in sol_b:
            sol_b.remove(inst_a)

        if len(sol_b) >= 2:
            return check_func_between(inst_a, sol_b)
        else:
            return False

    return check_func


@register_handler()
class ConstraintBetween(CSPConstraint):
    FUNC_NAME = ["CONSTRAINT_BETWEEN"]
    SIG_STR = "(target: CSPVar, anchors: set[CSPVar]) -> CSPConstraint"

    def call_type_check(self, target: CSPVar, anchors: set[CSPVar]) -> CSPConstraint:
        check(
            isinstance(target, CSPVar),
            f"parameter @target has wrong type: {type(target)}.",
        )
        check_set_of_type(
            anchors,
            CSPVar,
            f"parameter @anchors has wrong type: {type(target)}.",
        )

        if isinstance(anchors, set):
            check(
                (len(anchors) >= 2),
                "parameter @anchors must include at least two variables.",
            )
            check(
                all(isinstance(x, CSPVar) for x in anchors),
                "parameter @anchors contains invalid element.",
            )

        check(target not in anchors, "@anchors must not include the @target!")

        check(not target.negative, "@target cannot be negative.")
        check(
            all(not anchor.negative for anchor in anchors),
            "@anchors cannot contain negative variables.",
        )

        con = self.__class__()
        con.target = target
        return con

    def call(self, target: CSPVar, anchors: set[CSPVar]) -> CSPConstraint:
        check(isinstance(target, CSPVar))
        check_set_of_type(anchors, CSPVar)
        con = self.__class__(target=target, anchors=anchors)
        CSP_SOLVER.add_constraint(constraint=con)
        return con

    @staticmethod
    def check_func_between(
        inst_0: ObjInstance,
        inst_1_arr: list[ObjInstance],
    ) -> bool:
        if len(inst_1_arr) == 2:
            c0 = inst_0.bbox.center
            c1 = inst_1_arr[0].bbox.center
            c2 = inst_1_arr[1].bbox.center

            diff = c2 - c1
            diff_norm = np.linalg.norm(diff) + 1e-5
            diff /= diff_norm

            # the projected length should be between 0 and diff_norm
            t = (c0 - c1).dot(diff)
            if t <= 1e-3 or t >= diff_norm - 1e-3:
                return False

            d = np.linalg.norm(np.cross(c2 - c1, c1 - c0)) / (
                np.linalg.norm(c2 - c1) + 1e-5
            )

            # max_extent = max(
            #     inst_0.bbox.max_extent,
            #     inst_1_arr[0].bbox.max_extent,
            #     inst_1_arr[1].bbox.max_extent,
            # )
            # threshold = get_config("between_distance_ratio") * max_extent
            threshold = Configs.between_distance

            return d < threshold

        elif len(inst_1_arr) > 2:
            c0 = inst_0.bbox.center
            c1_arr = [inst_1.bbox.center for inst_1 in inst_1_arr]
            c1 = np.mean(c1_arr, axis=0)

            d = np.linalg.norm(c0 - c1)

            # or better: decide with barycentric coordinates on the horizontal plane
            # return d < inst_0.bbox.max_extent * get_config("between_distance_ratio")
            return d < Configs.between_distance

        raise SystemError(
            "not enough anchors: at least two required, "
            f"but only {len(inst_1_arr)} were given."
        )

    def get_desc_str(self) -> str:
        check_set_of_type(self.anchors, CSPVar)
        return (
            f"[target: {get_var_identifier(self.target)}]"
            f" [anchors: {' '.join(anchor.get_identifier() for anchor in self.anchors)}]"
        )

    def __init__(
        self,
        target: CSPVar | None = None,
        anchors: set[CSPVar] | None = None,
    ):
        if target is None or anchors is None:
            return

        super().__init__()
        self.target = target
        self.anchors = anchors
        self.check_func: Callable | None = None

        self.check_func = build_check_func_between(
            target=self.target,
            anchors=self.anchors,
            check_func_between=self.check_func_between,
        )

        # collect variables used in this constraint
        self.variables = {self.target, *self.anchors}

    def get_target_var(self) -> CSPVar:
        return self.target

    def get_vars(self) -> set[CSPVar]:
        return self.variables

    def check_solution(self, solution_dict: Solution) -> bool:
        check(self.target in solution_dict)
        check(
            isinstance(self.anchors, set)
            and all(anchor in solution_dict for anchor in self.anchors)
        )
        return self.check_func(solution_dict)


@register_handler(cfc.DISABLE_MINMAX)
class ConstraintMin(CSPConstraint):
    FUNC_NAME = "CONSTRAINT_MIN_OF"
    SIG_STR = "(target: CSPVar, score_func: str, anchor: CSPVar | None = None) -> CSPConstraint"
    SELECT_FUNC = min

    def call_type_check(
        self,
        target: CSPVar,
        score_func: str,
        anchor: CSPVar | None = None,
    ) -> CSPConstraint:
        check(
            isinstance(target, CSPVar),
            f"parameter @target has wrong type: {type(target)}.",
        )
        check(
            anchor is None or isinstance(anchor, CSPVar),
            f"parameter @anchor has wrong type: {type(anchor)}.",
        )
        check(
            isinstance(score_func, str),
            f"parameter @score_func has wrong type: {type(score_func)}.",
        )

        check(
            (anchor is None or target != anchor),
            "parameter @target and @anchor should not be the same.",
        )
        check(
            (score_func in SCORE_FUNCTIONS),
            f"score function [{score_func}] is not defined!",
        )

        if anchor is None:
            check(
                SCORE_FUNCTIONS[score_func].NEED_ANCHOR is False,
                (
                    "you did not specify the @anchor parameter, "
                    f"but the score function you used ({score_func}) require an anchor."
                ),
            )
        else:
            check(
                SCORE_FUNCTIONS[score_func].NEED_ANCHOR is True,
                (
                    "you specified the @anchor parameter, but the score function you "
                    f"used ({score_func}) does not require an anchor."
                ),
            )

        check(not target.negative, "@target cannot be negative.")
        check(anchor is None or not anchor.negative, "@anchor cannot be negative.")

        con = self.__class__()
        con.target = target
        return con

    def call(
        self,
        target: CSPVar,
        score_func: str,
        anchor: CSPVar | None = None,
    ) -> CSPConstraint:
        con = self.__class__(target=target, anchor=anchor, score_func=score_func)
        CSP_SOLVER.add_constraint(constraint=con)
        return con

    def get_desc_str(self) -> str:
        return (
            f"[target: {get_var_identifier(self.target)}]"
            f" [anchor: {get_var_identifier(self.anchor)}]"
        )

    def __init__(
        self,
        target: CSPVar | None = None,
        anchor: CSPVar | None = None,
        score_func: str | None = None,
    ):
        # anchor can be none
        if target is None or score_func is None:
            return

        super().__init__()
        self.target = target
        self.anchor = anchor
        self.score_func = SCORE_FUNCTIONS[score_func]

        if self.anchor is not None:
            self.variables = {self.target, self.anchor}
        else:
            self.variables = {self.target}

    def get_target_var(self) -> CSPVar:
        return self.target

    def get_vars(self) -> set[CSPVar]:
        return self.variables

    def check_solution(self, solution_dict: Solution) -> bool:
        raise NotImplementedError()

    def filter_solutions(self, solutions: list[Solution]) -> list[Solution]:
        if not solutions:
            return []

        check(all(self.target in sol for sol in solutions))

        anchor_inst = None
        if self.anchor is not None:
            check(all(self.anchor in sol for sol in solutions))
            # check(len(set(sol[self.anchor] for sol in solutions)) == 1)
            anchor_inst = solutions[0][self.anchor]

        cand_insts = [sol[self.target] for sol in solutions]
        check(len(cand_insts) > 0)

        select_func = self.SELECT_FUNC

        scores = self.score_func.get_scores(cand_insts, anchor_inst)
        # print()
        # print(scores)
        # if self.anchor is not None:
        #     print("has anchor!")
        # for inst in cand_insts:
        #     print(inst.inst_id, inst.label)
        # if anchor_inst is not None:
        #     print("anchor:", anchor_inst.inst_id, anchor_inst.label)
        # print()
        check(len(scores) == len(solutions))

        return [select_func(zip(solutions, scores), key=lambda x: x[1])[0]]


@register_handler(cfc.DISABLE_MINMAX)
class ConstraintMax(ConstraintMin):
    FUNC_NAME = "CONSTRAINT_MAX_OF"
    SELECT_FUNC = max


@register_handler()
class ConstraintMore(CSPConstraint):
    FUNC_NAME = "CONSTRAINT_MORE"
    SIG_STR = "(target: CSPVar, reference: CSPVar, score_func: str, anchor: CSPVar | None = None) -> CSPConstraint"

    @staticmethod
    def COMPARE_FUNC(a, b):
        return a > b

    def call_type_check(
        self,
        target: CSPVar,
        reference: CSPVar,
        score_func: str,
        anchor: CSPVar | None = None,
    ) -> CSPConstraint:
        # TODO: allow @target to be CSPSetVar (maybe also reference and anchor?)

        check(
            isinstance(reference, CSPVar),
            f"parameter @reference has wrong type: {type(reference)}.",
        )
        check(
            isinstance(target, CSPVar),
            f"parameter @target has wrong type: {type(target)}.",
        )
        check(
            anchor is None or isinstance(anchor, CSPVar),
            f"parameter @anchor has wrong type: {type(anchor)}.",
        )
        check(
            isinstance(score_func, str),
            f"parameter @score_func has wrong type: {type(score_func)}.",
        )

        check(
            (score_func in SCORE_FUNCTIONS),
            f"score function [{score_func}] is not defined!",
        )

        check(
            (anchor is None or target != anchor),
            "parameter @target and @anchor should not be the same.",
        )

        check(
            (target != reference),
            "parameter @target and @reference should not be the same.",
        )

        if anchor is None:
            check(
                SCORE_FUNCTIONS[score_func].NEED_ANCHOR is False,
                (
                    "you did not specify the @anchor parameter, "
                    f"but the score function you used ({score_func}) require an anchor."
                ),
            )
        else:
            check(
                SCORE_FUNCTIONS[score_func].NEED_ANCHOR is True,
                (
                    "you specified the @anchor parameter, but the score function you "
                    f"used ({score_func}) does not require an anchor."
                ),
            )

        check(not target.negative, "@target cannot be negative.")
        check(not reference.negative, "@reference cannot be negative.")
        check(anchor is None or not anchor.negative, "@anchor cannot be negative.")

        con = self.__class__()
        con.target = target
        return con

    def call(
        self,
        target: CSPVar,
        reference: CSPVar,
        score_func: str,
        anchor: CSPVar | None = None,
    ) -> CSPConstraint:
        con = self.__class__(
            target=target, reference=reference, anchor=anchor, score_func=score_func
        )
        CSP_SOLVER.add_constraint(constraint=con)
        return con

    def get_desc_str(self) -> str:
        return (
            f"[target: {get_var_identifier(self.target)}]"
            f" [reference: {get_var_identifier(self.reference)}]"
            f" [anchor: {get_var_identifier(self.anchor)}]"
        )

    def __init__(
        self,
        target: CSPVar | None = None,
        reference: CSPVar | None = None,
        anchor: CSPVar | None = None,
        score_func: str | None = None,
    ):
        # anchor can be none
        if target is None or reference is None or score_func is None:
            return

        super().__init__()
        self.target = target
        self.reference = reference
        self.anchor = anchor
        self.score_func = SCORE_FUNCTIONS[score_func]

        if self.anchor is not None:
            self.variables = {self.target, self.reference, self.anchor}
        else:
            self.variables = {self.target, self.reference}

    def get_target_var(self) -> CSPVar:
        return self.target

    def get_dependent_var(self) -> CSPVar | None:
        return self.target

    def get_vars(self) -> set[CSPVar]:
        return self.variables

    def check_solution(self, solution_dict: Solution) -> bool:
        check(isinstance(self.target, CSPVar))
        check(self.target in solution_dict)
        check(self.reference in solution_dict)
        check(self.anchor is None or self.anchor in solution_dict)

        inst_target = solution_dict[self.target]
        inst_ref = solution_dict[self.reference]

        if self.anchor is None:
            scores = self.score_func.get_scores([inst_target, inst_ref])
        else:
            scores = self.score_func.get_scores(
                [inst_target, inst_ref], solution_dict[self.anchor]
            )

        return self.COMPARE_FUNC(scores[0], scores[1])


@register_handler()
class ConstraintLess(ConstraintMore):
    FUNC_NAME = "CONSTRAINT_LESS"

    @staticmethod
    def COMPARE_FUNC(a, b):
        return a < b