\section{Installing PIANOS}

There is no installing to be done with PIANOS. The program is path-independent and runnable right from the CD-ROM (it cannot write the generated program on the CD-ROM, though). The only thing that needs to be done is to pick a directory and copy everything from the directory `release' (on the CD-ROM) there. After doing this you are ready to run PIANOS.

Note that PIANOS requires a Java runtime environment of version 1.5 or later.

\section{Starting the program}
\label{starting_program}

This section describes how to run PIANOS and also acts as a quick-start guide. There are several example models and simulation files that can be used for experimentation in the directory `release/models' on the PIANOS CD-ROM or the tar.gz package. The directory release also contains examples on how to run PIANOS.

There are two methods to run PIANOS on the command-line, and one Java static method for further development.

On the command-line, the user can specify one file that contains the file names of the simulation parameter files and the model file, or these files can be given directly on the command-line.

\textbf{An example:}

\begin{verbatim}
java -jar PIANOS.jar allfiles.txt
\end{verbatim}

In this case, `allfiles.txt' should contain file names in the format:

\begin{verbatim}
user distributions:     relative/path/to/user_dist.f90
model:                  relative/path/to/modelFile
initial values:         relative/path/to/initialValuesFile
simulation:             relative/path/to/simulationFile
proposals:              relative/path/to/proposalsFile
update strategy:        relative/path/to/updateFile
to output:              relative/path/to/toOutputFile
last values:            relative/path/to/lastValuesFile
\end{verbatim}

Here the order of the header - file name pairs is arbitrary. this file can also contain empty lines and comment lines (starting with a hash `\#'). \newline
Note that the file name of the user distributions file must always be `user\_dist.f90' and it must contain a valid Fortran module named `user\_dist' (even when all used distributions would be provided ones).

The other method on the command line is used like this:

\begin{verbatim}
java -jar PIANOS.jar user_dist.f90 modelFile initialValuesFile 
    simulationFile proposalsFile updateFile 
    toOutputFile lastValuesFile
\end{verbatim}

Here each parameter is the relative path to the file such as above.

As the user can see, the methods differ only in the way of providing the necessary files.

Refer to the Javadoc documentation for details on the Java method to run PIANOS with.

\section{Running the simulation}

After PIANOS has finished there should be a couple of .f90-files in the program directory. These are the simulation program that can be compiled and run on a computer with a Fortran compiler and the NAG library. List of produced files:

\begin{itemize}
\item definitions.f90
\item input.f90
\item main.f90
\item output.f90
\item proposal.f90
\end{itemize}

In addition to these the user needs a Fortran module file named `user\_dist.f90' that contains the user-defined distributions for the model used. With PIANOS are provided a few of these, one for each example model and one that combines all the contents of the separate files for the models. The larger collection of distributions can be found in the directory `release/models' while each model's specific user\_dist.f90 can be found in the model's directory ( `release/models/themodel').

The simulation program requires some of the model files, including data and initial values file, to be available when it is started. To be on the safe side, we encourage users to copy all of the model files to the computer used for the simulation.

Note that the files need to be in the same relative path as they were when running the PIANOS generator program.

\textbf{An example:}

We have PIANOS at `home/we/PIANOS/release'. We have the model files for the example model called simplebirds\_spatial in  `home/we/PIANOS/release/models/simplebirds\_spatial'. First we run PIANOS:

\begin{verbatim}
java -jar PIANOS.jar models/simplebirds_spatial/allfiles.txt
\end{verbatim}

Now, we transfer the .f90-files to a suitable computer:

\begin{verbatim}
scp *.f90 models/simplebirds_spatial/user_dist.f90 
we@computer:work/.
\end{verbatim}


We already have a directory called models under `work/' at the computer. We transfer the model files there:

\begin{verbatim}
scp -r models/simplebirds_spatial/
we@computer:work/models/.
\end{verbatim}

Now we only need to compile and run the simulation at the computer.

When all these files are on a suitable computer, compiling and running the simulation is done like this:

\begin{verbatim}
f95 -lnag -c definitions.f90
f95 -lnag -c proposal.f90
f95 -lnag -c user_dist.f90
f95 -lnag -c input.f90
f95 -lnag -c output.f90

f95 -lnag -o main main.f90 definitions.o 
proposal.o user_dist.o input.o output.o

./main
\end{verbatim}

Note that running a simulation with a large number of iterations might take a long time. The simulation prints messages on its progress while it is running. See \ref{outputsfortran} on the outputs of the simulation.