Allocate

---

Allocate is a staff allocation tool designed to assist course coordinators in producing a reasonable allocation of course staff (such as tutors) to the available course hours. This allocation needs to be based on a number of factors, including staff availability, preferences about contiguous hours and max hours in a week, and whether the given staff are junior (often requiring supervision of some sort) or senior.

Allocate takes this information about staff availability and other requirements, and uses Google OR-Tools, a software suite which tackles optimisation problems. Within this suite, the tool makes use of the CP-SAT solver specifically. This allows constraint programming (finding a model that meets a set of constraints) and also basic optimisation of that model.

A frontend exists for this, however the backend allocation software can be used independently, and is fully functional.

Once Allocate has been deployed (as described here), it is ready to be used for staff allocation.

The Path to Allocation Enlightenment

The path to allocation enlightenment is a simple, four step process.

1. Add classes
2. Add tutors
3. Add availabilities
4. Generate an allocation!

When the Allocation frontend is first opened, you will be met with a four-tab layout, as follows:

These tabs work as follows:

• Main: Provides instructions about utilising the allocation system (these are essentially an abridged version of this wiki page)
• Classes: Performs the Add classes functionality
• Tutors: Performs the Add tutors and Add availabilities functionality
• Generate: Generates and displays the allocation

Add classes

Adding classes can be done in two different ways:

• Manual entry of details
• CSV upload

Manual entry

Manual entry of data can be easily performed by filling in the text boxes on screen. The following details can be provided:

• A unique identifier for each class (eg. T01)
• The day of the business week each class runs on
• The starting time of each class, in 24-hour time (i.e. 1:00pm is written as 13:00)
• The minimum and maximum tutors allocated to each class - usually the minimum and maximum will be equal, however in the case that not all classes can be filled, these bounds can be provided and the system will try to maximise the number of tutors on any session

New classes can be added using the + button, and classes can be removed using the - button. New classes are pre-filled with information defaults - remember to always update this information with a unique class identifier and other relevant info.

CSV Upload

The manual entry technique does not persistently store data - that is, the inputted data will be cleared when the page is closed or refreshed. The CSV upload method is more appropriate method if persistent data storage is required, as it is possible to locally store a CSV file of the class data and then upload to the system when an allocation is required.

The following is an example of an accepted CSV. Any CSVs uploaded must contain the 6 columns as below, in the given order.

ID	MIN_TUTORS	MAX_TUTORS	DAY	START_TIME	DURATION
T01	1	2	Mon	9	1
P02	2	2	Tue	10	2

In raw form this appears as:

ID,MIN_TUTORS,MAX_TUTORS,DAY,START_TIME,DURATION
T01,1,2,Mon,9,1
P01,2,2,Tue,10,2

Uploading a CSV takes two steps:

1. Click on Upload Info CSV
2. Once the filename has appeared in the upload box, click the Upload button, and wait until the file is fully uploaded

It is also possible to download CSVs using the Download Info CSV button. This allows a combination of the manual and CSV upload techniques to be used. For example, you may want to enter data manually for the first time, then download it as a CSV file to re-use later on.

Add tutors & availability

Manual entry

Inputting tutor details is very similar to class details. It is possible to do this manually or by uploading CSVs. The following details about tutors can be provided:

• Their name (ensure all tutors have a unique name)
• The minimum and maximum number of weekly hours each tutor wants to work
• The maximum number of hours each tutor wants to work each day (for example, a tutor may not want to work a large number of contiguous hours, in which case their daily hours can be reduced)
• The minimum number of hours each tutor wants to work for each type of class. Currently three types of classes are accepted: tutorials (T), practicals (P), and studios (U). Not every course has all three types of classes, so the values can be left as zero if no classes of those type exist. Courses with other classes (eg. "I" classes) should represent these classes with one of the three existing class types.
• Whether the tutor is a first-time tutor for the course (a junior tutor)
• Whether the tutor would prefer to work contiguous blocks of hours

Like classes, tutors can be added and removed using the + and - buttons.

Availability

Tutors also have availability for certain classes, which can be manually entered using the associated input field. Class availability can be added by expanding the dropdown menu and clicking on a class. The x button next to each class in the availability input can be used to change tutors to unavailable for that class. It is essential that any classes are already uploaded before this availability is selected, as only existing classes can be selected.

Info CSV upload

Tutor info can be uploaded in a similar fashion to class info, using the Upload info file box. The following format is expected for tutor info uploads:

NAME	MIN_HRS	MAX_HRS	MIN_TUTE_HRS	MIN_PRAC_HRS	MIN_STUDIO_HRS	IS_JUNIOR	DAILY_MAX	PREF_CONTIG
Henry	1	5	1	0	0	FALSE	4	FALSE
Brae	1	10	0	2	0	TRUE	10	TRUE

In raw form this is written as:

NAME,MIN_HRS,MAX_HRS,MIN_TUTE_HRS,MIN_PRAC_HRS,MIN_STUDIO_HRS,IS_JUNIOR,DAILY_MAX,PREF_CONTIG
Henry,1,5,1,0,0,FALSE,4,FALSE
Brae,1,10,0,2,0,TRUE,10,TRUE

Availability CSV upload

Availability can be uploaded using the box on the right of the tutor upload box - Upload availability file. The following format is expected, where A represents a tutor-class pairing where the tutor is available, and U represents a tutor-class pairing where the tutor is unavailable.

	Henry	Brae
T01	A	A
P01	A	U

In raw form this is written as:

,Henry,Brae
T01,A,A
P01,A,U

Generate allocations

Once all the tutors and classes have been entered, the Generate tab will advise you on the number of entities that have been recorded, as follows:

If this looks correct, you are able to generate an allocation by clicking the button. Allocation can take a moment to complete, so please be patient, especially for large data sets. You should expect one of three outputs:

• The allocation is successfully generated
• There is a clear problem with the inputted model, in which case the allocation process was terminated prior to executing the constraint satisfaction engine
• The constraint satisfaction engine could not find a valid model

Constraints

The allocation engine takes into account the following constraints:

• Ensuring minimum and maximum tutor, class, and hour allocations
• Maximising the number of tutors on a class, if the minimum number of tutors does not equal the maximum number of tutors
• Ensuring no tutor is on two classes running simultaneously
• Ensuring junior tutors are paired with a non-junior tutor (on classes where more than one tutor is required)
• Maximising the contiguous hours worked by any tutor who prefers this (while adhering to any other constraints)

Success!

If the constraint satisfaction engine yields a result of "satisfiable", you will be given a tutor-class allocation that meets the given constraints. It is possible to edit this allocation with any manual adjustments, and then download it in CSV form. In this output, "Y" indicates an allocated class, while "N" indicates a non-allocated class.

Fail :(

If the constraint satisfaction fails, you will be notified. In some cases, the engine will alert you to the source of the problem. You will then have to make adjustments to the input data before being able to perform the allocation again.

Complex Allocations

The tool has no direct functionality to deal with complex allocations (such as extra tutors in certain weeks). It is however possible to achieve these by modifying the input data. Two techniques are available to generate extra tutor allocations:

1. Treat extra tutors on classes as separate classes (it would be necessary to adjust each class's duration to an appropriate value)
2. Generate multiple allocations - i.e. generate regular tutors on an initial run of the engine, then generate extras using a second run of the engine

There are pros and cons to these two options. Option 1 is more difficult to model, and will likely be slower to generate, however should give more optimal allocations. Option 2 is easier to model and faster to generate, but may not generate optimal models (and may result in cases where extras cannot be found).

Happy allocating!