feat: sync ScoreAnalysis API

Author: zepfred

pyproject.toml

@@ -3,6 +3,7 @@ requires = [
     "setuptools>=69.1.1",
     "stubgenj>=0.2.5",
     "JPype1>=1.5.0",
-    "wheel"
+    "wheel",
+    "multipledispatch>=1.0.0"
 ]
 build-backend = "setuptools.build_meta"

tests/test_solution_manager.py

@@ -3,6 +3,19 @@
 from timefold.solver.config import *
 from timefold.solver.score import *
 
+import inspect
+import re
+
+from ai.timefold.solver.core.api.score import ScoreExplanation as JavaScoreExplanation
+from ai.timefold.solver.core.api.score.analysis import (
+    ConstraintAnalysis as JavaConstraintAnalysis,
+    MatchAnalysis as JavaMatchAnalysis,
+    ScoreAnalysis as JavaScoreAnalysis)
+from ai.timefold.solver.core.api.score.constraint import Indictment as JavaIndictment
+from ai.timefold.solver.core.api.score.constraint import (ConstraintRef as JavaConstraintRef,
+                                                          ConstraintMatch as JavaConstraintMatch,
+                                                          ConstraintMatchTotal as JavaConstraintMatchTotal)
+
 from dataclasses import dataclass, field
 from typing import Annotated, List
 
@@ -128,14 +141,14 @@ def assert_score_analysis(problem: Solution, score_analysis: ScoreAnalysis):
 
 
 def assert_score_analysis_summary(score_analysis: ScoreAnalysis):
-    summary = score_analysis.summary
+    summary = score_analysis.summarize
     assert "Explanation of score (3):" in summary
     assert "Constraint matches:" in summary
     assert "3: constraint (Maximize Value) has 3 matches:" in summary
     assert "1: justified with" in summary
 
     match = score_analysis.constraint_analyses[0]
-    match_summary = match.summary
+    match_summary = match.summarize
     assert "Explanation of score (3):" in match_summary
     assert "Constraint matches:" in match_summary
     assert "3: constraint (Maximize Value) has 3 matches:" in match_summary
@@ -166,3 +179,40 @@ def test_solver_manager_score_manager():
 
 def test_solver_factory_score_manager():
     assert_solution_manager(SolutionManager.create(SolverFactory.create(solver_config)))
+
+
+def test_score_manager_solution_initialization():
+    solution_manager = SolutionManager.create(SolverFactory.create(solver_config))
+    problem: Solution = Solution([Entity('A', 1), Entity('B', 1), Entity('C', 1)], [1, 2, 3])
+    score_analysis = solution_manager.analyze(problem)
+    assert score_analysis.is_solution_initialized
+
+    second_problem: Solution = Solution([Entity('A', None), Entity('B', None), Entity('C', None)], [1, 2, 3])
+    second_score_analysis = solution_manager.analyze(second_problem)
+    assert not second_score_analysis.is_solution_initialized
+
+
+def test_score_manager_diff():
+    solution_manager = SolutionManager.create(SolverFactory.create(solver_config))
+    problem: Solution = Solution([Entity('A', 1), Entity('B', 1), Entity('C', 1)], [1, 2, 3])
+    score_analysis = solution_manager.analyze(problem)
+    second_problem: Solution = Solution([Entity('A', 1), Entity('B', 1), Entity('C', 1), Entity('D', 1)], [1, 2, 3])
+    second_score_analysis = solution_manager.analyze(second_problem)
+    diff = score_analysis.diff(second_score_analysis)
+    assert diff.score.score == -1
+
+    constraint_analyses = score_analysis.constraint_analyses
+    assert len(constraint_analyses) == 1
+
+def test_score_manager_constraint_analysis_map():
+    solution_manager = SolutionManager.create(SolverFactory.create(solver_config))
+    problem: Solution = Solution([Entity('A', 1), Entity('B', 1), Entity('C', 1)], [1, 2, 3])
+    score_analysis = solution_manager.analyze(problem)
+    constraints = score_analysis.constraint_analyses
+    assert len(constraints) == 1
+
+    constraint_analysis = score_analysis.constraint_analysis('package', 'Maximize Value')
+    assert constraint_analysis.constraint_name == 'Maximize Value'
+
+    constraint_analysis = score_analysis.constraint_analysis(ConstraintRef('package', 'Maximize Value'))
+    assert constraint_analysis.constraint_name == 'Maximize Value'

timefold-solver-python-core/src/main/python/score/_score_analysis.py

@@ -2,6 +2,7 @@
 from .._jpype_type_conversions import to_python_score
 from _jpyinterpreter import unwrap_python_like_object, add_java_interface
 from dataclasses import dataclass
+from multipledispatch import dispatch
 
 from typing import TypeVar, Generic, Union, TYPE_CHECKING, Any, cast, Optional, Type
 
@@ -456,7 +457,7 @@ def __init__(self, delegate: '_JavaConstraintAnalysis[Score_]'):
         delegate.constraintRef()
 
     def __str__(self):
-        return self.summary
+        return self.summarize
 
     @property
     def constraint_ref(self) -> ConstraintRef:
@@ -485,7 +486,7 @@ def score(self) -> Score_:
         return to_python_score(self._delegate.score())
 
     @property
-    def summary(self) -> str:
+    def summarize(self) -> str:
         return self._delegate.summarize()
 
 class ScoreAnalysis:
@@ -518,15 +519,19 @@ class ScoreAnalysis:
     constraint_analyses : list[ConstraintAnalysis]
         Individual ConstraintAnalysis instances that make up this ScoreAnalysis.
 
-    summary : str
-        Returns a diagnostic text
-        that explains the solution through the `ConstraintMatch` API
-        to identify which constraints cause that score quality.
+    summarize : str
+        Returns a diagnostic text that explains the solution through the `ConstraintAnalysis` API to identify which
+        Constraints cause that score quality.
+        The string is built fresh every time the method is called.
 
         In case of an infeasible solution, this can help diagnose the cause of that.
+
         Do not parse the return value, its format may change without warning.
-        Instead, to provide this information in a UI or a service,
-        use `constraint_analyses` and convert those into a domain-specific API.
+        Instead, provide this information in a UI or a service,
+        use `constraintAnalyses()`
+        and convert those into a domain-specific API.
+
+    is_solution_initialized : bool
 
     Notes
     -----
@@ -539,7 +544,7 @@ def __init__(self, delegate: '_JavaScoreAnalysis'):
         self._delegate = delegate
 
     def __str__(self):
-        return self.summary
+        return self.summarize
 
     @property
     def score(self) -> 'Score':
@@ -562,10 +567,81 @@ def constraint_analyses(self) -> list[ConstraintAnalysis]:
                 list['_JavaConstraintAnalysis[Score]'], self._delegate.constraintAnalyses())
         ]
 
+    @dispatch(str, str)
+    def constraint_analysis(self, constraint_package: str, constraint_name: str) -> ConstraintAnalysis:
+        """
+        Performs a lookup on `constraint_map`.
+
+        Parameters
+        ----------
+        constraint_package : str
+        constraint_name : str
+
+        Returns
+        -------
+        ConstraintAnalysis
+            None if no constraint matches of such constraint are present
+        """
+        return ConstraintAnalysis(self._delegate.getConstraintAnalysis(constraint_package, constraint_name))
+
+    @dispatch(ConstraintRef)
+    def constraint_analysis(self, constraint_ref: ConstraintRef) -> ConstraintAnalysis:
+        """
+        Performs a lookup on `constraint_map`.
+
+        Parameters
+        ----------
+        constraint_ref : ConstraintRef
+
+        Returns
+        -------
+        ConstraintAnalysis
+            None if no constraint matches of such constraint are present
+        """
+        return self.constraint_analysis(constraint_ref.package_name, constraint_ref.constraint_name)
+
     @property
-    def summary(self) -> str:
+    def summarize(self) -> str:
         return self._delegate.summarize()
 
+    @property
+    def is_solution_initialized(self) -> bool:
+        return self._delegate.isSolutionInitialized()
+
+
+    def diff(self, other: 'ScoreAnalysis') -> 'ScoreAnalysis':
+        """
+        Compare this `ScoreAnalysis to another `ScoreAnalysis`
+        and retrieve the difference between them.
+        The comparison is in the direction of `this - other`.
+
+        Example: if `this` has a score of 100 and `other` has a score of 90,
+        the returned score will be 10.
+        If this and other were inverted, the score would have been -10.
+        The same applies to all other properties of `ScoreAnalysis`.
+
+        In order to properly diff `MatchAnalysis` against each other,
+        we rely on the user implementing `ConstraintJustification` equality correctly.
+        In other words, the diff will consider two justifications equal if the user says they are equal,
+        and it expects the hash code to be consistent with equals.
+
+        If one `ScoreAnalysis` provides `MatchAnalysis` and the other doesn't, exception is thrown.
+        Such `ScoreAnalysis` instances are mutually incompatible.
+
+        Parameters
+        ----------
+        other : ScoreAnalysis
+
+        Returns
+        -------
+        ScoreExplanation
+            The `ScoreAnalysis` corresponding to the diff.
+        """
+        return ScoreAnalysis(self._delegate.diff(other._delegate))
+
+
+
+
 
 __all__ = ['ScoreExplanation',
            'ConstraintRef', 'ConstraintMatch', 'ConstraintMatchTotal',

tox.ini

@@ -13,8 +13,9 @@ deps =
     pytest-cov>=4.1.0
     coverage>=7.4.3
     JPype1>=1.5.0
+    multipledispatch>=1.0.0
 commands =
-    pytest --import-mode=importlib {posargs} tests
+    pytest -s --import-mode=importlib {posargs} tests
 
 [coverage:paths]
 source =