Updated dok for binaryMDPWriter. Closes #16.

R/binaryMDPWriter.R

@@ -5,22 +5,49 @@
 #' Binary files are efficent for storing large models. Compared to the HMP (XML)
 #' format the binary files use less storage space and loading the model is faster.
 #'
-#' The functions which can be used are: \itemize{
-#'   \item{\code{setWeights(labels, ...)}: }{Set the labels of the weights used in the actions.
-#'      \code{labels} is a vector of label names, \code{...} are not used.
-#'      The function must be called before starting building the model.}
+#' The functions which can be used are: 
+#' \itemize{
+#'   \item{\code{setWeights(labels, ...)}: }{Set the labels of the weights used in the actions. 
+#'   \code{labels} is a vector of label names, \code{...} are not used. The function must be called
+#'   before starting building the model.}
+#'   
 #'   \item{\code{process()}: }{Starts a (sub)process.}
+#'   
 #'   \item{\code{endProcess()}: }{Ends a (sub)process.}
-#'   \item{\code{stage(label=NULL)}: }{Starts a stage. Currently \code{label} are not used in the binary format.}
+#'   
+#'   \item{\code{stage(label=NULL)}: }{Starts a stage. Currently \code{label} are not used in the
+#'   binary format.}
+#'   
 #'   \item{\code{endStage()}: }{Ends a (sub)process.}
-#'   \item{\code{state(label=NULL)}: }{Starts a state. Returns (invisible) the states index number sIdx.}
+#'   
+#'   \item{\code{state(label=NULL)}: }{Starts a state. Returns (invisible) the states index number
+#'   sIdx.}
+#'   
 #'   \item{\code{endState()}: }{Ends a stage.}
-#'   \item{\code{action(label=NULL, weights, prob, ...)}: }{Starts an action. Parameter \code{weights} must be a vector of action weights,
-#'      \code{prob} must contain triples of (scope,idx,pr) (see the description of actionIdx.bin below), \code{...} is currently not used.}
+#'   
+#'   \item{\code{action(label=NULL, weights, prob, ...)}: }{Starts an action. Parameter
+#'   \code{weights} must be a vector of action weights, \code{prob} must contain triples of
+#'   (scope,idx,pr) (see the description of actionIdx.bin below), \code{...} is currently not used.}
+#'   
 #'   \item{\code{endAction()}: }{Ends an action.}
-#'   \item{\code{closeWriter()}: }{Close the writer. Must be called when the model description has finished.}}
+#'   
+#'   \item{\code{includeProcess(prefix, label=NULL, weights, prob, termStates)}: }{Include an 
+#'   external process. External processes will only be loaded in memory when needed. That is,
+#'   external processes is usefull when considering large models and have problems with memory.
+#'   Parameter \code{prefix} is the prefix of the external process. The next parameters specify the
+#'   child jump action to the process, i.e. \code{weights} must be a vector of action weights,
+#'   \code{prob} must contain triples of (scope,idx,pr) (see the description of actionIdx.bin
+#'   below), Finally \code{termStates} must specify the number of states at the last stage in the
+#'   external process. Note that inside an \code{includeProcess ... endIncludeProcess} you must
+#'   specify the father jump actions of the last stage in the external process. An external process
+#'   is represented using its first and last stage, together with its jump actions.}
+#'   
+#'   \item{\code{endIncludeProcess()}: }{Ends an includeProcess.}
+#'   
+#'   \item{\code{closeWriter()}: }{Close the writer. Must be called when the model description has
+#'   finished.}}
 #'
-#' Seven binary files are created using the following format:\itemize{
+#' Eight binary files are created using the following format:\itemize{
 #' \item{stateIdx.bin: }{File of integers containing the indexes defining all states in the format
 #' "n0 s0 -1 n0 s0 a0 n1 s1 -1 n0 s0 a0 n1 s1 a1 n2 s2 -1 n0 s0 ...". Here -1 is
 #' used to indicate that a new state is considered (new line).}
@@ -52,7 +79,11 @@
 #' indicate that a new action is considered (new line).} \item{externalProcesses.bin: }{File of
 #' characters containing links to the external processes. The format is "n0 s0 prefix -1 n0 s0 a0 n1
 #' s1 prefix -1 ...". Here -1 is used to indicate that a new external process is considered for the
-#' stage defined by the indexes.}}
+#' stage defined by the indexes.}
+#' \item{externalProcesses.bin: }{File of characters in the format "stageStr prefix stageStr prefix
+#' ..." Here stageStr corresponds to the index (e.g. n0 s0 a0 n1) of the stage corresponding to the
+#' first stage in the external process and prefix to the prefix of the external process. Note no
+#' delimiter is used.}}
 #'
 #' @param prefix A character string with the prefix added to \code{binNames}.
 #' @param binNames A character vector giving the names of the binary files storing the model.
@@ -158,7 +189,7 @@ binaryMDPWriter<-function(prefix="", binNames=c("stateIdx.bin","stateIdxLbl.bin"
 		invisible(NULL)
 	}
 
-   includeProcess<-function(prefix, label, weights, prob, termStates){     # prop contain tripeles (scope,idx,prob) - Here all scope must be 2!!
+   includeProcess<-function(prefix, label=NULL, weights, prob, termStates){     # prop contain tripeles (scope,idx,prob) - Here all scope must be 2!!
       #cat("action:\n")
       #print(weights)
       #print(prob)

inst/include/binaryMDPWriter.hpp

@@ -27,40 +27,7 @@ std::string inline ToString(T t) {
 
 /** Class for writing a HMDP model to binary files.
 
-The HMDP must be represented using the HMDP binary format (v1.0) which is a
-collection of 7 binary files:
-
-  Seven binary files are created using the following format:
-  - stateIdx.bin: File of integers containing the indexes defining all states in the format
-    "d0 s0 -1 d0 s0 a0 d1 s1 -1 d0 s0 a0 d1 s1 a1 d2 s2 -1 d0 s0 ...". Here -1 is
-    used to indicate that a new state is considered (new line).
-  - stateIdxLbl.bin: File of characters in the format "sIdx label sIdx label ..." Here
-    sIdx corresponds to the index/line number in stateIdxLbl.bin (index starts from 0).
-    Note no delimiter is used.
-  - actionIdx.bin: File of integers containing the indexes defining all actions in the format
-    "sIdx scope idx scope idx scope idx -1 sIdx scope idx scope idx -1 sIdx scope -1 ...".
-    sIdx corresponds to the index/line number in stateIdx.bin (index starts from 0).
-    Next pairs (scope idx) will follow indicating the possible transitions. Scope can be 4 values:
-    2 - A transition to a child process (stage zero in the child process), 1 - A transition
-    to next stage in the current process, 0 - A transition to the next stage in the father
-    process. Here idx in the pair denote the index of the state at the stage considered,
-    e.g. if scope=1 and idx=2 we consider state number 3 at next stage in the current
-    process. Finally, if scope = 3 then a transition to a state specified by it's state sIdx
-    is given. That is, if scope=3 and idx=5 then
-    we have a transition to the state specified at line 6 in stateIdxLbl.bin.
-    This is use full when considering shared child processes.
-  - actionIdxLbl.bin: File of characters in the format "aIdx label aIdx label ..." Here
-    aIdx corresponds to the index/line number in actionIdx.bin (index starts from 0).
-    Note no delimiter is used.
-  - actionWeight.bin: File of doubles containing the weights of the actions in the format
-    "c1 c2 c3 c1 c2 c3 ..." assuming three weights for each action.
-  - actionWeightLbl.bin: File of characters containing the labels of the
-    weights in the format "lable1 label2 label3" assuming three weights for each action.
-  - transProb.bin: File of doubles containing the probabilities of the transitions
-    defined in actions in actionIdx.bin. The format is
-    "p1 p2 p3 -1 p1 -1 p1 p2 -1 ...". Here -1 is
-    used to indicate that a new action is considered (new line).
-
+See the documentation of the binaryMDPWriter in R.
  */
 class BinaryMDPWriter
 {
@@ -102,14 +69,7 @@ class BinaryMDPWriter
     /** Constructor. */
     BinaryMDPWriter(){BinaryMDPWriter("");};
 
-    /** Set the pointer to the hypergraph we want to read data to.
-     * \param stateIdxFileN Filename of the state index file.
-     * \param stateIdxLblFileN Filename of the state label file.
-     * \param actionIdxFileN Filename of the action index file.
-     * \param actionIdxLblFileN Filename of the action label file.
-     * \param actionWFileN Filename of the action cost file.
-     * \param transProbFileN Filename of the transition probability file.
-     */
+    /** Open binary files for writing. */
     BinaryMDPWriter(string prefix) {
         string stateIdxFileN = prefix + "stateIdx.bin";
         string stateIdxLblFileN = prefix + "stateIdxLbl.bin";
@@ -134,6 +94,7 @@ class BinaryMDPWriter
         pExternalProcessesFile = fopen(externalProcessesFileN.c_str(), "wb");
     }
 
+    /** Close binary files. */
     void CloseWriter() {
       fclose(pStateIdxFile);
       fclose(pStateIdxLblFile);
@@ -147,12 +108,12 @@ class BinaryMDPWriter
       closed = true;
 
       log << "Create HMDP ...\n\n";
-   	log << "  Statistics:\n";
-		log << "    states : " << sTotal << "\n";
-		log << "    actions: " << aTotal << "\n";
-		log << "    weights: " << wLblLth << "\n\n";
-		log << "  Closing binary MDP writer.\n\n";
-		//log << "  Total time for writing to binary files: " << timer.ElapsedTime("sec") << " sec.\n\n";
+   	  log << "  Statistics:\n";
+      log << "    states : " << sTotal << "\n";
+      log << "    actions: " << aTotal << "\n";
+      log << "    weights: " << wLblLth << "\n\n";
+      log << "  Closing binary MDP writer.\n\n";
+      //log << "  Total time for writing to binary files: " << timer.ElapsedTime("sec") << " sec.\n\n";
     }
 
     ~BinaryMDPWriter() {
@@ -184,8 +145,7 @@ class BinaryMDPWriter
         wLblLth = wLblLth + labels.size();
     }
 
-    /** Start process.
-     */
+    /** Start a process. */
     void Process() {
         wFixed=true;
         iHMDP.push_back(-1);   // add stage idx
@@ -195,8 +155,7 @@ class BinaryMDPWriter
         //cout << "Start proc " << GetIHMDP() << endl;
     }
 
-    /** End process.
-     */
+    /** End a process. */
     void EndProcess() {
         iHMDP.pop_back();   // remove state
         iHMDP.pop_back();   // remove stage
@@ -205,15 +164,13 @@ class BinaryMDPWriter
         //cout << "End proc " << GetIHMDP() << endl;
     }
 
-    /** Start a stage.
-     */
+    /** Start a stage. */
     void Stage() {
         iHMDP[iHMDP.size()-2]++;    // increment stage index
         //cout << "Start stage " << GetIHMDP() << endl;
     }
 
-    /** End stage.
-     */
+    /** End a stage. */
     void EndStage() {
         iHMDP[iHMDP.size()-1]=-1;    // reset state index
         //cout << "End stage " << GetIHMDP() << endl;
@@ -231,15 +188,19 @@ class BinaryMDPWriter
         return sTotal-1;
     }
 
-    /** End state.
-     */
+    /** End state. */
     void EndState() {
         aCtr=-1;    // reset action ctr
         //cout << "End state " << GetIHMDP() << endl;
     }
 
     /** Add an action.
+     * \param scope Scope of the transition probabilities.
+     * \param index Index of the transition probabilities.
+     * \param prob Transition probabilities.
+     * \param weights Weights of the action.
      * \param label The label of the action.
+     * \param end True if not an action that define a child process.
      */
     void Action(const vector<int> &scope, const vector<int> &index,
                    const vector<flt> &prob, const vector<flt> &weights, const string &label, bool end) {
@@ -251,14 +212,20 @@ class BinaryMDPWriter
         if (end) EndAction();
     }
 
-    /** End action.
-     */
+    /** End action. */
     void EndAction() {
         iHMDP.pop_back();
         //cout << "End action " << GetIHMDP() << endl;
     }
 
    /** Add an external process.
+     * \param prefix The prefix of the external process
+     * \param scope Scope of the transition probabilities.
+     * \param index Index of the transition probabilities.
+     * \param prob Transition probabilities.
+     * \param weights Weights of the action.
+     * \param label The label of the action.
+     * \param termStates Number of states at the last stage in the external process.
      */
     void IncludeProcess(const string &prefix, const vector<int> &scope, const vector<int> &index,
                    const vector<flt> &prob, const vector<flt> &weights, const string &label, const int &termStates){
@@ -287,14 +254,14 @@ class BinaryMDPWriter
           EndStage();
     }
 
-    /** End of IncludeProcess statement */
+    /** End include process. */
     void EndIncludeProcess() {
        EndProcess();
        iHMDP.pop_back();
     }
 
     /** Add a state to the files stateIdx.bin and stateIdxLbl.bin.
-     * \param iHMDP The index vector of the HMDP state. Always of size
+     * \param index The index vector of the HMDP state. Always of size
      * 2+3*level, e.g vector [0,1,0,3,2] says that we consider stage 0,
      * state 1 and action 0 at the founder and stage 3 and state 2 at level one.
      * \param label The label of the state.
@@ -309,20 +276,21 @@ class BinaryMDPWriter
     }
 
     /** Add a state to the files stateIdx.bin.
-     * \param iHMDP The index vector of the HMDP state. Always of size
+     * \param index The index vector of the HMDP state. Always of size
      * 2+3*level, e.g vector [0,1,0,3,2] says that we consider stage 0,
      * state 1 and action 0 at the founder and stage 3 and state 2 at level one.
-     * \param label The label of the state.
      */
     void AddState(const vector<int> &index) {
         AddState(index, "");
     }
 
     /** Add a action to the binary files.
-     * \param actionIdxFile Filename of the action index file.
-     * \param actionIdxLblFile Filename of the action label file.
-     * \param actionWFile Filename of the action cost file.
-     * \param transProbFile Filename of the transition probability file.
+     * \param sId Id of the state.
+     * \param scope Scope of the transition probabilities.
+     * \param index Index of the transition probabilities.
+     * \param prob Transition probabilities.
+     * \param weights Weights of the action.
+     * \param label The label of the action.
      */
     void AddAction(int sId, const vector<int> &scope, const vector<int> &index,
                    const vector<flt> &prob, const vector<flt> &weights, const string &label) {
@@ -344,7 +312,7 @@ class BinaryMDPWriter
     // Output the index vector
     //string GetIHMDP() {return vec2String<int>(iHMDP);}
 
-    /** Stage string */
+    /** Stage string. */
     string StageStr() {
         std::ostringstream s;
         for (size_t i=0; i<iHMDP.size()-2; ++i) s << iHMDP[i] << ",";
@@ -369,8 +337,6 @@ class BinaryMDPWriter
     vector<int> sId;   ///< Containing the state id's (used to find the state id the action is defined under)
 	int sTotal; ///< Total number of states.
 	int aTotal; ///< Total number of actions.
-	//int nCtr; // current stage at current level
-	//int sCtr; // # of states
 	int aCtr; ///< current action at current state
 	int wLblLth;
 	bool wFixed; ///< TRUE if size of weights are fixed

src/hmdpReader.hh

@@ -20,7 +20,7 @@ class HMDPAction;   // forward declaration
 /** Class for reading/loading HMDP models.
 
 The HMDP must be represented using the HMDP binary format (v1.0) which is a
-collection of 7 binary files:
+collection of 8 binary files:
 
   Seven binary files are created using the following format:
   - stateIdx.bin: File of integers containing the indexes defining all states in the format
@@ -52,9 +52,10 @@ collection of 7 binary files:
     defined in actions in actionIdx.bin. The format is
     "p1 p2 p3 -1 p1 -1 p1 p2 -1 ...". Here -1 is
     used to indicate that a new action is considered (new line).
-
-Currently the files can be created using the MDP package in R.
-
+  - externalProcesses.bin: File of characters in the format "stageStr prefix stageStr prefix...".
+    Here stageStr corresponds to the index (e.g. n0 s0 a0 n1) of the stage corresponding to the
+    first stage in the external process and prefix to the prefix of the external process. Note no
+    delimiter is used.
  */
 class HMDPReader
 {