Output format and directories architecture

1. Directories architecture
This paragraph briefly presents the directories architecture that corresponds to the distribution provided, and that I frequently use in most of my runs. Nevertheless, this architecture is not mandatory. One is free to put the parameter input files and output in any directory. Also, the executable fargo could be copied into a global or local bin/ directory so as to reside in the path.

fargo directory (top of distribution)
Contains fargo executable
and IDL widget application mp.pro

in/ directory.
Contains parameter files (*.par)
and planetary system files (*.cfg)

out1/ directory
Contains files output by the run of in/template.par, or by one of the Stockholm test runs (Jupiter mass planet in a viscous disk).

out2/ directory

out3/ directory, etc.

src/ directory.
Contains FARGO source files

Although one can give to the output directories any name, it is useful to name them out1, out2, etc. Indeed, the mp.pro widget enables one to select automatically outn as the current output directory when one selects Disk Number n in the top left pull down menu 'Disk Number'. A good idea is to give an explanatory name to the output directory, such as output/JupiterAndUranus, and to create from the fargo directory a soft link to that directory: ln -s output/JupiterAndUranus out1

Note also that all the paths specified in a parameter file are the paths relative to the directory where fargo is launched. In all the cases included in the distribution, fargo has to be launched from the fargo directory (top of distribution), in the following manner: ./fargo in/parameterfile.par As a consequence, the planetary system files referred to by PlanetConfig in the parameter files provided are addressed as in/something.cfg instead of simply something.cfg. Similarly, the output directories are out1, out2, etc. instead of ../out1, ../out2, etc. Naturally, one can also give absolute paths instead of relative paths for the PlanetConfig and OutputDir parameters.

2. Output files format
The purpose of this paragraph is to provide a description of the different files written to the disk at runtime, and to describe their format. Note that at runtime any file fargo creates or updates is located in the directory referred to by OutputDir in the parameter file of the run. Nothing is done by fargo outside of this directory.

The hydrodynamics variables (density, radial velocity, azimuthal velocity, and possibly a passive scalar) are written every Ninterm * DT. They are written in raw format (unformatted). They are not directly readable through a more, cat or vi command. They are binary files. Their size is exactly Nsec * Nrad * 8 (this last factor is the number of bytes per double precision floating point value). The first value in a given file corresponds to the variable at azimuth 0 and lowest radius. The subsequent value corresponds to the variable at next azimuth value (2*PI/Nsec) and lowest radius, etc. Reading the corresponding field into an IDL matrix can be done as follows (we assume it is the density of output number 33, and that the run had Nsec=384 and Nrad=210):

density = dblarr(384,210)    ; Nsec goes first, then Nrad
openr,1,'gasdens33.dat'   ; we assume that IDL was launched in the output directory
readu,1,density   ; 'u' for unformatted
close,1
tvscl, density

It is possible that the platform on which fargo was run and the one on which you use IDL have different endian conventions. If this is the case you can use the following C program to convert the output files prior to their reading. Compile it using:
cc -o swpbytes convert.c -lm
and then use swpbytes on all unformatted output files:
for i in gas*.dat; do ./swpbytes $i; done (we assume you use the bash shell; note that swpbytes does not accept wildcards).
Alternatively, you can force this byte swapping directly under IDL. In the above example, you could have issued:
openr,1,'gasdens33.dat',/swap_endian

The naming convention of unformatted files is the following: they all begin with the prefix 'gas', then follows a string which indicates which HD field is contained in the file ('dens' for density, 'vrad' for radial velocity, 'vtheta' for the azimuthal velocity, and possibly 'label' for a passive scalar), then the output number, then a '.dat' suffix.
A number of files are also written in ASCII format (formatted). You can read them with a more, vi or cat command. Most of these files are updated every DT (fine grain sampling) except the files named planeti.dat (i being the planet number), which are updated every Ninterm * DT (i.e. at every output of hydrodynamics variables in the gas*.dat files). These files are:
- 'bigplaneti.dat', where i is the planet number. It is a 9-column file, which are respectively:
  1. The current output number (therefore repeated over Ninterm consecutive rows)
  2. The planet x coordinate
  3. The planet y coordinate
  4. The v_x velocity component of the planet
  5. The v_y velocity component of the planet
  6. The planet mass
  7. The mass lost by the mesh at the inner boundary
  8. The date
  9. The frame angular velocity
  Note that the planet velocity is always given in a non-rotating frame, regardless of the value of OmegaFrame.
- 'orbiti.dat', where i is the planet number. It is a 6-column file. The columns respectively contain:
  1. The date
  2. The planet eccentricity
  3. The planet semi-major axis
  4. The planet mean anomaly
  5. The planet true anomaly
  6. The periastron position angle
- 'tqwki.dat', where i is the planet number. It is a 10-column file. Its name is short for 'torque and work'. The columns respectively contain:
  1. The current output number (therefore repeated over Ninterm consecutive rows)
  2. The torque exerted by the inner disk onto the planet, without Roche lobe avoidance
  3. The torque exerted by the outer disk onto the planet, without Roche lobe avoidance
  4. The torque exerted by the inner disk onto the planet, with a Roche lobe tapering applied as described here.
  5. The torque exerted by the outer disk onto the planet, with a Roche lobe tapering.
  6. The power of the force exerted by the inner disk force (untapered) onto the planet.
  7. The power of the force exerted by the outer disk force (untapered) onto the planet.
  8. The power of the force exerted by the inner disk force (Roche lobe tapered) onto the planet.
  9. The power of the force exerted by the outer disk force (Roche lobe tapered) onto the planet.
  10. The date.
- If fargo is launched with the '-e' flag, an additional file is produced, which corresponds to the torque file format required by the EU hydrocode comparison page. This file is called 'torquei.dat', where i is the planet number. It is a 7-column file. The columns are respectively:
  1. The date
  2. The disk mass interior to the planet orbit
  3. The disk mass exterior to the planet orbit
  4. The torque exerted by the inner disk onto the planet, with a Roche lobe avoidance (r > R_H)
  5. The torque exerted by the outer disk onto the planet, with a Roche lobe avoidance (r > R_H)
  6. The torque exerted onto the planet by the Roche lobe material located between 0.5R_H and R_H, with a distance to the mesh center smaller than that of the planet.
  7. The torque exerted onto the planet by the Roche lobe material located between 0.5R_H and R_H, with a distance to the mesh center larger than that of the planet.
In addition to these fine-grain sampling files, the file(s) 'planeti.dat' are updated at every output, and they contain the same information as the files 'bigplaneti.dat'. Also, FARGO writes at the beginning of the run a number of files that provide useful information, e.g. for visualization purposes. These files are:
- 'dims.dat' : contains eight values. The first four are obsolete and are set to 0. The fifth is the mesh outer radius, the sixth value is the total number of output (as deduced from the parameter file, i.e. Ntot/Ninterm), the seventh value is the radial number of zones (NRAD) and the last one is the number of sectors (NSEC).
- 'run.commandline' : contains the string that was issued on the command line to launch the run.
- 'src.tar.bz2' : a bzipped tar file of the source that strictly corresponds to the code that was run. This archive is produced in the fargo directory at each built, as a hidden file. It is then copied at run time in the output directory only if fargo is launched from the fargo directory (ie only if it is found in the present working directory).
- 'used_rad.dat' : a one-column file with NRAD+1 entries that represent the radius of the zone interfaces, from RMIN to RMAX.