/**
   module file for all phases CORBA objects.  All properties are extensive,
   i.e. enthalpy, volume etc. are total for n moles of material.
   @todo out of bounds exception, state not set
   $Id: phases.idl,v 1.31 2007/09/19 21:26:45 kress Exp $
   @author Victor Kress
   $Revision: 1.31 $

*/
#include <orb.idl>
#include "common.idl"

module phases {

  //////////////////////////////////////////////////////////////////////////
  /// structure to hold status of phase instance and (optionally) client data
  struct PhaseStatus {
    /// time dPhase object created 
    long long timeCreated;
    /// last access time for dPhase object
    long long timeLastAccessed;
    /// current status of dPhase object
    string status;
    /// stringified IOR
    string ior;
    /// process id converted to long
    long pid;
    /// unique identifier for rock instance
    long identifier;
    /// client data structure
    common::ClientData client;
  };

  ///////////////////////////////////////////////////////////////////////////
  /// state structure for solutions
  struct PhaseState {
    /// temperature in Kelvins
    double tk;
    /// pressure in Pascals
    double pa;
    /// list of component moles
    CORBA::DoubleSeq comps;    
  };

  ////////////////////////////////////////////////////////////////////////
  /// dPhase
  interface dPhase {
    /**
       valid error types.
       INVALID: input data not valid
       BOUNDS: input data out of bounds for this phase
       STATE: Phase is in invalid state for requested calculation
       CALCULATION: internal calculation error
    */
    enum errorType {INVALID,BOUNDS,STATE,CALCULATION,UNKTYPE};
    /**
       valid error severities
       WARNING: Phase remains in usable state.  Retry with valid data.
       SERIOUS: Phase may not be in usable state. Future calcs suspect.
       FATAL: All hell has broken loose.  Start over.
    */
    enum errorSeverity {WARNING,SERIOUS,FATAL,UNKSEV};
    /// exception structure
    exception PhaseError {
      /// type of error
      errorType type;
      /// severity of error
      errorSeverity severity;
      /// string to hold caller name
      string caller;
      /// string to hold error description
      string description;
    };
     /// single call set of phase state. Members can be set independently
    void setState(in PhaseState ss) raises(PhaseError);
    /// set temperature in Kelvins
    void setTk(in double tk) raises(PhaseError);
    /// set pressure in Pascal
    void setPa(in double pa) raises(PhaseError);
    /// set total number of moles
    void setMoles(in double m) raises(PhaseError);
    /// set total weight in grams
    void setMass(in double w) raises(PhaseError);
    /// set component moles
    void setComps(in CORBA::DoubleSeq c) raises(PhaseError);
    /// set generic component (1-2 element) grams
    void setGenericWts(in CORBA::DoubleSeq c) raises(PhaseError);

    /// get phase name
    string getName();
    /// get component name for component i
    string getCompName(in short i);
    /// get list of component names
    CORBA::StringSeq getCompNames();
    /// get list of component formulas
    CORBA::StringSeq getCompFormulas();
    /// get list of relevant generic (1-2 element) component formulas
    CORBA::StringSeq getGenericCompFormulas();
    /// get chemical formula for phase
    string getFormula();
    /// get molecular weight (gm/mol)
    double getMW();
    /// get number of components
    unsigned short getNcomp();
    /// get number of generic (1-2 element) components
    unsigned short getGenericNcomp();

    /// get state structure for phase
    PhaseState getState();
    /// get temperature in Kelvins
    double getTk();
    /// get pressure in Pascal
    double getPa();
    /// get total moles
    double getMoles();
    /// get weight in grams
    double getMass();
    /// get component moles
    CORBA::DoubleSeq getComps();
    /// get generic component (1-2 element) grams
    CORBA::DoubleSeq getGenericWts();

    /// get Gibbs free energy in Joules
    double getG();
    /// get enthalpy in Joules
    double getH();
    /// get entropy in Joules/Kelvin
    double getS();
    /// get constant-pressure heat capacity in Joules/Kelvin
    double getCp();
    /// get volume in cubic meters
    double getV();
    /// get component potentials in Joules/mole
    CORBA::DoubleSeq getMu();

    /// update internal state. For most phases this is not used at all.
    /// It is present for synchronization of calculations in many-phase
    /// client implementations.  Single-direction call does not block
    /// client. If you need to ask, you probably don't need it.
    void update() raises(PhaseError);
    /// get time of last object access (seconds from local reference)
    long long getLastAccessTime();
    /// returns 1 if there are still active references to object
    unsigned short isActive();
    /// deactivate and remove dSolution object
    void remove();
  };

  ////////////////////////////////////////////////////////////////////////
  /// Server factory for spawning dPhase objects
  interface PhaseFactory {

    /// returns sequence of available phase names
    CORBA::StringSeq getPhaseNames();

    /// spawns and returns phase object by name
    dPhase spawnPhase(in string phaseName,in common::ClientData cd);

    /// same as spawnPhase() but phase launched in child process
    dPhase spawnPhaseProcess(in string phaseName,in common::ClientData cd);
  };

  /// simple test interface for debugging. Echoes input.
  interface Echo {
    string echoString(in string mesq);
  };

  ///////////////////////////////////////////////////////////////////////
  /// Manager object for monitoring and managing dPhase objects
  interface PhaseManager {
    typedef sequence<PhaseStatus> StatSeq;

    /// returns current grace period in seconds
    short getGracePeriod();
    /// sets grace period in seconds
    void setGracePeriod(in short sec);

    /// registers new phase with manager object
    void add(in dPhase dpv,in long pid,in common::ClientData cd);

    /// returns number of active phases
    short getNphase();

    /// returns sequence of PhaseStatus objects
    StatSeq getStatus();

    /// returns current processor load in percent.
    /// @param p processor number. -1 returns average.
    double getLoad(in short p);

    /// returns free memory available in bytes
    long getFreeMemory();

    /// returns memory used in CORBA processes
    long getAllocatedMemory();

    /// examine all spawned phases and prune those that are obsolete
    void update();
    
    /// induce dPhase to self-destruct in orderly manner
    /// @param i unique server id of dPhase to be killed.
    void remove(in long i);

    /// induce recalictrant or locked dPhase to self-destruct
    /// @param i unique server id of dPhase to be killed.
    void apoptosize(in long i);
  };

};