How to Use Meta's Rebalancer for Task Placement and Optimization

In this tutorial, we walk through Rebalancer, Meta's open-source assignment solver, which pairs a high-performance C++ core with a Python binding. Rebalancer is designed to answer the classic infrastructure question: given a set of objects and a set of containers, which object goes where? That question sits at the heart of scheduling workloads across datacenters, placing shards across storage nodes, and distributing services across hosts.

We will cover how to describe objects, containers, dimensions, scopes, and partitions; how to add constraints and goals; and how to choose between the built-in local search solver and the exact mixed-integer solver HiGHS. From there, we build a small datacenter, drain a busy host, and compare the two solvers across several scenarios: toy models, mutually exclusive hosts, synthetic clusters, and 60 published OR-Library instances.

A recurring theme throughout is validation. Rather than trusting the solver's flags, we judge every plan by recounting the returned assignment. That discipline matters: in this build, across 24 solves, the solved flag read True in 14 solves that still left memory over capacity. Similarly, running HARD constraints under local search returned a violating start without raising an error, misspelled spec keys were ignored silently, and enum names were rejected outright.

All timings below come from an Apple M4 using the macOS wheel. Note that Colab's Linux wheel may time differently.

Why Task Placement Still Matters in 2026

As AI clusters scale into the tens of thousands of accelerators, placement decisions compound quickly. A poor assignment wastes scarce GPU memory bandwidth, creates thermal hotspots, and strands capacity behind fragmented reservations. Rebalancer's abstraction of objects-into-containers maps cleanly onto modern orchestration problems, from packing inference replicas onto heterogeneous GPU pools to rebalancing shards after a node drain. Treating placement as an explicit optimization problem, rather than a side effect of a scheduler heuristic, is what makes tools like Rebalancer valuable in 2026 infrastructure stacks.

Getting Started

Install Rebalancer via the Python wheel, then import the binding:

import rebalancer

The core concepts you need to internalize are:

• Objects — the things being placed (tasks, shards, replicas).
• Containers — the destinations (hosts, nodes, racks).
• Dimensions — the resources consumed (CPU, memory, GPU).
• Scopes — named groupings that constrain where assignment can occur.
• Partitions — subdivisions of containers used to express locality or exclusivity.

Modeling a Small Datacenter

We start with a toy datacenter: a handful of hosts, each with a fixed memory dimension, and a set of tasks with memory requirements. The goal is to place every task without exceeding any host's capacity.

# Define the universe
objects = ["task_0", "task_1", "task_2"]
containers = ["host_0", "host_1"]

# Each object consumes memory; each container provides memory
memory = {"host_0": 16, "host_1": 16}
task_memory = {"task_0": 8, "task_1": 8, "task_2": 8}

After defining the model, we add constraints and goals, then hand the problem to either local search or the exact HiGHS solver.

solver = rebalancer.Solver()
solver.set_object_memory(task_memory)
solver.set_container_memory(memory)

# Solve with local search
solution = solver.solve_local_search()

Drain a Busy Host

Rebalancer's real value shows up when you need to move work rather than place it from scratch. Draining a host means constraining that host to accept no new objects and then re-solving so its existing objects migrate elsewhere. This is exactly the operation you perform ahead of maintenance or a hardware swap.

# Mark host_1 as drained
solver.exclude_container("host_1")
solution = solver.solve_local_search()

Comparing Local Search and HiGHS

Local search is fast and scales to large clusters, but it offers no optimality guarantee and can silently return a violating start. HiGHS provides exact answers at the cost of runtime, making it practical for smaller models or for validating a local-search result.

| Scenario | Local Search | HiGHS |

| --- | --- | --- |

| Toy model | Fast, may violate | Exact |

| Mutually exclusive hosts | Fast, needs careful validation | Exact |

| Synthetic cluster | Scales well | Runtime grows quickly |

| OR-Library instances (60) | Good heuristic coverage | Exact where tractable |

We also tested against 60 published OR-Library instances, which are a standard benchmark family for assignment and bin-packing problems.

Validation Lessons from This Build

Several behaviors in this build are worth flagging, because each one can silently corrupt a placement plan if you trust the solver's word:

1. The solved flag is not trustworthy on its own. Across 24 solves, solved read True in 14 cases that still left memory over capacity. Always recount the returned assignment.
2. HARD constraints under local search can be returned violated without raising. Local search may start from an infeasible state and never flag it.
3. Misspelled spec keys are ignored silently. A typo in a dimension or container name can change the model without any error.
4. Enum names are rejected. Passing an enum value by name raises an error, so use the expected typed value.



Conclusion




Rebalancer gives you a practical, embedded optimization engine for task placement, with a fast local search for scale and HiGHS for exactness. The most important habit is to validate every plan by recounting the returned assignment, never by trusting solver flags alone. Run the models above, then extend them toward your own cluster topology, dimensions, and constraints. In 2026's dense AI infrastructure, that validation discipline is what separates a working placement plan from a quietly overcommitted one.

via MarkTechPost