Running an Optimization
Configure and launch a Balance run: choosing an approach, setting objectives, and constraining the result.
Optimization runs live at /home/<team>/optimize, labelled Balance in the sidebar. The page lists your past runs and starts new ones.
Before you run
Three checks, in order:
- Is the data current? Look at the freshness indicator on the dashboard. See Sync and Data Freshness.
- Is the data right? See Understanding Your Data.
- Is the region structure right? The run starts from your current regions. If those do not reflect how you operate, fix them in the Data Editor first.
Skipping these is the most common reason a run produces a confusing answer.
The wizard
1. Introduction
Name the run and describe what you are trying to achieve. The description is free text and is worth writing properly — it is what you will read in three months when you are trying to remember why you ran this.
Here you also choose:
The data source. Live data, or a saved configuration from the Preview sandbox.
The approach. Several are available:
| Approach | What it does | Typical time |
|---|---|---|
| ReCom MCMC (recommended) | Advanced redistricting that produces high-quality contiguous regions | 30 seconds to 2 minutes |
| Boundary Rebalance | Keeps your existing boundaries and moves only a few adjacent areas | 10 seconds to 1 minute |
| AI-Powered (Generative) | Uses a language model to balance territories and explain its reasoning in plain language | 1 to 3 minutes |
| GA with Adjacency | Genetic algorithm with geographic contiguity enforced | Varies |
| GA-Adjacency + LP | The above, followed by a linear-programming refinement pass | Varies |
| Genetic Algorithm | Basic genetic algorithm without geographic constraints | Varies |
Start with ReCom MCMC. It is the default and the right answer for most questions.
Choose Boundary Rebalance when you have a structure that broadly works and you want a minimal, defensible adjustment rather than a redraw. It is much easier to sell to the people who have to live with it.
Choose AI-Powered when the explanation matters as much as the result — it produces natural-language reasoning alongside the assignment.
The plain Genetic Algorithm does not enforce geographic contiguity, so it can produce regions made of disconnected pieces. It is there for comparison; it is rarely what you want operationally.
2. Constraints
Number of regions. How many territories the result should have. Defaults to what you have now. Changing it is a much bigger operational change than rebalancing the same number.
Geographic contiguity. Whether regions must be made of connected areas. Leave this on unless you have a specific reason — a territory in two disconnected pieces is not a territory anyone can work.
Compactness. How tightly grouped regions should be. Higher compactness means less driving and less freedom to balance the numbers exactly. This is the main trade-off you are steering.
Iterations. How long the search runs. More iterations mean a better result and a longer wait, with diminishing returns.
Deviation budget (Boundary Rebalance only). Caps how much can change, either as a maximum number of areas moved or a maximum percentage. This is what makes the approach politically viable — you can say up front that no more than a set number of areas will move.
3. Objectives
Choose which metrics the run should balance, and how much each matters relative to the others.
- Pick a small number. Two or three well-chosen metrics beat eight. Every metric you add dilutes the others and makes the result harder to explain.
- Weight them deliberately. Equal weights say all your objectives matter equally, which is rarely true.
- Prefer hours over visit counts when you are balancing workload — a visit is not a fixed quantity of work.
- Be careful with rates. Balancing an average is a different question from dividing a total. See Metrics Reference.
You can also add free-text objectives and constraints describing goals in plain language.
4. Summary
Everything you have chosen, in one place. Read it. This is the last point at which a mistake is cheap.
5. Progress
The run executes. You see progress as it goes, and for the iterative approaches a convergence chart showing the solution improving.
Runs are asynchronous — you can leave the page and come back. A run that does not respond within ten minutes is marked as timed out.
You can cancel a run in progress.
6. Results
The proposed assignment, with before-and-after comparison. Covered in Reviewing Results.
Job status
| Status | What it means |
|---|---|
| Draft | Configured but not submitted |
| Pending | Submitted, waiting to start |
| Running | Executing |
| Completed | Finished, results available |
| Failed | Something went wrong — see the error on the job |
| Cancelled | Stopped by a user |
One run at a time per team. If a run is already in progress, wait for it or cancel it.
Running more than one
Running two or three configurations and comparing them is good practice, not indecision. Try a different weighting, or a Boundary Rebalance alongside a full ReCom run, and see how much of the benefit you can get for how much disruption.
Give each run a name that says what is different about it.
If a run fails
| Symptom | Usual cause |
|---|---|
| "No caseload data available" | The team has no data source, or it has never synced successfully |
| "At least one feature must be selected" | No objective metrics were chosen |
| Job timed out | The problem is very large, or the optimization service is unavailable. Reduce iterations and retry; if it recurs, contact support. |
| Already in progress | Another run is active. Wait or cancel it. |
More in Troubleshooting.