(******************************************************************************
 ** PLS.sml
 ** sml
 ** 
 ** Umut A. Acar
 **
 ** The signature for piecewise-linear system (PLS).
 ******************************************************************************)
 
signature PLS = 
sig

  type pls 



  structure Vertex:  VERTEX 
  type vertex = Vertex.vertex

  structure PolytopeId : ID
  type polytopeId = PolytopeId.id
  type polytope


  structure PolytopeIdTable : TABLE where type index = polytopeId
    
  structure LabelTable: TABLE where type index = string

  
  (******************************************************************************
   **** Exceptions
   ******************************************************************************)

  exception UndefinedLabel   (* Found an undefined label in the input. *)
  exception UnexpectedEndOfFile (* Encountered an unexpected eof in input. *)
  
  (******************************************************************************
   **** Constructors 
   ******************************************************************************)
    
  (* Construct a PLS from a data stream. *)
  (*  val fromStream: -> pls *)
    
  (* Construct a PLS from a file. *)
  val fromFile: string -> pls * 
                          Vertex.vertex PolytopeIdTable.table  *
			  polytopeId LabelTable.table
			  
  (******************************************************************************
   **** Operations on polytopes
   ******************************************************************************)

  (******************************************************************************
   ** dim:  the dimension of a polytope
   ** Input:  a polytope.
   ** Output: the dimension of the polytope. 
   ******************************************************************************)
  val polytopeDim: polytope -> int
  val polytopeLabel: polytope -> string
    
  (******************************************************************************
   ** printPoltope: print the label, the id and the dimension of a polytope. 
   ** Input: a polytope
   ** Output: unit
   ******************************************************************************)
  val printPolytope: polytope -> unit

  (******************************************************************************
   ** printPls 
   ** Input: a pls
   ** Output: none
   ******************************************************************************)
  val printPls: pls -> unit

  (******************************************************************************
   **** Access operations 
   *****************************************************************************)
  val plsTable: pls -> polytope PolytopeIdTable.table

  (******************************************************************************
   ** find: Find a polytope in a pls. 
   ** Input: A polytope id. 
   ** Output:  The polytope if found NONE otherwise. 
   ******************************************************************************)    
  val find: pls *  polytopeId -> polytope option

 
  (******************************************************************************
   **** Structural update operations
   ******************************************************************************)
   
   (******************************************************************************
    ** add: add a polytope.
    ** Input: a pls and the dimension of the new polytope. 
    ** Output: the pls and the id of the new polytope. 
    ******************************************************************************)
   val add: pls * int -> pls * polytopeId

   (******************************************************************************
    ** remove: remove a polytope.
    ** Input: a pls and the id of the polytope to remove
    ** Output: the pls.
    ******************************************************************************)
   val rem: pls * polytopeId -> pls

   (******************************************************************************
    ** addBoundary:  add a boundary edge. 
    ** Input: a pls and a directed edge in that order
    ** Output: the pls.
    ******************************************************************************)
   val addBoundary: pls * polytopeId * polytopeId -> pls

   (******************************************************************************
    ** addBoundary:  add an internal edge. 
    ** Input: a pls and a directed edge in that order
    ** Output: the pls.
    ******************************************************************************)
   val addInternal: pls * polytopeId * polytopeId -> pls

  
  (******************************************************************************
   ******************************************************************************
   ** Operations with constraints
   ******************************************************************************
   ******************************************************************************)

  (******************************************************************************
   ** boundary: the boundary of a polytope. 
   ** Input: a pls and the id of a polytope. 
   ** Output: The polytopes in the boundary. 
   ******************************************************************************)
  val boundary: pls * polytopeId -> polytopeId Sequence.seq 

  (******************************************************************************
   ** internal: the internal constraints of a polytope. 
   ** Input: a pls and the id of a polytope. 
   ** Output: The polytopes internal to the polytope. 
   ******************************************************************************) 
  val internal:  pls * polytopeId ->  polytopeId Sequence.seq

 
  (******************************************************************************
   ** constrained: the polytopes that a polytope constrains.
   ** Input: a pls and the id of a polytope. 
   ** Output: The constrainted polytopes. 
   ******************************************************************************) 
  val constrained: pls * polytopeId -> polytopeId Sequence.seq

  


end