Table of Contents


weekdaze - Attempts to find a timetable satisfying the types of criteria typically required by a school.


weekdaze [OPTIONS]


A command-line application, which attempts to automatically compose a suitable timetable, from the requirements defined in either a local configuration-file or database.
N.B.: The configuration is described separately in section-5 of the manual pages for this product, but occasional references to specific configuration-fields from this document, are for distinction, both double-quoted & emboldened.

The resulting timetable is rendered in XHTML, as a set of two-dimensional slices through a conceptually three-dimensional Cartesian graph. Each slice is bounded by axes ranging over the days of the week, & the constant, but configurable, number of time-slots into which the day has been sub-divided, & identifies any lessons booked. The third axis (which defines each slice) identifies a resource (either the students, the teachers, or the locations in which classes are held); depending on the intended audience for the timetable. A timetable can be inverted to change this axis so that it can be more readily be interpreted by another type of observer, whilst still presenting the same set of bookings.
The timetable can also be rendered as XML, organised in a form suitable for viewing by any of these types of observer, to facilitate either transport of the solution-data to another system, or fed-back into this application as the initial state from which to evolve further.

Since the solution is progressively evolved, the quality depends on the time available. Regrettably, the application can’t in general, prove in advance, that all the configured criteria can be satisfied; thought it may be able to prove that some of them can’t. Consequently, it can’t guarantee that a completely satisfactory solution for a specific problem can ever be found, however much time is devoted to it; though it will return the best solution found. In this respect, it is incumbent on the user to understand the ramifications of their choice of constraints, & to provide sufficient resources to permit a solution.


In the context of this application, the following terminology is employed. The terms have been coined as the need has arisen, & don’t necessarily correspond to the jargon used by other solutions in this problem-domain.
You may prefer to skip ahead & refer back to this dictionary as required. To prompt one to the existence of some special meaning (since these terms express nuances beyond their meaning outside the context of this application), such terms have been distinguished by underscoring.
The whole days when a resource is available to be booked.
Fractions of days can’t be directly expressed, though if the resource is human, any unavailable portion of a day can be reserved artificially, using the meetings of a single-member group (which has no purpose & doesn’t require a location).
A rendezvous defined in the timetable, for a specific lesson @ a specific time.
Similar to a meeting, but refers to a lesson, rather than a group. Though the booking-times of a lesson can be specified in the configuration, typically it is allocated @ run-time by weekdaze, which inserts it between the fixed meeting-times of groups.
Defines a set of proximate locations, between which intraday migration is trivial.
If the time required to migrate between locations is significant, then one may partition them into campuses to allow the application to minimise the number of such journeys.
A set of lessons in a common subject, offered by a single teacher.
Though a subject would typically require many weeks of tuition, only one week is configured, on the assumption that others have similar scheduling-requirements.
A course springs into existence, when it is offered as part of a teacher’s service, rather than existing as an independent part of the configuration to which teachers & student-bodies refer.
The working portion (rather than the full 24 hours), of a day of the week.
The day forms one of two temporal axes, from the three Cartesian coordinates used to describe the single-week timetable.
A method used by the application to liberate space in the timetable, by selectively un-booking lessons.
The lessons are selected; in order to reduce some undesirable trait; to re-cast any established routine; or arbitrarily, merely to permit exploration of an alternative region in the solution-space.
One of many methods used by the application, in an attempt to evolve the timetable. Each is composed from a depletion-strategy & a reconstruction-strategy.
An attribute of a location, which can in some way support a course.
The size of the population of candidate-timetables, that the application breeds in any one generation of the evolution of a solution.
Used either to quantify the:
suitability of each member of a set of alternative lessons to book in the timetable @ a specific time, using a weighted-mean of lesson-criteria;
value of each member of a set of alternative timetables, using a weighted-mean of a set of timetable-criteria.
A set of one or more people (teachers or student-bodies) with a common interest or duty.
This is a more flexible structure than the single teacher & student-class used to define a lesson.
The set of one of more subjects required by a student-body. It is partitioned into those personally considered (other student-bodies may categorise them differently) to be either core or optional.
An arrangement between a single teacher & a student-class, to teach a course for one period @ a specific location & time-slot.
A lesson as depicted in the results, always specifies the course’s subject, but only two of the three types of resource, the third being implied by the coordinate @ which it is booked on the observer-id axis of the timetable.
The metrics used by the application when constructing a solution, to quantify & therefore to facilitate selection, of the best lesson from those which are permissible @ specific coordinates.
The value of each criterion is typically neither dependent on what has already been booked elsewhere, nor does it change as further bookings are made.
Each criterion has an associated configurable weight, which allows one to change its significance relative to other lesson-criteria.
cf. timetable-criteria which are used to quantify & therefore select the best from a population of candidate-timetables.
The level @ which a topic is taught, or the personal academic capability or year of a student.
Continuity of the teacher-student relationship, for the tuition of a specific course, may need to be guaranteed in the years leading up to examination. This can be implemented simply by requiring that those teachers offering such a course, specify a level which includes a unique code. Student-bodies requesting this subject can then specify the unique level corresponding to their teacher from the previous year.
A generalisation of a class-room, to encompass any space available to support either a booking or a meeting.
It is described by its availability, capacity, & the facilities it offers to support courses.
A rendezvous defined in the timetable, between group-members @ a specific time.
Similar to a booking, but refers to a group, rather than a lesson.
The meeting-times of a group are configured, & are therefore reserved by the application, forcing lessons to float around them.
The target audience for a timetable, which may be any type of resource.
The same timetable-data may be re-organised into a form suitable for any of three types of observer, by enumerating unique resource-identifiers along one axis of the timetable (the remaining two axes are always the day & the timeslot-id), thus permitting all observers of that type to rapidly access their personal timetable for the week.
N.B. since a location is clearly incapable of observing anything, one may more correctly consider the timetable indexed by location-id, to be ideally organised for observation by maintenance-staff.
Similar to a time-slot, but refers more to a duration than to a position on the time-axis.
Population-diversity Ratio
The ratio of distinct members to all the members, in a population of candidate-timetables.
Either a location, a student-body or a teacher.
Since each lesson requires one of each type of resource, the most basic function of weekdaze is to avoid scheduling-conflicts between them; no individual can be booked @ more than one location @ any time, & no location can host more than either one class or one meeting @ a time.
cf. Observer.
The relationship established between resources, when teaching the lessons of a course.
It is considered desirable that such routines are preserved, so that for any one subject, a student-body isn’t taught either @ more than one location or by more than one teacher.
The set of courses offered by a teacher.
N.B.: a teacher who offers no service directly to students, may still exist in the timetable @ the meetings they attend.
This is the personal academic capability or year of a student-body.
The requirement for a student-body to have a stream isn’t obvious, since it can be inferred from the level of the topics in their knowledge-requirements, but it can be used to prevent the various student-bodies studying a subject from being merged into a single student-class (should that be undesirable).
An individual, whose requirements are described by the student-body of which they’re a member.
A set of students with identical requirements (availability, stream, knowledge-requirements, group-membership).
These sets are typically manually configured, but additional or larger sets, may optionally be automatically discovered by the application; it can also relax the requirement that the students belong to the same groups, if the groups for which memberships differ, never actually meet.
Student-body Combinations
This refers to an undesirable trait in a timetable, where the set of student-bodies, who’re temporarily merged into a student-class for the tuition of a course, changes throughout the lessons booked in a week.
E.g. where three student-bodies, S1, S2, S3, are enrolled on course C1, taught by teacher T1, which requires two lessons per week; S1 may be merged with S2 to form a student-class @ time t1, S2 merged with S3 @ time t2, & S3 with S1 @ time t3.
The undesirable consequence is that teacher T1 must synchronise progress through the course, between these student-classes.
A set of student-bodies, which are temporarily merged during the tuition of a single course.
Student-class Combinations
This refers to an undesirable trait in a timetable, in which lessons for a set of synchronised courses have been booked. Though the courses which share a "synchronisationId", may have been booked without any undesirable student-body combinations, each lesson may be synchronised with different student-classes in the other courses of the set.
E.g. take two synchronised courses, C1 taught by teacher T1, & C2 taught by teacher T2, each of which requires two lessons per week. Student-bodies S1 & S2 are enrolled on C1, while student-bodies S3 & S4 are enrolled on C2. Whilst these four student-bodies could be merged into two student-classes {S1, S2} & {S3, S4} under these circumstances no undesirable student-body combinations can arise, but should their availability dictate that they must form four singleton student-classes, different pairs of singleton student-classes may be synchronised @ various times throughout the week.

The consequence of this only becomes apparent, when any one of these student-bodies decides to migrate to the other course in this set of synchronised courses; which, as required, is possible without shuffling the timetable, but results in a student-body combination.
E.g. Should S1 decide to migrate from C1 to C2, a student-class is then formed between S1 & S4 @ t2, but between S1 & S3 @ t3.

A combination of a topic & the level @ which it is taught.
It is a component of both a student’s knowledge-requirements & teacher’s service, & can only be required by the former, when offered by the latter.
Synchronised courses
A set of courses, whose respective lessons must be synchronised. The member-courses:
may have different subjects,
must define the same "requiredLessonsPerWeek",
can in aggregate only define either one ideal timeslot-id, or specify precise booking-times the union of which is limited in size by "requiredLessonsPerWeek",
must be offered by teachers whose availabilities intersect.
Since the structure of the timetable is largely independent of precisely which of these member-courses is selected by a student, migration of a student between them (should their initial choice prove hasty), is relatively easy. The use-cases fall into two categories:
Use-caseSynchronised CoursesPurpose
Iso-levelDifferent topics @ the same levelPermits students to select only one of the topics offered, but to migrate easily.
Iso-topicDifferent levels of the same topicPermits students to migrate between ability-streams.

Whilst the flexibility exists to synchronise the scheduling of courses whose topics & level differ, this concept is hard to justify.

A description of an individual’s availability, the proportion of their working-week devoted to teaching, the service they offer to students, & the groups of which they’re members.
The partitions into which each day is similarly divided, each one of which is available for the booking of a lesson or meeting.
Similar to a period, but refers more to a position on the time-axis than to a duration.
Conceptually a cuboid, whose three Cartesian axes are indexed by; day, timeslot-id, & observer-id. The observer-id axis can be any resource-type, depending on the target-audience; there’s no change to the data, they’re merely re-indexed.
The metrics used by the application, to quantify the degree to which a timetable meets the specified problem-parameters. These allow it to select amongst alternative solutions, while searching for the optimum.
Though the semantics of each criterion are hard-coded, each has an associated configurable weight, which allows one to change its significance relative to other timetable-criteria.
cf. lesson-criteria which are used to quantify & therefore select the best amongst alternative lessons.
The component of a subject which is independent of the level @ which it is taught.


Though this explanation descends into esoteric details, & you could skip ahead to the next major section (OPTIONS), some understanding of the wheels & levers behind the curtain is required to fine-tune the executionOptions, when attempting to improve an unsatisfactory solution.
The problem is tackled using several algorithms sequentially, some of which can be turned-off if they prove to be consistently ineffective for the type of problem posed.
Initial Deterministic Timetable
Starting with an empty timetable, whose x-axis identifies each day, whose y-axis identifies each timeslot-id, & whose z-axis identifies a type of resource, the solution starts with the booking of the meetings of groups (since the configuration currently requires these to occur @ predefined times). A solution compatible with the remaining problem-parameters is then constructed progressively, by raster-scanning over the three dimensions of the timetable. On visiting unbooked coordinates, when a "studentBody" is available to be taught, the best lesson, according to a fitness-function (implemented as the weighted mean of a set of lesson-criteria), is booked. The aim of this procedure, is to begin the subsequent random evolution of the timetable from a reasonable starting-point in the solution-space.
Though the weights of the lesson-criteria & timetable-criteria are configurable, the criteria themselves are hard-coded.
This process is deterministic; for a given raster-scan & problem-parameters, it will always produce the same result.
The pattern of the raster-scan dictates the order in which time-slots are visited & potentially booked with a lesson. Because the three axes of the timetable represent different concepts, the order in which they’re visited, results in solutions with different characteristics. Less obviously, the "sense" in which an axis is traversed, also makes a difference; because if the problem-parameters break symmetry, the resulting timetable isn’t merely a mirror-image, with bookings reflected around either the middle day of the week or the middle time-slot of the day. One may specify the specific order & "sense" in which the axes of the timetable should be traversed, but since it can be difficult to guess in advance, which of these will result in the best timetable, normally one merely requests the default behaviour, which is that all permutations of raster-scan be evaluated, & the best, according to a fitness-function (implemented as the weighted mean of a set of timetable-criteria), be selected.
The application can also read an initial solution from the file-system, typically after exporting it from a previous run of the application.

Having created an initial solution, an attempt is made to progressively evolve it, using a variety of evolution-strategies, each of which involves depleting the timetable, by selectively un-booking lessons, & then reconstructing it in various ways to form a population of candidates in which there might be a superior solution. Each of these strategies represents a unary variation-operator, rather than the binary variation-operators (AKA recombination) typically used in genetic algorithms; no attempt is made to combine the desirable characteristics of two solutions whose fitness has been measured by a fitness-function to be high, to produce better offspring, but merely to take a single solution whose fitness has been measured by a fitness-function to be high, & to mutate it in isolation. Each variation operation is equivalent to a step across the solution-space, & by using steps of different magnitude, it is hoped that relatively inaccessible regions within the solution-space can be reached, in order to ensure that given sufficient time this algorithm can reach the optimal solution.
Various depletion-strategies are used; most target some undesirable trait, whilst the remainder attempt to improve some desirable metric. Since some depletion-strategies don’t in isolation liberate sufficient space in the timetable for any beneficial mutation to occur, they can be arbitrarily combined; though this feature is hard-coded rather than configurable. Each depletion-strategy may identify many alternative sets of lessons to unbook, resulting in a population of candidate-timetables, the size of which is limited by its fecundity (configured independently for each evolution-strategy). By zeroing this fecundity, individual evolution-strategies can be disabled.
Each depleted timetable is then reconstructed by visiting all undefined time-slots in a random order, booking lessons selected by either the same deterministic algorithm used to form the initial solution, or randomly from those which are viable.
After constructing the population of candidates in any one generation, the fittest n, according to the weighted mean of the timetable-criteria, are selected; some of which may be less fit than their parent. Each of these children is then used as the parent of a new generation of candidates, from which the fittest (n - 1) are selected, resulting in a spreading tree-structure each successive node of which produces fewer branches. When n decreases to zero, this family-tree withers, & all the last-generation offspring are compared with the original parent to determine whether progress has been made, & consequently whether to re-seed the process using the best child, or whether to terminate the process.
The various depletion-strategies are described below.

Synchronised Course Mutation
This evolution-strategy tackles only synchronised courses, by un-booking all the lessons for courses sharing a "synchronisationId", in turn.
Because a typical student’s timetable is almost fully booked, there are relatively few times remaining which are free to accept a booking, & even fewer which can accept the synchronised bookings required for the members of a set of synchronised courses. Consequently, the only solution typically accessible from this initial state, is the original, & the probability of a beneficial change to the timetable, is therefore low. To improve the probability, a variety of coincidentally synchronised groups of lessons from non-synchronised courses, selected to ensure that all may easily be relocated, are un-booked first, to provide alternative coordinates @ which to book the awkward synchronised lessons of synchronised courses.
Synchronised Course by Day Mutation
This evolution-strategy tackles only synchronised courses, by selecting each synchronised course in turn, & then each day in turn, & un-booking all the corresponding lessons.
As for Synchronised Course Mutation, alternative coordinates for the required lessons are created, to improve the probability of finding a superior solution.
Excess Runlength Mutation
This evolution-strategy focuses on the reduction in one particular undesirable trait in a timetable; excessively long unbroken sessions of identical lessons (& therefore with identical subjects). It finds all instances whose duration exceeds the corresponding course’s value for "minimumConsecutiveLessons". Then for each session in turn; reduces its length by un-booking either of the terminal lessons; along with an arbitrary booking, on any other day, & @ a time to which the original lesson might be relocated.
CAVEAT: because "timetableCriteriaWeights/minimiseRatioOfConsecutiveEqualLessons" is typically lighter than other criterion-weights, the timetable may be improved by this evolution-strategy, whilst paradoxically increasing the number of long unbroken sessions of identical lessons. One could correct this anomaly by increasing the relative weight of this criterion, but that would merely result in a degradation of the solution in some arguably more important respect; the final solution is a compromise.
Homogeneous Student-view Lesson Mutation
The bookings in the timetable, are divided into groups composed from homogeneous lessons; actually, whether two lessons are considered to be identical, depends on the perspective from which they’re viewed, but in this context, it’s from the student-body’s perspective (i.e. the same teacher, teaching the same subject, @ the same location, but to any student-class). Each set of lessons is un-booked & the timetable reconstructed, before proceeding to the next set.
Since each set of identical lessons must be taught by the same teacher in the same location, un-booking all of them, breaks any routine, allowing the timetable to be reconstructed with an alternative routine, & facilitating the transfer of workload between teachers whose services intersect.
Incomplete Course Mutation
This evolution-strategy focuses on the reduction in one particular undesirable trait in a timetable; incompletely booked courses. Each course offered by a teacher requires a precisely defined number of lessons per week. Each student defines the courses they want to study. If the timetable for any one student doesn’t schedule the required number of lessons, then arguably they may as well not attend any of the lessons for that course.
This evolution-strategy mutates the timetable, by un-booking all the lessons, for each such incompletely booked course in turn, & for each student-body in turn. It un-books them even if; they’re booked @ times specifically requested for the course of which they’re a part, to permit alternative locations to be used, or for the student to associate with a different teacher offering a compatible course; the corresponding course defines a non-trivial "minimumConsecutiveLessons", because given that all lessons for the course are un-booked, no inconsistent state remains.
Random Lesson Mutation
Over a specified number of random trials, a number of randomly selected lessons are un-booked from the timetable & the timetable reconstructed.
Lessons which have been booked @ times specifically requested for the course of which they’re a part, are excluded from the random selection, because the probability of a beneficial change to the timetable is too low to justify the effort.
Singleton Student-class Mutation
This evolution-strategy focuses on promotion of one particular desirable trait in a timetable; the temporary merger of student-bodies into student-classes. Lessons whose student-classes have been composed from a single specific student-body, are un-booked from the timetable, which is then reconstructed before proceeding to un-book singleton student-classes for another specific student-body.
Lessons; whose course is synchronised; or whose course defines a non-trivial "minimumConsecutiveLessons"; or which have been booked @ times specifically requested for the course of which they’re a part, are excluded from the selection, because the probability of a beneficial change to the timetable is too low to justify the effort. The former are addressed separately by Synchronised Course Mutation.
Split Session Mutation
This evolution-strategy focuses on the reduction in one particular undesirable trait in a timetable; split sessions of identical lessons (& therefore with identical subjects). It finds all lessons which have been booked more than once in any day, but with some non-zero time-span between, then un-books one contiguous session.
The probability of a beneficial change to sessions which either include a booking @ a time requested by "timeslotRequest/specifically", or whose lessons are for a course which is synchronised, is too low to justify the effort; consequently they’re excluded.
Split sessions are typically only introduced by the "randomConstructor" (see section-5 of the manual pages for this product), though they can also be introduced manually via the command-line option --inputStudentViewTimetable.
Student-body Combination Mutation
This evolution-strategy focuses on the reduction in one particular undesirable trait in a timetable; those which contain lessons for any one course, attended by a student-class, which @ various booking-times has been composed from different combinations of student-bodies. So, if student-bodies A & B both require the same subject, one would probably prefer to consistently teach {A, B} (or failing that, to teach singleton student-classes, composed from each student-body in isolation), rather than various different combinations of student-body; {A}, {B}, {A, B}.
Proliferation of student-body combinations, amongst the lessons booked for a course, can be discouraged by applying a relatively large weighting to "lessonCriteriaWeights/minimiseStudentBodyCombinations" & "timetableCriteriaWeights/minimiseMeanStudentBodyCombinationsPerLesson" (see section-5 of the manual pages for this product), but unless all instances of a specific student-body combination for a course, are un-booked simultaneously, a better weighted mean of the timetable-criteria is unlikely to result, & therefore the resulting timetable probably won’t be selected as the basis of the next generation.
This evolution-strategy mutates the timetable, by finding instances where different student-classes have been booked for any one lesson, then for each student-class in turn, un-books all the corresponding lessons.
Student-view Timetable-for-day Mutation
For each student-body in turn, then for combinations of the specified number of day, remove all bookings. If the number of days is unspecified, then combinations of any number of days will be tried.
This creates the contiguous space required to book courses which specify a non-trivial "minimumConsecutiveLessons", & when the specified number of days exceeds one, the ability to relocate them to another day. Lessons whose course either is synchronised or specifically requests any times on the current day, are excluded because the probability of a beneficial change to the timetable is too low to justify the effort.
Student-view Timetable-for-week Mutation
Similar to "Random Lesson Mutation", except that each student-body is mutated independently.
Synchronous Lesson Mutation
The bookings in the timetable, are divided into synchronous groups of otherwise arbitrary lessons. Each set of lessons is un-booked & the timetable reconstructed, before proceeding to the next set. This is a rather arbitrary procedure, neither specifically addressing an undesirable trait, nor attempting to promote some desirable metric, but it is useful when deployed in combination with depletion-strategies which do address specific problems, which in isolation typically don’t liberate sufficient free space to be effective.
Lessons which have been booked @ times specifically requested for the course of which they’re a part, and lessons forming a consecutive sequence whose minimum length has been configured, are excluded from each group, because the probability of a beneficial change to the timetable is too low to justify the effort.


The time-complexity of the problem is known to be exponential, which is bad news if you’re hoping to find an optimal solution. The problem’s complexity is dependent on the number of locations, student-bodies, teachers, & timeslots-per-day, but because these quantities are related (e.g. one can’t indefinitely increase the number of students without increasing both teacher-hours & the total capacity of the locations in which they’re taught), it’s difficult to quantify the time-complexity more precisely.
Regardless, it’s clear that as these quantities increase, it takes longer to assess the viability of a timetable, & consequently to arrive at an acceptable solution. If the solution takes an unacceptably long time, then perhaps one may reduce it by partitioning the day into fewer longer time-slots, or by coercing the students into a more rigid curriculum requiring fewer larger student-bodies.

The quality of the final solution returned within a given time, depends on the ease with which the evolutionary algorithm can move through the solution-space. It may become grid-locked by; courses which demand a large "minimumConsecutiveLessons", or which reference a "synchronisationId", or which have a "timeslotRequest" (each of which are described in section-5 of the manual pages for this product); teachers who are fully booked; or locations which are fully utilised. So if the final timetable isn’t an acceptable compromise, then removing unnecessary constraints on courses, or providing more resources should improve the result.


Using the command-line option --verbosity=Deafening, the output on stderr, contains the following information:
The weighted mean over all heterogeneous timetable-criteria, of the deterministic timetable resulting from each raster-scan; & the (minimum, maximum)The application has performed a raster-scan over the timetable, booking lessons selected to optimise the value of lesson-criteria. This is repeated using a variety of different rasters, reporting for each the resulting weighted mean over all timetable-criteria. Finally the raster-patterns which were worst & best are reported.
The weighted timetable-criteria of the best deterministic timetableThe individual timetable-criteria used to compose the weighted mean, in the best raster-scan, are reported in the configured order.
The ((mean, standard deviation), (minimum, maximum)) over the best deterministic timetable, of each weighted lesson-criterionThe values of lesson-criteria, by which lessons were selected during the best raster-scan are reported. Their standard deviation, & minimum & maximum value, over the best timetable, identifies their influence on the selection of lessons, & where perhaps individual weights may be fine-tuned. This is the end of the initial deterministic phase, from which random evolution now begins.
The (relative improvement in the weighted mean over all heterogeneous timetable-criteria, the number of generations through which the timetable evolved, the final fecundity, & the weighted timetable-criteria for the selected candidate), for each evolution-strategy/timetable-constructorHere we report four statistics for each evolution/reconstruction strategy; a quantification of the improvement according to the weighted mean over all the timetable-criteria, resulting from this strategy; the number of generations of evolution, since strategies are terminated when improvements cease; the final fecundity of the breeding-program, since this is reduced by a feedback-loop, when the population-diversity ratio of the candidate-population drops beneath a threshold; the individual weighted timetable-criteria, in configuration-order, from which the mean is composed.
The final weighted timetable-criteria, & the improvement, from the best deterministic timetableThe final value of each weighted timetable-criterion is reported, along with the absolute amount by which it was changed during evolution. The order in which they’re reported matches the configured "timetableCriteriaWeights".

Faced with an unacceptable solution, first determine precisely what aspect of the resulting timetable is unacceptable. If this aspect is associated with one of the timetable-criteria, determine whether during the evolutionary process, the value of less important criteria, benefit to the detriment of the criterion of interest. If so, then one can re-configure the weight of criteria, to compensate. The sensitivity of the solution, to the various criterion-weights, is different, & also problem-specific, so start with a small change, perhaps 1%, & check whether the result improves.


fatal error: file read error: "file not found" when accessing ".../dtd/weekdaze.dtd"
The XML configuration-file has referenced a DTD which doesn’t exist; amend its DOCTYPE-declaration to correctly reference the packaged file "dtd/weekdaze.dtd".


Many of these options have default values defined by similarly named fields in the configuration-file; see section-5 of the manual pages for this product.


The configuration can be read either from an XML-file, or from a SQL-database. One can connect either to a MySQL-server either using its native interface defined by libmysqlclient, or to a generic SQL-server using ODBC; the choice may be configured during the build-process. When connecting to a data-server using ODBC, those connection-parameters specified in a .odbc.ini file (Server, Port, User, Password, Database), won’t be available from the command-line.
-i File-path, --inputConfigFilePath=File-path
Read the configuration from the specified XML-file, as an alternative to [--dataServerHost, --dataServerPort, ...].
--dataServerHost=Host-name [""].
Define the host on which to look for the data-server holding the configuration, as an alternative to --inputConfigFilePath.
CAVEAT: this option is unavailable from the command-line when connecting via ODBC.
--dataServerPort=Int [3306]
Define the port on which to attempt connection to the referenced data-server.
CAVEAT: this option is unavailable from the command-line when connecting via ODBC.
Define the user-id with which to log-onto the referenced data-server; cf. --databaseUserId.
CAVEAT: this option is unavailable from the command-line when connecting via ODBC.
Define the password required for authentication with the referenced data-server; cf. --databasePassword.
CAVEAT: this option is unavailable from the command-line when connecting via ODBC.
--databaseName=String [weekdaze]
Define the database on the referenced data-server.
CAVEAT: this option is unavailable from the command-line when connecting via ODBC.
Identify a specific user’s configuration amongst all those in the referenced database; typically one’s email-address, since this is naturally unique; cf. --dataServerUserId.
Define the password for the user’s configuration in the referenced database; cf. --dataServerPassword.
Define the project, amongst those owned by the referenced database user-id, in the referenced database, from which to read the configuration.


Each option overrides a similarly named configuration-field in "executionOptions", where they’re more completely described.
--optimiseLessonCriteriaWeights=’(Int, Float, Float)’ [(0, 1, 0.5)]
-r[Int], --randomSeed[=Int]
This option takes an optional integral argument with which to seed the single pseudo-random number-generator used for all random operations.
In the absence of the whole field, the random-number generator will be seeded unpredictably from the operating-system. In the absence of the integer-argument, 0 will be inferred.

Generic Program-information

These options govern the output of ancillary information. The application will terminate after performing the requested action.

-?, --help
Print this help-text.
Generate a rough Document Type Definition, defining the XML-format of the input-options configuration-file.
CAVEAT: the resulting DTD must be manually amended to identify "IMPLIED", "ID", & "IDREF" attributes.
See the packaged instance dtd/weekdaze.dtd.
Generate a rough Document Type Definition, defining the XML-format of a timetable viewed from the specified perspective.
See the packaged instances; dtd/locationViewTimetable.dtd, dtd/studentViewTimetable.dtd & dtd/teacherViewTimetable.dtd.
-v, --version
Print version-information.


These options govern the presentation of the solution.
Most override a similarly named configuration-field in "outputOptions" & in these cases no description is provided here; see section-5 of the manual pages for this product.
This option takes an optional boolean argument which specifies whether the run-time log is rendered in all "fileFormat"s of type "XHTML" (see section-5 of the manual pages for this product).
The default value, in the absence of this option, is False, but in the absence of only the boolean argument, True will be inferred.
Append a file-path to those defined in "fileFormat" (see section-5 of the manual pages for this product), to receive the resulting timetable, as seen from the perspective of student-bodies & formatted as XML; this can subsequently be referenced using --inputStudentViewTimetable.


0 on success, & non-0 if an error occurs.


weekdaze --randomSeed --inputConfigFilePath=’xml/example_08.xml’ --outputStudentViewTimetable=’/tmp/studentViewTimetable_08.xml’
+RTS -N -RTS >/tmp/timetable_08.xhtml;

cd ’sql/MySQL/’ && cat ’weekdazeCreate.sql’ ’weekdazeTriggers.sql’ | mysql --host=host
--database=’weekdaze’ --user=’root’ --password;

weekdaze --databaseUserId=’example@bogus.tld’ --databaseProjectName=’example_01’
| less;


css/weekdaze.cssThe default Cascading Style-sheet, used when rendering the XHTML-output, which defines; colours, fonts, images, & the spacing used within tables.
dtd/studentViewTimetable.dtdThe formal description of the XML-format for any initial timetable as seen from the perspective of student-bodies.
dtd/weekdaze.dtdThe formal description of the XML-format for the input configuration-file.
images/weekdazeControlFlow.pdfA picture of the application’s control-flow.
images/weekdazeIO.pdfA picture of the application’s I/O.
man/man5/weekdaze.5Section-5 of the manual pages for this product, describing the configuration-file format.
sql/MySQL/*.sqlSQL-scripts used to define the database-structure, optionally including the example timetable-problems.


Written by Dr. Alistair Ward.


Reporting Bugs

Report bugs to "".

Further Development


Copyright © 2013-2015 Dr. Alistair Ward

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 < >.

See Also

Table of Contents