Zahnrad
Zahnrad is a tool for automatically and optimally assigning students to exercises classes. Users can use a web interface to select their preferences for the available time slots. The tool will try to respect these preferences when creating the assignment.
Zahnrad is implemented and deployed using various technologies including Java, Gradle, Spring, Thymeleaf, SQL and Docker.
Zahnrad was succesfully used at the Institute for Theoretical Computer Science at TU Braunschweig in 2019.
This page is a showcase for Zahnrad, presenting its features and providing some information about the implementation. Note that Zahnrad itself is proprietary closed-source software and not publicly available.
About the code
Zahnrad is written in Java and uses Gradle as a build system and for dependency management. Zahnrad uses the Spring framework and its various components, e.g. it relies on Spring Security for the secure communication with an LDAP server.
Zahnrad uses an SQL server to store its data. On the Java side of things, it uses the Java Persistence API and JQL queries to access this database.
The frontend of Zahnrad uses Thymeleaf as a template engine.
The optimal assignment is computed by solving an integer linear programming using the open-source tool lpsolve. To this end, Zahnrad contains a Java wrapper for lpsolve.
Zahnrad is intended to be deployed in the form of a Docker container that hosts the webserver.
Zahnrad consists of about 11 000 lines of code (8500 Java, 2000 HTML, 700 CSS).
User experience
Login
Zahnrad does not maintain the user login data. Instead, it uses Spring Security to establish a secure connection to an LDAP server provided by TU Braunschweig. After the first login, each user is asked to provide some additional information that cannot be retrieved from the LDAP server.
Selecting a course
After logging in, each user is presented the list of courses or lectures that are available in the current term. They may sign up for the exercises classes associated to each lecture.
Selecting preferences
After signing up for a lecture, the user is presented with a list of dates for the weekly exercises classes. For each date, the user can select whether they prefer this date or whether they cannot participate at this date (e.g. because of a conflicting lecture).
One should note that typically, the dates shown at this stage are a superset of the dates at which exercise classes will actually take place. This means that if a user tries to game the system by selecting "Impossible" for all but one date, this might end badly for them.
Linking users
The exercise classes will usually assign homework to the students which has to be solved and submitted in groups of multiple people. In order to allow students to form a group with their friends, Zahnrad provides so-called links. To this end, a user may provide the student id number of another student. If this link is also established in the other direction (i.e. the other student provides the student id number of the first one), Zahnrad will try to assign the two students to the same date for the exercise classes.
Viewing the assignment
Eventually, the administrator will close the signup process, create the optimized assignment, and then publish it. Afterwards, the user can see the exercise class they have been assigned to, i.e. the date, the room, and the teaching assistant that will hold the exercise classes.
Admin experience
Creating courses
Before the term starts, the admin may create the courses or lectures that will be available. Initially, these courses should be created as hidden, meaning that they will be only visible as administrators and not to the students. The admin should provide the course name, some additional information, and the amount of links that each user is allowed to have.
Creating slots
The admin cannot create a list of time slots that will be available. For each time slot, the date, the room, and the name of the teaching assistant can be provided. However, only the date will be shown to the students until the final assignment has been created and published.
Afterwards, the course status can be set to "Open", meaning that the students can sign up for this course.
Automatic optimal assignment
After the deadline for signing up has passed, the admin can close the signing up phase. Before starting the optimal assignment, a few parameters need to be set: The amount of students per exercise class and the number of exercise classes that will take place. If multiple exercise classes will take place in the same time slot, the admin may duplicate that time slot, which will also copy the students' preferences for that time slot.
Afterwards, the automatic assignment can be started. Zahnrad will construct an integer linear program, call lpsolve in order to this optimization problem, and then import the solution.
Statistics
The assignment that has been created is not yet visible to the students. It is recommended to check the statistics before publishing it.
In the example in the picture, Zahnrad had to pick 4 out of the 5 timeslots and then assign students to them. We see that the optimizer has excluded the first timeslot which was preferred by only 10% of the students. When assigning the students, it managed to assign 75% of the students to a timeslot for which they had selected "Preferred". (The "Undefined" column corresponds to students that have signed up for the course, but who have failed to set their preferences.) Additionally, the automatic assignment respects all the links created by the users.
Now, the assignment can be published, at which point it becomes visible to the students.