Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
8a98921
comparison: shape solution comparison contract and search integration
zayenz Sep 10, 2026
93b21eb
comparison: require optimization comparison and refine objective read…
zayenz Sep 10, 2026
08d71cc
comparison: make comparability model-defined and plan future search uses
zayenz Sep 10, 2026
4ed08f0
Add tasks to comparison
zayenz Sep 10, 2026
ed324ad
comparison: add space and integer objective comparison
zayenz Sep 10, 2026
a25ee31
comparison: add float objective comparison
zayenz Sep 10, 2026
69818c5
comparison: use comparison for sequential incumbents
zayenz Sep 10, 2026
89671e6
Use comparison in parallel BAB
zayenz Sep 10, 2026
07ac3c7
Integrate comparison through portfolios
zayenz Sep 10, 2026
062959c
Add tasks to comparison
zayenz Sep 22, 2026
4d81421
Fix comparison failure ownership and clarify the public contract
zayenz Sep 22, 2026
8ac086a
Fix search tests that relied on BAB enumeration or shared counters
zayenz Nov 3, 2026
4a9b38e
Rank A* and CABS solutions with comparison
zayenz Nov 3, 2026
934fec1
Shorten the comparison documentation
zayenz Nov 3, 2026
ee572fb
Add Sense and compare_int for objective comparison
zayenz Nov 3, 2026
e0dda3a
Report missing comparison for FlatZinc satisfaction models
zayenz Nov 12, 2026
5e8dc79
Add a temporary comparison to the Cartesian heart example
zayenz Nov 12, 2026
42d98b1
Report parallel search failures before comparing pending solutions
zayenz Nov 15, 2026
b8cff1b
Keep the inherited Gist compare overloads in examples
zayenz Nov 15, 2026
5ffcd2b
Use scoped comparison enums and report incompatible objectives
zayenz Nov 15, 2026
f65adb2
Clarify float comparison documentation and asset failure reporting
zayenz Nov 19, 2026
9359b1a
Remove the zdev planning records
zayenz Nov 19, 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
20 changes: 20 additions & 0 deletions changelog.in
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,26 @@ Date: unreleased
[DESCRIPTION]
This is the development changelog for the next Gecode release.

[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. An exception thrown in an asset of a
parallel portfolio, or by compare() in parallel BAB, is now rethrown by next()
instead of terminating the program.

[RELEASE]
Version: 6.6.0
Date: 2026-11-16
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 @@ -929,6 +929,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
28 changes: 28 additions & 0 deletions gecode/flatzinc/flatzinc.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -2098,6 +2098,34 @@ 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
GECODE_NEVER;
return SpaceComparison::Incomparable;
#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
36 changes: 36 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 @@ -2506,6 +2528,10 @@ namespace Gecode {
* 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
*/
class GECODE_VTABLE_EXPORT FloatMinimizeSpace : public Space {
Expand All @@ -2520,6 +2546,9 @@ namespace Gecode {
/// Member function constraining according to cost
GECODE_MINIMODEL_EXPORT
virtual void constrain(const Space& best);
/// Compare upper endpoints of assigned costs (same step required)
GECODE_MINIMODEL_EXPORT
virtual SpaceComparison compare(const Space& other) const;
/// Return variable with current cost
virtual FloatVar cost(void) const = 0;
};
Expand All @@ -2531,6 +2560,10 @@ namespace Gecode {
* 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
*/
class GECODE_VTABLE_EXPORT FloatMaximizeSpace : public Space {
Expand All @@ -2545,6 +2578,9 @@ namespace Gecode {
/// Member function constraining according to cost
GECODE_MINIMODEL_EXPORT
virtual void constrain(const Space& best);
/// Compare lower endpoints of assigned costs (same step required)
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