================================================================================================
____ . ________ _________ . __
\ \ / /_ /| | _ \ _ ___ | |__ / | ___________
\ Y / | ) | | / | / \ /| _ __ _ \ _ \ / _ _ __
\ / | | |/ | \ ___| || | // __ | |> > | ( <> ) | /
_/ /_______ /|_______ _____ /______ /||| (___ / /|| _/||
/ / / / /|_|
(Formerly)
/ /_ / __ __ / | __ _________ ____
_ \ | | _ __ \ | _/ \ \ | _ __ _/ __
/ \ | | | | / | /\ _| | | | /| | /\ /
/ / || |__| |/ ___ >| |____/ || ___ >
/ / /
. .
_ /|| ____ | /
| ) | |/ \ / __ |/ __ _ __
| \ | | | / /_/ \ /| | /
_ / ||| /___ |___ >_|
/ / / /
___ _______________________________ ___
/ / / /_ /_ / \
/ / _ \ | | | ) \
( ( / \ | | | \ ) )
\ \ / / |____| _ / / /
__\ / / //
================================================================================================
VELOCIraptor (formerly STructure Finder)
================================================================================================ developed by:
Pascal Jahan Elahi (continuously)
Additional contributors:
Rhys Poulton
Rodrigo Canas
================================================================================================
Content
(for more information type make doc in main dir and in NBodylib dir and
see documents in the doc directory)
================================================================================================ src/ contains main source code for the algorithm analysis/ contains routines that can be used to analyze the (sub)structures found in a simulation. Typically, these routines read in the Nbody data and then calculate a variety of properties doc/ contains Doxygen generated latex and html file of code NBodylib/ contains library of objects and routines used by algorithm (can also be used by other routines) NBodylib/lib library containing libMath, libNBody, libKD, libAnalysis, libCosmology, libInitCond NBodylib/include/ include files NBodylib/src/ contains source code for the libraries NBodylib/doc/ contains Doxygen generated latex and html file of code
Makefile.config contains compilation flags
================================================================================================
Compiling (see documentation for more information)
================================================================================================
If you use the GNU C compiler version 5.0 or above type "make" at the command prompt.
For extra documentation, type make doc, which will produce html and latex documents using
Doxygen. This will be located in doc/html/index.html and doc/latex/refman.tex
This will contain extra information on what configuration options can be changed in the
Makefile.config file (cp Makefile.config.template and edit).
A quick summary of flags that can be adjusted are
mpi compilers, openmp flags, precision used (floats versus doubles, ints versus longs).
VELOCIraptor and all variants do not support non-Unix environments. (Mac OS X is fine; Windows is not).
================================================================================================
Running (see documentation for more information)
================================================================================================
Running is as simple as
./bin/stf -i input -s nsnaportype -C configfile
a sample of a configuation file is in examples
for mpi enabled executable
mpirun -np mutipleoftwo ./bin/stf
Note that at the moment, mpirun assumes that a single structure can fit onto the shared
memory local to the mpi thread. If larger haloes are to be analyzed, it is suggested that
the iSingleHalo option be set to 1, and the analysis is done on a shared memory machine
with enough memory. A more complete version capable of handling large structures across
mpi domains that are then searched for substructures is in the works.
Outputs:
The code will produce several files related to the configuration options (.configuration)
input data (.siminfo), units information based on the input and the configuration options (.units)
and several files containing information about the structures identified. These files can be split
into separate files containing field objects (halos) and internal structures (subhalos) if desired
(set by configuration option). The files can be in several formats
(ascii, binary [not recommended], HDF, ADIOS [in works, alpha]).
These files are
i) Properties File (.properties)
Contains a variety of properties calculate for each structure identified and also contains
some information regarding the relationship of this object to others (if object is a substructure,
what is its hostHaloID).
ii) Catalog_ files (.catalog_groups, .catalog_particles, .catalog_parttypes)
Contains particle information to extract read particles from an input file or for tracking (ie: producing halo merger trees).
The catalog_groups contains the sizes of groups and the offsets to read the associated .catalog_particles (.catalog_particles.unbound)
.catalog_parttypes (.catalog_parttypes.unbound) which just listed the IDS and Types of particles belonging to groups.
For examples of how to read this information, see the python tools included. When combined with raw particle data can
be used for extra processing (such as calculating properties/profiles not calculated by default by VELOCIraptor).
These files are also necessary if one wishes to construct "halo merger trees" or cross match haloes between catalogues.
TreeFrog, an associated MPI+OpenMP tool, has inbuilt readers for VELOCIraptor output.
iii) Field Structure / Substructure relationships (.hierarchy)
Contains the substructure hierarchy information, such as the hostID (which is -1 if it is a field structure)
an objects ID, number of direct substructures.
The code can also output a simple list which is particle id ordered that simply has the (sub)halo of a paritcle
(and is zero if particle doesn't belong to a list.) These outputs are outname.fof.grp. Note that the fof.grp
format is collected from all MPI threads and is only ascii output.
================================================================================================
Altering IO for other file types (see documentation for more information)
================================================================================================
Naturally, not all simulations will be in the io formats already written. An example of
several implemented io routines are in the src directory. The routine needs to load all
the appropriate date into a Particle array.
Currently VELOCIraptor can read Gadget (1,2), HDF, RAMSES, TIPSY, and Nchilada (alpha)
================================================================================================
Associated analysis:
================================================================================================
TreeFrog (Fomerly Halotree):
--------------------------------------------------------------------------------------------
This is a MPI+OpenMP code that reads in particle IDs information between various structure
catalogues and cross matches catalogues assuming that particle IDs are unique and constant
across snapshots. Though it is built as a cross correlator (in that it can match particles
across several different catalogues), its principle use is as halo merger tree builder. The
code produces links between objects found at different snapshots (or catalogues) and uses
several possible functions to evaluate the merit of a link between one object at a given
snapshot (or in a given catalogue) to another object in a previous snapshot
(or different catalogue). It can also produce a full graph.
This code naturally reads VELOCIraptor output and is optimised for it but can also read output
from other structure finders like AHF.
Running the code is
mpirun -np numberofmpi ./bin/treefrog -i filelist.txt -o outname -s numberofsnapsorcatalogues
The code also has many other command line arguments. Simply pass -?
Note that building a tree can be quite memory intensive for large simulations with lots of snapshots.
In mpi mode, the snapshots are split so as to approximately have the same number of particles in
structures per mpi process (load balance the memory footprint). This means that some mpi threads will
process significantly more snapshots than others (consider early times where few particles belong
to groups compared to late times where lots of structure has formed.) In that case it may be useful
to play with the load balancing when running in mpi. This can be done using a single mpi thread and
specifying the desired number of mpithreads and the desired number of particles per mpi thread.
mpirun -np 1 ./bin/treefrog -i filelist.txt -o outname -s numberofsnapsorcatalogues -z nummpi -n numpermpi
This will produce a file containing the load balance (ie: what files a mpi process should read).
Baryons (discontinued/in need of major revision)
--------------------------------------------------------------------------------------------
Tool designed to calculate numerous properties and profiles based on the input from
VELOCIraptor catalogs.
================================================================================================
Tools:
================================================================================================
Contains some example of reading routines for velociraptor output. For example will show
how a routine will read the output of velociraptor.