# Show scheduling rules

A show is the complete event, including every dated daypart. It may span several
calendar dates. Counts do not restart on a new date.

## Required performances

The manager chooses **preferredDayParts**, the desired number of distinct dayparts, per show.
It defaults to two, or one for a show with only one daypart. A show can be saved
without dayparts but cannot be scheduled. If dayparts are removed, preferredDayParts is retained
and must be corrected before scheduling when it exceeds the remaining count.

Every nonempty regular, selection and pre-education group performs in exactly preferredDayParts
dayparts, once in each. Each preschool group performs exactly once in the whole
show. Every showcase performs once in every daypart. Groups without dancers are
skipped completely, including for showcase positions and balancing.

With at least two showcases, one opens and another closes every daypart. Any
additional showcases may appear between them. The opening and closing groups can
change between dayparts. A single showcase may open or close, but never performs
twice in the same daypart. Without showcases there is no opening/closing rule.

## People and changing clothes

An ordinary dancer must perform in no more than preferredDayParts distinct dayparts across all
of their groups. The same dancer registration must be used in every group.

Showcase participants necessarily perform in every daypart. For their other
performances, exceeding preferredDayParts dayparts is allowed but discouraged. We count their
non-showcase dayparts, subtract preferredDayParts, and count only positive excesses. The planner's
first preference is to minimize the sum of these excesses across dancers.

A coach registration must be explicitly linked to the corresponding dancer;
names are not used to guess identity. Coaches are available throughout the show
and are exempt from both the preferredDayParts limit and the excess penalty. A coach only performs
with a group if included in its dancer membership. Being a group's coach alone
never adds a performance or forces that group into extra dayparts.

Between any two performances involving the same person, at least two other
performances must intervene in which that person does not dance. This includes
coaches accompanying preschoolers, coaches dancing in other groups, and showcases.
There are no exceptions. Between dayparts we assume sufficient changing time,
so the gap rule restarts even if the dayparts are on the same date.

## Balance and preferences

All performances count equally, including preschool groups and showcases. The
busiest daypart may have at most two more performances than the quietest. Zero
is ideal. Preschool groups can cause a difference but have no special exemption.

Among schedules satisfying every mandatory rule, optimize in this strict order:

1. Minimize non-showcase daypart excess for showcase participants, excluding coaches.
2. Minimize the difference in performance counts between dayparts.
3. Minimize similarity of consecutive performances within each daypart.

A lower priority cannot worsen a higher priority. OR-Tools solves these objectives
in sequence, fixing each proven optimum before working on the next. If it finds
only a feasible result at a priority, it returns that valid result without
claiming that the complete schedule is optimal.

For variety, style similarity is the fraction of shared styles among all distinct
styles of the two groups. Two groups without styles have no style penalty.
Age similarity is one for equal average ages, falling linearly to zero at a
five-year difference and remaining zero above that difference. Style and age
have equal weight. Each component is rounded to millionths for CP-SAT's integer
objective. Showcases count in this comparison. Average age includes every dancing
member equally, including coaches, measured in completed years on the first date
of the show. Empty groups are already excluded.

## Results, drafts and final schedules

Scheduling can take up to thirty minutes in total across the optimization stages.
A feasible result is accepted even when optimality is unproven. Every mandatory
rule still applies. Proven infeasibility and reaching the time limit without a
result are reported differently. Failures preserve the saved assignments and
order. Concurrent runs are rejected and changed inputs invalidate pending results.

Automatic results are drafts for manager review. Managers can also move, add,
remove and reorder performances manually and save incomplete or invalid drafts.
The application lists the rules those drafts violate. An explicit finalization
action checks all mandatory rules; only a valid schedule can become final.
Preferences alone never block finalization.

Manual edits and relevant membership, dancer-age, coach-link or show-setting
changes return final schedules to draft. Existing schedules and imported schedules
are drafts. Import retains assignment order and recalculates violations. Export
is available for both statuses and records status, preferredDayParts and coach identity links;
reimport always requires a fresh finalization.