Goals and Constraints

Rebalancer lets you express what you want from an assignment as goals and constraints, built from a library of 25+ reusable specs. Some specs work only as a goal, some only as a constraint, and many as either.

• A constraint defines what makes an assignment valid; it must hold.
• A goal is a quantity to minimize; with several goals, their relative priority decides how they trade off.

To add them to the solver, use addConstraint and addGoal. Only the spec is required; the remaining parameters are optional:

solver.addConstraint(spec, policy, invalidCost, invalidState, tuplePosIfBroken);
solver.addGoal(spec, weight, tuplePos);

• For a constraint, policy and the invalidCost / invalidState / tuplePosIfBroken tuning control its constraint policy: how a constraint that is already broken in the initial assignment is treated (fixed best-effort by default, or made strictly hard or soft).
• For a goal, weight and tuplePos control its goal priorities: how it trades off against other goals.

Available specs

Where a spec has its own page, its name links to it. The Type column shows whether a spec can be used as a goal, a constraint, or either. Examples links to the spec's unit tests.

Capacity and limits

Spec	Type	Description	Examples
Capacity	Both	Limit each scope item's utilization for a dimension to a max (or min)	unit tests
ToFree	Both	Drain the listed containers, driving their utilization for a dimension to zero	unit tests
Group Count	Both	Limit how many objects of a group a scope item holds, or their total for a dimension	unit tests
GroupDiversity	Both	Require each scope item to hold at least, or at most, N distinct groups	unit tests
CapacityWithGroupPresence	Both	Limit each scope item's utilization, with every present group counting for at least a minimum weight	unit tests
GroupCapacity	Both	Limit each group's total utilization across all scope items in a scope	unit tests
GroupIsolationLimit	Both	Limit how many groups may exceed their utilization limit in the same scope item (default 1)	unit tests
DisasterRecoveryCapacity	Both	Reserve enough spare capacity so scope items can survive correlated failure scenarios	unit tests

Balancing and packing

Spec	Type	Description	Examples
Balance	Goal	Balance a dimension's utilization evenly across scope items	unit tests
UtilIncreaseCost	Goal	Penalize raising a scope item's utilization above a lower bound	unit tests
MinimizeContainers	Goal	Minimize the number of scope items used	unit tests
MaximizeAllocation	Goal	Maximize utilization on a set of scope items	unit tests
MinimizeNthLargestUtilization	Goal	Minimize the n-th largest scope-item utilization (n is 0-based)	unit tests
MinimizeSquares	Goal	Minimize the sum of squared scope-item utilizations	unit tests
WorkingSet	Goal	Minimize the average or maximum working-set size across scope items	unit tests

Placement

Spec	Type	Description	Examples
NonAccepting	Constraint	Prevent objects from moving into the listed scope items	unit tests
AvoidAssignments	Constraint	Forbid specific object-to-scope-item assignments	unit tests
ColocateGroups	Both	Limit how many scope items each group spreads across (default: one)	unit tests
ExclusiveScopeItems	Both	Forbid pairs of scope items from being used at the same time	unit tests

Movement

Spec	Type	Description	Examples
AvoidMoving	Constraint	Prevent the listed objects from moving	unit tests
GroupMoveLimit	Constraint	Limit how many objects of a group may move	unit tests
MovesInProgress	Constraint	Account for objects already moving between containers	unit tests
MinimizeMovement	Both	Minimize the number (or dimension-weighted amount) of objects moved	unit tests

Affinities

Spec	Type	Description	Examples
AssignmentAffinities	Goal	Make specific objects prefer specific scope items	unit tests
PairAffinities	Both	Make pairs of objects prefer the same scope item	unit tests
GroupAssignmentAffinities	Goal	Make specific groups prefer specific scope items	unit tests
ScopeAffinities	Goal	Reward or penalize each scope item's utilization of a dimension via a per-scope-item weight	unit tests