feat: Add support for enterprise edition and multithreaded solving (#31)

Christopher-Chianelli · web-flow · commit 158aca773579 · 2024-04-15T10:20:13.000-04:00
* feat: Add support for enterprise edition and multithreaded solving

- To install enterprise edition:

  - Replace `timefold-solver` with `timefold-solver-enterprise` (which
    has `timefold-solver` as a dependency).

- Add tests for the exception raised when an enterprise feature is
  requested and enterprise is not installed

- Add support for multithreaded solving in the SolverConfig

- Use PlanningImmutable API for immutable types in the Java Python Interpreter
diff --git a/jpyinterpreter/src/main/java/ai/timefold/jpyinterpreter/types/Ellipsis.java b/jpyinterpreter/src/main/java/ai/timefold/jpyinterpreter/types/Ellipsis.java
@@ -1,8 +1,9 @@
 package ai.timefold.jpyinterpreter.types;
 
 import ai.timefold.jpyinterpreter.builtins.GlobalBuiltins;
+import ai.timefold.solver.core.impl.domain.solution.cloner.PlanningImmutable;
 
-public class Ellipsis extends AbstractPythonLikeObject {
+public class Ellipsis extends AbstractPythonLikeObject implements PlanningImmutable {
     public static final Ellipsis INSTANCE;
     public static final PythonLikeType ELLIPSIS_TYPE = new PythonLikeType("EllipsisType", Ellipsis.class);
     public static final PythonLikeType $TYPE = ELLIPSIS_TYPE;
diff --git a/jpyinterpreter/src/main/java/ai/timefold/jpyinterpreter/types/PythonBytes.java b/jpyinterpreter/src/main/java/ai/timefold/jpyinterpreter/types/PythonBytes.java
@@ -29,8 +29,9 @@
 import ai.timefold.jpyinterpreter.types.numeric.PythonInteger;
 import ai.timefold.jpyinterpreter.util.ByteCharSequence;
 import ai.timefold.jpyinterpreter.util.StringFormatter;
+import ai.timefold.solver.core.impl.domain.solution.cloner.PlanningImmutable;
 
-public class PythonBytes extends AbstractPythonLikeObject implements PythonBytesLikeObject {
+public class PythonBytes extends AbstractPythonLikeObject implements PythonBytesLikeObject, PlanningImmutable {
 
     public static final PythonBytes EMPTY = new PythonBytes(new byte[0]);
 
diff --git a/jpyinterpreter/src/main/java/ai/timefold/jpyinterpreter/types/PythonNone.java b/jpyinterpreter/src/main/java/ai/timefold/jpyinterpreter/types/PythonNone.java
@@ -6,8 +6,9 @@
 import ai.timefold.jpyinterpreter.PythonUnaryOperator;
 import ai.timefold.jpyinterpreter.builtins.GlobalBuiltins;
 import ai.timefold.jpyinterpreter.types.numeric.PythonBoolean;
+import ai.timefold.solver.core.impl.domain.solution.cloner.PlanningImmutable;
 
-public class PythonNone extends AbstractPythonLikeObject {
+public class PythonNone extends AbstractPythonLikeObject implements PlanningImmutable {
     public static final PythonNone INSTANCE;
 
     static {
diff --git a/jpyinterpreter/src/main/java/ai/timefold/jpyinterpreter/types/PythonString.java b/jpyinterpreter/src/main/java/ai/timefold/jpyinterpreter/types/PythonString.java
@@ -37,8 +37,9 @@
 import ai.timefold.jpyinterpreter.util.DefaultFormatSpec;
 import ai.timefold.jpyinterpreter.util.StringFormatter;
 import ai.timefold.jpyinterpreter.util.arguments.ArgumentSpec;
+import ai.timefold.solver.core.impl.domain.solution.cloner.PlanningImmutable;
 
-public class PythonString extends AbstractPythonLikeObject implements PythonLikeComparable<PythonString> {
+public class PythonString extends AbstractPythonLikeObject implements PythonLikeComparable<PythonString>, PlanningImmutable {
     public final String value;
 
     public final static PythonString EMPTY = new PythonString("");
diff --git a/jpyinterpreter/src/main/java/ai/timefold/jpyinterpreter/types/collections/PythonLikeTuple.java b/jpyinterpreter/src/main/java/ai/timefold/jpyinterpreter/types/collections/PythonLikeTuple.java
@@ -26,10 +26,12 @@
 import ai.timefold.jpyinterpreter.types.numeric.PythonBoolean;
 import ai.timefold.jpyinterpreter.types.numeric.PythonInteger;
 import ai.timefold.solver.core.impl.domain.solution.cloner.PlanningCloneable;
+import ai.timefold.solver.core.impl.domain.solution.cloner.PlanningImmutable;
 
 public class PythonLikeTuple<T extends PythonLikeObject> extends AbstractPythonLikeObject implements List<T>,
         PlanningCloneable<PythonLikeTuple<T>>,
         PythonLikeComparable<PythonLikeTuple>,
+        PlanningImmutable,
         RandomAccess {
     public static PythonLikeTuple EMPTY = PythonLikeTuple.fromList(Collections.emptyList());
 
diff --git a/jpyinterpreter/src/main/java/ai/timefold/jpyinterpreter/types/datetime/PythonDate.java b/jpyinterpreter/src/main/java/ai/timefold/jpyinterpreter/types/datetime/PythonDate.java
@@ -28,11 +28,13 @@
 import ai.timefold.jpyinterpreter.types.numeric.PythonInteger;
 import ai.timefold.jpyinterpreter.types.numeric.PythonNumber;
 import ai.timefold.jpyinterpreter.util.arguments.ArgumentSpec;
+import ai.timefold.solver.core.impl.domain.solution.cloner.PlanningImmutable;
 
 /**
  * Python docs: <a href="https://docs.python.org/3/library/datetime.html#datetime.date">date objects</a>
  */
-public class PythonDate<T extends PythonDate<?>> extends AbstractPythonLikeObject implements PythonLikeComparable<T> {
+public class PythonDate<T extends PythonDate<?>> extends AbstractPythonLikeObject implements PythonLikeComparable<T>,
+        PlanningImmutable {
     static final long EPOCH_ORDINAL_OFFSET = Duration.between(LocalDateTime.of(LocalDate.of(0, 12, 31), LocalTime.MIDNIGHT),
             LocalDateTime.of(LocalDate.ofEpochDay(0), LocalTime.MIDNIGHT)).toDays();
 
diff --git a/jpyinterpreter/src/main/java/ai/timefold/jpyinterpreter/types/datetime/PythonDateTime.java b/jpyinterpreter/src/main/java/ai/timefold/jpyinterpreter/types/datetime/PythonDateTime.java
@@ -32,11 +32,12 @@
 import ai.timefold.jpyinterpreter.types.numeric.PythonInteger;
 import ai.timefold.jpyinterpreter.types.numeric.PythonNumber;
 import ai.timefold.jpyinterpreter.util.arguments.ArgumentSpec;
+import ai.timefold.solver.core.impl.domain.solution.cloner.PlanningImmutable;
 
 /**
  * Python docs: <a href="https://docs.python.org/3/library/datetime.html#datetime.datetime">datetime objects</a>
  */
-public class PythonDateTime extends PythonDate<PythonDateTime> {
+public class PythonDateTime extends PythonDate<PythonDateTime> implements PlanningImmutable {
     // Taken from https://docs.python.org/3/library/datetime.html#datetime.datetime.fromisoformat
     private static final Pattern ISO_FORMAT_PATTERN = Pattern.compile("^(?<year>\\d\\d\\d\\d)-(?<month>\\d\\d)-(?<day>\\d\\d)" +
             "(.(?<hour>\\d\\d)" +
diff --git a/jpyinterpreter/src/main/java/ai/timefold/jpyinterpreter/types/datetime/PythonTime.java b/jpyinterpreter/src/main/java/ai/timefold/jpyinterpreter/types/datetime/PythonTime.java
@@ -21,8 +21,9 @@
 import ai.timefold.jpyinterpreter.types.errors.ValueError;
 import ai.timefold.jpyinterpreter.types.numeric.PythonInteger;
 import ai.timefold.jpyinterpreter.util.arguments.ArgumentSpec;
+import ai.timefold.solver.core.impl.domain.solution.cloner.PlanningImmutable;
 
-public class PythonTime extends AbstractPythonLikeObject {
+public class PythonTime extends AbstractPythonLikeObject implements PlanningImmutable {
     // Taken from https://docs.python.org/3/library/datetime.html#datetime.time.fromisoformat
     private static final Pattern ISO_FORMAT_PATTERN = Pattern.compile("^(?<hour>\\d\\d)" +
             "(:(?<minute>\\d\\d)" +
diff --git a/jpyinterpreter/src/main/java/ai/timefold/jpyinterpreter/types/datetime/PythonTimeDelta.java b/jpyinterpreter/src/main/java/ai/timefold/jpyinterpreter/types/datetime/PythonTimeDelta.java
@@ -20,11 +20,13 @@
 import ai.timefold.jpyinterpreter.types.numeric.PythonInteger;
 import ai.timefold.jpyinterpreter.types.numeric.PythonNumber;
 import ai.timefold.jpyinterpreter.util.arguments.ArgumentSpec;
+import ai.timefold.solver.core.impl.domain.solution.cloner.PlanningImmutable;
 
 /**
  * Python docs: <a href="https://docs.python.org/3/library/datetime.html#timedelta-objects">timedelta-objects</a>
  */
-public class PythonTimeDelta extends AbstractPythonLikeObject implements PythonLikeComparable<PythonTimeDelta> {
+public class PythonTimeDelta extends AbstractPythonLikeObject implements PythonLikeComparable<PythonTimeDelta>,
+        PlanningImmutable {
     private static final int NANOS_IN_SECOND = 1_000_000_000;
     private static final int SECONDS_IN_DAY = 86400; // 24 * 60 * 60
 
diff --git a/jpyinterpreter/src/main/java/ai/timefold/jpyinterpreter/types/datetime/PythonTzinfo.java b/jpyinterpreter/src/main/java/ai/timefold/jpyinterpreter/types/datetime/PythonTzinfo.java
@@ -10,8 +10,9 @@
 import ai.timefold.jpyinterpreter.types.BuiltinTypes;
 import ai.timefold.jpyinterpreter.types.PythonLikeType;
 import ai.timefold.jpyinterpreter.types.PythonString;
+import ai.timefold.solver.core.impl.domain.solution.cloner.PlanningImmutable;
 
-public class PythonTzinfo extends AbstractPythonLikeObject {
+public class PythonTzinfo extends AbstractPythonLikeObject implements PlanningImmutable {
     public static PythonLikeType TZ_INFO_TYPE = new PythonLikeType("tzinfo",
             PythonTzinfo.class);
 
diff --git a/jpyinterpreter/src/main/java/ai/timefold/jpyinterpreter/types/numeric/PythonComplex.java b/jpyinterpreter/src/main/java/ai/timefold/jpyinterpreter/types/numeric/PythonComplex.java
@@ -5,8 +5,9 @@
 import ai.timefold.jpyinterpreter.PythonOverloadImplementor;
 import ai.timefold.jpyinterpreter.types.AbstractPythonLikeObject;
 import ai.timefold.jpyinterpreter.types.PythonLikeType;
+import ai.timefold.solver.core.impl.domain.solution.cloner.PlanningImmutable;
 
-public class PythonComplex extends AbstractPythonLikeObject implements PythonNumber {
+public class PythonComplex extends AbstractPythonLikeObject implements PythonNumber, PlanningImmutable {
     final PythonNumber real;
     final PythonNumber imaginary;
 
diff --git a/jpyinterpreter/src/main/java/ai/timefold/jpyinterpreter/types/numeric/PythonFloat.java b/jpyinterpreter/src/main/java/ai/timefold/jpyinterpreter/types/numeric/PythonFloat.java
@@ -27,8 +27,9 @@
 import ai.timefold.jpyinterpreter.types.errors.arithmetic.ZeroDivisionError;
 import ai.timefold.jpyinterpreter.util.DefaultFormatSpec;
 import ai.timefold.jpyinterpreter.util.StringFormatter;
+import ai.timefold.solver.core.impl.domain.solution.cloner.PlanningImmutable;
 
-public class PythonFloat extends AbstractPythonLikeObject implements PythonNumber {
+public class PythonFloat extends AbstractPythonLikeObject implements PythonNumber, PlanningImmutable {
     public final double value;
 
     static {
diff --git a/jpyinterpreter/src/main/java/ai/timefold/jpyinterpreter/types/numeric/PythonInteger.java b/jpyinterpreter/src/main/java/ai/timefold/jpyinterpreter/types/numeric/PythonInteger.java
@@ -24,8 +24,9 @@
 import ai.timefold.jpyinterpreter.types.errors.arithmetic.ZeroDivisionError;
 import ai.timefold.jpyinterpreter.util.DefaultFormatSpec;
 import ai.timefold.jpyinterpreter.util.StringFormatter;
+import ai.timefold.solver.core.impl.domain.solution.cloner.PlanningImmutable;
 
-public class PythonInteger extends AbstractPythonLikeObject implements PythonNumber {
+public class PythonInteger extends AbstractPythonLikeObject implements PythonNumber, PlanningImmutable {
     private static final BigInteger MIN_BYTE = BigInteger.valueOf(0);
     private static final BigInteger MAX_BYTE = BigInteger.valueOf(255);
 
diff --git a/setup.py b/setup.py
@@ -75,10 +75,11 @@ def find_stub_files(stub_root: str):
 
 this_directory = Path(__file__).parent
 long_description = (this_directory / "README.md").read_text()
+version = '999-dev0'
 
 setup(
     name='timefold-solver',
-    version='999-dev0',
+    version=version,
     license='Apache License Version 2.0',
     license_file='LICENSE',
     description='An AI constraint solver that optimizes planning and scheduling problems',
diff --git a/tests/test_user_error.py b/tests/test_user_error.py
@@ -104,3 +104,10 @@ def not_proxied():
                 constraint_provider_function=not_proxied  # noqa
             )
         )._to_java_solver_config()
+
+
+def test_missing_enterprise():
+    with pytest.raises(RequiresEnterpriseError, match=re.escape('multithreaded solving')):
+        solver_config = SolverConfig(
+            move_thread_count=MoveThreadCount.AUTO
+        )._to_java_solver_config()
diff --git a/timefold-solver-python-core/src/main/python/config/config.py b/timefold-solver-python-core/src/main/python/config/config.py
@@ -1,4 +1,5 @@
 from ..constraint import ConstraintFactory
+from ..timefold_java_interop import is_enterprise_installed
 
 from typing import Any, Optional, List, Type, Callable, TYPE_CHECKING
 from dataclasses import dataclass, field
@@ -83,12 +84,26 @@ def _get_java_enum(self):
         return _lookup_on_java_class(_java_termination_composition_style, self.name)
 
 
+class MoveThreadCount(Enum):
+    AUTO = auto()
+    NONE = auto()
+
+
+class RequiresEnterpriseError(EnvironmentError):
+    def __init__(self, feature):
+        super().__init__(f'Feature {feature} requires timefold-solver-enterprise to be installed. '
+                         f'See https://docs.timefold.ai/timefold-solver/latest/enterprise-edition/'
+                         f'enterprise-edition#switchToEnterpriseEdition for instructions on how to '
+                         f'install timefold-solver-enterprise.')
+
+
 @dataclass(kw_only=True)
 class SolverConfig:
     solution_class: Optional[Type] = field(default=None)
     entity_class_list: Optional[List[Type]] = field(default=None)
     environment_mode: Optional[EnvironmentMode] = field(default=EnvironmentMode.REPRODUCIBLE)
     random_seed: Optional[int] = field(default=None)
+    move_thread_count: int | MoveThreadCount = field(default=MoveThreadCount.NONE)
     termination_config: Optional['TerminationConfig'] = field(default=None)
     score_director_factory_config: Optional['ScoreDirectorFactoryConfig'] = field(default=None)
     xml_source_text: Optional[str] = field(default=None)
@@ -124,6 +139,16 @@ def _to_java_solver_config(self) -> '_JavaSolverConfig':
                     raise FileNotFoundError(e.getMessage()) from e
 
             # Next, override fields
+            if self.move_thread_count is not MoveThreadCount.NONE:
+                if not is_enterprise_installed():
+                    raise RequiresEnterpriseError('multithreaded solving')
+                if isinstance(self.move_thread_count, MoveThreadCount):
+                    out.setMoveThreadCount(self.move_thread_count.name)
+                else:
+                    out.setMoveThreadCount(str(self.move_thread_count))
+            elif out.getMoveThreadCount() is not None and not is_enterprise_installed():
+                raise RequiresEnterpriseError('multithreaded solving')
+
             if self.solution_class is not None:
                 from ai.timefold.solver.core.api.domain.solution import PlanningSolution as JavaPlanningSolution
                 java_class = get_class(self.solution_class)
@@ -133,6 +158,7 @@ def _to_java_solver_config(self) -> '_JavaSolverConfig':
                     raise TypeError(f'{self.solution_class} is not a @planning_solution class. '
                                     f'Maybe move the @planning_solution decorator to the top of the decorator list?')
                 out.setSolutionClass(get_class(self.solution_class))
+
             if self.entity_class_list is not None:
                 from ai.timefold.solver.core.api.domain.entity import PlanningEntity as JavaPlanningEntity
                 entity_class_list = ArrayList()
@@ -145,16 +171,21 @@ def _to_java_solver_config(self) -> '_JavaSolverConfig':
                                         f'Maybe move the @planning_entity decorator to the top of the decorator list?')
                     entity_class_list.add(java_class)
                 out.setEntityClassList(entity_class_list)
+
             if self.environment_mode is not None:
                 out.setEnvironmentMode(self.environment_mode._get_java_enum())
+
             if self.random_seed is not None:
                 out.setRandomSeed(self.random_seed)
+
             if self.score_director_factory_config is not None:
                 out.setScoreDirectorFactoryConfig(
                     self.score_director_factory_config._to_java_score_director_factory_config())
+
             if self.termination_config is not None:
                 out.setTerminationConfig(
                     self.termination_config._to_java_termination_config(out.getTerminationConfig()))
+
             return out
 
 
@@ -234,4 +265,5 @@ def _to_java_termination_config(self, inherited_config: '_JavaTerminationConfig'
 
 
 __all__ = ['Duration', 'EnvironmentMode', 'TerminationCompositionStyle',
+           'RequiresEnterpriseError', 'MoveThreadCount',
            'SolverConfig', 'ScoreDirectorFactoryConfig', 'TerminationConfig']
diff --git a/timefold-solver-python-core/src/main/python/timefold_java_interop.py b/timefold-solver-python-core/src/main/python/timefold_java_interop.py
@@ -5,19 +5,25 @@
 from jpype import JOverride, JImplements
 import importlib.resources
 from typing import cast, List, Type, TypeVar, Callable, Union, TYPE_CHECKING
-from .timefold_python_logger import timefold_logger
 from .jpype_type_conversions import PythonSupplier, ConstraintProviderFunction
 
 if TYPE_CHECKING:
     # These imports require a JVM to be running, so only import if type checking
     from java.lang import ClassLoader
-    from ai.timefold.solver.core.api.score.stream import Constraint as _Constraint, ConstraintFactory as _ConstraintFactory
+    from ai.timefold.solver.core.api.score.stream import (Constraint as _Constraint,
+                                                          ConstraintFactory as _ConstraintFactory)
     from ai.timefold.solver.core.api.score.calculator import IncrementalScoreCalculator as _IncrementalScoreCalculator
     from ai.timefold.solver.core.api.domain.variable import VariableListener as _VariableListener
 
 Solution_ = TypeVar('Solution_')
 ProblemId_ = TypeVar('ProblemId_')
 Score_ = TypeVar('Score_')
+_enterprise_installed: bool = False
+
+
+def is_enterprise_installed() -> bool:
+    global _enterprise_installed
+    return _enterprise_installed
 
 
 def extract_timefold_jars() -> list[str]:
@@ -30,9 +36,20 @@ def extract_timefold_jars() -> list[str]:
 
     :return: None
     """
+    global _enterprise_installed
+    try:
+
+        enterprise_dependencies = [str(importlib.resources.path('timefold.solver.enterprise.jars',
+                                                                p.name).__enter__())
+                                   for p in importlib.resources.files('timefold.solver.enterprise.jars').iterdir()
+                                   if p.name.endswith(".jar")]
+        _enterprise_installed = True
+    except ModuleNotFoundError:
+        enterprise_dependencies = []
+        _enterprise_installed = False
     return [str(importlib.resources.path('timefold.solver.jars', p.name).__enter__())
             for p in importlib.resources.files('timefold.solver.jars').iterdir()
-            if p.name.endswith(".jar")]
+            if p.name.endswith(".jar")] + enterprise_dependencies
 
 
 def init(*args, path: List[str] = None, include_timefold_jars: bool = True, log_level='INFO'):
