@Chapter
    @Title { Introduction }
    @Tag { nrc_intro }
@Begin
This document describes NRConv, a program for converting
instances of nurse rostering problems from various existing
formats into a common XML format called XESTT.
@PP
In NRConv's view of the world, there are three kinds of
models.  They all model instances of nurse rostering problems,
and solutions to those instances, but they do it in different ways.
@PP
A @I { source model } is one of the models (concretely, file
formats) that NRConv converts.  At present NRConv can convert
four source models:  the Curtois `original instances' model,
the first international nurse rostering competition model,
the second international nurse rostering competition model,
and the Curtois-Qu 2014 model.  However, NRConv is designed
to minimize the work needed to add new source models.
@PP
# There is more to an NRConv  source model than just a format.
# There are @I { instance source models }, which define the
# format of source instances but also the contents of the
# metadata fields of converted instances.  And there are
# @I { solution source models }, which define the format
# of source solutions, and the names and metadata fields of
# the solution groups they give rise to, as well as defining
# how the instance that a solution is for is determined, and
# how the solution group that the solution goes into is determined.
# @PP
The @I { intermediate model }, also called the @I { NRC model }
after the software platform that implements it, represents the
concepts underlying source models, including metadata, days,
shifts, cover, patterns, and so on.  If something in some source
model is not in the intermediate model, then either the intermediate
model needs to be extended, or else the source model is beyond the
scope of NRConv.  The intermediate model also includes its own
versions of the XESTT concepts of archive (a set of instances
and solution groups) and solution group (a set of solutions).
There is no file format for the intermediate model; its values
are held only in memory.
@PP
Finally, there is the @I { target model }, XESTT.  Its main concepts
are archives, instances, times, resources, events, constraints,
solution groups, and solutions.  It lies in memory, in objects
defined by the KHE platform which implements XESTT, and it also
has a file format version.  The user of NRConv does not need to
be a KHE expert, because NRConv uses it only behind the scenes.
@PP
There are two parts to NRConv, a @I { platform } called NRC and
the @I { converters }.  NRC defines many types and functions,
culminating in type @C { NRC_ARCHIVE }, representing a set of
instances and a set of solution groups in the intermediate
model, and function @C { NrcArchiveWrite }, which converts an
@C { NRC_ARCHIVE } object into a target model archive and writes
it by calling @C { KheArchiveWrite }.
@PP
Each converter is a function which reads instance and solution files
in one source model and converts what it reads into intermediate
model objects.  Since the intermediate model understands all the
source model concepts, this conversion should be straightforward, a
matter of reading the source model file and generating calls to the
NRC platform.  After this is done, the converter completes the
conversion to the target model by calling @C { NrcArchiveWrite }.
@PP
NRConv is written in C, and is packaged with the author's KHE
distribution, which is a gzipped tar file.  To install it you
need to get that file, unzip it, untar it, modify @C { makefile }
slightly to say where you want the final @C { nrconv } binary to
be copied to, and run @C { make }.  After compiling, execute the
@C { nrconv } binary with no command line options to get a comprehensive
usage message.
@End @Chapter
