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
CapacitySpec	Both	Limit each scope item's utilization for a dimension to a max (or min)	unit tests
ToFreeSpec	Both	Drain the listed containers, driving their utilization for a dimension to zero	unit tests
GroupCountSpec	Both	Limit how many objects of a group a scope item holds, or their total for a dimension	unit tests
GroupDiversitySpec	Both	Require each scope item to hold at least, or at most, N distinct groups	unit tests
CapacityWithGroupPresenceSpec	Both	Limit each scope item's utilization, with every present group counting for at least a minimum weight	unit tests
GroupCapacitySpec	Both	Limit each group's total utilization across all scope items in a scope	unit tests
GroupIsolationLimitSpec	Both	Limit how many groups may exceed their utilization limit in the same scope item (default 1)	unit tests
DisasterRecoveryCapacitySpec	Both	Reserve enough spare capacity so scope items can survive correlated failure scenarios	unit tests

Balancing and packing

Spec	Type	Description	Examples
BalanceSpec	Goal	Balance a dimension's utilization evenly across scope items	unit tests
UtilIncreaseCostSpec	Goal	Penalize raising a scope item's utilization above a lower bound	unit tests
MinimizeContainersSpec	Goal	Minimize the number of scope items used	unit tests
MaximizeAllocationSpec	Goal	Maximize utilization on a set of scope items	unit tests
MinimizeNthLargestUtilizationSpec	Goal	Minimize the n-th largest scope-item utilization (n is 0-based)	unit tests
MinimizeSquaresSpec	Goal	Minimize the sum of squared scope-item utilizations	unit tests
WorkingSetSpec	Goal	Minimize the average or maximum working-set size across scope items	unit tests

Placement

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

Movement

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

Affinities

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