Requirements, preferences, and objectives

Three different promises

GroupMixer separates rules into three categories because they have different meanings:

Do not use a very large preference weight as a substitute for a requirement. A weighted target remains negotiable when the solver compares it with other costs.

Requirements are invariants

The Scenario Editor currently exposes three requirement families:

• Immovable People fixes selected people to a named group in selected sessions.
• Must Stay Together requires selected people to share a group in its configured scope.
• Must Stay Apart requires selected people to occupy different groups in its configured scope.

A returned result that violates one of these required rules indicates a solver or validation defect. It is not a normal compromise for a better score.

Requirements can still make the input infeasible. For example, three people fixed to a group with capacity two cannot all be assigned there, and the same pair cannot be required both together and apart in the same session. GroupMixer should reject or fail such a scenario honestly rather than ignore a requirement.

Use a requirement only when violating it makes the schedule unusable. Each non-redundant invariant can remove possible schedules.

Preferences describe weighted targets

Preferences include Repeat Encounter, Should Stay Together, Should Not Be Together, Attribute Balance, Attribute Sum, Encounters, and Group Visits. Each expresses a measurable target while leaving the solver permission to return the least costly valid schedule it can find.

Scope answers who, where, and when the target covers. A scope omitted in the editor commonly means all applicable people, groups, or sessions; a selected scope means only those named entities. Read the summary shown on the saved constraint rather than assuming a blank-looking field means “none.”

Bounds answer what counts as a deviation. Depending on the preference, the editor may offer an exact value, lower bound, upper bound, range, or a target specific to that constraint family.

Understand weight and scoring curves

For one measured target with raw bound distance d and weight w:

Example: with weight 10, one raw deviation of 2 costs 20 under a linear curve and 40 under a squared curve. When a constraint evaluates several people, groups, or sessions, GroupMixer applies the curve to each measurement and sums those costs.

The curve and weight both matter. Available compliance evidence differs by preference family, and a card can report raw deviations without expanding the weighted cost for every row. Use raw evidence to understand what happened and the score breakdown to understand aggregate optimization cost.

Weights are relative. Doubling every active weight does not create new feasibility. Start with comparable values, solve, inspect the actual trade-off, and adjust one priority deliberately.

Objectives shape broader search goals

The exposed objective is Maximize Contacts. Its weight controls how strongly the solver values new person-to-person contacts relative to configured constraint penalties. Setting its weight to zero deactivates it; higher values increase its relative importance.

Maximize Contacts does not override requirements. It can compete with weighted preferences—for example, a contact objective may favor mixing people while a Should Stay Together preference favors keeping a pair together.

Repeat Encounter and Maximize Contacts are related but not identical controls. Repeat Encounter penalizes meetings beyond its allowed count and scope. Maximize Contacts rewards broader unique contact coverage. Use result evidence to see whether the chosen combination produced the intended behavior.

Choose the right category

Ask these questions in order:

1. Would violating this rule make the schedule invalid? Use a requirement if the product exposes the needed invariant.
2. Is the rule desirable but legitimately negotiable? Use a preference with an explicit scope and weight.
3. Is it a broad quality direction rather than a local rule? Use an objective.
4. Does the product lack the semantics you need? Do not approximate a missing hard rule with a hidden or oversized soft target.

After solving, Understand results explains where to check invariants, raw deviations, weighted penalties, and contact evidence.