% $OpenXM: OpenXM/src/R/r-packages/hgm/man/hgm.Rhgm.Rd,v 1.2 2015/03/27 02:36:30 takayama Exp $
\name{hgm.Rhgm}
\alias{hgm.Rhgm}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{
The function hgm.Rhgm performs the holonomic gradient method (HGM)
for a given Pfaffian system and an initial value vector.
}
\description{
The function hgm.Rhgm performs the holonomic gradient method (HGM)
for a given Pfaffian system and an initial value vector
with the deSolve package in R.
}
\usage{
hgm.Rhgm(th0, G0, th1, dG.fun, times=NULL, fn.params=NULL)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{th0}{ A d-dimensional vector which is an initial point of the parameter vector th (theta).}
\item{G0}{
A r-dimensional vector which is the initial value of the vector G
of the normalizing constant and its derivatives.
}
\item{th1}{
A d-dimensional vector which is the target point of th.
}
\item{dG.fun}{
dG.fun is the ``right hand sides'' of the Pfaffian system.
It is a d*r-dimensional array.
}
\item{times}{a vector; times in [0,1] at which explicit estimates for G are desired.
If time = NULL, the set {0,1} is used, and only the final value is returned.
}
\item{fn.params}{
fn.params: a list of parameters passed to the function dG.fun.
If fn.params = NULL, no parameter is passed to dG.fun.
}
}
\details{
The function hgm.Rhgm computes the value of a holonomic function
at a given point, using HGM.
This is a ``Step 3'' function (see the reference below),
which can be used for an arbitrary input, in the HGM framework.
Efficient ``Step 3'' functions are given for some distributions
in this package.
The Pfaffian system assumed is
d G_j / d th_i = (dG.fun(th, G))_{i,j}
The inputs of hgm.Rhgm are the initial point th0, initial value G0, final point th1,
and Pfaffian system dG.fun. The output is the final value G1.
If the argument `times' is specified, the function returns a matrix,
where the first column denotes time, the following d-vector denotes th,
and the remaining r-vector denotes G.
% \code{\link[RCurl]{postForm}}.
}
\value{
The output is the value of G at th1. The first element of G is the normalizing
constant.
}
\references{
\url{http://www.math.kobe-u.ac.jp/OpenXM/Math/hgm/ref-hgm.html}
}
\author{
Tomonari Sei
}
%\note{
%%% ~~further notes~~
%}
%% ~Make other sections like Warning with \section{Warning }{....} ~
%\seealso{
%%%\code{\link{oxm.matrix_r2tfb}}
%}
\examples{
# Example 1.
# A demo program; von Mises--Fisher on S^{3-1}
G.exact = function(th){ # exact value by built-in function
c( sinh(th[1])/th[1], cosh(th[1])/th[1] - sinh(th[1])/th[1]^2 )
}
dG.fun = function(th, G, fn.params=NULL){ # Pfaffian
dG = array(0, c(1, 2))
sh = G[1] * th[1]
ch = G[2] * th[1] + G[1]
dG[1,1] = G[2] # Pfaffian eq's
dG[1,2] = sh/th[1] - 2*ch/th[1]^2 + 2*sh/th[1]^3
dG
}
th0 = 0.5
th1 = 15
G0 = G.exact(th0)
G0
G1 = hgm.Rhgm(th0, G0, th1, dG.fun) # HGM
G1
G1.exact = G.exact(th1)
G1.exact
#
# Example 2.
#
hgm.Rhgm.demo1()
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{ Normalization constant }
\keyword{ Holonomic gradient method }
\keyword{ HGM }