The KHE Timetabling Suite
=========================

Jeffrey H. Kingston
jeff@it.usyd.edu.au
http://jeffreykingston.id.au

This is the KHE timetabling suite, containing C source code for
several timetabling programs, and their documentation.

"KHE" originally stood for "Kingston's High school timetabling engine",
but now it is the name for all of Jeff Kingston's timetabling code as
packaged here, including things other than high school timetabling.


License
-------

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 3, 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 (file gpl.txt); if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston MA 02111-1307 USA


KHE Version history
-------------------

I've only kept track of version history from Version 2.3:

    Version            Date released       Notes
    ------------------------------------------------------------------
    KHE Version 2.3    20 April 2019
    KHE Version 2.4    20 January 2020
    KHE Version 2.5    7 February 2020    2.4 + small bug fix only
    KHE Version 2.6    14 March 2021      New nurse rostering solvers  
    KHE Version 2.7    31 March 2022      More on nurse rostering
    KHE Version 2.8    16 June 2023       More on nurse rostering
    KHE Version 2.9    21 December 2023   Many improvements and bug fixes
    KHE Version 2.10   15 February 2024   Bug fixes; a holding release
    KHE Version 2.11   7 March 2024       A stable release
    KHE Version 2.12   20 April 2024      bug fixes
    KHE Version 2.13   14 December 2024   Bug fixes, improved mtasks
    KHE Version 2.14   4 December 2025    Bug fixes, nurse rostering
    ------------------------------------------------------------------


Brief overview of the code
--------------------------

KHE is separated into the two parts:  the platform, which does the
basic operations including reading and writing XML and incremental
evaluation of solutions, and the solvers, which are built on the
platform.  Programs that don't use the solvers can omit them altogether.

Your compiler command line should look like this:

    gcc -Ikhe/src_platform ... khe/src_platform/khe_platform.a

with #include "khe_platform.h" in your source files.  Or if you are
using KHE's solvers as well as the platform, your command line is

    gcc -Ikhe/src_platform -Ikhe/src_solvers ...	\
      khe/src_solvers/khe_solvers.a khe/src_platform/khe_platform.a

with #include "khe_solvers.h" in your source files.  In this case you
don't need #include "khe_platform.h" in your source files, because
"khe_solvers.h" has it.

Multiple object (.o) files have been replaced by single archive (.a)
files.  This is clearer and reduces the size of the executables by
allowing uncalled functions to be culled when the archive files are
linked.  As always with archive files, the order they appear on your
command line matters.  They go at the end, and khe_platform.a must
appear after khe_solvers.a when both are present.

The KHE main program has also been separated out, which should
avoid annoying error messages about multiple main programs.

Files in this directory
-----------------------

  README

      This file.

  gpl.txt

      A copy of the Gnu Public License, under which this software
      is distributed.

  makefile

      A makefile for compiling all of KHE.  Running "make" compiles
      everything and copies three executables (khe, hseval.cgi, and
      nrconv) to places you specify.  Before you do that you need to
      specify the three places, by changing the value of the first
      symbol in each of these files:

         src_khe/makefile
	 src_hseval/makefile
	 src_nrconv/makefile

      If you only want (say) khe you can do "cd src_khe; make", again
      after setting the location of the executable.
      
  src_platform

      A directory containing the C source code for the basic module
      of the system, called KHE or "the platform".  It supports the
      creation of XHSTT/XESTT archives, including reading and writing
      XML files, and update of solutions when solving.  Its interface
      is defined in "src_platform/khe_platform.h".  It compiles to
      archive file "src_platform/khe_platform.a", not to an executable.

  src_solvers

      A directory containing the C source code for Jeff Kingston's
      solvers.  It uses the platform and was once bundled with it.
      Its interface is defined in "src_solvers/khe_solvers.h", which
      #includes "khe_platform.h".  It compiles to archive file
      "khe_solvers.a", not to an executable.  The archive file does
      not include "khe_platform.a", so a compile which includes
      "khe_solvers.a" must also include "khe_platform.a".  As usual
      with archives, they must appear in reverse dependency order:
      "khe_platform.a" must come later than "khe_solvers.a".

  src_khe

      A directory containing the C source code for a main program
      that calls Jeff Kingston's solvers.  When compiled it produces
      executable file "src_khe/khe", incorporating "khe_platform.a",
      "khe_solvers.a", and the main program.  Running "make" here or
      in "src_khe" compiles this executable and copies it to a place
      of your choice.  Then run "khe -h" for usage information.

  src_hseval

      A directory containing the C source code for the HSEval program,
      which when run with no command-line arguments functions as a web
      server implementing the HSEval web site, but which can also be
      run from the command line to produce tables (e.g. in LaTeX)
      showing evaluations of solutions.  It compiles to executable
      file "src_hseval/hseval.cgi", incorporating "khe_platform.a"
      and its own object files.  Running "make" here or in "src_hseval"
      compiles this executable and copies it to a place of your choice.
      Then run "hseval.cgi -h" for usage information.

      It can be handy to copy "hseval.cgi" into your own cgi-bin
      directory and access it via "localhost".  I do it myself.
      But please think twice before making HSEval available as a
      public web service, like the one at jeffreykingston.id.au.
      We don't want conflicting evaluators out there on the web.

  src_nrc

      A directory containing the C source code for the NRC nurse
      rostering platform.  This defines nurse rostering instances
      and solutions in a familiar model, and writes them in XESTT
      format.  Its interface is defined in file "src_nrc/nrc.h".
      It compiles to archive file "src_nrc/nrc.a", not to an
      executable.  Any compile which includes "nrc.a" must also
      include "khe_platform.a".

  src_nrconv

      A directory containing the C source code for the NRConv nurse
      rostering converter, which converts instances and solutions of
      nurse rostering problems in several formats to XESTT format.  It
      compiles to executable file "src_nrconv/nrconv", incorporating
      "khe_platform.a", "nrc.a", and some object files of its own.
      Running "make" here or in "src_nrconv" compiles this executable
      and copies it to a place of your choice.  Run "nrconv -h" for
      usage information.

  doc_khe

      A directory containing the Lout source of the documentation
      for the KHE platform and solvers.  You can get the PDF of
      this from http://jeffreykingston.id.au/khe/.

  doc_nrconv

      A directory containing the Lout source of the documentation
      for the NRC and NRConv parts of KHE.  You can get the PDF of
      this from http://jeffreykingston.id.au/khe/.

  diary

      A directory containing my diaries (one for each calendar year)
      recording progress on the KHE project, things to do, etc.
