\documentclass[a4paper]{article}
\usepackage[a4paper,vmargin={30mm,20mm},hmargin={25mm,25mm}]{geometry}
\usepackage{graphicx}

\begin{document}

\title{TPCI - quick start}
\author{Michal Salz}

\maketitle

\section{Introduction}

The PLUTO CLOUDY Interface (TPCI) is a interface between the two simulation codes PLUTO\footnote{http://plutocode.ph.unito.it/} and CLOUDY\footnote{http://www.nublado.org/}. It can be used to simulate hydrodynamic evolution under irradiation from a source. For more information see (paper).

WARNING! Any user of TPCI should be familiar with PLUTO and CLOUDY individually. Both codes provide test problems, which are also included in this package. These problems are described in the userguides {\tt PLUTO/Doc/userguide.pdf} and {\tt TPCI/c13.01/docs/hazy2\_c13.pdf}.

\section{Terms of use}

TPCI is distributed freely under the GNU general public license. Users should reference the PLUTO and CLOUDY codes (see the web pages). Additionally the method paper should be referenced (paper). 

\section{Getting started}

The download package contains a packed version of PLUTO v. 4.0 and Cloudy 13.01. Minor changes were applied to both source codes, so the Interface only runs with the provided versions of PLUTO and CLOUDY. In the directory {\tt test\_prob/}, the package further contains:
\begin{itemize}
  \setlength{\itemsep}{-3pt}
  \item the interface {\tt call\_cloudy.cpp}
  \item the {\tt local\_make} file
  \item versions of the local makefile for g++ and mpic++
  \item two shell scripts to apply changes to the {\tt makefile} (see below)
  \item {\tt earth\_spec.ini} a solar EUV spectrum
  \item the {\tt main.cpp} replacement of the standard PLUTO {\tt main.c} file
  \item PLUTO start files: {\tt definitions.h, init.c, pluto.ini}
  \item {\tt userdef\_output.c} a changed PLUTO file needed to run TPCI
\end{itemize}
The start files are initialized to run the TPCI test problem, which you should be able to do after the following steps. 

\subsection{Compile CLOUDY}

Go into the directory {\tt c13.01/source/} and compile CLOUDY (type {\tt <make>}). In case of any problems see the StepByStep instruction on (http://www.nublado.org/). Compiling CLOUDY takes a couple of minutes, but less than one hour.

Check if the code runs correctly: Go to the directory {\tt c13.01/} and run the test problem {\tt <source/cloudy.exe -r test>}. Open the {\tt test.out} file and see, fit the last line says that {\tt CLOUDY exited OK}. If so, you are good to go. (For a complete test you have to run the TestSuite, also described on the CLOUDY web page.)

\subsection{Export the paths}

Export the paths to the source files. For the bash:\newline
{\indent\tt export PLUTO\_DIR=.../TPCI/PLUTO/}\\
{\indent\tt export CLOUDY\_DIR=.../TPCI/c13.01/source/}\\
For the dots please insert the full path to the {\tt TPCI} directory.


\subsection{PLUTO setup} 

Go in the {\tt test\_prob/} directory. Run the Python PLUTO setup script:\\
{\tt\indent python \$PLUTO\_DIR/setup.py}\\
and select the setup of PLUTO. The start screen of the setup looks as follows:
\begin{verbatim}
Working dir: .../TPCI
PLUTO dir  : .../TPCI/PLUTO/

 Setup problem
 Change makefile
 Auto-update
 Save Setup
 Quit
\end{verbatim}
Items are selected with the arrow keys. To set up the first test problem, just hit {\tt enter} until you reach the start screen again. Go one down and select a makefile, e.g., {\tt Linux.gcc.defs}. Then quit the setup.

You now have to edit the {\tt makefile}, because the interface must be compiled with the {\tt g++} compiler, while PLUTO is compiled with a c-compiler.
You can try to run the {\tt INS\_MAKE\_g++.sh} shell script. If that does not work, run the Python PLUTO setup again and subsequently apply the changes manually. In the {\tt makefile} change this:
\begin{verbatim}
# ---------------------------------------------------------
#    PLUTO target rule
# ---------------------------------------------------------

pluto: $(OBJ) 
	$(CC) $(OBJ) $(LDFLAGS) -o $@
\end{verbatim}
to this:
\begin{verbatim}
# ---------------------------------------------------------
#    PLUTO target rule
# ---------------------------------------------------------

pluto: $(OBJ) 
	g++ $(OBJ) $(CLOUDY_OBJ) $(LDFLAGS) -o $@
\end{verbatim}


\subsection{Make PLUTO}

You are ready the compile the interface. Type {\tt make} inside the {\tt test\_prob/} directory. This should be pretty fast (less than one minute).


\subsection{Run the test problem}

Execute {\tt ./pluto}. TPCI needs about 20 minutes to run the problem, depending on your workstation.

The test problem is a simple hydrogen only simulation of a density clump irradiated at a distance of 0.001~AU, so just above the solar surface. This is not intended as a physically correct setup. The spectral energy distribution is defined in the file {\tt earth\_spec.ini}, a solar EUV spectrum extended with a black body.  The test case will create 50 tabulated output files for PLUTO and about 10 for CLOUDY. They can be displayed as the individual userguides describe. E.g., the PLUTO output can be viewed with gnuplot:\\
{\tt\indent plot "data.0000.tab" u 1:3}\\
gives the density (4: velocity, 5: pressure, 6: temperature (K), 7: mean molecular weight, 8: heating/cooling (erg cm-3 s-1), 9: radiative acceleration (cm s-1), 10: heating efficiency, 11: electron density (cm-3), 12: hydrodynamic timescale (s), 13: hydrogen recombination timescale (s), 14: molecular timescale (s), 13: time).
Density, velocity, pressure and time are in dimensionless form and the unit variables defined in {\tt init.c} can be used to convert them (see the PLUTO userguide).

The evolution of the test problem shows, that the density clump is heated and expands. It is pushed away from the source due to slightly higher pressure at the source facing boundary and due to radiation pressure. The density is on the order of $10^9$~cm$^{-3}$ and the temperature $10^4$~K.


\section{Setup an own problem}

To set up your own problem, copy the {\tt test\_prob/} directory to anywhere on your system. 
Basically everything can be changed in the test problem (density, pressure, irradiation, composition), but one has to be careful to choose plausible start parameters. Any changes of PLUTO are done in the usual way, see the userguide. Adapting the CLOUDY setup is done in the file {\tt call\_cloudy.cpp} in the function {\tt CloudyInputScript} just as described by the userguide Hazy2 of CLOUDY in the section "Example Call as a Subroutine". 

Restrictions for the interface:
\begin{itemize}
  \setlength{\itemsep}{-3pt}
  \item PLUTO grid: Cartesian 1D-3D or 1D spherical
  \item CLOUDY: do not use any CLOUDY commands changing the density, pressure, or temperature handling (e.g., {\tt constant density, constant pressure, constant temperature}).
\end{itemize}

CLOUDY print frequency, the use of the advective solver, and the {\tt change\_factor} are adapted in the header of {\tt call\_cloudy.cpp}. The use of CLOUDY can also be turned off, then PLUTO runs independently.

To run your test problem you have to redo the steps 2.2 to 2.5. Step 2.1 does not have to be repeated; the CLOUDY source files are compiled only once.


\section{MPI runs}

TBD


\section{Questions?}

For questions: {\tt msalz@hs.uni-hamburg.de}. Good look.


\end{document}