diff --git a/R/binaryMDPWriter.R b/R/binaryMDPWriter.R index 9ec1ddb..fbe5dcc 100644 --- a/R/binaryMDPWriter.R +++ b/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) diff --git a/inst/include/binaryMDPWriter.hpp b/inst/include/binaryMDPWriter.hpp index ceab456..ecd3e9f 100644 --- a/inst/include/binaryMDPWriter.hpp +++ b/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 &scope, const vector &index, const vector &prob, const vector &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 &scope, const vector &index, const vector &prob, const vector &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 &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 &scope, const vector &index, const vector &prob, const vector &weights, const string &label) { @@ -344,7 +312,7 @@ class BinaryMDPWriter // Output the index vector //string GetIHMDP() {return vec2String(iHMDP);} - /** Stage string */ + /** Stage string. */ string StageStr() { std::ostringstream s; for (size_t i=0; i 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 diff --git a/src/hmdpReader.hh b/src/hmdpReader.hh index 2a93e03..6a7a8c5 100644 --- a/src/hmdpReader.hh +++ b/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 {