GETTING APPOINNEAL
------------------
The most recent version of appoinneal, 0.7, is available from the 
Sourceforge project page of its parent project drawnneal,
at http://sf.net/projects/drawnneal


WHAT APPOINNEAL DOES
--------------------
Imagine you were to create a schedule for a number of appointments with 
various appointers (maybe companies) and appointees (maybe students on a
career fair).
The day will contain several rounds/slots of appointments and you'll have
a limited number of rooms. Both the companies and the students might have
individual limitations as to when they can be present. Every company can
only speak to one or another limited number of students simultaneously.
They don't like empty slots very much, either. Students can only have one
appointment at a time. While they prefer to have a break or an empty slot
between different appointments, they don't like to wait several slots.

Appoinneal will create and optimize such schedules using a simulated 
annealing algorithm. Schedules are rated by their accordance to the 
criteria named above and slight changes are applied to them, in the 
beginning possibly even making them worse, then slowly but surely 
improving them to something close to a global optimum. Your schedule will
be made in no time (well, almost) and better than any human could ever
make it.


BUILDING APPOINNEAL
-------------------
You just have to compile appoinneal.cpp using a c++ compiler. For typical
GNU/Linux systems you'll probably be using gcc/g++ and a simple

	make

will suffice. If you happen to have a different compiler installed please
see the appropriate documentation for how compile 'appoinneal.cpp' into an
executable 'appoinneal'.


RUNNING APPOINNEAL
-----------------
A simple

	./appoinnneal appointee-file appointer-file

will start appoinneal in interactive mode. You will be asked a couple of
things about your plannings. You need to enter

 * the number of subsequent appointments (slot) you'll have
 * the number of rooms you have
 * which of your slots lie after a break in your schedule 
   (so nobody's in a rush if they have appointments before AND after)


APPOINNEAL CONFIGURATION FILES
------------------------------
You will have to give information about your appointees (patients, students, 
...) and appointers (counselors, company officials, teachers, ...) in two
text files. Look at the *-example.tab files in this directory while you
familiarize yourself with the format.

Appointee configuration file
----------------------------
The appointee configuration file just contains
 * one string (no spaces) in the first line; just keep the comment in the 
   example file, since it'll remind you of the format
 * one line for each appointee, which contains
   ID NameWithoutSpaces EarliestPossible LatestPossible NumberOfRoomsRequired
   where ID should run from 0,1,... in the correct order, the name must not 
   contain spaces, EarliestPossible is an integer giving the first slot
   (1,2,...) the appointee can accept (0 if no problem with the first slot)
   and LatestPossible is the same story for the last slot he/she can accept;
   NumberOfRoomsRequired is the number of rooms an appointment with this
   appointee requires. For most people, this should be 1 ;) -- however,
   it is sometimes useful to set it to zero if there are real or virtual
   appointments that do not require an extra room.

Appointer configuration file
----------------------------
The appointer configuration files contains all information about the 
appointers themselves and the appointments they have. It has
 * one string (no spaces) in the first line; just keep the comment in the 
   example file, since it'll remind you of the format
 * one line for each appointer, which contains
   ID NameWithoutSpaces NumberOfApp ID1 ID2 ... Earliest Latest Cap Dur
   where ID should run from 0,1,... in the correct order, the name must not 
   contain spaces, NumberOfApp is the number of appointees this appointer
   has and is followed by a space separated list of their IDs, Earliest is an
   integer giving the first slot (1,2,...) the appointer can accept (0 if no
   problem with the first slot) and Latest is the same story for the last
   slot they can accept, Cap is the number of parallel appointments this
   appointer can accomodate (usually 1) and Dur is the duration (in numbers 
   of slots) an appointment with this appointer takes (usually 1).

Example files
-------------
Much can be done by using these options smartly. Look at the example config
files included to find how presentations given by the appointers (see 
appointees P* with fixed schedule) or meetings of appointers in a common slot
(see appointees S* in slot 5) can be modelled.


RUNNING APPOINNNEAL SMARTLY
---------------------------
As you might have noticed running appoinneal in interactive mode does not
exactly meet today's standard of user interfaces. So that's the reason I
recommend the following, even more low level method of entering your data,
which can also be used to run many instances of appoinneal as a script.

Just run
echo "12 19 3 5 0 1" | ./appoinneal appointers-example.tab appointees-example.tab
to create an appointment schedule for the (fake) appointers and appointees
listed in the example files with 6 slots with 10 rooms and breaks before 
slots 3 and 5. The random seed is 1 and can be changed to produce different
optimized schedules (you should always try a few different ones).


HACKING APPOINNEAL
------------------
You may change some of the internal parameters of appoinneal by editing the
source file and recompiling (with a simple 'make'). This is less difficult
than it may sound and it might help you create even better draws.

i) annealing parameters
You can change the parameters thot (initial temperature), tfactor (factor
by which temperature is multiplied with each step, should be lower than 1.0)
or freeze_timeout (number of unsuccessful steps before draw is considered 
optimized) to change the annealing process.

ii) rating parameters
How the different criteria mentioned are judged in comparison depends 
essentially on the penalties for deviation from the ideal configuration a
draw gets. You can change either of the 'malus' factors and see what happens.

iii) rating procedure
Deeper changes to the rating procedure can be made by editing the function 
'double rateDraw'. Take care :)


COPYING AND DISTRIBUTING APPOINNEAL, LEGAL STUFF
------------------------------------------------
This program is free software; you can redistribute it and/or modify it 
under the terms of the GNU General Public License as published by the Free
Software Foundation; either version 2, 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.


CONTACTING THE AUTHOR
---------------------
Appoinneal has been written an is maintained by Daniel Gruen . 
Don't hesitate to contact me to send comments, bug reports, wishlists or even money ;)
If you need help with your schedule, let me know.