<!-- external parameter entity declaration gets dtd ELEMENTs from WCS -->
<!ENTITY    %   wcsentities     SYSTEM  "WCS.dtd"               >
<!-- parameter entity reference inserts WCS elements into dtd here -->
%wcsentities;

<!-- internal parameter entity declarations to be used as shortcuts -->
<!ENTITY    %   amp2ccd         "wcs"   >
<!ENTITY    %   ccd2pane        "wcs"   >
<!ENTITY    %   ccd2others      "wcs*"  >
  <!--##################################################################-->
  <!--##################################################################-->

  <!ELEMENT
	DetectorSchema  (
		CCDgeom+,
		CCDtype+,
		(
			AmpType,
			%amp2ccd;
		)+,
		CCD+,
		(
			MosaicDesign,
			(
				CCDloc,
				%ccd2pane;
			)+,
			AmpLoc+
		)+,
		(
			AmpWiring,
			AmpWire+
		)+,
		(
			BuiltMosaic,
			(
				CCDpos,
				%ccd2others;
			)+
		)+,
		Controller+
	)
  >
  <!--##################################################################-->
  <!--##################################################################-->
  <!--
  CCDgeomList is a list of all the different geometries of CCD which
  will ever be relevant to any detector mosaic.
  -->
  <!--
  CCDgeomId     a unique identifier for each designed geometry
  CCDgeomName   the unique name for each designed geometry
  -->
  <!ELEMENT     CCDgeom         EMPTY >
    <!ATTLIST   CCDgeom         Id              ID      #REQUIRED >
    <!ATTLIST   CCDgeom         Name            CDATA   #REQUIRED >
    <!ATTLIST   CCDgeom         NumImgPix1      CDATA   #REQUIRED >
    <!ATTLIST   CCDgeom         NumImgPix2      CDATA   #REQUIRED >
    <!ATTLIST   CCDgeom         SizImgPix1      CDATA   #REQUIRED >
    <!ATTLIST   CCDgeom         SizImgPix2      CDATA   #REQUIRED >
  <!--##################################################################-->
  <!--
  CCDtypeList is a list of all the different types of CCD which
  will ever be relevant to any detector mosaic.
  -->
  <!--
  CCDtypeId     a unique identifier for each type of CCD
  CCDtypeName   the unique name for each type of CCD
  -->
  <!ELEMENT     CCDtype         EMPTY >
    <!ATTLIST   CCDtype         Id              ID      #REQUIRED >
    <!ATTLIST   CCDtype         Name            CDATA   #REQUIRED >
  <!--##################################################################-->
  <!--
  AmpTypeList is a list of all the different amplifiers designed onto
  CCDs which will ever be relevant to any detector mosaic.
  -->
  <!--
  AmpTypeId     a unique identifier for each designed amplifier
  AmpTypeName   the unique name for each designed amplifier
  CCDgeomId     the unique identifier of the CCD design hosting this amp
  wcs           the amp2ccd WCS for each amplifier design
  -->
  <!ELEMENT     AmpType         EMPTY >
    <!ATTLIST   AmpType         Id              ID      #REQUIRED >
    <!ATTLIST   AmpType         Name            CDATA   #REQUIRED >
    <!ATTLIST   AmpType         NumPrePix1      CDATA   #REQUIRED >
    <!ATTLIST   AmpType         NumPrePix2      CDATA   #REQUIRED >
    <!ATTLIST   AmpType         CCDgeomId       IDREF   #REQUIRED >
  <!--##################################################################-->
  <!--
  CCDlist is a list of all the individual diced chunks of silicon
  which will ever be relevant to any detector mosaic.
  -->
  <!--
  CCDid         a unique identifier for each diced chunk of silicon
  CCDname       what this diced chunk of silicon is called
  CCDgeomId     a link to information about the design of the CCD

  One might imagine that there would be other information about
  individual CCDs such as defect lists.
  -->
  <!ELEMENT     CCD             EMPTY >
    <!ATTLIST   CCD             Id              ID      #REQUIRED >
    <!ATTLIST   CCD             Name            CDATA   #REQUIRED >
    <!ATTLIST   CCD             CCDgeomId       IDREF   #REQUIRED >
    <!ATTLIST   CCD             CCDtypeId       IDREF   #REQUIRED >

  <!--##################################################################-->
  <!--##################################################################-->

  <!--
  MosaicDesign is the data structure that contains all of the elements
  which are needed to describe the designed layout of a detector
  mosaic.

  Id            a unique identifier for each designed layout of mosaic
  Name          what this design is called to distinguish it from others
  NumAmp        the number of amplifiers from which image pixels can be read
  NumCCD        the number of CCDs (disjoint regions of contiguous pixels)
  -->
  <!ELEMENT     MosaicDesign    EMPTY >
    <!ATTLIST   MosaicDesign    Id              ID      #REQUIRED >
    <!ATTLIST   MosaicDesign    Name            CDATA   #REQUIRED >
    <!ATTLIST   MosaicDesign    NumCCD          CDATA   "1" >
    <!ATTLIST   MosaicDesign    NumAmp          CDATA   "1" >
  <!--##################################################################-->
  <!--
  CCDlocList describes the designed layout of a mosaic.
  A batch of CCDloc entities which share a MosaicDesignId is reusable
  for many constructed mosaics so long as they all use a layout of
  identical CCDs in the same pattern.

  Note that we require a WCS.  This WCS is the PANE WCS.
  In our model of reality there must be a PANE WCS for each CCD in the
  design of the mosaic.
  The PANE WCS can be any coordinate system which makes sense for
  describing the designed layout of the CCDs.
  -->
  <!--
  CCDlocId      a unique ID for each different CCD/mosaic design combination
  CCDlocName    the unique ID for each CCD in the mosaic from ENG drawing
  CCDgeomId     identifies which known CCD types is intended to be used
  wcs           describes the CCD2pane transform for each CCD in the design
  -->
  <!ELEMENT     CCDloc          EMPTY >
    <!ATTLIST   CCDloc          Id              ID      #REQUIRED >
    <!ATTLIST   CCDloc          Name            CDATA   #REQUIRED >
    <!ATTLIST   CCDloc          CCDgeomId       IDREF   #REQUIRED >
    <!ATTLIST   CCDloc          MosaicDesignId  IDREF   #REQUIRED >
  <!--##################################################################-->
  <!--
  AmpLocList describes the designed layout of a mosaic.

  It associates the amplifier numbering scheme on the engineering drawing
  with a particualar amplifier on a particular CCD in the design.

  A batch of AmpLoc entities which share a MosaicDesignId is reusable
  for many constructed mosaics so long as they all use a layout of
  identical CCDs in the same pattern.
  -->
  <!--
  Id            a unique ID for each different Amp/mosaic design combination
  Name          name/number for each CCD in the ENG drawing of the mosaic
  CCDlocId      identifies which CCD in the design this amp is on
  AmpTypeId     identifies which known amp type this one is

  Note that it is possible for this to be inconsistent with the
  CCDlocList and AmpTypeList.  The AmpTypeId here might not agree with
  the AmpTypeIds known to be possible for the CCDgeomId at the
  location of CCDlocId.
  -->
  <!ELEMENT     AmpLoc          EMPTY >
    <!ATTLIST   AmpLoc          Id              ID      #REQUIRED >
    <!ATTLIST   AmpLoc          Name            CDATA   #REQUIRED >
    <!ATTLIST   AmpLoc          AmpTypeId       IDREF   #REQUIRED >
    <!ATTLIST   AmpLoc          CCDlocId        IDREF   #REQUIRED >
  <!--##################################################################-->
  <!--##################################################################-->
  <!--
  AmpWiring describes the design of the cable connections between the
  CCD amplifiers and the CCD crate video inputs.
  It handles the situation that arises because the CCD controller
  video signal input wires can be permuted.

  However, it is likely that there will only be a small subset of
  permutation which are actually ever used, and those permutations
  are likely to be shared by several different constructed mosaics.

  An AmpWiring applies only to a single design of CCD controller.
  DEIMOS will have two of these entities, one design for science CCDs
  and one design for flexure CCDs.

  Note that the DEIMOS hardware routes each amplifier signal through
  numerous connectors between the CCD and CCD controller.
  Permutations of the cables could happen at any of these places, but
  hopefully only the end result is of any archival interest.
  -->
  <!ELEMENT     AmpWiring       EMPTY >
    <!ATTLIST   AmpWiring       Id              ID      #REQUIRED >
    <!ATTLIST   AmpWiring       Name            CDATA   #REQUIRED >
  <!--
  VideoInputEnum sequential numbering of video inputs by CCD controller s/w
  AmpLocId      unique ID for each amplifier in the mosaic from ENG drawing
  -->
  <!ELEMENT     AmpWire         EMPTY >
    <!--
    The usage of VideoInputEnum is as an array index during a fast
    lookup.  For this reason we strongly prefer that its values for
    any given AmpWiring be a sequence of consecutive integers starting
    from 0 or 1.

    In this sense VideoInputEnum and AmpWiringId serve as a compound
    primary key for a database table consisting of AmpWire structs.

    Note that one AmpLocId may occur several times in here because of
    different wirings.
    -->
    <!ATTLIST   AmpWire         VideoInputEnum  CDATA   #REQUIRED >
    <!ATTLIST   AmpWire         AmpLocId        IDREF   #REQUIRED >
    <!ATTLIST   AmpWire         AmpWiringId     IDREF   #REQUIRED >
  <!--##################################################################-->
  <!--##################################################################-->

  <!--
  BuiltMosaic is the master data structure that contains all of the
  elements which are needed to describe a particular instance of
  detector mosaic.

  Id           a unique ID for each constructed mosaic
  Name         what this mosaic is called to distinguish it from others
  MosaicDesignId        the unique ID for the design of this mosaic
  NumCCD       number of CCDs (disjoint regions of contiguous pixels)
  NumAmp       number of amplifiers from which image pixels can be read
  -->
  <!ELEMENT     BuiltMosaic     EMPTY >
    <!ATTLIST   BuiltMosaic     Id              ID      #REQUIRED >
    <!ATTLIST   BuiltMosaic     Name            CDATA   #REQUIRED >
    <!ATTLIST   BuiltMosaic     MosaicDesignId  IDREF   #REQUIRED >
    <!ATTLIST   BuiltMosaic     NumCCD          CDATA   "1" >
    <!ATTLIST   BuiltMosaic     NumAmp          CDATA   "1" >
  <!--##################################################################-->
  <!--
  CCDposList describes a mosaic as-built.
  It refers to a single instance of constructed mosaic and contains
  the data which describe its peculiarities.
  -->
  <!--
  CCDlocId is the unique ID for each CCD in the mosaic from ENG drawing
  CCDid is a unique ID for the silicon of each diced CCD
  wcs describe the CCD2ndet and any other CCD2other coordinate systems
  -->
  <!ELEMENT     CCDpos          EMPTY >
    <!--
    We have a ccd2ndet WCS, which is specific to a BuiltMosaic,
    referring to a CCCloc from a MosaicDesign.  This leaves no way to
    pick out WCSs which are specific to the particular CCDloc for a
    BuiltMosaic, i.e., specific to this CCDpos.
    We could fix this by forcing the WCS to have two owners (in
    effect recognizing that BuiltMosaicId and CCDlocId are a
    compound primary key for the table of CCDpos entries), but
    that would mean that the C code implementation would have to
    admit the possibility of 2 owner pointers within all WCS structures.
    We could fix this by adding a separate primary key to a CCDpos,
    but that introduces undesired opportunity for redundancy.

    In a historical sense a given CCD may occur in more than one
    BuiltMosaic (just not at the same time ++ one BuiltMosaic must
    be deconstructed in order for this to happen.)

    As such, CCDlocId and BuiltMosaicId serve as a compound primary
    key for a database table consisting of CCDpos structs.

    However, in the C realm we need to be able to refer to one
    of these from each ccd2other WCS, so we need a unique Id there.

    Alternatively, we must permit each C WCS structure to have
    two owners, but this is a bit to weird for me right now.

    So, as a compromise, add a redundant primary key (Id) to a CCDpos.
    -->
    <!ATTLIST   CCDpos          Id              ID      #REQUIRED >
    <!ATTLIST   CCDpos          CCDlocId        IDREF   #REQUIRED >
    <!ATTLIST   CCDpos          CCDid           IDREF   #REQUIRED >
    <!ATTLIST   CCDpos          BuiltMosaicId   IDREF   #REQUIRED >
  <!--##################################################################-->
  <!--##################################################################-->
  <!--
  Controller describes the portion of a mosaic which is read out by
  a single CCD controller.  In the case of DEIMOS we have two
  controllers for one mosaic.

  Name          human-readable name for this readout configuration
		unique ID provided by CCD controller in the mosaic IMBEGIN
		is currently defined in the C code by file detconfid.h
  Macro         C preprocessor macro defined to have the MacroValue
  MacroValue    an integer value substituted by the C preprocessor
  BuiltMosaicId the detector mosaic read by this controller
  AmpWiringId   the amplifier wiring scheme used by this controller
  NumAmp        number of amplifiers handled by this controller
  -->
  <!ELEMENT     Controller      EMPTY >
    <!ATTLIST   Controller      Name            CDATA   #REQUIRED >
    <!ATTLIST   Controller      Macro           CDATA   #REQUIRED >
    <!ATTLIST   Controller      MacroValue      CDATA   #REQUIRED >
    <!ATTLIST   Controller      BuiltMosaicId   IDREF   #REQUIRED >
    <!ATTLIST   Controller      AmpWiringId     IDREF   #REQUIRED >
    <!ATTLIST   Controller      NumAmp          CDATA   "1" >

  <!--##################################################################-->
  <!--##################################################################-->