Manual for ko-fbd
usage:
./a.out [options] [--1|--2] [x11 x12 x13 ... x22 x23 ... x33 ... ... y1 y2 y3 ... ]
NAME
ko-fbd - evaluate the Fisher-Bingham integral on n-dimensional sphere
DESCRIPTION
ko-fbd evaluate the Fisher-Bingham integral and initial value for HGD.
USAGE
./ko-fbd [options] x11 x12 x13 ... x22 x23 ... x33 ... ... y1 y2 y3 ...
OPTIONS
The options may be given in any order. Options without an argument can be combined
after a single dash.
--1 Compute the integral \int_{S^n}\exp(\sum_{i\leq j} x_{ij}t_it_j+y_it_i)|dt|.
--2 Compute the integral \int_{S^n}\exp(\sum_{i, j} x_{ij}t_it_j+y_it_i)|dt|.
-h, --help
Give a bit of help about the command line arguments and options.
--verbose[=1-3]
output detail result. For example,
the initial point and the initial value of the Runge-Kutta.
-c, --confidence
estimate confidence intervals stated at the 95 percent confidence level
-f {filename}, --file {filename}
Read a matrix and a vector from file.
--time
measure the computational times.
--diag
When the input matrix is diagonal, user can omit inputting non-diagonal element
with this option as
./ko-fbd --diag x_11 x_22 ... x_nn y_1 y_2 ... y_n
--rkerror {floating number}
control the error values of Runge-Kutta method
Examples
The command:
./ko-fbd 1.23 2.39 3.22 2.12 3.32
evaluates the Fisher-Bingham integral on 1 dimensional integral
F(X,Y)
=\int_{S^1} \exp((t,Xt)+(y,t)) |dt|
=\int_{S^1} \exp(x11*t1^2+x12*t1*t2+x22*t2^2+y1*t1+y2*y2) |dt|
at
/ x11 x12/2 \ / 1.23 2.39/2 \ / y1 \ / 2.12 \
X = | | = | |, Y = | | = | |
\ x12/2 x22 / \ 2.39/2 3.22 / \ y2 / \ 3.32 /.
This command will return outputs
dim: 1
input matrix and vector:
1.230000 1.195000 :2.120000
1.195000 3.220000 :3.320000
result:
1814.38
The input matrix and vector are the values of X and Y. The result is the
value of F(X,Y)
The long option "--2" omits dividing non-diagonal element of X. Hence,
the command:
./ko-fbd 1.0 2.0 3.0 4.0 5.0 --2
returns the value of
F(X,Y)
=\int_{S^1} \exp((t,Xt)+(y,t)) |dt|
=\int_{S^1} \exp(x11*t1^2+2*x12*t1*t2+x22*t2^2+y1*t1+y2*y2) |dt|
where
/ x11 x12 \ / 1.0 2.0 \ / y1 \ / 4.0 \
X = | | = | |, Y = | | = | |
\ x12 x22 / \ 2.0 3.0 / \ y2 / \ 5.0 /.
If the matrix X is diagonal, user can omit inputting non-diagonal element
with "--diag" option. The command:
./ko-fbd 1.0 2.0 3.0 4.0 --diag
evaluate the Fisher-Bingham integral at
/ x11 0 \ / 1.0 0.0 \ / y1 \ / 3.0 \
X = | | = | |, Y = | | = | |
\ 0 x22 / \ 0.0 2.0 / \ y2 / \ 4.0 /.
Matrix X and vector Y can be read from a file.
The command:
./ko-fbd -f foo.txt
returns same result with the command;
./ko-fbd 1.23 2.39 3.22 2.12 3.32
if the following text is written in foo.txt.
1
1.230000 2.390000
2.390000 3.220000
2.120000 3.320000
The number in the first line of foo.txt have to be the dimension of
the sphere.
The option "-f" and "--f" are available with the option "--diag".
In this case, the format of the input file is as follows:
n-1
x11 x22 ... xnn
y1 y2 ... yn.
For example, the command:
./ko-fbd -f foo.txt --diag
returns same result with the command:
./ko-fbd 1.0 2.0 3.0 4.0 --diag
if the following text is written in foo.txt.
1
1.0 2.0
3.0 4.0
SEE ALSO
This program is based on the article
Tamio Koyama, Hiromasa Nakayama, Kenta Nishiyama, Nobuki Takayama:
Holonomic Gradient Descent for the Fisher-Bingham Distribution on
the $n$-dimensional Sphere, arXiv:1201.3239.