=====================================================================
***  Limited Data Checking on Tables in Optimization [Dec 2013]   ***
***  Internal Design Notes / Phil, 12-19-2013 (Revision 2)        ***
=====================================================================
http://cadswes2.colorado.edu/~philw/2013/Opt/LimitTableCheck/notes2.txt

The design document (of 11-21-2013) specifies the utilization of existing
(and probably unused) TableSlot column minimum and maximum fields for 
representing "Optimization Min/Max" values.  In discussion, Patrick, Tim 
and Phil agreed that it would probably be better to introduce new fields 
for this special use.  The new Optimization Min/Max values have a use and 
meaning quite different from what those fields are used for on SeriesSlots. 

---------------------------------------------------------------------
(1) Support for 'X', 'Y' and 'Z' variable / table column associations
---------------------------------------------------------------------

The use of particular TableSlot columns for 'X', 'Y' and 'Z' optimization
variables will now be supported at the TableSlot level.  (Furthermore, 
support for optimization value limits by columns will be provided in 
terms of these associations, see next section).

  int  _xColIndex;  // default (-1)
  int  _yColIndex;  // default (-1)
  int  _zColIndex;  // default (-1)

Column support for optimization value limits will be in terms of these
variables (currently provided for only the 'X' and 'Z' variables):

  bool _xColUsesOptMinMax;
  bool _zColUsesOptMinMax;

These new properties are configured for particular TableSlot entities 
on Engineering Object types in Sim::setupPrototype() methods. That method
on Reservoir, for example, currently has column setup calls such as 
these:

  regulatedSpillTable->setUnitType_bycol(LENGTH, 0);
  regulatedSpillTable->setUnitType_bycol(FLOW, 1);

(Note that 'regulatedSpillTable' IS a TableSlotProxy. Its 'operator->' 
yields a mutable TableSlot instance).

In a similar way, the indicies of the optionally designated 'X' 'Y' and 'Z'
columns are supported with these accessors:

TableSlot accessor declarations:

  void setXcolIndex (int, bool supportsOptMinMax=false);
  void setYcolIndex (int);
  void setZcolIndex (int, bool supportsOptMinMax=false);

  int xColIndex() const { return _xColIndex; } // (-1): not supported
  int yColIndex() const { return _yColIndex; } // (-1): not supported
  int zColIndex() const { return _zColIndex; } // (-1): not supported

  bool xColUsesOptMinMax() const { return _xColUsesOptMinMax; }
  bool zColUsesOptMinMax() const { return _zColUsesOptMinMax; }

Here is an example optimization variable and column limit configuration 
for the regulatedSpillTable slot on Reservoir:

  regulatedSpillTable->setXcolIndex(0, true); // supportsOptMinMax
  regulatedSpillTable->setYcolIndex(1); 

------------------------------------------------------------------
(2) "Optimization Min/Max" values on TableSlot Columns
------------------------------------------------------------------

The actual limit (min and max) values for the 'X' and 'Z' optimization 
variables are dynamic data edited by the user.  They are represented 
with these fields:

  double _xColOptMin; 
  double _xColOptMax; 
  double _zColOptMin; 
  double _zColOptMax; 

Accessor methods:

  void setXcolOptLimits (double min, double max);
  void setZcolOptLimits (double min, double max);

  double xColOptMin() const { return _xColOptMin; }
  double xColOptMax() const { return _xColOptMax; }
  double zColOptMin() const { return _zColOptMin; }
  double zColOptMax() const { return _zColOptMax; }

The serialization of these values in model files -- for TableSlot instances
which have any of these values defined -- will be something like this:

  "$s" setXcolOptLimits 30 NaN
  "$s" setZcolOptLimits 100 2000

-----------------------------------------------------------------
(3) Effected Modules/Tasks: Setting up Data Model and GUI Support
-----------------------------------------------------------------

(1) TableSlot data fields (discussed above).
(2) TableSlot, new data field persistence (Tcl serialization).
(3) DMI support for the column optimization min/max values.

(4) GUI: TableSlot config dialog: when the selected column corresponds to 
 the TableSlot's 'X' or 'Z' column, new entry fields for "Optimization Min"
 and "Optimization Max" are provided.

(5) GUI: multiple-slot "Configure Existing Slots" dialog: when all of the 
 slot/column list items are 'X' or 'Z' columns (on TableSlots), a new 
 "Optimization Minimum and Maximum Values" section is enabled and available
 for use. This will be similar to the existing section for "Minimum and 
 Maximum Values".

---