The packaged example configuration-files are largely self-describing,
but their structure is more rigorously defined by "dtd/weekdaze.dtd" (which
is used in the application by a validating parser). Whilst this DTD may
define the permissible structure, it says nothing about the semantics,
which is the domain of this document. The corollary is that this document
may not detail trivial XML-tags required for purely syntactic purposes,
& so it is intended to be read with both the DTD & one of the packaged examples,
open for reference.
This application can for greater relational integrity & slightly fewer features,
can also read its configuration from a SQL-database. The database-schema for
which is defined in "sql/*.sql" & has been structured so that this application
can be run from a website, in that it caters for many isolated users, each
with many independent timetable-problems.
In the following description, default configuration-values, are where relevant
defined in brackets following their identifiers.
Some of the configuration can also be over-ridden by command-line options;
see section-1 of the man-pages.
| Resource | Attribute | Safe Change |
| ======== | ========= | =========== |
| group | "meetingTimes" | Reduce |
| location | "capacity" | Increase |
| location | "facilities" | Increase |
| teacher | "service" | Expand |
| teacher | course/"synchronisationId" | Remove |
| teacher | course/"maximumClassSize" | Increase or remove |
| teacher | course/"minimumConsecutiveLessons" | Reduce |
| teacher | course/"requiredFacilities" | Reduce |
| teacher | course/"timeslotRequest"/"ideally" | Any |
| teacher | "freePeriodPreference" | Any |
| teacher | "groupMembership" | Reduce |
| teacher | "specialtyTopic" | Any |
| teacher | "maximumTeachingRatio" | Increase |
| student-body | "freePeriodPreference" | Any |
| student-body | "groupMembership" | Reduce |
| student-body | "knowledgeRequirements" | Migrate a subject between "core" & "optional" sections |
| student-body | "studentId"s | Reduce |
| student-body | "teachingRatio" | Increase, with compensatory increase in "knowledgeRequirements" |
| "availability" | Increase |
| deterministicConstructor | which uses the lesson-criteria in an attempt to select the best lesson to place in each time-slot. |
| randomConstructor | which merely selects a lesson randomly, from those which are viable. |
The former is far more effective, but the optimum
timetable might only be reached by means of some sub-optimal lesson-selections,
which can only be taken by the "randomConstructor".
One can define the fecundity (i.e. how large a population of candidate solutions
to breed) depending on which constructor is used, for each of the depletion-strategies
(defined in section-1 of the man-pages).
synchronisedCourseByDayMutation, synchronisedCourseMutation, excessRunlengthMutation, homogeneousStudentViewLessonMutation, incompleteCourseMutation, randomLessonMutation, singletonStudentClassMutation, splitSessionMutation, studentBodyCombinationMutation, studentViewTimetableForDayMutation, studentViewTimetableForWeekMutation, synchronousLessonMutation.
CAVEAT: the default fecundity of 0, deactivates the corresponding evolution-strategy.
N.B.: some of these depletion-strategies will be irrelevant in the context of a given problem; e.g. "synchronisedCourseMutation" where no synchronised courses have been defined; but under these circumstances, the irrelevant depletion-strategy takes a negligible time, so there’s little to be gained from manually zeroing the fecundity of each of the corresponding constructors.
randomLessonMutationNTrials [256]
The number of random trials to use in "randomLessonMutation".
randomLessonMutationNTimeslots
[3]
The number of lessons to un-book in each random trial during "randomLessonMutation".
studentViewTimetableForDayMutationNDays [all]
The number of days to un-book in "studentViewTimetableForDayMutation". If
unspecified, then all valid values will be tried.
studentViewTimetableForWeekMutationNTrials
[16]
The number of random trials to use in "studentViewTimetableForWeekMutation".
studentViewTimetableForWeekMutationNTimeslots [4]
The number of lessons to un-book in each random trial during "studentViewTimetableForWeekMutation".
fecundityDecayRatio [0.5]
The factor (in the closed unit-interval [0,1]) by which the fecundity of
the breeding-program for future generations, is multiplied (& therefore exponentially
reduced), when the population-diversity ratio falls beneath "minimumPopulationDiversityRatio".
Each generation of the evolution of the timetable, involves breeding a population of candidate solutions (of size fecundity), then sparking multiple threads, to evaluate the fitness of each. This scales well on a multi-core machine, but if too many candidates are generated, inefficiency begins to creep in (even if CPU-cores are available to support them); either because more superior solutions are found, than are selected as parents for a subsequent generation; or because some mutations are identical, resulting in duplication of effort. Consequently, the initial fecundity is reduced by a feedback-loop, which monitors the population-diversity ratio of the candidates, & should it be observed to fall beneath a critical threshold, the fecundity of the breeding-program for future generations, is decreased by the specified factor.
minimumPopulationDiversityRatio [0.5]
The population-diversity ratio (in the closed unit-interval [0,1]), beneath
which a reduction in the fecundity of the breeding-program for future generations,
by a factor of "fecundityDecayRatio", is triggered.
nInitialScouts [1]
Each generation of the evolution of the timetable, involves breeding a
population of candidate solutions, from which the best (even when less
fit than their parent) few are selected. Each selected scout is used independently
to seed the breeding of a sub-generation of candidates from which one fewer
scouts are then selected. The resulting family-tree, sprouts fewer branches
with each successive generation, & so eventually withers. The best from all
the scouts (nodes) in this family-tree, is then compared with the fitness
of the original parent; & is either found to be fitter, & consequently used
to re-start this process (i.e. this paragraph), or is found to be less fit,
& the evolutionary process is terminated.
| nInitialScouts | Inferior | Breeding- | Total Scouts | Behaviour |
| Generations | sessions | |||
| Tolerated | ||||
| ============== | =========== | =============== | ================= | ========= |
| 0 | 0 | ? | ? | A variable number of scouts is used. Each candidate comparing equal best, & better than their parent, is selected. This results in monotonically increasing fitness (equivalent to a hill-climbing algorithm), & might result in a very wide search, but is typically effective. |
| 1 | 0 | 1 | 1 | Only the best child is selected from the single breeding-session & compared with the parent; no inferior candidates can propagate to subsequent generations. This results in monotonically increasing fitness (equivalent to a hill-climbing algorithm), & has the disadvantage that it can become trapped in a local maximum solution; actually such traps can still be escaped if the variation operations (i.e. mutations) permit large enough steps across the solution-space. |
| 2 | 1 | 3 | 4 | The best two scouts are selected from the breeding-session in the first generation; & from each independently bred second generation, the single best scout is selected. This differs conceptually in that one generation of inferior children is tolerated; though to be successful, @ least one of the four scouts (two children & two grandchildren), must be fitter than the original parent. |
| 3 | 2 | 10 | 15 | The best three scouts are selected from the breeding-session in the first generation; & from each independently bred second generation, the best two scouts are selected; & from each independently bred third generation, the single best scout is selected. Two inferior generations are tolerated; though to be successful, @ least one of the fifteen scouts (three children, six grandchildren & six great-grandchildren), must be fitter than the original parent. |
| n | n-1 | X(n) =1+n*X(n-1) | Y(n) =n*[1+Y(n-1)] | Execution-time is approximately proportional to (X(n) / n), which is approximately (n - 1)!. Though the best scout is never worse than that found from fewer initial scouts, the improvement doesn’t typically justify the additional effort; except that it makes the evolutionary process less prone to premature termination than when using a smaller number of scouts, where there’s a greater chance that none are better than their parent. Such levels result in a wider search of the solution-space, & may be employed in desperation when tackling timetable-problems which have resisted one’s initial solution-attempt; one can see an example of this in section-1 of the manual pages for this product. |
| Criterion-weight | |
| ================ | |
| areResourcesReused | A lesson is preferred, if the required resources (locations & teachers) are shared with other student-bodies, by temporarily merging them into a single larger student-class. |
| greatestMinimumConsecutiveLessons | A lesson is preferred, if the course’s "minimumConsecutiveLessons" is larger, since this makes it harder to book later, into the smaller spaces remaining. |
| greatestRemainingCourseLessons | A course is preferred, if it has greater un-booked lessons, since a course requiring only one lesson can be booked on any day. |
| greatestSynchronisedCourseSetSize | A course is preferred, if it is a member of a larger set of synchronised courses; it seems prudent to book the most constrained course’s lessons, early. |
| isCoreKnowledgeRequirement | A subject is preferred, if it is categorised by the student, as a "core" knowledge-requirement. |
| isSpecialistInTopic | A teacher is preferred, if their "specialtyTopic" matches the proposed "topic". |
| matchCourseClassSizeToLocationCapacity | A location is preferred, the closer its "capacity" matches the course’s optional "maximumClassSize"; provided it’s sufficient. |
| maximiseRelativeFacilityUtilisation | A location is preferred, the more its "facilities" are used; cf. "minimiseWasteOfScarceFacilities", which tries to make a distinction based on the type of the wasted facility. |
| maximiseStudentClassSizeOverCourseClassSize | A course is preferred, the more its "maximumClassSize" is filled by the proposed student-class. |
| maximiseStudentClassSizeOverLocationCapacity | A location is preferred, the more its "capacity" is filled by the proposed student-class. |
| minimiseBookingAtAnotherCoursesSpecifiedTime | A booking-time is preferred, if there’s minimal probability that courses for the student-body’s other knowledge-requirements, will require that time according to "timeslotRequest/specifically"; the probability becomes a certainty for those knowledge-requirements which can only be satisfied by one course. |
| minimiseBookingOfLocationByOtherTeachers | A location is preferred, when booked by the fewest other teachers. |
| minimiseDeviationFromTimeslotRequest | A course is preferred, if it is booked closer to any "timeslotRequest". |
| minimiseInterCampusMigrationsOfStudents | A course is preferred, if inter-campus migrations of students are minimised. |
| minimiseInterCampusMigrationsOfTeachers | A course is preferred, if inter-campus migrations of teachers are minimised. |
| minimiseStudentBodyCombinations | A lesson is preferred, when the number of student-body combinations is minimised. |
| minimiseTeachersLocusOperandi | A location is preferred, if the size of teacher’s locus-operandi is minimised; based merely on the number of distinct locations booked, rather than the distance between them. |
| minimiseWasteOfScarceFacilities | A lesson is preferred, if the location’s unused "facilities", are commonly available elsewhere; cf. "maximiseRelativeFacilityUtilisation", which treats all facilities equally. |
| Attribute | Default | Explanation |
| ========= | ======= | =========== |
| nTrials | 0 | The number of random trials to use when attempting to improve the specified lesson-criteria weights. |
| changeMagnitude | 1 | This positive number governs the size of the random change applied independently to each lesson-criterion weight. The chosen value permits an increase or decrease by a factor of up to 1 + x in the weight of a lesson-criterion. |
| reductionFactor | 0.9 | The factor in the closed unit-interval, by which "changeMagnitude" is multiplied after each success. |
| useMeanOverRasterScans | False | Whether to accept a proposed set of lesson-criteria weights on the basis of the mean (as opposed to the maximum) over the specified raster-scans, of the weighted mean over all heterogeneous timetable-criteria. Use of the mean over the raster-scans reduces the chance that weighted mean over heterogeneous timetable-criteria for the initial deterministic timetable was a freak result, & as such an inappropriate set of lesson-criteria weights with which to attempt to evolve the solution. Use of the maximum over the raster-scans will result in a good initial deterministic timetable, but it may not perform well during the subsequent evolution. |
| Criterion-weight | |
| ================ | |
| maximiseComplianceWithFreePeriodPreferences | A timetable is preferred, when it complies with any "freePeriodPreference" of student-bodies & teachers. |
| maximiseMeanRatioOfStudentClassSizeToLocationCapacity | A timetable is preferred, when the mean over all bookings, of the ratio of the size of the student-class to the location’s "capacity", is greatest. |
| maximiseMeanStudentClassSize | A timetable is preferred, when the mean size of student-classes, is greatest. |
| maximiseSynchronisationOfSynchronisedCourses | A timetable is preferred, when the lessons of synchronised courses are consistently synchronised. |
| maximiseWeightedMeanStudentBodyUtilisationRatio | A timetable is preferred, when the mean over all student-bodies, of the time currently booked to the total time in their working-week, is maximised. It doesn’t distinguish between "core" & "optional" knowledge-requirements like "minimiseMeanRatioOfIncompletelyBookedCoreKnowledge" & "minimiseMeanRatioOfIncompletelyBookedOptionalKnowledge", but it does value partially booked courses. |
| minimiseAverageAbsoluteDeviationFromIdealTimeslotRequest | A timetable is preferred more, the closer lessons are booked to any ideal timeslot-request for their course. |
| minimiseDispersionOfStudentFreePeriodsPerDay | A timetable is preferred, when each student-body’s free periods are spread evenly across their working-week. |
| minimiseDispersionOfTeacherFreePeriodsPerDay | A timetable is preferred, when each teacher’s free periods are spread evenly across their working-week. |
| minimiseDispersionOfTeacherWorkload | A timetable is preferred, when the relative workload between all teachers, is similar. |
| minimiseMeanInterCampusMigrationsOfStudents | A timetable is preferred, when the average over all students, of the number of inter-campus migrations in a week, is minimised. |
| minimiseMeanInterCampusMigrationsOfTeachers | A timetable is preferred, when the average over all teachers, of the number of inter-campus migrations in a week, is minimised. |
| minimiseMeanLocationChangesOfTeachers | A timetable is preferred, when the average over all teachers, of the number of changes in their location during the week, is minimised; cf. "minimiseMeanLocusOperandiOfTeachers", which merely counts the number of distinct locations used. |
| minimiseMeanLocusOperandiOfTeachers | A timetable is preferred, when the average over all teachers, of the size of their locus-operandi, is minimised; based merely on the number of locations, rather than the distance or the number of changes, between them. |
| minimiseMeanRatioOfIncompletelyBookedCoreKnowledge | A timetable is preferred, when the average over all student-bodies, of the ratio of incompletely booked "core" knowledge-requirements, to all requirements, is minimised. All incomplete courses are valued equally, regardless of the extent; cf. "maximiseWeightedMeanStudentBodyUtilisationRatio". |
| minimiseMeanRatioOfIncompletelyBookedOptionalKnowledge | A timetable is preferred, when the average over all student-bodies, of the ratio of incompletely booked "optional" knowledge-requirements, to all requirements, is minimised. All incomplete courses are valued equally, regardless of the extent; cf. "maximiseWeightedMeanStudentBodyUtilisationRatio". |
| minimiseMeanStudentBodyCombinationsPerLesson | A timetable is preferred, when the average number of combinations of student-body per lesson-definition, is minimised; ideally a student-body always studies a subject, in a class composed from the same other student-bodies. |
| minimiseRatioOfConsecutiveEqualLessons | A timetable is preferred, when blocks of consecutive identical lessons are booked, whose length least exceeds the course’s "minimumConsecutiveLessons". |
| minimiseRatioOfSeparatedEqualLessonsWithinAnyDay | A timetable is preferred, when the lessons of any course, are on any day, booked in one contiguous session. |
The evolution-algorithm uses the weighted mean of these criteria, to select
from candidate timetables, in a search for the optimum. This raises the
question of whether it’s valid to compare the observed value of criteria
which represent utterly different concepts; how can a criterion which has
the dimensions of time, meaningfully be included in a weighted mean with
another criterion which has dimensions of length ? To make these criteria
comparable, they’re all represented as dimensionless quantities, mapped
into the closed unit-interval [0,1]; e.g. by dividing by their maximum theoretical
value. This should reduce the question of what weight to apply to each,
to the simple question of their relative significance to the user, in the
context of the current problem; the most important could be set to 1, &
the others proportionately less.
Regrettably this seldom results in the desired outcome, because within
a typical population of candidate solutions, the observed value of some
criteria may range across the entire unit-interval, while the observed value
of others may be constrained to a minuscule portion. Consequently, within
the domain of this population of candidates, relatively large gains are
possible for some criteria, typically @ the expense of others, irrespective
of the user-defined significance of the corresponding concepts. The same
parasitic effect may also result between criteria, even when the values
typically found in the candidate population, range across spans of similar
length, but do so in different profiles, creating zones of sensitivity
to the underlying concept they measure. Whilst one may compensate for the
former effect, by adjusting the weight applied to specific criteria, that
regrettably decouples the weight, from the user-defined significance of
the concept being measured; compensating for the latter effect would require
a more complex mechanism that a single weight, & so far this hasn’t been
addressed. Some criteria may result in contrary views on the fitness of
a timetable; e.g. "minimiseRatioOfConsecutiveEqualLessons" downgrades a timetable
when the number of consecutive equal lessons exceeds the course’s "minimumConsecutiveLessons",
whereas "minimiseMeanLocationChangesOfTeachers" prefers the lack of a change
to a teacher’s location & "minimiseMeanInterCampusMigrationOfStudents" prefers
the lack of any requirement to migrate to another campus.
Consequently, it is probably best to start by merely copying the criteria-weights,
from the most appropriate of the packaged examples. If some aspect of the
resulting timetable isn’t acceptable, set "verbosity" to "Deafening", to
discover which criteria benefited from the evolution, & ask whether you
can afford to sacrifice some of the concepts they measure.
| displayViews [[LocationView,StudentView,TeacherView]] | An XML-element containing a list of XML-elements each called "perspective", each of which contains a single XML-attribute "view" (see below), which defines whether to display the timetable from that perspective. The three-dimensional matrix which defines a timetable, is inverted so that the axis which identifies the various student-bodies, is replaced by either one defining location-ids or one defining teacher-ids. The remaining two axes, representing the day of the week & the time-slot within each day, are displayed in all views. The same data are contained in each view, it’s merely re-indexed. |
| cssURL | References the cascading style-sheet defining the required style. It can either be a fully qualified URL or a path into the local file-system. This XML-attribute is optional; in its absence, the packaged CSS-file will be referenced, which though adequate to render the packaged examples, will need to be tailored to appropriately depict (via a dedicated background colour or image) new topics as they’re added to the curriculum. |
| mergeDuplicateTimeslots | Contains an XML-element called "timeAxes", which defines boolean XML-attributes tagged by "byDay" & "byTimeslotId", defining whether adjacent identical time-slots are merged. This reduces repetition, draws attention to duplicate lessons, & uses the limited space efficiently. This XML-element is optional; the default is "True" for both XML-attributes. |
| displayAxisLabels | Contains an XML-element called "timeAxes", which defines boolean XML-attributes tagged by "byDay" & "byTimeslotId", defining whether to label the axes of the output timetable. This XML-element is optional; the default is "True" for both XML-attributes. |
| displayRuntimeLog [False] | This boolean XML-attribute defines whether to display the runtime-log. |
| displaySupplementaryInformation [True] | This boolean XML-attribute defines whether additionally to display statistics, & summarise deviations between the solution & the configured requirements. |
| weekend [["Saturday", "Sunday"]] | An XML-element containing those days which constitute the weekend, & which are rendered differently. |
| generateLessonColourFrom | An optional XML-attribute, which specifies a data-source (one of "Lesson", "Subject", "Topic", "Level" or "ResourceIds"), from which to automatically generate an HTML-colour for the lesson when ultimately displayed. In the absence of any specification, the colour may be defined by the CSS-file specified via "cssURL". |
| minimumContrastRatio [1/16] | An optional XML-attribute, which defines the minimum acceptable contrast-ratio between the foreground lesson-colour generated according to "generateLessonColourFrom" and the complementary background-colour. |
"view" has a value of; "LocationView", "StudentView", or "TeacherView"; depending on which view of the resulting timetable to export. The precise format of the XML, is formally described by the corresponding packaged file; "dtd/locationViewTimetable.dtd", "dtd/studentViewTimetable.dtd", or "dtd/teacherViewTimetable.dtd".
| Level | Output |
| ===== | ====== |
| Silent | The lack of output might leave the user wondering whether anything is actually happening; it is, though it can take a long time. |
| Normal | The default-level. Delivers a progress-report on the reading, parsing & validation of the XML-configuration & any "inputStudentViewTimetable". Prints a "." as each evolution-strategy is completed. |
| Verbose | Provides more detail when reading xml. Reports statistics (to a precision governed by "nDecimalDigits") on the values of criteria as the solution evolves. |
| Deafening | Enhances the statistics reported by "Verbose". |
The latter two levels are unlikely to be intelligible to most users, but allow one to adjust criteria to drive the solution in the desired direction.
| checkAvailabilityOfAnyGroupMember | Check that @ least one member, can attend each meeting of a group. |
| checkCapacityOfLocationsForMeetings | Check that any location, specified for the meetings of a group, has adequate "capacity". |
| checkCoursesForSynchronousSpecifiedTimes | Check that no courses, required to satisfy a student’s knowledge-requirements, specify the same booking-time. |
| checkDuplicateMeetingLocationIds | Check that when more than one group requires the same location, that their meeting-times are mutually exclusive. |
| checkDuplicateOwnLocationIds | Check that when more than one teacher claims a single location as their own, that their working-weeks are mutually exclusive. |
| checkForAlternativesToSynchronisedCourses | Ensure that students can migrate easily between synchronised courses, by prohibiting any teacher from offering an alternative course outside the set of synchronised courses, but with an identical subject to one of the member-courses. |
| checkForDuplicateStudentIds | Check that no "studentId" has been defined in more than one student-body. |
| checkForIdleStudents | Check for student-bodies who require zero subjects, but have allocated one or more time-slots for teaching. |
| checkForIdleTeachers | Check for teachers who offer zero courses, but have allocated one or more time-slots for teaching. |
| checkForInvalidMeetingTimes | Check that all the timeslot-ids, used to define the meeting-times of groups, are within permissible bounds. |
| checkForMultipleCoursesPerTeacherPerSynchronisationId | Check that no teacher offers more than one course with the same "synchronisationId". |
| checkForNonExistentFacilities | Check for the existence in @ least one "locationProfile", of all the "requiredFacilities" for each course. |
| checkForNonExistentGroupIds | Check the existence of all "groupId"s, referenced by student-bodies or teachers. |
| checkForNonExistentMeetingLocationIds | Check the existence of all "locationId"s, required for the meetings of groups. |
| checkForNonExistentOwnLocationIds | Check the existence of all personal "locationId"s, claimed by teachers. |
| checkForOverloadedStudents | Check for student-bodies who have allocated zero time-slots for teaching, but have requested one or more subjects. |
| checkForSingletonSynchronisedCourses | Check for teachers offering a course which is a singleton set of synchronised courses. |
| checkForStudentsRequiringMultipleSynchronisedSubjects | Check for any student-body requiring more than one subject from any one set of synchronised courses. |
| checkForStudentsWithUnrealisableFreePeriodPreference | Check for any student whose "freePeriodPreference", can never be realised because of the meeting-times of groups of which they’re members. |
| checkForSynchronisedCoursesWithDifferentIdealTimeslots | Check that synchronised courses don’t define "timeslotRequest"s with different ideal timeslot-ids. |
| checkForSynchronisedCoursesWithDifferentLessonsPerWeek | Check that synchronised courses don’t define different "requiredLessonsPerWeek". |
| checkForSynchronisedCoursesWithExcessLessonsPerWeek | Check that synchronised courses don’t define a greater "requiredLessonsPerWeek", than the number of time-slots when all the interested student-bodies & required teachers are simultaneously available. |
| checkForSynchronisedCoursesWithExcessSpecifiedTimes | Check that synchronised courses don’t have fewer "requiredLessonsPerWeek" than the number of booking-times specified by the union of their "timeslotRequest"s. |
| checkForSynchronisedCoursesWithExcessTimeslotRequests | Check that synchronised courses don’t specify via "timeslotRequest"s, both ideal timeslot-ids & precise booking-times; these are intended to be alternatives. |
| checkForSynchronisedCoursesWithoutSuitableLocations | Check for synchronised courses which lack sufficient locations offering the "requiredFacilities", which are simultaneously available to the teachers & all interested student-bodies. |
| checkForSynchronisedCoursesWithUnavailableSpecifiedDays | Check for synchronised courses which specify times, on days when not all the interested student-bodies & required teachers, are available. |
| checkForTeachersWithUnrealisableFreePeriodPreference | Check for any teacher whose "freePeriodPreference", can never be realised because of the meeting-times of groups of which they’re members. |
| checkIfStudentBodiesExceedTeachers | Check that there are sufficient teachers, for the number of student-bodies, available on each day. |
| checkIfStudentBodySizeExceedsCapacityOfAllLocations | Check whether each student-body can be accommodated within the largest available location. |
| checkIfStudentBodySizeExceedsLocationCapacity | Check whether all student-bodies can be accommodated within the locations, available on each day. |
| checkIndependenceOfStudentTimeslotsRequestsAndMeetings | Check that student-bodies are members of groups which specify meeting-times (even those which don’t mandate attendance), which match any of the specified booking-times of courses they must attend. |
| checkIndependenceOfTeacherTimeslotsRequestsAndMeetings | Check that teachers are members of groups which specify meeting-times (even those which don’t mandate attendance), which match any of the specified booking-times of courses they must attend. |
| checkLocationsAvailabilityToSupportCourses | Check that there are sufficient locations, simultaneously available to at least one student-body & at least one teacher, to support the total number of time-slots required for the courses offered by all teachers. |
| checkLocationsForSynchronousSpecifiedTimes | Check there are enough locations in which to book lessons of courses offered by different teachers, which specify the same booking-time. |
| checkMeetingLocationsAvailability | Check that any location required for a group, is available @ all meeting-times. |
| checkMinimumConsecutiveLessons | Check that a course’s "minimumConsecutiveLessons" doesn’t exceed the number of time-slots per day. |
| checkNullGroupId | Check for null identifiers in the "groupCatalogue". |
| checkNullLocationCatalogue | Check whether the "locationCatalogue" is empty. |
| checkNullStudentBodyRegister | Check whether the "studentBodyRegister" is empty. |
| checkNullTeacherRegister | Check whether the "teacherRegister" is empty. |
| checkOwnLocationsAvailability | Check for teachers who’ve got their own location, that it’s simultaneously available on @ least one day. |
| checkRequiredLessonsPerWeek | Check that no course is offered, which requires more lessons per week, than the teacher works. |
| checkSimultaneousAvailabilityOfGroupMembers | Check that all the members of each group which both meets & mandates attendance, are simultaneously available. |
| checkStudentsAvailabilityForMandatoryMeetings | Check that students are available for the meeting-times of the groups of which they’re members. |
| checkStudentsAvailabilityForSpecifiedTimes | Check that no course, required to satisfy a student’s knowledge-requirements, specifies a time, on a day when they’re unavailable. |
| checkStudentsForMultipleLevelsOfSameTopic | Check that the knowledge-requirements of each student-body, don’t specify more than one level in any topic. |
| checkStudentsForSynchronousMeetings | Check that students aren’t members of groups with synchronous meeting-times. |
| checkStudentsLowerWorkloadBound | Check that students request sufficient subjects to fill their working-week to the required extent. |
| checkStudentsUpperWorkloadBound | Check that students don’t request more subjects than can be booked in their working-week. |
| checkSubjectExistence | Check that all subjects requested by students, are included in the services offered by teachers. |
| checkSuitableLocationsForKnowledgeRequirements | Check that there are suitable locations for each knowledge-requirement of each student-body. |
| checkTeachersAvailabilityForMandatoryMeetings | Check that teachers are available for the meeting-times of the groups of which they’re members. |
| checkTeachersForSynchronousMeetings | Check that teachers aren’t members of groups with synchronous meeting-times. |
| checkTeachersUpperWorkloadBound | Check that teachers don’t commit to more meetings than they’ve time to attend. |
| checkTeachingCapacityBySubject | Check that there’s sufficient teaching-capacity, to satisfy the demand by students for each subject. CAVEAT: This check is very lax. To maximise the efficiency with which teachers are used, it is typically assumed that any student-body which can be temporarily merged into a student-class, (see "permitTemporaryStudentBodyMerger"); no subsequent account is taken of whether both teachers & locations, can cope with the size of the resulting student-class. Additionally, an error is raised only when the demand for a subject exceeds the total supply, without any account of whether some of the teachers, are simultaneously required to support the other courses in their service. |
| checkTimeslotIdBounds | Check the range of timeslot-ids defined, is sufficient. |
| checkTimeslotRequests | Check that all "timeslotRequest"s reference either a valid timeslot-id or valid times. |
| checkBookedSubjectsAreRequired | Check that all subjects for which there’s a booking, are required by the student-body. |
| checkBookedSubjectsHaveService | Check that all subjects for which there’s a booking, have been offered as a course, by the referenced teacher. |
| checkSynchronisedCourses | Check that all the teachers of a set of synchronised courses, have booked synchronous lessons. |
| checkExistenceOfLocationIds | Check that all "locationId"s referenced in an imported studentViewTimetable, exist in the "locationCatalogue". |
| checkExistenceOfStudentBodies | Check that all student-bodies referenced in an imported studentViewTimetable, exist in the "studentBodyRegister". |
| checkExistenceOfTeacherIds | Check that all "teacherId"s referenced in an imported studentViewTimetable, exist in the "teacherRegister". |
| checkForBookingMeetingClash | Check for lessons booked @ the same time as a meeting, with a common resource-requirement. |
| checkForMisplacedLessons | Check for lessons booked @ locations lacking either adequate capacity or the facilities for their course. |
| checkForOverbookedSubjects | Check for student-bodies for whom more lessons have been booked, in a specific subject, than the course’s "requiredLessonsPerWeek". |
| checkForOverloadedStudentBodies | Check for student-bodies for whom more lessons have been booked, than allocated for tuition in one week. |
| checkForOverloadedTeachers | Check for teachers for whom more lessons have been booked, than allocated for tuition in one week. |
| checkForResourceConflicts | Check for times when resources have been allocated in more than one location. |
| checkMinimumConsecutiveLessons | Check for lessons which have been booked in run-lengths shorter than their course’s "minimumConsecutiveLessons". |
| checkResourceAvailability | Check that resources have been booked only on days when they’re going to be available. |
| checkTimeslotsPerDay | Check that all days have the correct number of time-slots. |
| subject | Defines the topic-string & the level @ which it is being taught. A course’s level is merely an arbitrary string. It’s free-format, but may represent both the academic year & the learning-capability expected of students before they express interest. The value must match those defined in the "knowledgeRequirements" of students. |
| requiredLessonsPerWeek | Defines the regular integral number of lessons required per week. CAVEAT: there is no facility to vary this from week to week; should it do so, a different timetable must be generated. Typically an integral multiple of "minimumConsecutiveLessons". |
| requiredFacilities | An XML-element defining a set of strings, which must be a subset of the "facilities" offered @ any location @ which the course is ultimately booked. |
| timeslotRequest | Optionally defines either the ideal timeslot-id within any day, @ which to book a lesson in this course (ideally timeslot-id), or specifies the times each week, @ which some of the lessons of this course should be booked (specifically [ time, time ... ]. CAVEAT: all student-bodies enrolled on this course, must form a single student-class @ the specified time, so either a suitably large location must be available, or another teacher must offer the same subject). If there are no special requirements then omit this XML-element, i.e. accept the default. |
| minimumConsecutiveLessons | Optionally defines the minimum integral number of consecutive periods which must be booked for this course; defaulting to 1. This constrains the booking of lessons in topics which either can’t be conducted in a shorter time-span, or for which either long preparation or long clean-up makes short sessions infeasible. The specified value represents an ideal, but if "requiredLessonsPerWeek" isn’t an integral multiple of this value, then on @ least one occasion, "minimumConsecutiveLessons" must be exceeded. |
| maximumClassSize | Optionally defines the maximum integral number of students with whom the teacher can cope, for the tuition of this course. In the absence of this XML-attribute, the "capacity" of the location in which the class is held, is the only limiting factor on class-size. |
| synchronisationId | Optionally identifies by means of a shared string, a set of courses offered by different teachers, whose lessons must be synchronised. In the absence of this XML-attribute, the lessons for this course need not be synchronised with those of any other course. Students may select only one member from such sets, but may migrate to a different member without disrupting the structure of the timetable. |
| Preference | |
| ========== | |
| Pre | A preference for unallocated time-slots to precede the first lesson or meeting of the day. |
| Terminal | A preference for unallocated time-slots either to precede the first or to follow the last, lesson or meeting of the day. |
| Post | A preference for unallocated time-slots to follow the last, lesson or meeting, of the day. |
| File-name | Time-slots | Student | XHTML-output | XML-output | Configuration-features | |||||||||
| xml/*.xml | per day | bodies | xhtml/*.xhtml | xml/*.xml | generateLessonColourFrom | campus | facilityName | freePeriodPreference | groupId | maximumClassSize | minimumConsecutiveLessons | specialtyTopic | synchronisationId | timeslotRequest |
| ========= | ========== | ======= | ============ | ========== | ======================== | ====== | ============ | ==================== | ======= | ================ | ========================= | ============== | ================= | =============== |
| example_01 | 1 | 3 | timetable_01 | studentViewTimetable_01 | Y | |||||||||
| example_02 | 2 | 2 | timetable_02 | studentViewTimetable_02 | Y | Y | Y | Y | ||||||
| example_03 | 3 | 2 | timetable_03 | studentViewTimetable_03 | Y | Y | Y | Y | Y | |||||
| example_05 | 5 | 11 | timetable_05 | studentViewTimetable_05 | Y | Y | Y | Y | Y | Y | Y | |||
| example_05_1 | 5 | 3 | timetable_05_1 | studentViewTimetable_05_1 | Y | Y | Y | Y | Y | Y | ||||
| example_08 | 8 | 11 | timetable_08 | studentViewTimetable_08 | Y | Y | Y | Y | Y | Y | Y | Y | ||
| example_13 | 13 | 11 | timetable_13 | studentViewTimetable_13 | Y | Y | Y | Y | Y | Y | Y | Y | Y | |
| example_21 | 21 | 11 | timetable_21 | studentViewTimetable_21 | Y | Y | Y | Y | Y | Y | Y | Y | Y | |
| template | 0 |
CAVEAT: should any of these files be relocated, then its "DOCTYPE"-declaration, will need to be corrected to reference weekdaze.dtd.
| File-name | Contents |
| dtd/*.dtd | |
| ========= | ======== |
| locationViewTimetable | The formal description of the XML-format for the resulting timetable as seen from the perspective of locations. |
| studentViewTimetable | The formal description of the XML-format for the resulting timetable as seen from the perspective of student-bodies. |
| teacherViewTimetable | The formal description of the XML-format for the resulting timetable as seen from the perspective of teachers. |
| weekdaze | The formal description of the XML-format for the input configuration-file. |
| File-name | Contents |
| sql/*.sql | |
| ========= | ======== |
| weekdazeCreate | Defines the database-schema; all the tables & all the rows. |
| weekdazeTriggers | Defines extra rules required to preserve relational integrity as data is inserted. |
| weekdazeExamples | Defines a set of example timetable-problems (the same as those defined in XML). |
This program is free software: you can redistribute it &/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/ >.