***************************************************************** * PINOCCHIO V3.0 * * (PINpointing Orbit-Crossing Collapsed HIerarchical Objects) * ***************************************************************** This code was written by Pierluigi Monaco, Tom Theuns, Giuliano Taffoni Copyright (C) 2013 web page: http://adlibitum.oats.inaf.it/monaco/Homepage/Pinocchio/ This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA ***************************************************************** This file contains information on how to run PINOCCHIO-3.0 ***************************************************************** This documentation is meant to give technical support in running the PINOCCHIO code. It is not meant to explain the scientific and cosmological background of the code. The user is supposed to be familiar with the formalism that has been used to develop PINOCCHIO. Complete information can be found in the papers quoted at the end of this file, and in the PINOCCHIO web-site http//adlibitum.oats.inaf.it/monaco/Homepage/Pinocchio/ ***************************************************************** INDEX 0. V3.0.1 1. Differences with previous versions 2. The package - V3.0 3. The parameter file 4. Pre-compiler options 5. Outputs 6. Limitations 7. PINOCCHIO papers ***************************************************************** 0. V3.0.1 This version solves a bug contained in the 3.0 version: when the power spectrum was input in the code through a file, the code was incorrectly tilting the spectrum by k**(1-PowerSpectrum). This has been fixed. Moreover, this documentation file gives more precise indications on how to give the power spectrum through an input file. ***************************************************************** 1. DIFFERENCES WITH PREVIOUS VERSIONS V1 of pinocchio is in fortran 77 and is not parallel. It adopts an out-of-core strategy to minimize memory requirements, so it needs fast access to the disc. V2 has been re-written in fortran 90. The fmax code is fully parallel but maintains the out-of-core design, so it keeps memory requirements low but needs fast disc access. It uses fftw-2.1.5 to compute FFTs, in place of the code based on Numerical Recipes. The fragment code is provided in two versions, a scalar one and a parallel one. This parallelization has no restrictions in validity but does not have good scaling properties, the scalar code on a shared-memory machine is preferable whenever possible. V3 is fully, parallel, is written in fortran90 + C, and uses Message Passing Interface (MPI) for communications. It has been designed to run on hundreds if not thousands of cores of a massively parallel super-computer. Main features: - Parameters are passed to the code with a Gadget-like parameter file. - The two separate codes (fmax and fragment) have been merged and no out-of-core strategy is adopted, so i/o is very limited but the amount of needed memory rises by a factor of three. This version of the code needs ~110 bytes per particle. - Fragmentation is performed by dividing the box into sub-volumes and distributing one sub-volume to each MPI task. The tasks do not communicate during fragmentation, so each sub-volume needs to extend the calculation to a boundary layer, where reconstruction is affected by boundaries. For small boxes at very high resolution the overhead implied by the boundary layer would become dominant; in this case the fragmentation code of version 2 would be preferable. - We have merged PINOCCHIO with the generator of a Gaussian density field embedded in the N-GenIC code by V. Springel. - The code has also been extended to consider a wider range of cosmologies including a generic, redshift-dependent equation of state of the quintessence. - The code can generate a full-sky catalog of halos in the past-light-cone up to a redshift specified by the user. In this case the box is replicated using periodic boundary conditions to fill the needed cosmological volume. A complete description of the code is provided in Monaco et al. (2013); see Section 7 below. ***************************************************************** 2. THE PACKAGE - V3.0 This software has been tested successfully on a few machines, including linux clusters and the Fermi Blue-Gene super-computer. You are most warmly encouraged to use this code and report any problem to monaco@oats.inaf.it. The src/ directory of the PINOCCHIO-3.0 package contains the following files: fortran modules: numbers.F90 pinocchio-module.F90 fmax-modules.F90 fragment-modules.F90 makefile: Makefile main code: pinocchio-3.0.F90 - calls fmax and fragment ReadParamfile.c - reads parameter values from the parameter file computation of collapse times: fmax.F90 - main code for computation of Fmax fmax-subs.F90 - subdirectories for computing derivatives of initial potential fmax-init.F90 - initialization routines fmax-fftw.F90 - calls of FFTW fmax-rw.F90 - i/o operations fmax-alloc.F90 - allocations of big matrices fmax-random.F90 - random number generator (not used by GenIC) fragmentation: fragment.F90 - builds halos and writes catalogs distribute.F90 - distributes planes to sub-volumes generation of initial conditions: GenIC.c - taken from 2LPTic, contained in N-GenIC other tools: cosmo.F90 - cosmological routines tools.F90 - various routines direxist.c - called by F90 to check the existence of a directory The package contains also the results of an example run, see below and the INSTALLATION file for more details. ***************************************************************** 3. THE PARAMETER FILE Parameters are passed to the code through a parameter file similar to the one used in Gadget. The file named parameters in the rundir/ directory gives a list of all allowed parameters. Each line starting with # or % will be interpreted as a comment. There are two kinds of keywords in this file, those that require an argument and MUST be present, and logical keywords that require no argument and, if absent, are assumed as FALSE. # Name of the run RunFlag example # Output redshifts will be read from the file outputs, one number per line OutputList outputs # Cosmological parameters; PowerSpectrum gives the primordial spectral index Omega0 0.25 OmegaLambda 0.75 OmegaBaryon 0.044 Hubble100 0.7 Sigma8 0.8 PowerSpectrum 0.96 # These parameters describe the dark energy equation of state DEw0 -1.0 DEw1 0.0 # The EoS can be provided through a file with two columns: # 1) scale factor, 2) value of w # if the provided string is "no" then the w0-w1 parameterization is used TabulatedEoSfile no # Size of the simulated box, in Mpc. If the logical keyword BoxInH100 is # used, then the box size is provided in Mpc/h. BoxSize 200.0 BoxInH100 # Number of grid points per side, for a cubic box. For non-cubic boxes, see below. GridSize 100 # Seed for random numbers RandomSeed 1099 # The first flag requires catalogs to be written in ascii, the second # requires that the quantities are given in h100 (Mpc/h, Msun/h) # instead than in true Mpc, Msun (default) CatalogInAscii OutputInH100 # Starting redshift for Past Light Cone output (requires PLC option), # negative values mean that PLC output is not requested StartingzForPLC -1 # Further parameters required by GenIC: # you can provide the input power spectrum in a file, if "no" is # specified then the Eisenstein & Hu fit is used FileWithInputSpectrum no # this gives the unit of measure of length (in cm/h) used in the input # file of the power spectrum, 0=Mpc/h InputSpectrum_UnitLength_in_cm 0 # WDM is implemented as an exponential cutoff of P(k) WDM_PartMass_in_kev 0.0 # Special behaviour: # WriteFmax % the code writes the Fmax file readable by Pinocchio-2 # WriteVmax % the code writes the vmax files readable by Pinocchio-2 # WriteRmax % the code writes the Rmax file # WriteDensity % the code writes the linear density # WriteDisplacements % the code writes the Zel'dovich displacements at the first output redshift # DoNotFragment % the code writes Fmax, vmax, the run.info e run.var files, and then exits before fragmenting See the section OUTPUTS for a better explanation of the format As in N-GeniIC and 2LPTic, you can provide a power spectrum to the code. The filename containing the code will be given as an argument of the FileWithInputSpectrum keyword. The file is supposed to provide two columns with Log k (in h/Mpc) and Log ( k**3 * P(k) ). ***************************************************************** 4. PRE-COMPILER OPTIONS There are three pre-compiler options that can be specified in the Makefile. The first, PLC, switches on the code that generates the output in the Past Light Cone. In this case the code chooses one random position in the box to locate the observer, replicates the box to fill the spherical volume defined by the comoving distance at the redshift provided through StartingzForPLC, and stores the properties of all the groups that cross the PLC in each of the replications. The catalog is output at the end. The second options, DO_NOT_USE_GENIC, generates the linear density field with the native PINOCCHIO generator. There is no reason to prefer it to the GenIC one, except that this way the code does not need the GSLs any more (though some coding is needed to compile without them), or that GenIC, in this version, cannot generate non-cubic grids. In case you need to generate a box with different number of grid points per side, you have to switch on DO_NOT_USE_GENIC and NON_CUBIC. In this case in the parameter file you will have to provide three grid sizes, like e.g.: GridSize 100 128 144 ***************************************************************** 5. OUTPUTS The code produces the following files: - pinocchio.[output redshift].[run name].catalog.out It gives, for the specified output redshift, the catalog of all halos with at least 100 particles; this number can be changed by changing the value of MIN_MASS_FOR_CAT in pinocchio-module.F90. The file contains the following information, as specified in the file header that is written when the keyword CatalogInAscii is specified in the parameter file (here we use OutputInH100): # Group catalog for redshift [redshift] and minimal mass of 100 particles # All quantities are relative to H0=100 km/s/Mpc # 1) group ID # 2) group mass (Msun/h) # 3- 5) initial position (Mpc/h) # 6- 8) final position (Mpc/h) # 9-11) velocity (km/s) # 12) number of particles If CatalogInAscii is not specified, the same quantities are provided in fortran binary format. Floating-point quantities are in double precision. - pinocchio.[output redshift].[run name].mf.out It gives, for the specified output redshift, the mass function of all halos with at least 100 particles; this number can be changed by changing the value of MIN_MASS_FOR_CAT in pinocchio-module.F90. It is an ascii file with the following format (as specified in the file header, and in the case of OutputInH100): # Mass function for redshift [output redshift] # All quantities are relative to H=100 km/s/Mpc # 1) mass (Msun) # 2) n(m) (Mpc^-3 Msun^-1) # 3) upper +1-sigma limit for n(m) (Mpc^-3 Msun^-1) # 4) lower -1-sigma limit for n(m) (Mpc^-3 Msun^-1) # 5) number of halos in the bin # 6) analytical n(m) from Warren et al. 2006 (Mpc^-3 Msun^-1) Errorbars give only the Poisson error on the number of halos. The analytic mass function is specified by the variable flag_ps and can be chosen from the following list: ! flag_ps=0: Press & Schechter (1974) ! flag_ps=1: Sheth & Tormen (2001) ! flag_ps=2: Jenkins et al. (2001) ! flag_ps=3: Warren et al. (2006) ! flag_ps=4: Reed et al. (2007) ! flag_ps=5: Crocce et al. (2010) ! flag_ps=6: Tinker et al. (2008) ! flag_ps=7: Courtin et al. (2010) The value of flag_ps is set in the file fmax-init.F90. - pinocchio.[run name].histories.out This file is generated at the final output redshift and gives the merger histories of halos. At each merging event the largest halo maintains its ID-number, while the other groups are labelled as non-existing and are not updated any more. In the merger trees only the halos with at least ten particles are considered. The content of the file is illustrated by the header obtained for the ascii output: # Merger histories for halos with minimal mass of 100 particles # 1) group ID # 2) belongs to # 3) linking list # 4) merged with # 5) mass of halo at merger (particles) # 6) mass of main halo it merges with, at merger (particles) # 7) unused # 8) merger redshift # 9) redshift of last major merger # 10) appearance redshift Group ID is the id-number of the halo, and corresponds to the ID of the peak of Fmax from which the halo has been created. If (i,j,k) are its coordinates in grid units, 0<=i