NUCS 7.0.0__tar.gz → 7.2.0__tar.gz

{nucs-7.0.0 → nucs-7.2.0/NuCS.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: NuCS
-Version: 7.0.0
+Version: 7.2.0
 Summary: A Numpy and Numba based Python library for solving Constraint Satisfaction Problems over finite domains
 Author-email: Yan Georget <yan.georget@gmail.com>
 Project-URL: Homepage, https://github.com/yangeorget/nucs

{nucs-7.0.0 → nucs-7.2.0}/NuCS.egg-info/SOURCES.txt

@@ -26,6 +26,9 @@ nucs/examples/bibd/bibd_problem.py
 nucs/examples/donald/__init__.py
 nucs/examples/donald/__main__.py
 nucs/examples/donald/donald_problem.py
+nucs/examples/employee_scheduling/__init__.py
+nucs/examples/employee_scheduling/__main__.py
+nucs/examples/employee_scheduling/employee_scheduling_problem.py
 nucs/examples/golomb/__init__.py
 nucs/examples/golomb/__main__.py
 nucs/examples/golomb/golomb_problem.py
@@ -88,6 +91,7 @@ nucs/propagators/alldifferent_propagator.py
 nucs/propagators/and_eq_propagator.py
 nucs/propagators/count_eq_c_propagator.py
 nucs/propagators/count_eq_propagator.py
+nucs/propagators/count_geq_c_propagator.py
 nucs/propagators/count_leq_c_propagator.py
 nucs/propagators/dummy_propagator.py
 nucs/propagators/element_eq_propagator.py
@@ -118,10 +122,12 @@ nucs/solvers/shaving_consistency_algorithm.py
 nucs/solvers/solver.py
 tests/__init__.py
 tests/test_heaps.py
+tests/examples/__init__.py
 tests/examples/test_all_interval_series.py
 tests/examples/test_alpha.py
 tests/examples/test_bibd.py
 tests/examples/test_donald.py
+tests/examples/test_employee_scheduling.py
 tests/examples/test_golomb.py
 tests/examples/test_knapsack.py
 tests/examples/test_latin_square.py
@@ -150,6 +156,7 @@ tests/propagators/test_affine_leq.py
 tests/propagators/test_alldifferent.py
 tests/propagators/test_count_eq.py
 tests/propagators/test_count_eq_c.py
+tests/propagators/test_count_geq_c.py
 tests/propagators/test_count_leq_c.py
 tests/propagators/test_element_eq.py
 tests/propagators/test_element_l_eq.py

{nucs-7.0.0/NuCS.egg-info → nucs-7.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: NuCS
-Version: 7.0.0
+Version: 7.2.0
 Summary: A Numpy and Numba based Python library for solving Constraint Satisfaction Problems over finite domains
 Author-email: Yan Georget <yan.georget@gmail.com>
 Project-URL: Homepage, https://github.com/yangeorget/nucs

{nucs-7.0.0 → nucs-7.2.0}/docs/source/conf.py

@@ -6,8 +6,8 @@ project = 'NuCS'
 copyright = '2024-2025, Yan Georget'
 author = 'Yan Georget'
 
-release = '7.0.0'
-version = '7.0.0'
+release = '7.2.0'
+version = '7.2.0'
 
 # -- General configuration
 

nucs-7.2.0/nucs/examples/employee_scheduling/__main__.py

@@ -0,0 +1,31 @@
+###############################################################################
+# __   _            _____    _____
+# | \ | |          / ____|  / ____|
+# |  \| |  _   _  | |      | (___
+# | . ` | | | | | | |       \___ \
+# | |\  | | |_| | | |____   ____) |
+# |_| \_|  \__,_|  \_____| |_____/
+#
+# Fast constraint solving in Python  - https://github.com/yangeorget/nucs
+#
+# Copyright 2024-2025 - Yan Georget
+###############################################################################
+from nucs.constants import OPTIM_MODES, OPTIM_PRUNE
+from nucs.examples.default_argument_parser import DefaultArgumentParser
+from nucs.examples.employee_scheduling.employee_scheduling_problem import EmployeeSchedulingProblem
+from nucs.heuristics.heuristics import DOM_HEURISTIC_MAX_VALUE
+from nucs.solvers.backtrack_solver import BacktrackSolver
+
+# Run with the following command (the second run is much faster because the code has been compiled):
+# NUMBA_CACHE_DIR=.numba/cache python -m nucs.examples.employee_scheduling
+if __name__ == "__main__":
+    parser = DefaultArgumentParser()
+    parser.add_argument("--opt_mode", choices=OPTIM_MODES, default=OPTIM_PRUNE)
+    args = parser.parse_args()
+    problem = EmployeeSchedulingProblem()
+    solver = BacktrackSolver(problem, dom_heuristic_idx=DOM_HEURISTIC_MAX_VALUE, log_level=args.log_level)
+    solution = solver.maximize(problem.satisfied_request_nb, mode=args.opt_mode)
+    if args.stats:
+        solver.print_statistics()
+    if args.display:
+        problem.print_solution(solution)

nucs-7.2.0/nucs/examples/employee_scheduling/employee_scheduling_problem.py

@@ -0,0 +1,107 @@
+###############################################################################
+# __   _            _____    _____
+# | \ | |          / ____|  / ____|
+# |  \| |  _   _  | |      | (___
+# | . ` | | | | | | |       \___ \
+# | |\  | | |_| | | |____   ____) |
+# |_| \_|  \__,_|  \_____| |_____/
+#
+# Fast constraint solving in Python  - https://github.com/yangeorget/nucs
+#
+# Copyright 2024-2025 - Yan Georget
+###############################################################################
+from typing import Any, List
+
+from numpy.typing import NDArray
+
+from nucs.problems.problem import Problem
+from nucs.propagators.propagators import ALG_COUNT_EQ, ALG_COUNT_EQ_C, ALG_COUNT_LEQ_C
+
+
+# TODO: GCC instead of booleans
+# TODO: get rid of count variables, use count_leq and count_geq
+# TODO: use custom heuristic (cf requests)
+class EmployeeSchedulingProblem(Problem):
+    """
+    See https://developers.google.com/optimization/scheduling/employee_scheduling.
+    """
+
+    def shift_index(self, day: int, shift: int, nurse: int) -> int:
+        return day * self.shift_nb * self.nurse_nb + shift * self.nurse_nb + nurse
+
+    def nurses(self, day: int, shift: int) -> List[int]:
+        start_shift = self.shift_index(day, shift, 0)
+        return list(range(start_shift, start_shift + self.nurse_nb))
+
+    def shifts(self, day: int, nurse: int) -> List[int]:
+        start_shift = self.shift_index(day, 0, nurse)
+        return list(
+            range(
+                start_shift,
+                start_shift + self.shift_nb * self.nurse_nb,
+                self.nurse_nb,
+            )
+        )
+
+    def __init__(self) -> None:
+        """
+        Initializes the problem.
+        """
+        self.day_nb = 7
+        self.shift_nb = 3
+        self.nurse_nb = 5
+        self.shift_total_nb = self.day_nb * self.shift_nb * self.nurse_nb
+        self.shift_requests_nds = [
+            [[0, 0, 1], [0, 0, 0], [0, 0, 0], [0, 0, 0], [0, 0, 1], [0, 1, 0], [0, 0, 1]],
+            [[0, 0, 0], [0, 0, 0], [0, 1, 0], [0, 1, 0], [1, 0, 0], [0, 0, 0], [0, 0, 1]],
+            [[0, 1, 0], [0, 1, 0], [0, 0, 0], [1, 0, 0], [0, 0, 0], [0, 1, 0], [0, 0, 0]],
+            [[0, 0, 1], [0, 0, 0], [1, 0, 0], [0, 1, 0], [0, 0, 0], [1, 0, 0], [0, 0, 0]],
+            [[0, 0, 0], [0, 0, 1], [0, 1, 0], [0, 0, 0], [1, 0, 0], [0, 1, 0], [0, 0, 0]],
+        ]
+        shift_requests_dsn = [
+            self.shift_requests_nds[n][d][s]
+            for d in range(self.day_nb)
+            for s in range(self.shift_nb)
+            for n in range(self.nurse_nb)
+        ]
+        min_shift_count_per_nurse = (self.shift_nb * self.day_nb) // self.nurse_nb
+        max_shift_count_per_nurse = min_shift_count_per_nurse + (
+            0 if self.shift_nb * self.day_nb % self.nurse_nb == 0 else 1
+        )
+        super().__init__([(0, 1)] * self.shift_total_nb)  # the boolean variables for shifts
+        self.add_variables(
+            [(min_shift_count_per_nurse, max_shift_count_per_nurse)] * self.nurse_nb
+        )  # the number of shifts per nurse
+        self.satisfied_request_nb = self.add_variable((0, self.shift_total_nb))  # the number of satisfied requests
+        self.add_propagators(
+            [(self.nurses(d, s), ALG_COUNT_EQ_C, [1, 1]) for d in range(self.day_nb) for s in range(self.shift_nb)]
+        )
+        self.add_propagators(
+            [(self.shifts(d, n), ALG_COUNT_LEQ_C, [1, 1]) for d in range(self.day_nb) for n in range(self.nurse_nb)]
+        )
+        self.add_propagators(
+            [
+                (list(range(n, self.shift_total_nb + self.nurse_nb, self.nurse_nb)), ALG_COUNT_EQ, [1])
+                for n in range(self.nurse_nb)
+            ]
+        )
+        self.add_propagator(
+            (
+                [index for index in range(0, self.shift_total_nb) if shift_requests_dsn[index]]
+                + [self.satisfied_request_nb],
+                ALG_COUNT_EQ,
+                [1],
+            )
+        )
+
+    def solution_as_printable(self, solution: NDArray) -> Any:
+        return {
+            d: [
+                [
+                    (("W" if self.shift_requests_nds[n][d][s] else "w") if solution[self.shift_index(d, s, n)] else " ")
+                    for n in range(self.nurse_nb)
+                ]
+                for s in range(self.shift_nb)
+            ]
+            for d in range(self.day_nb)
+        }

{nucs-7.0.0 → nucs-7.2.0}/nucs/problems/problem.py

@@ -12,7 +12,7 @@
 ###############################################################################
 import copy
 import logging
-from typing import Any, List, Optional, Self, Tuple, Union
+from typing import Any, List, Optional, Self, Sequence, Tuple, Union
 
 import numpy as np
 from numba import njit
@@ -114,7 +114,7 @@ class Problem:
 
     def add_variables(
         self,
-        domains: List[Union[int, Tuple[int, int]]],
+        domains: Sequence[Union[int, Tuple[int, int]]],
         variables: Optional[List[int]] = None,
         offsets: Optional[List[int]] = None,
     ) -> int:

{nucs-7.0.0 → nucs-7.2.0}/nucs/propagators/affine_eq_propagator.py

@@ -39,7 +39,7 @@ def get_triggers_affine_eq(n: int, dom_idx: int, parameters: NDArray) -> int:
 @njit(cache=True)
 def compute_domains_affine_eq(domains: NDArray, parameters: NDArray) -> int:
     """
-    Implements Sigma_i a_i * x_i = a_{n-1}.
+    Implements Sigma_i a_i * x_i = a_{n}.
     :param domains: the domains of the variables, x is an alias for domains
     :param parameters: the parameters of the propagator, a is an alias for parameters
     :return: the status of the propagation (consistency, inconsistency or entailment) as an int

{nucs-7.0.0 → nucs-7.2.0}/nucs/propagators/affine_geq_propagator.py

@@ -47,7 +47,7 @@ def get_triggers_affine_geq(n: int, dom_idx: int, parameters: NDArray) -> int:
 @njit(cache=True)
 def compute_domains_affine_geq(domains: NDArray, parameters: NDArray) -> int:
     """
-    Implements Sigma_i a_i * x_i >= a_{n-1}.
+    Implements Sigma_i a_i * x_i >= a_{n}.
     :param domains: the domains of the variables, x is an alias for domains
     :param parameters: the parameters of the propagator, a is an alias for parameters
     :return: the status of the propagation (consistency, inconsistency or entailment) as an int

{nucs-7.0.0 → nucs-7.2.0}/nucs/propagators/affine_leq_propagator.py

@@ -47,7 +47,7 @@ def get_triggers_affine_leq(n: int, dom_idx: int, parameters: NDArray) -> int:
 @njit(cache=True)
 def compute_domains_affine_leq(domains: NDArray, parameters: NDArray) -> int:
     """
-    Implements Sigma_i a_i * x_i <= a_{n-1}.
+    Implements Sigma_i a_i * x_i <= a_{n}.
     :param domains: the domains of the variables, x is an alias for domains
     :param parameters: the parameters of the propagator, a is an alias for parameters
     :return: the status of the propagation (consistency, inconsistency or entailment) as an int

nucs-7.2.0/nucs/propagators/count_geq_c_propagator.py

@@ -0,0 +1,65 @@
+###############################################################################
+# __   _            _____    _____
+# | \ | |          / ____|  / ____|
+# |  \| |  _   _  | |      | (___
+# | . ` | | | | | | |       \___ \
+# | |\  | | |_| | | |____   ____) |
+# |_| \_|  \__,_|  \_____| |_____/
+#
+# Fast constraint solving in Python  - https://github.com/yangeorget/nucs
+#
+# Copyright 2024-2025 - Yan Georget
+###############################################################################
+from numba import njit  # type: ignore
+from numpy.typing import NDArray
+
+from nucs.constants import EVENT_MASK_MIN_MAX, MAX, MIN, PROP_CONSISTENCY, PROP_ENTAILMENT, PROP_INCONSISTENCY
+
+
+def get_complexity_count_geq_c(n: int, parameters: NDArray) -> float:
+    """
+    Returns the time complexity of the propagator as a float.
+    :param n: the number of variables
+    :param parameters: the parameters, unused here
+    :return: a float
+    """
+    return n
+
+
+@njit(cache=True)
+def get_triggers_count_geq_c(n: int, dom_idx: int, parameters: NDArray) -> int:
+    """
+    This propagator is triggered whenever there is a change in the domain of a variable.
+    :param parameters: the parameters, unused here
+    :return: an array of triggers
+    """
+    return EVENT_MASK_MIN_MAX
+
+
+@njit(cache=True)
+def compute_domains_count_geq_c(domains: NDArray, parameters: NDArray) -> int:
+    """
+    Implements Sigma_i (x_i == a) >= c.
+    :param domains: the domains of the variables, x is an alias for domains
+    :param parameters: the parameters of the propagator, a is the first parameter, c is the second parameter
+    :return: the status of the propagation (consistency, inconsistency or entailment) as an int
+    """
+    a = parameters[0]
+    c = parameters[1]
+    count_max = len(domains)
+    count_min = 0
+    for domain in domains:
+        if domain[MIN] > a or domain[MAX] < a:
+            count_max -= 1
+            if count_max < c:
+                return PROP_INCONSISTENCY
+        elif domain[MIN] == a and domain[MAX] == a:
+            count_min += 1
+            if count_min >= c:
+                return PROP_ENTAILMENT
+    if count_max == c:  # we cannot have more domains different from a
+        for domain in domains:
+            if domain[MIN] <= a <= domain[MAX]:
+                domain[:] = a
+        return PROP_ENTAILMENT
+    return PROP_CONSISTENCY

{nucs-7.0.0 → nucs-7.2.0}/nucs/propagators/count_leq_c_propagator.py

@@ -51,12 +51,12 @@ def compute_domains_count_leq_c(domains: NDArray, parameters: NDArray) -> int:
     for domain in domains:
         if domain[MIN] > a or domain[MAX] < a:
             count_max -= 1
+            if count_max <= c:
+                return PROP_ENTAILMENT
         elif domain[MIN] == a and domain[MAX] == a:
             count_min += 1
             if count_min > c:
                 return PROP_INCONSISTENCY
-    if count_max <= c:
-        return PROP_ENTAILMENT
     if count_min == c:  # we cannot have more domains equal to a
         all_different = True
         for domain in domains:

{nucs-7.0.0 → nucs-7.2.0}/nucs/propagators/propagators.py

@@ -48,6 +48,11 @@ from nucs.propagators.count_eq_propagator import (
     get_complexity_count_eq,
     get_triggers_count_eq,
 )
+from nucs.propagators.count_geq_c_propagator import (
+    compute_domains_count_geq_c,
+    get_complexity_count_geq_c,
+    get_triggers_count_geq_c,
+)
 from nucs.propagators.count_leq_c_propagator import (
     compute_domains_count_leq_c,
     get_complexity_count_leq_c,
@@ -140,6 +145,7 @@ ALG_ALLDIFFERENT = register_propagator(
 )
 ALG_COUNT_EQ = register_propagator(get_triggers_count_eq, get_complexity_count_eq, compute_domains_count_eq)
 ALG_COUNT_EQ_C = register_propagator(get_triggers_count_eq_c, get_complexity_count_eq_c, compute_domains_count_eq_c)
+ALG_COUNT_GEQ_C = register_propagator(get_triggers_count_geq_c, get_complexity_count_geq_c, compute_domains_count_geq_c)
 ALG_COUNT_LEQ_C = register_propagator(get_triggers_count_leq_c, get_complexity_count_leq_c, compute_domains_count_leq_c)
 ALG_DUMMY = register_propagator(get_triggers_dummy, get_complexity_dummy, compute_domains_dummy)
 ALG_ELEMENT_EQ = register_propagator(get_triggers_element_eq, get_complexity_element_eq, compute_domains_element_eq)

{nucs-7.0.0 → nucs-7.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name="NuCS"
-version="7.0.0"
+version="7.2.0"
 authors = [
   { name="Yan Georget", email="yan.georget@gmail.com" },
 ]

nucs-7.2.0/tests/examples/test_employee_scheduling.py

@@ -0,0 +1,27 @@
+###############################################################################
+# __   _            _____    _____
+# | \ | |          / ____|  / ____|
+# |  \| |  _   _  | |      | (___
+# | . ` | | | | | | |       \___ \
+# | |\  | | |_| | | |____   ____) |
+# |_| \_|  \__,_|  \_____| |_____/
+#
+# Fast constraint solving in Python  - https://github.com/yangeorget/nucs
+#
+# Copyright 2024-2025 - Yan Georget
+###############################################################################
+from nucs.examples.employee_scheduling.employee_scheduling_problem import EmployeeSchedulingProblem
+
+
+class TestEmployeeScheduling:
+    def test_nurses(self) -> None:
+        assert EmployeeSchedulingProblem().nurses(0, 0) == [0, 1, 2, 3, 4]
+        assert EmployeeSchedulingProblem().nurses(0, 1) == [5, 6, 7, 8, 9]
+        assert EmployeeSchedulingProblem().nurses(1, 0) == [15, 16, 17, 18, 19]
+        assert EmployeeSchedulingProblem().nurses(1, 1) == [20, 21, 22, 23, 24]
+
+    def test_shifts(self) -> None:
+        assert EmployeeSchedulingProblem().shifts(0, 0) == [0, 5, 10]
+        assert EmployeeSchedulingProblem().shifts(0, 1) == [1, 6, 11]
+        assert EmployeeSchedulingProblem().shifts(1, 0) == [15, 20, 25]
+        assert EmployeeSchedulingProblem().shifts(1, 1) == [16, 21, 26]

nucs-7.2.0/tests/propagators/test_count_geq_c.py

@@ -0,0 +1,55 @@
+###############################################################################
+# __   _            _____    _____
+# | \ | |          / ____|  / ____|
+# |  \| |  _   _  | |      | (___
+# | . ` | | | | | | |       \___ \
+# | |\  | | |_| | | |____   ____) |
+# |_| \_|  \__,_|  \_____| |_____/
+#
+# Fast constraint solving in Python  - https://github.com/yangeorget/nucs
+#
+# Copyright 2024-2025 - Yan Georget
+###############################################################################
+from typing import List, Optional, Tuple, Union
+
+import pytest
+
+from nucs.constants import PROP_CONSISTENCY, PROP_ENTAILMENT, PROP_INCONSISTENCY
+from nucs.propagators.count_geq_c_propagator import compute_domains_count_geq_c
+from tests.propagators.propagator_test import PropagatorTest
+
+
+class TestCountGeqC(PropagatorTest):
+    @pytest.mark.parametrize(
+        "domains,parameters,consistency_result,expected_domains",
+        [
+            (
+                [(1, 4), (3, 5), (3, 6), (6, 8), 3, 5],
+                [9, 1],
+                PROP_INCONSISTENCY,
+                None,
+            ),
+            (
+                [(1, 4), (3, 5), (3, 5), (6, 8), 3, 5],
+                [5, 3],
+                PROP_ENTAILMENT,
+                [[1, 4], [5, 5], [5, 5], [6, 8], [3, 3], [5, 5]],
+            ),
+            (
+                [(1, 4), (3, 5), (3, 6), (6, 8), 3, 5],
+                [5, 2],
+                PROP_CONSISTENCY,
+                [[1, 4], [3, 5], [3, 6], [6, 8], [3, 3], [5, 5]],
+            ),
+        ],
+    )
+    def test_compute_domains(
+        self,
+        domains: List[Union[int, Tuple[int, int]]],
+        parameters: List[int],
+        consistency_result: int,
+        expected_domains: Optional[List[List[int]]],
+    ) -> None:
+        self.assert_compute_domains(
+            compute_domains_count_geq_c, domains, parameters, consistency_result, expected_domains
+        )