alrahma_sunday_school/docs/distribution_classes.md

# Balanced Student Section Distribution Plan

## 1. Purpose

This plan describes how already-promoted students will be distributed into sections for the next academic year.

Promotion, deliberation, passing decisions, and student eligibility have already been completed and are outside the scope of this process.

The distribution process must ensure that:

* Students are divided as equally as possible among sections.
* Each section contains a balanced number of students from every score range.
* Section average scores are reasonably close.
* User-defined minimum and maximum section sizes are respected.

## 2. Required User Inputs

Before starting the distribution, the user must enter:

| Input                        | Description                                   |
| ---------------------------- | --------------------------------------------- |
| Number of Sections           | Number of sections to be created              |
| Minimum Students per Section | Minimum permitted section size                |
| Maximum Students per Section | Maximum permitted section size, if applicable |

The student list must already include each student’s final score from the previous academic year.

## 3. Score Range Classification

Students must be classified using their previous-year final scores:

| Score Group |  Score Range |
| ----------- | -----------: |
| Group 1     |       90–100 |
| Group 2     |        80–89 |
| Group 3     |        70–79 |
| Group 4     | 69 and below |

Each student must belong to exactly one score group.

## 4. Validate the Number of Sections

Let:

* **N** = Total number of students to distribute.
* **S** = Number of sections entered by the user.
* **M** = Minimum number of students per section.
* **X** = Maximum number of students per section.

The requested section count is valid only when:

**S × M ≤ N**

When a maximum section size is used, the following condition must also be satisfied:

**N ≤ S × X**

Therefore, the complete validation rule is:

**S × M ≤ N ≤ S × X**

If no maximum section size is used, only the minimum condition applies.

## 5. Validation Results

The system should return one of the following results:

### Insufficient Students

The requested number of sections cannot be created because the total number of students is below the required minimum.

### Capacity Exceeded

The requested sections cannot contain all students without exceeding the maximum section size.

### Valid Setup

The entered number of sections and section-size limits are valid, and distribution may proceed.

The system must not automatically change the number of sections entered by the user.

## 6. Determine the Target Section Sizes

Divide the total number of students by the number of sections.

Each section should receive:

**Base section size = N divided by S**

Any remaining students should be assigned one at a time to different sections.

The difference between the largest and smallest section should not exceed one student.

Example:

* Total students: 61
* Number of sections: 2

Result:

* Section 1: 31 students
* Section 2: 30 students

## 7. Calculate the Score-Group Allocation

For each score group:

1. Count the number of students in that group.
2. Divide the group total by the number of sections.
3. Assign the base number to every section.
4. Distribute any remaining students across different sections.

For a score group containing **G** students:

**Base allocation = G divided by S**

**Remaining students = G modulo S**

Example:

* Students scoring 90–100: 11
* Sections: 2

Result:

* Section 1: 6 students
* Section 2: 5 students

The difference between sections within the same score group should not exceed one student.

## 8. Mathematical Limitation

Exact equality is not always possible.

For example, nine students from one score group cannot be divided equally between two sections. One section must receive five students and the other must receive four.

Therefore, the required rule is:

* Equal distribution when mathematically possible.
* A maximum difference of one student when exact equality is impossible.

## 9. Student Assignment Method

Within each score group:

1. Sort students from highest score to lowest score.
2. Assign them using a snake-distribution method.
3. Reverse the assignment direction after each round.

For two sections, use:

* First round: Section 1, Section 2
* Second round: Section 2, Section 1
* Third round: Section 1, Section 2

For three sections, use:

* First round: Section 1, Section 2, Section 3
* Second round: Section 3, Section 2, Section 1

This prevents one section from repeatedly receiving the highest-scoring students.

## 10. Rotate Remaining Students

Additional students caused by uneven division should not always be assigned to the first section.

The section receiving the extra student should rotate between score groups.

Example with two sections:

| Score Range  | Section Receiving the Extra Student |
| ------------ | ----------------------------------- |
| 90–100       | Section 1                           |
| 80–89        | Section 2                           |
| 70–79        | Section 1                           |
| 69 and below | Section 2                           |

This helps maintain equal total section sizes.

## 11. Balance the Average Scores

After the initial distribution, calculate the average previous-year score for every section.

The difference between the highest and lowest section averages should preferably not exceed one percentage point.

If the difference is too large, students may be exchanged between sections when:

* They belong to the same score range.
* The exchange improves the average-score balance.
* Section sizes remain valid.
* Minimum and maximum limits are still satisfied.

## 12. Additional Distribution Considerations

After academic balancing, the distribution may also be reviewed for:

* Gender balance, where applicable.
* Special educational needs.
* Language-support requirements.
* Behavioral considerations.
* Documented student-separation requirements.
* Medical or accessibility needs.

Any adjustment should preserve the score-range and section-size balance as much as possible.

## 13. Final Distribution Summary

The final result should include:

| Section   | Total Students | 90–100 | 80–89 | 70–79 | 69 and Below | Average Score |
| --------- | -------------: | -----: | ----: | ----: | -----------: | ------------: |
| Section 1 |             30 |      5 |     8 |     9 |            8 |          78.4 |
| Section 2 |             30 |      5 |     7 |     9 |            9 |          78.2 |

## 14. Final Validation Checklist

Before confirming the distribution, verify that:

* The number of sections was entered by the user.
* The minimum section size was entered by the user.
* The maximum section size was entered, when applicable.
* All students have been assigned exactly once.
* No section is below the minimum size.
* No section exceeds the maximum size.
* Total section sizes differ by no more than one student.
* Score-group counts differ by no more than one student.
* Average scores are reasonably balanced.
* No student is missing or duplicated.

## 15. Final Rule

The system distributes students only after promotion and deliberation are complete.

The user determines the number of sections and the section-size limits.

The system validates those values and creates the most balanced possible distribution based on:

* Total student count.
* Score-range counts.
* Section-size limits.
* Average section scores.