How the Algorithm Works

How the Algorithm Works

At its core, Shibutz solves a constraint satisfaction and optimization problem. Given a set of students, classes, and rules, the algorithm finds the arrangement that best satisfies all of your requirements while keeping every class as balanced as possible.

This page explains what the algorithm does and why, without diving into implementation details. The goal is to give educators confidence in how placements are determined.

What the Algorithm Optimizes

The algorithm considers multiple dimensions simultaneously when placing students into classes:

1. Friend Placement

When students or parents submit friend preferences, the algorithm tries to place those friends in the same class. It maximizes the number of honored requests while respecting all other constraints. Not every request can be fulfilled — especially when two students are also subject to a separation restriction — but the algorithm treats each preference as a goal to pursue.

2. Scale Balancing

Every student has four scale scores: social, emotional, behavioral, and learning. The algorithm distributes students so that the average score for each scale is as similar as possible across all classes. This prevents situations where one class ends up with a disproportionate concentration of students who need extra support in a particular area.

3. Gender Balance

The algorithm aims for an even gender distribution in every class. If your cohort has 52% girls and 48% boys, each class should reflect roughly that same ratio rather than having one class skew heavily in either direction.

4. School Cohesion

When students come from multiple feeder schools or groups, the algorithm spreads them across classes so that no single class is dominated by students from one origin. This helps students from smaller schools feel included and encourages new social connections.

Hard Constraints vs. Soft Constraints

Not all rules carry the same weight. The algorithm distinguishes between two types:

• Hard constraints — these must always be respected. Student restrictions (e.g., "Student A and Student B must not be in the same class") and pre-assignments are hard constraints. The algorithm will never violate them.
• Soft constraints — these are goals the algorithm tries to achieve as well as possible. Friend preferences, scale balance targets, and gender balance targets are soft constraints. The algorithm optimizes for them but may trade off one against another to find the best overall outcome.

How Pre-Assignments Are Handled

If you have pre-assigned students to specific classes, those placements are locked in before the optimization begins. The algorithm then fills the remaining seats around those fixed students. Keep in mind that the more students you pre-assign, the less flexibility the algorithm has to optimize balance across the remaining dimensions.

The Iterative Process

The algorithm doesn't simply drop students into classes one by one. Instead, it explores many different configurations, evaluating each one against all of your constraints and objectives. Through this iterative process, it converges on the arrangement that provides the best overall balance.

Because the algorithm tries many possibilities, running it multiple times may produce slightly different results. Each run is an opportunity to discover a configuration that better fits your priorities.

What "Best Balance" Means

Balancing classes involves trade-offs. Honoring every friend request might conflict with achieving perfect scale balance. Keeping gender ratios identical might limit how well origin schools can be distributed. The algorithm weighs all of these objectives together and finds the configuration where the combined outcome is as good as possible — even if no single dimension is perfectly optimized.

You can influence these trade-offs through your assignment settings. Adjusting thresholds and priorities tells the algorithm which dimensions matter most to your school.

Designed for Educators

Shibutz's algorithm was built by engineers who work closely with educators and school administrators. Every optimization rule reflects real-world placement concerns — not abstract math. The goal is to save you hours of manual work while producing class lists that are fairer and more balanced than what's typically achievable by hand.

To see how well the algorithm performed on your data, visit the Understanding Results page after generating an assignment.