README
======

Basic Concepts
~~~~~~~~~~~~~~

Model
-----

The internal data model must be as general as possible. This will put fewer
future limits on the views, GUIs and sources. Also this simplifies exporting
the various problems to an automatic solvers (which should accept input in a
general form).

Designing a general representation of time tabling problems as objects is not
trivial, especially with regard to constraints. It is closely linked to the
design problem a common data file representation for timetabling problems. There
have been two attempts at this TTML [1] which is a MathML [2] derivative, and
STTL [3].

Fortunately XML can be thought if as a hierarchy of objects, therefore object
equivalents of TTML XML stanzas are a good first approximation. This is the
logical choice as TTML will probably be the method of communicating timetabling
problems to automatic solvers.

To fillful the GUI spec that the GUI must be an interactive timetabling solving environment, the objects of this data model will be able to perform calculations
on themselves. i.e. a constraint object which can tell if it is valid or not.

GUI
---

A highly specialized GUI for each view. To keep things general and allow
different graphical libraries, the library specific code will be separated from
library independent code.

This higher level interface to the timetabler will allow control by a simple
script, simplifying the writing of functional tests.

Views
-----

A view is a way of looking at a data model that only has relevance to a
specific type of problem. Specific types of problems are simplifications of the
very general data model.

For example (applicable to the class scheduling view with no guarantee of
correctness:)
* All class scheduling view problems have Subject/Class pairs as variables.
* Class scheduling problems have 3 domains, Time, Classrooms and Teachers.
* noresclash is an implicit constraint (i.e. all problems of this type have
  this)

These simplifications can greatly simplify the tasks of importing data from
various sources and creating a simple, problem optimized GUI.

Sources
-------

A source is somewhere timetabling data can come from (apart from the gui) and
go to that is specifiable by a URL. Different parts of a timetabling problem
are importable and exportable to different sources. e.g. It is possible to
import lists of variables and domain members from a SchoolTool server, but no
the other way around.

It is also expected that not all sources will support all views.

File Hirearchy
~~~~~~~~~~~~~~

README              - This file
comments            - Questions and answers on the design
src/                - The source code
    timetabling/        - The timetabling module
        __init__.py
        interfaces.py       - Main interfaces
        model.py            - Data object model
        gui/                - A GUI module
            __init__.py
            interfaces.py       - Common GUI interfaces
            main.py             - The meta GUI
            class_scheduling.py - Specific GUI to class scheduling
        sources/            - A module for communication with sources
            __init__.py
            test.py             - Import and export to a text file URL
            schooltool.py       - Import and export to a schooltool server
            ttml.py             - Import and export to a ttml file URL
        views/              - A module for gui independent view specific code
            __init__.py