% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/writer.R
\name{binaryMDPWriter}
\alias{binaryMDPWriter}
\title{Function for writing an HMDP model to binary files. The function defines
sub-functions which can be used to define an HMDP model saved in a set of binary
files.}
\usage{
binaryMDPWriter(
  prefix = "",
  binNames = c("stateIdx.bin", "stateIdxLbl.bin", "actionIdx.bin", "actionIdxLbl.bin",
    "actionWeight.bin", "actionWeightLbl.bin", "transProb.bin", "externalProcesses.bin",
    "transWeight.bin", "transWeightLbl.bin"),
  getLog = TRUE
)
}
\arguments{
\item{prefix}{A character string with the prefix added to \code{binNames}.}

\item{binNames}{A character vector giving the names of the binary files storing the model.}

\item{getLog}{Output log text.}
}
\value{
A list of functions.
}
\description{
Binary files are efficient for storing large models. Compared to the HMP (XML)
format the binary files use less storage space and loads the model faster.
}
\details{
The returned writer exposes these functions:
\itemize{
\item \code{setWeights(labels, ...)}: sets the labels of the weights used in the actions.
\code{labels} is a vector of label names. \code{...} is currently ignored. Call this
before building the model.
\item \code{process()}: starts a (sub)process. It may also be used to specify a
traditional MDP using matrices in \code{MDPtoolbox} style. In that style, \code{P} is
a list of matrices, one per action, each of size \verb{$S x S$} where \verb{$S$} is
the number of states. Each used row must sum to one, or all entries in a
row must be zero if unused. \code{R} is a matrix of size \verb{$S x A$}, where \verb{$A$}
is the number of actions, and \code{D} is a matrix of size \verb{$S x A$} with
durations. If \code{D} is omitted, all durations are assumed to be 1.
\item \code{endProcess()}: ends a (sub)process.
\item \code{stage(label = NULL)}: starts a stage. \code{label} is currently unused in the
binary format.
\item \code{endStage()}: ends a stage.
\item \code{state(label = NULL)}: starts a state and returns, invisibly, the state id.
That id can later be referenced with scope 3.
\item \code{endState()}: ends a state.
\item \code{action(scope = NULL, id = NULL, pr = NULL, prob = NULL, weights, transWeights = NULL, label = NULL, end = FALSE, ...)}: starts an action.
\code{weights} must be a vector of action weights. \code{transWeights} must contain
transition weights ordered by transition, with all transition weight labels
for the first transition followed by all labels for the second transition,
and so on. Transition probabilities can be entered in two ways:
\enumerate{
\item \code{prob} contains triples \verb{(scope, id, pr)}.
\item \code{id} and \code{pr} are vectors of equal length. If \code{scope} is omitted, all
scopes default to 1.
}

See the description of \code{actionIdx.bin} below. If \code{end = TRUE}, calling
\code{endAction()} is not necessary. \code{...} is currently ignored.
\item \code{endAction()}: ends an action. Do not use this if \code{end = TRUE} was used
when the action was specified.
\item \code{includeProcess(prefix, label = NULL, weights, prob, termStates, transWeights = NULL)}: includes an external process. External processes are
loaded into memory only when needed, which helps with large models. \code{prefix}
is the external process prefix. \code{weights} must be a vector of action
weights, and \code{prob} must contain triples \verb{(scope, idx, pr)}; see the
description of \code{actionIdx.bin} below. \code{termStates} must specify the number
of states at the last stage in the external process. Inside an
\verb{includeProcess ... endIncludeProcess}
block, you must specify the father jump actions of the last stage in the
external process. The external process is represented by its first and last
stage together with its jump actions. The function returns, invisibly, the
state ids of the first stage in the external process, which can later be
referenced with scope 3.
\item \code{endIncludeProcess()}: ends an \code{includeProcess} block.
\item \code{closeWriter()}: closes the writer. Call this when the model description is
finished.
}

Ten binary files are created:
\itemize{
\item \code{stateIdx.bin}: integers defining all states in the format
\code{"n0 s0 -1 n0 s0 a0 n1 s1 -1 n0 s0 a0 n1 s1 a1 n2 s2 -1 n0 s0 ..."}.
Here \code{-1} indicates that a new state is considered.
\item \code{stateIdxLbl.bin}: character data in the format \verb{sIdx label sIdx label ...}.
Here \code{sIdx} corresponds to the index or line number in \code{stateIdxLbl.bin},
starting from 0. No delimiter is used.
\item \code{actionIdx.bin}: integers defining all actions in the format
\verb{sIdx scope idx scope idx scope idx -1 sIdx scope idx scope idx -1 sIdx scope -1 ...}.
\code{sIdx} corresponds to the index or line number in \code{stateIdx.bin}, starting
from 0. The following \verb{(scope, idx)} pairs indicate possible transitions.
Scope can take four values:
\itemize{
\item \code{2}: a transition to a child process, at stage zero in the child process.
\item \code{1}: a transition to the next stage in the current process.
\item \code{0}: a transition to the next stage in the father process.
\item \code{3}: a transition to a state specified by its state \code{sIdx}.
}

For example, if \code{scope = 1} and \code{idx = 2}, the transition is to state
number 3 at the next stage in the current process. If \code{scope = 3} and
\code{idx = 5}, the transition is to the state specified at line 6 in
\code{stateIdxLbl.bin}. This is useful when considering shared child processes.
\item \code{actionIdxLbl.bin}: character data in the format \verb{aIdx label aIdx label ...}.
Here \code{aIdx} corresponds to the index or line number in \code{actionIdx.bin},
starting from 0. No delimiter is used.
\item \code{actionWeight.bin}: doubles containing action weights in the format
\code{"c1 c2 c3 c1 c2 c3 ..."}, assuming three weights for each action.
\item \code{actionWeightLbl.bin}: character data containing the weight labels in the
format \verb{label1 label2 label3}, assuming three weights for each action.
\item \code{transProb.bin}: doubles containing transition probabilities defined in
\code{actionIdx.bin}. The format is \code{"p1 p2 p3 -1 p1 -1 p1 p2 -1 ..."}. Here
\code{-1} indicates that a new action is considered.
\item \code{externalProcesses.bin}: character data containing links to external
processes in the format \verb{stageStr prefix stageStr prefix ...}. Here
\code{stageStr} corresponds to the stage index, for example \verb{n0 s0 a0 n1}, of
the stage corresponding to the first stage in the external process, and
\code{prefix} is the external process prefix. No delimiter is used.
\item \code{transWeight.bin}: doubles containing transition weights in the format
\code{"t11 t12 t21 t22 -1 ..."}, assuming two transition weights for each
transition and two transitions in the first action.
\item \code{transWeightLbl.bin}: character data containing the transition weight
labels.
}
}
\note{
Note all indexes are starting from zero (C/C++ style).
}
\examples{
## Use temp dir
wd <- setwd(tempdir())

# Create a small HMDP with two levels
w<-binaryMDPWriter()
w$setWeights(c("Duration","Net reward","Items"))
w$process()
   w$stage()
      w$state(label="M0")
         w$action(label="A0",weights=c(0,0,0),prob=c(2,0,1))
            w$process()
               w$stage()
                  w$state(label="D")
                     w$action(label="A0",weights=c(0,0,1),prob=c(1,0,0.5,1,1,0.5))
                     w$endAction()
                  w$endState()
               w$endStage()
               w$stage()
                  w$state(label="C0")
                     w$action(label="A0",weights=c(0,0,0),prob=c(1,0,1))
                     w$endAction()
                     w$action(label="A1",weights=c(1,2,1),prob=c(1,0,0.5,1,1,0.5))
                     w$endAction()
                  w$endState()
                  w$state(label="C1")
                     w$action(label="A0",weights=c(0,0,0),prob=c(1,0,1))
                     w$endAction()
                     w$action(label="A1",weights=c(1,2,1),prob=c(1,0,0.5,1,1,0.5))
                     w$endAction()
                  w$endState()
               w$endStage()
               w$stage()
                  w$state(label="C0")
                     w$action(label="A0",weights=c(1,4,0),prob=c(0,0,1))
                     w$endAction()
                  w$endState()
                  w$state(label="C1")
                     w$action(label="A0",weights=c(1,4,0),prob=c(0,0,1))
                     w$endAction()
                  w$endState()
               w$endStage()
            w$endProcess()
         w$endAction()
         w$action(label="A1",weights=c(0,0,0),prob=c(2,0,1))
            w$process()
               w$stage()
                  w$state(label="D")
                     w$action(label="A0",weights=c(0,0,1),prob=c(1,0,1))
                     w$endAction()
                  w$endState()
               w$endStage()
               w$stage()
                  w$state(label="C0")
                     w$action(label="A0",weights=c(0,0,0),prob=c(1,0,1))
                     w$endAction()
                     w$action(label="A1",weights=c(1,2,1),prob=c(1,0,0.5,1,1,0.5))
                     w$endAction()
                  w$endState()
               w$endStage()
               w$stage()
                  w$state(label="C0")
                     w$action(label="A0",weights=c(1,4,0),prob=c(0,0,1))
                     w$endAction()
                  w$endState()
                  w$state(label="C1")
                     w$action(label="A0",weights=c(1,4,0),prob=c(0,0,1))
                     w$endAction()
                     w$action(label="A1",weights=c(0,10,5),prob=c(0,0,0.5,0,1,0.5))
                     w$endAction()
                  w$endState()
               w$endStage()
            w$endProcess()
         w$endAction()
      w$endState()
      w$state(label="M1")
         w$action(label="A0",weights=c(0,0,0),prob=c(2,0,1))
            w$process()
               w$stage()
                  w$state(label="D")
                     w$action(label="A0",weights=c(0,0,1),prob=c(1,0,0.5,1,1,0.5))
                     w$endAction()
                  w$endState()
               w$endStage()
               w$stage()
                  w$state(label="C0")
                     w$action(label="A0",weights=c(0,0,0),prob=c(1,0,1))
                     w$endAction()
                  w$endState()
                  w$state(label="C1")
                     w$action(label="A0",weights=c(0,0,0),prob=c(1,0,1))
                     w$endAction()
                  w$endState()
               w$endStage()
               w$stage()
                  w$state(label="C0")
                     w$action(label="A0",weights=c(1,4,0),prob=c(0,0,1))
                     w$endAction()
                  w$endState()
                  w$state(label="C1")
                     w$action(label="A0",weights=c(1,4,0),prob=c(0,0,1))
                     w$endAction()
                  w$endState()
               w$endStage()
            w$endProcess()
         w$endAction()
      w$endState()
   w$endStage()
w$endProcess()
w$closeWriter()

## Info about the binary files (don't have to load the model first)
getBinInfoStates()
getBinInfoActions()

## reset working dir
setwd(wd)
}
