Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
25cdae2
comparison: shape solution comparison contract and search integration
zayenz Sep 10, 2026
5773769
comparison: require optimization comparison and refine objective read…
zayenz Sep 10, 2026
d59ea87
comparison: make comparability model-defined and plan future search uses
zayenz Sep 10, 2026
b3fa08c
Add tasks to comparison
zayenz Sep 10, 2026
e06a5a6
comparison: add space and integer objective comparison
zayenz Sep 10, 2026
1d0b7a0
comparison: add float objective comparison
zayenz Sep 10, 2026
02baafd
comparison: use comparison for sequential incumbents
zayenz Sep 10, 2026
2cbda6a
Use comparison in parallel BAB
zayenz Sep 10, 2026
a21f88d
Integrate comparison through portfolios
zayenz Sep 10, 2026
3395e67
Add tasks to comparison
zayenz Sep 22, 2026
13c49cd
Fix comparison failure ownership and clarify the public contract
zayenz Sep 22, 2026
4483102
Fix search tests that relied on BAB enumeration or shared counters
zayenz Nov 3, 2026
70a390d
Rank A* and CABS solutions with comparison
zayenz Nov 3, 2026
0221e15
Shorten the comparison documentation
zayenz Nov 3, 2026
900a02a
Add Sense and compare_int for objective comparison
zayenz Nov 3, 2026
f43c805
Report missing comparison for FlatZinc satisfaction models
zayenz Nov 12, 2026
5c5e329
Add a temporary comparison to the Cartesian heart example
zayenz Nov 12, 2026
36c63d7
Report parallel search failures before comparing pending solutions
zayenz Nov 15, 2026
68bd27c
Keep the inherited Gist compare overloads in examples
zayenz Nov 15, 2026
c921888
Use scoped comparison enums and report incompatible objectives
zayenz Nov 15, 2026
b767864
Remove the zdev planning records
zayenz Nov 15, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions changelog.in
Original file line number Diff line number Diff line change
Expand Up @@ -166,6 +166,24 @@ fnmul above. The opaque negation prevents that, and the float examples run
two to four times faster with MSVC. With GCC and clang on x86-64 the opaque
negation is an empty asm barrier instead of a volatile round trip.

[ENTRY]
Module: search
What: change
Rank: major
[DESCRIPTION]
Add Space::compare(), which ranks two solutions without modifying them.
Best-solution search uses it to choose between solutions, for example in
parallel BAB, portfolios, external incumbents, and the experimental A* and
CABS engines. constrain() still prunes the search. Optimization models with a
custom constrain() must now also override compare(). compare() returns the
scoped enum SpaceComparison (Better, Equivalent, Worse, Incomparable), and the
optimization direction is the scoped enum Sense (Minimize, Maximize).
compare_int(), compare_float(), and compare_lex() compare integer, float, and
lexicographic objective values for a given Sense. Comparing solutions whose
objectives differ in direction, float step, or size throws
SpaceIncompatibleObjectives. Search engines throw Search::Incomparable when
compare() reports incomparable solutions.

[RELEASE]
Version: 6.5.0
Date: 2026-10-31
Expand Down
8 changes: 7 additions & 1 deletion examples/car-sequencing.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -369,6 +369,13 @@ class CarSequencing : public Script {
rel(*this, nstall, IRT_LE, best.nstall.val());
}

using Script::compare;
/// Compare objective values
virtual SpaceComparison compare(const Space& _other) const {
const CarSequencing& other = static_cast<const CarSequencing&>(_other);
return compare_int(nstall.val(), other.nstall.val(), Sense::Minimize);
}

/// Print solution
virtual void
print(std::ostream& os) const {
Expand Down Expand Up @@ -634,4 +641,3 @@ namespace {
};

// STATISTICS: example-any

16 changes: 16 additions & 0 deletions examples/cartesian-heart.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,22 @@ class CartesianHeart : public Script {
(f[1] >= (b.f[1].max()+step)) ||
(f[1] <= (b.f[1].min()-step)));
}
using Script::compare;
/**
* \brief Compare with solution \a other
*
* This model has no objective: constrain only keeps later solutions apart
* from earlier ones. A solution counts as better than \a other when it
* is far enough from \a other to satisfy constrain, so parallel search keeps
* the same kind of solutions as sequential search. This is not an order.
*/
virtual SpaceComparison compare(const Space& _other) const {
const CartesianHeart& b = static_cast<const CartesianHeart&>(_other);
bool apart = (f[0].min() >= (b.f[0].max()+step)) ||
(f[1].min() >= (b.f[1].max()+step)) ||
(f[1].max() <= (b.f[1].min()-step));
return apart ? SpaceComparison::Better : SpaceComparison::Worse;
}
/// Print solution coordinates
virtual void print(std::ostream& os) const {
os << "XY " << f[0].med() << " " << f[1].med()
Expand Down
2 changes: 1 addition & 1 deletion examples/fifteen-puzzle.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -418,7 +418,7 @@ run(PuzzleOptions& opt) {
case PuzzleOptions::SEARCH_ASTAR:
case PuzzleOptions::SEARCH_CABS:
{
Search::HeuristicGuidance guidance(Search::HeuristicGuidance::MINIMIZE,
Search::HeuristicGuidance guidance(Sense::Minimize,
[](const Space& home) -> std::int64_t {
return static_cast<const Model&>(home).bound();
});
Expand Down
2 changes: 1 addition & 1 deletion examples/tsptw.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -381,7 +381,7 @@ main(int argc, char* argv[]) {
case TSPTW::SEARCH_ASTAR:
case TSPTW::SEARCH_CABS:
{
Search::HeuristicGuidance g(Search::HeuristicGuidance::MINIMIZE,
Search::HeuristicGuidance g(Sense::Minimize,
[](const Space& s) -> std::int64_t {
return static_cast<const TSPTW&>(s).cost().min();
});
Expand Down
1 change: 1 addition & 0 deletions gecode/driver.hh
Original file line number Diff line number Diff line change
Expand Up @@ -901,6 +901,7 @@ namespace Gecode { namespace Driver {
template<class BaseSpace>
class ScriptBase : public BaseSpace {
public:
using BaseSpace::compare;
/// Constructor
ScriptBase(const Options& opt);
/// Constructor used for cloning
Expand Down
12 changes: 11 additions & 1 deletion gecode/flatzinc.hh
Original file line number Diff line number Diff line change
Expand Up @@ -576,7 +576,7 @@ namespace Gecode { namespace FlatZinc {
Gecode::FloatVarArray fv_aux;
/// Indicates whether a float variable is introduced by mzn2fzn
std::vector<bool> fv_introduced;
/// Step by which a next solution has to have lower cost
/// Step used by float optimization cuts and comparison compatibility
Gecode::FloatNum step;
#endif
/// Whether the introduced variables still need to be copied
Expand Down Expand Up @@ -626,6 +626,16 @@ namespace Gecode { namespace FlatZinc {
/// Compare this space with space \a s and print the differences on
/// \a out
void compare(const Space& s, std::ostream& out) const;
/**
* \brief Compare compatible optimization objectives
*
* Integer objectives compare assigned values. Float objectives require
* the same direction and step, and assigned intervals, which may span
* adjacent float values. Float minimization ranks lower endpoints and
* maximization ranks upper endpoints, independently of the step used by
* constrain().
*/
virtual SpaceComparison compare(const Space& s) const;
/// Compare this space with space \a s and print the differences on
/// \a out using \a p
void compare(const FlatZincSpace& s, std::ostream& out,
Expand Down
27 changes: 27 additions & 0 deletions gecode/flatzinc/flatzinc.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -2098,6 +2098,33 @@ namespace Gecode { namespace FlatZinc {
}
}

SpaceComparison
FlatZincSpace::compare(const Space& s) const {
const FlatZincSpace* other = dynamic_cast<const FlatZincSpace*>(&s);
if (other == nullptr)
throw DynamicCastFailed("FlatZincSpace::compare");
if ((_method != MIN) && (_method != MAX))
throw SpaceNoComparison("FlatZincSpace::compare");
if ((_optVarIsInt != other->_optVarIsInt) ||
(_method != other->_method))
throw SpaceIncompatibleObjectives("FlatZincSpace::compare");
Sense sense = (_method == MIN) ? Sense::Minimize : Sense::Maximize;
if (_optVarIsInt)
return compare_int(iv[_optVar].val(),other->iv[other->_optVar].val(),
sense);
#ifdef GECODE_HAS_FLOAT_VARS
if (step != other->step)
throw SpaceIncompatibleObjectives("FlatZincSpace::compare");
FloatVal a=fv[_optVar].val();
FloatVal b=other->fv[other->_optVar].val();
FloatNum ak=(_method == MIN) ? a.min() : a.max();
FloatNum bk=(_method == MIN) ? b.min() : b.max();
return compare_float(ak,bk,sense);
#else
throw DynamicCastFailed("FlatZincSpace::compare");
#endif
}

bool
FlatZincSpace::slave(const MetaInfo& mi) {
if (mi.type() == MetaInfo::RESTART) {
Expand Down
9 changes: 9 additions & 0 deletions gecode/float.hh
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,15 @@ namespace Gecode {
*/
typedef double FloatNum;

/// Compare objective value \a x with \a y for direction \a s
forceinline SpaceComparison
compare_float(FloatNum x, FloatNum y, Sense s) {
if (x == y)
return SpaceComparison::Equivalent;
return ((x < y) == (s == Sense::Minimize)) ?
SpaceComparison::Better : SpaceComparison::Worse;
}

/// Return lower bound of \f$\pi/2\f$
FloatNum pi_half_lower(void);
/// Return upper bound of \f$\pi/2\f$
Expand Down
5 changes: 5 additions & 0 deletions gecode/kernel/core.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -896,6 +896,11 @@ namespace Gecode {
Space::constrain(const Space&) {
}

SpaceComparison
Space::compare(const Space&) const {
throw SpaceNoComparison("Space::compare");
}

bool
Space::master(const MetaInfo& mi) {
switch (mi.type()) {
Expand Down
38 changes: 38 additions & 0 deletions gecode/kernel/core.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,29 @@

namespace Gecode {

/// Result of comparing two solutions according to their objectives
enum class SpaceComparison {
Better, ///< The receiver has a better objective
Equivalent, ///< Both objectives are equivalent
Worse, ///< The receiver has a worse objective
Incomparable ///< Neither objective dominates the other
};

/// Optimization direction
enum class Sense {
Minimize, ///< Smaller objective values are better
Maximize ///< Larger objective values are better
};

/// Compare objective value \a x with \a y for direction \a s
forceinline SpaceComparison
compare_int(int x, int y, Sense s) {
if (x == y)
return SpaceComparison::Equivalent;
return ((x < y) == (s == Sense::Minimize)) ?
SpaceComparison::Better : SpaceComparison::Worse;
}

class Space;

/**
Expand Down Expand Up @@ -2153,6 +2176,21 @@ namespace Gecode {
* \ingroup TaskModelScript
*/
GECODE_KERNEL_EXPORT virtual void constrain(const Space& best);
/**
* \brief Compare function for best solution search
*
* Must return whether this solution is better than, equivalent to,
* worse than, or incomparable with solution \a other, without modifying
* either. The result must agree with constrain: solutions admitted by
* constrain(b) are better than b, and a better b admits no more solutions.
*
* The default function throws SpaceNoComparison, so a space overriding
* constrain must also override compare.
*
* \ingroup TaskModelScript
*/
GECODE_KERNEL_EXPORT virtual SpaceComparison
compare(const Space& other) const;
/**
* \brief Master configuration function for meta search engines
*
Expand Down
6 changes: 6 additions & 0 deletions gecode/kernel/exception.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,12 @@ namespace Gecode {
SpaceNoBrancher::SpaceNoBrancher(const char* l)
: Exception(l,"Attempt to commit with no brancher") {}

SpaceNoComparison::SpaceNoComparison(const char* l)
: Exception(l,"Space does not support comparison") {}

SpaceIncompatibleObjectives::SpaceIncompatibleObjectives(const char* l)
: Exception(l,"Spaces with incompatible objectives cannot be compared") {}

SpaceIllegalAlternative::SpaceIllegalAlternative(const char* l)
: Exception(l,"Attempt to commit with illegal alternative") {}

Expand Down
14 changes: 14 additions & 0 deletions gecode/kernel/exception.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,20 @@ namespace Gecode {
SpaceNoBrancher(const char* l);
};

/// %Exception: Comparison not implemented by space
class GECODE_KERNEL_EXPORT SpaceNoComparison : public Exception {
public:
/// Initialize with location \a l
SpaceNoComparison(const char* l);
};

/// %Exception: Comparison of spaces with incompatible objectives
class GECODE_KERNEL_EXPORT SpaceIncompatibleObjectives : public Exception {
public:
/// Initialize with location \a l
SpaceIncompatibleObjectives(const char* l);
};

/// %Exception: Commit with illegal alternative
class GECODE_KERNEL_EXPORT SpaceIllegalAlternative : public Exception {
public:
Expand Down
34 changes: 34 additions & 0 deletions gecode/minimodel.hh
Original file line number Diff line number Diff line change
Expand Up @@ -2429,6 +2429,16 @@ namespace Gecode {
* \ingroup TaskModelMiniModel
*/

/**
* \brief Compare assigned \a x with \a y lexicographically for \a s
*
* The first position where the values differ decides the result. Throws
* SpaceIncompatibleObjectives if the sizes differ.
* \ingroup TaskModelMiniModelOptimize
*/
GECODE_MINIMODEL_EXPORT SpaceComparison
compare_lex(const IntVarArgs& x, const IntVarArgs& y, Sense s);

/**
* \brief Class for minimizing integer cost
* \ingroup TaskModelMiniModelOptimize
Expand All @@ -2442,6 +2452,9 @@ namespace Gecode {
/// Member function constraining according to decreasing cost
GECODE_MINIMODEL_EXPORT
virtual void constrain(const Space& best);
/// Compare integer costs (both costs must be assigned)
GECODE_MINIMODEL_EXPORT
virtual SpaceComparison compare(const Space& other) const;
/// Return variable with current cost
virtual IntVar cost(void) const = 0;
};
Expand All @@ -2459,6 +2472,9 @@ namespace Gecode {
/// Member function constraining according to increasing cost
GECODE_MINIMODEL_EXPORT
virtual void constrain(const Space& best);
/// Compare integer costs (both costs must be assigned)
GECODE_MINIMODEL_EXPORT
virtual SpaceComparison compare(const Space& other) const;
/// Return variable with current cost
virtual IntVar cost(void) const = 0;
};
Expand All @@ -2476,6 +2492,9 @@ namespace Gecode {
/// Member function constraining according to decreasing costs
GECODE_MINIMODEL_EXPORT
virtual void constrain(const Space& best);
/// Compare integer costs lexicographically
GECODE_MINIMODEL_EXPORT
virtual SpaceComparison compare(const Space& other) const;
/// Return variables with current costs
virtual IntVarArgs cost(void) const = 0;
};
Expand All @@ -2493,6 +2512,9 @@ namespace Gecode {
/// Member function constraining according to increasing costs
GECODE_MINIMODEL_EXPORT
virtual void constrain(const Space& best);
/// Compare integer costs lexicographically
GECODE_MINIMODEL_EXPORT
virtual SpaceComparison compare(const Space& other) const;
/// Return variables with current costs
virtual IntVarArgs cost(void) const = 0;
};
Expand All @@ -2505,6 +2527,9 @@ namespace Gecode {
* The class supports using a step value \a step that will make sure
* that better solutions must be better by at least the value of
* \a step.
* Comparison ranks the upper endpoint of assigned costs independently of
* the step. Both operands must use this base class and the same step.
* Assigned costs may be tight intervals between adjacent float values.
*
* \ingroup TaskModelMiniModelOptimize
*/
Expand All @@ -2520,6 +2545,9 @@ namespace Gecode {
/// Member function constraining according to cost
GECODE_MINIMODEL_EXPORT
virtual void constrain(const Space& best);
/// Compare upper endpoints of assigned costs with a common step policy
GECODE_MINIMODEL_EXPORT
virtual SpaceComparison compare(const Space& other) const;
/// Return variable with current cost
virtual FloatVar cost(void) const = 0;
};
Expand All @@ -2530,6 +2558,9 @@ namespace Gecode {
* The class supports using a step value \a step that will make sure
* that better solutions must be better by at least the value of
* \a step.
* Comparison ranks the lower endpoint of assigned costs independently of
* the step. Both operands must use this base class and the same step.
* Assigned costs may be tight intervals between adjacent float values.
*
* \ingroup TaskModelMiniModelOptimize
*/
Expand All @@ -2545,6 +2576,9 @@ namespace Gecode {
/// Member function constraining according to cost
GECODE_MINIMODEL_EXPORT
virtual void constrain(const Space& best);
/// Compare lower endpoints of assigned costs with a common step policy
GECODE_MINIMODEL_EXPORT
virtual SpaceComparison compare(const Space& other) const;
/// Return variable with current cost
virtual FloatVar cost(void) const = 0;
};
Expand Down
Loading
Loading