ZOBOV

Version 1.0 Documentation

Note: this is the documentation to ZOBOV v.1.0, not the current version, included in voboz1.2.tgz. It's now easier to install, but otherwise it's about the same. See the README in voboz1.2.tgz for more info. This disclaimer may disappear if I get around to updating the text below.

   ZOBOV (ZOnes Bordering On Voidness) is a parameter-free algorithm designed to detect haloes in N-body cosmological simulations, written by Mark Neyrinck. It is an inversion of the halo-finding algorithm, VOBOZ, which was developed with the guidance of Andrew Hamilton and Nick Gnedin. This file contains instructions on installing and using ZOBOV. It would be difficult to use these instructions by themselves; they are intended to be used in conjunction with the paper describing ZOBOV, available at arXiv:/0712.3049. I hope that, with help from the paper, this file contains enough information to get one started using ZOBOV. Of course, questions, comments, and bug reports (without absolute guarantees of prompt fixing) are very welcome; please direct them to Mark Neyrinck. This is free software, which may be freely copied, modified, and redistributed, as long as ZOBOV and its author are acknowledged. There is no warranty or other guarantee of fitness for ZOBOV; it is provided "as is."

    The URL of this file is http://www.ifa.hawaii.edu/~neyrinck/voboz/zobovhelp.html.

    Click here to go back to the VOBOZ/ZOBOV home page. This document was last updated on Jan 5, 2008.

    Here is a table of contents, for easy navigation:
Installation
Use
    voz
        vozinit
        voz1b1
        voztie
    jozov

Installation

Assuming you already have a computer and a C compiler for it, there are two things that you need to download to use ZOBOV: our software, zobov1.0.tgz; and the Qhull package, qhull2002.1.tgz. ZOBOV might work on later versions of the Qhull software, but maybe not.

    To install ZOBOV, first gunzip and untar the Qhull package into its own directory (e.g. ~/qhull2002.1/). Go into the ./src directory therefrom (e.g. ~/qhull2002.1/src/), and mess around with the Makefile until it lets you compile everything via make. Qhull also includes a utility which is supposed to ease this process, Make-config.sh.

    Next, you get to compile ZOBOV itself. Gunzip and untar zobov.tar.gz, whose contents will go into their own, zobov/ directory. You should get the following files:
Makefile      jozov.c       voz.h         voztie.c readfiles.c   voz1b1.c      vozutil.c findrtop.c    readme.txt    vozinit.c

Now, unfortunately, more Makefile fiddling may be necessary in the ZOBOV directory, but "make" should produce for you a quartet of useful programs. Make sure that the directories linking to the Qhull header files and library file are correct in the Makefile. By default, the Makefile is set to work with a gcc C-compiler. Please email me if you encounter difficulties.

Use

The ZOBOV algorithm has two steps: (1) computing the Voronoi diagram of the simulation particles, returning the volume of each particle and its set of adjacent particles (the same as the first step of VOBOZ); and (2) grouping them into prospective voids. There are thus two different groups of programs comprising ZOBOV:

voz

This trio of programs (VOronoi Zones) computes the Voronoi diagram of a set of particles satisfying periodic boundary conditions, and, for each particle, the programs return the volume of its Voronoi cell, and its set of Voronoi adjacencies. This step is broken into three steps because the memory requirements of computing the Voronoi diagram can be prohibitive if a large simulation is analyzed directly. So, we break up the simulation into at least two equal parts in each dimension, resulting in at least eight "sub-boxes."

vozinit

    This first program does not actually have to be run, but it gives some idea of how equal the partition of the simulation will be, checks that the number of guard points is sufficient, and generates a script file which may be used to complete the "voz" step. The input parameters are:
arg1: position file -- discussed below
arg2: buffer size (default 0.1) -- discussed below
arg3: box size -- the range of positions of particles in each dimension
arg4: number of divisions (default 2) -- the no. of partitions in each dimension; must be at least 2 (giving 8 sub-boxes)
arg5: suffix describing this run -- a label for the output files

    The position file contains the positions of all particles. By default, this is a Fortran 77 - formatted file, written as below.   The user may also wish to modify the input format in readfiles.c to suit his/her own data format.

open(unit=1, file=outname, form='unformatted')write(1) num_particles write(1) (x(i),i=1,num_particles) write(1) (y(i),i=1,num_particles) write(1) (z(i),i=1,num_particles) close(1)
     The buffer size sets the size, in units such that the box size of the data cube is 1, of the buffer around each sub-box when calculating the Voronoi diagram. To reduce the amount of memory required, ZOBOV divides the particle data cube into at least two equal parts in each dimension, resulting in a minimum of eight sub-boxes. Undoubtedly, particles along the edge of each sub-box will have neighbors outside it, and the buffer should be big enough to catch all neighbors. To make sure that it is big enough, guard particles are deployed inside the buffer. If a guard particle is returned as a neighbor of particle p inside the sub-box, there is a chance that a particle outside the buffer should be included in p's list of neighbors (which also affects the volume returned). See the paper for more details on this process.
    It is possible that, for a given border size, there will be an insufficient number of guard points, a hard-coded number. If vozinit gives you an error message declaring as much, you will have to either increase the buffer size, or increase the number of guard points, set in voz.h.

    The output of vozinit is a script file which, if paths are defined to allow it, will run voz1b1 on each sub-box, and then voztie:

voz1b1

    This program (VOZ one-by-one) calculates the Voronoi diagram on one sub-box of the data cube. Ideally, one would not have to use the input parameters, since they would be set in the vozinit script file, but one argument might have to be changed if a guard point is encountered while diagramming one of the sub-boxes. Only the sub-box(es) encountering guard particles need be rediagrammed. Here are the relevant arguments:
arg2: border size arg6-8: 0 to (Ndiv-1)

    If a guard point is encountered, the easiest way to fix the problem is to expand the border size (which will result in a larger memory requirement, and calculation time). This may require the number of guard particles to be increased in voz.h and voz1b1 to be recompiled. Arguments 6-8 are labels for the sub-box being calculated.

    The output of voz1b1 is a file containing the Voronoi adjacencies and volumes of particles in the sub-box: part.%s.%02d.%02d.%02d, where %s is the "suffix," and the %02d's are the three two-digit labels identifying the sub-box.

voztie

This program ties the sub-boxes together, returning single adjacency (adj%s.dat, where %s is the "suffix,") and volume (vol%s.dat) files for the whole datacube. The volume file is formatted simply in C (not Fortran77) format: it consists of a 4-byte integer containing the number of particles, followed by an array of 4-byte floats containing each particle volume. The adjacency file is formatted in a more complicated manner to reduce its size from the doubly linked list used within the code. If you wish to access this, please look at the voztie.c code, or the jozov.c code, which reads the adjacency file.

jozov

This program (JOin ZOnes to form Voids) first finds "zones" (one for each density minimum), and then links them together in the manner described in the paper. Its arguments are:

arg1: adjacency file arg2: volume file arg3: output file containing particles in each zone arg4: output file containing zones in each void arg5: output text file arg6: Density threshold (0 for no threshold)

The density threshold is an optional parameter, which can limit the growth of voids into high-density regions. For example, if this is set to 0.2 (the canonical density of a void, overdensity -0.8), voids will not include zones with minimum density >0.2 times the mean. Note that this does not mean that voids cannot include individual particles of density > 0.2. If this parameter is zero, then ZOBOV will attain its full parameter-independence. However, you might find voids extending alarmingly into haloes.

There are 3 outputs of jozov: a zone membership file which contains the particles in each zone; a void membership file containing the zones in each void, and a text file. For the format of the first two files, please see the code. Here is an example text file. The results may not be typical, because the simulation they come from has very low mass resolution.

2097152 particles, 21700 voids. Void# FileVoid# CoreParticle CoreDens ZoneVol Zone#Part Void#Zones VoidVol Void#Part VoidDensContrast VoidProb 1 2662 260883 2.032275e-01 2.974649e+02 259 21700 2.097152e+06 2097152 1279.210938 0.00e+00 2 8645 834829 2.833641e-01 1.838204e+02 293 1 1.838204e+02 293 2.221071 4.75e-04 3 4669 451867 2.042070e-01 7.996089e+02 696 11766 1.499532e+06 1383822 2.162961 7.65e-04 . . . 21698 2488 243485 5.446460e-01 3.238563e+01 54 1 3.238563e+01 54 1.000017 1.00e-00 21699 4314 413373 3.878621e-01 8.989334e+01 121 1 8.989334e+01 121 1.000003 1.00e-00 21700 14565 1421200 3.783489e-01 1.347543e+01 11 1 1.347543e+01 11 1.000001 1.00e-00

Here is a key:

Void#: What rank the void has, in decreasing order of VoidDensContrast.
FileVoid#: The number of this void (starting with 0) in the first two files.
CoreParticle: The particle number (starting with 0) of the void's (and zone's) core particle (i.e. if CoreParticle=2, it would be the third particle in vol...dat and adj...dat). Currently, because jozov does not load in particle positions (saving memory), looking up the coordinates of this particle in the original position file is currently the only way of finding the x,y,z position of the core of the void. With some prodding, the author might change this.
CoreDens: The density, in units of the mean, of the void's core particle.
ZoneVol: The volume of the central zone of the void, in units of the volume occupied by a mean-density particle.
Zone#Part: The number of particles in the central zone of the void.
Void#Zones: The number of zones in the void.
VoidVol: The volume of the void, in units of the volume occupied by a mean-density particle.
Void#Part: The number of particles in the void.
VoidDensContrast: The density contrast of the void, i.e. the ratio between the critical density at which water in that zone would flow into a deeper zone to the minimum density.
VoidProb: The probability that that DensContrast would arise from Poisson noise, using eq. 1 of the ZOBOV paper. This probability is based on a fit to the probability distribution of DensContrasts from a Poisson particle distribution.

Note that in this example, the largest void encompasses the whole simulation. This is because subvoids are also enumerated in the list (i.e. particles may belong to multiple voids). If this situation is undesirable, a density threshold may be imposed in jozov, or subvoids can be removed from voids (e.g., particles may be assigned to the void they belong to with the smallest probability over some cut-off).