Name

Synopsis

Description

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 requirements for just one arbitrary week are configured, on the assumption that those for other weeks are similar.
• The process is non-interactive; if the final result is inappropriate, then the request must be re-configured to express the missing requirement, & re-started.

  Pros	Whereas an interactive solution may take several weeks of iterative manual adjustments, before the timetable for a moderately sized school, is acceptable, this solution permits sufficiently precise configuration that it can be left alone to complete the job.
  	The configuration encapsulates the description of the whole problem, rather than being defined by free-format notes which must be digested by another user before any attempt is made to alter it. A solution which involves manual intervention may use the user’s unwritten understanding of the problem, making hand-over difficult.
  Cons	One can’t realistically implement a configuration-grammar which is sufficiently general to account for all future requirements; one can merely aim to address the important requirements of the majority of users.
  	Deviation from a regular weekly routine, for example around bank-holidays or examinations, can’t currently be configured.
  	A minor change to the requirements may result in a radically different solution.
  	These objections have been addressed by permitting one to define not just the precise configuration, but also the initial state of the solution, using a timetable exported in XML from a previous run. This permits either manual adjustment of the solution or minor changes to the configuration, while retaining an expectation of a similar solution. This is described pictorially in the packaged file images/weekdazeIO.pdf.

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.

Terminology

Availability

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

Booking

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.

Campus

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.

Course

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.

Day

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.

Depletion-strategy

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.

Evolution-strategy

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.

Facility

An attribute of a location, which can in some way support a course.

Fecundity

The size of the population of candidate-timetables, that the application breeds in any one generation of the evolution of a solution.

Fitness-function

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.

Group

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.

Knowledge-requirements

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.

Lesson

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.

Lesson-criteria

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.

Level

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.

Location

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.

Meeting

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.

Observer

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.

Period

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.

Resource

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.

Routine

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.

Service

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.

Stream

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

Student

An individual, whose requirements are described by the student-body of which they’re a member.

Student-body

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.

Teacher	Student	t1	t2	t3
	body
=======	=======	==	==	==
	S1	C1		C1
T1	S2	C1	C1
	S3		C1	C1

Student-class

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.

Teacher	Student	t1	t2	t3	t4
	class
=======	=======	==	==	==	==
T1	S1		C1	C1
	S2	C1			C1
T2	S3	C2		C2
	S4		C2		C2

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.

Subject

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-case	Synchronised Courses	Purpose
========	====================	=======
Iso-level	Different topics @ the same level	Permits students to select only one of the topics offered, but to migrate easily.
Iso-topic	Different levels of the same topic	Permits 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.

Teacher

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.

Time-slot

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.

Timetable

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.

Timetable-criteria

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.

Topic

The component of a subject which is independent of the level @ which it is taught.

Implementation

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.

Solution-quality

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.

Diagnostics

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.

Trouble-shooting

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

Options

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.

Input

-i File-path, --inputConfigFilePath=File-path

Read the configuration from the specified XML-file, as an alternative to [--dataServerHost, --dataServerPort, ...].

--dataServerHost=Host-name ["127.0.0.1"].

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.

--dataServerUserId=String

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.

--dataServerPassword=String

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.

--databaseUserId=String

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.

--databasePassword=String

Define the password for the user’s configuration in the referenced database; cf. --dataServerPassword.

--databaseProjectName=String

Define the project, amongst those owned by the referenced database user-id, in the referenced database, from which to read the configuration.

Execution

--fecundityDecayRatio=Float

--inputStudentViewTimetable=File-path

--minimumPopulationDiversityRatio=Float

--nInitialScouts=Int

--optimiseLessonCriteriaWeights=’(Int, Float, Float)’ [(0, 1, 0.5)]

--permitTemporaryStudentBodyMerger[=(False|True)]

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

--reduceStudentBodyRegister[=(False|True)]

--removeRedundantCourses[=(False|True)]

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.

--printInputOptionsXMLDTD

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.

--printTimetableXMLDTD=(LocationView|StudentView|TeacherView)

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.

Output

--displayRuntimeLog[=(False|True)]

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.

--nDecimalDigits=Int

--outputConfigFilePath=File-path

--outputStudentViewTimetable=File-path

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.

--verbosity=(Silent|Normal|Verbose|Deafening)

Exit-status

Examples

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

• Note that the random-seed’s default value of 0 has been accepted.
• One of the packaged examples has been referenced (using a relative path which you may need to adjust).
• An XML-version of the solution has been requested, in case it might need to be fed-back as the initial state for a subsequent run.
• The run-time system has been instructed to use an appropriate number of CPU-cores to exploit the parallelism in the implementation.
• The result is returned on standard-output, which has been redirected to a file.

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

• The *nix-specific command to define the structure of a MySQL-database in which to store configuration.
• A MySQL data-server must be running on host (typically localhost).
• A database arbitrarily called "weekdaze" was referenced, & this must exist (though potentially empty) on the data-server.
• The database-password is interactively read from standard-input; assuming one has been defined.

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

• The executable was in this instance built with the Cabal-flag "-fHDBC-mysql" to connect to the data-server using the native MySQL-interface, so data-server connection-parameters had to be specified on the command-line, rather than via a .odbc.ini file.
  I could also have explicitly specified --dataServerHost=’127.0.0.1’ --dataServerPort=’3306’ --dataServerUserId=’root’ --databaseName=’weekdaze’, but these are the defaults (though a less privileged database-user would be preferrable).
  The database-password is interactively read from standard-input.
• Run the specified example from the database. Since the database’s schema has been designed for multi-user use as may be required when running from a web-server, each example in the database belongs to a user (identified by there email-address to guarantee uniqueness); the corresponding email-address is specified.
  Each user in the database own many projects (i.e. example timetable-problems); a specific example is referenced.
• The result on standard-output is paged.

Files

Author

Bugs

Reporting Bugs

Report bugs to "weekdaze@functionalley.com".

Further Development

• The ability to describe the availability of resources, is limited to whole days rather than individual time-slots. This inhibits precise configuration of teachers who’re contracted to be available for only part of some of the days in their working-week, & prevents configuration of locations which are available for only part of some days (perhaps because it’s booked by something outside the domain of the current problem).
• The courses taken by a student, are configured as either "core" or "optional" in the context of that student’s education, & don’t reflect on their inherent worth. This classification merely permits the application to attempt to limit any failures to meet a student’s knowledge-requirements, to those courses personally designated optional. Course-selection is assumed to be overseen by some external authority, to ensure that each student studies an appropriate set.
  One could alternatively qualify a course, with the credit a student would earn from studying it, & require that the set of courses studied, should meet a minimum credit-threshold, which would remove the requirement to oversee course-selection to ensure sufficient academic rigour.
• There’s currently no mechanism for exporting the results in a CSV-format suitable for import into a Management Information System, as may be used by a school to record other data. Since the precise CSV-format is unknown, this requirement should probably be met by some external translator between the XML provided & the required CSV.
• The splitting of a double-lesson over morning break, lunchtime, or a free period, may for some courses be preferable to splitting it with a lesson in a different subject, but this distinction isn’t currently addressed by the available criteria.
• The application has neither any concept of the time-duration between time-slots within any day, nor of the geographic coordinates of any location, so it is unable to assess the feasibility of the journey between locations.
• This application currently only caters for timetables spanning one week (the requirements for all other weeks, are assumed to be identical), but timetables spanning multiple weeks, are required either to facilitate scheduling of courses whose "minimumConsecutiveLessons" exceeds their "requiredLessonsPerWeek". The disadvantage in such multi-week timetables, is the difficulty in faultlessly following such a routine, particularly if the students are young & the timetables for each of the constituent weeks are utterly different, so the most likely requirement is for a fortnightly timetable, where the alternative weeks varying only slightly.
• Desirable time-slots should be evenly allocated amongst similarly specified courses, to avoid those students on one of the courses gaining an unfair advantage over those on the other course.
• The timetable for examination-level students is more critical than those for other students, & should be prioritised.
• Teachers who offer a broad service, may need to allocate their total teaching-time by department.

Copyright

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

See Also

• Home-page: <https://functionalley.com/WeekDaze/weekdaze.html >.
• Source-documentation is generated by Haddock, & is available in the distribution.
• <https://www.haskell.org/haddock/ >.
• man/man5/weekdaze.5.
• <https://www.haskell.org/cabal/ >.

Table of Contents

• Name
• Synopsis
• Description
• Terminology
• Implementation
• Solution-quality
• Diagnostics
• Trouble-shooting
• Options
• Input
• Execution
• Generic Program-information
• Output
• Exit-status
• Examples
• Files
• Author
• Bugs
• Reporting Bugs
• Further Development
• Copyright
• See Also