0) About CHIPMINK v1.0
1) Installing CHIPMINK v1.0
2) Running a job
3) Computing in detail
4) Technical remarks
\* -------------------------------- *\
0) About CHIPMINK v1.0
CHIPMINK v1.0 is a new, completely revised version of a code used to compute the Minkowski functionals (MFs) of point data sets, which was originally written by Jens Schmalzing and Andreas Rabus in 1998, now rewritten by Matthias Ostermann and Alexander Wiegand. CHIPMINK calculates the partial MFs of a given point data set by means of the germ grain model, then them adds up and determines the global densities (global MFs normalized by the density of the point sample). It comes in the MINKOWSKI-4 package, the fourth in a series of codes that have been written for the calculation of the Minkowski functionals of point sets and that can be obtained by sending mail to Thomas Buchert buchert@cosmunix.de (see also http://www.cosmunix.de/buchert_software.html).
\* -------------------------------- *\
1) Installing CHIPMINK v1.0
The code and its helper modules form the MINKOWSKI-4 package which is contained in the g-zipped tar-archive 'minkowski4.tar.gz'. The file expands upon the following hierarchy of directories:
./minkowski4/
./minkowski4/dat/
./minkowski4/jobs/
./minkowski4/src/
./minkowski4/src/nbr/
./minkowski4/src/ran/
./minkowski4/src/uti/
./minkowski4/src/mfs/
./minkowski4/src/spp/
./minkowski4/src/dpp/
The source codes of the modules can be found in the directory 'minkowski4/src/'. The module 'src/nbr/' determines a list of neighbours, i.e. points in a distance up to a given maximal radius, for any given point data set (in the following just called 'neighborlist'); 'src/mfs/' reads the neighbourlists and calculates the four MFs and puts them into the output file. The third and fourth, additional modules 'src/spp/' and 'src/dpp/' throw randomly distributed points into the unit cube ('spp' for a single Poisson process, resp. 'dpp' for a double Poisson process) and thus provide data which is required for the volume computation as well as for test runs. Information in more detail can be found below.
To compile and link the CHIPMINK modules, use the shell script 'install' in the main directory 'minkowski4'. To execute the script, type in
sh install
on your shell. If needed, you can also compile and link the modules separately using the makefile in the respective directory.
With the shell script 'clean' you can now clear the source directories. It will remove unnecessary files like ".o" etc. For this operation, type "sh clean" in your shell. If you want to remove the executable files as well, use the script 'tidy'.
\* -------------------------------- *\
2) Running a job
A test job can be run using
bash runTests.sh
To run a customized job on a given point sample just follow these steps:
1. Extract your point sample to the folder ./minkowski4/dat/PI/SI/points/ (or specify the -p option in the Parameters file)
PI is the name of the project and SI the name of the point sample within this project.
The latter may be useful when extracting data with different properties from the basic data e.g. a certain selection of galaxies by luminosity.
2. Extract or generate random Poisson points that fill the full mask in ./minkowski4/dat/PI/SI/random/ (or specify the -P option in the Parameters file)
Make sure that the points are continuously distributed in the outer boundary. Inner boundaries are not supported and holes in the distribution of the random points will yield wrong results
3. Specify the other parameters of your sample in the file Parameters found in the ./minkowski4/ folder
4. Run CHIPMINK with these parameters by using
bash runParameters.sh -n1 Parameters
The -n1 option is needed but only takes effect if you specified several files to analyze. Then it stands for the index of the file in the list of files you specified in the Parameters file.
5. Find the results in the folder ./minkowski4/jobs/PI/SI/RI/mfs/ and if you have gnuplot installed there are plots generated in ./minkowski4/jobs/PI/SI/RI/plot/
In addition to the analysis program, there is a generator that throws random points in a box and a generator for a Double-Poisson point process that also throws the corresponding random points in a box. The poisson generator can be run in a similar way by bash runPoissonGenerator.sh PoissonParameters.
\* -------------------------------- *\
3) Computing in detail
In the Boolean grain model all Minkowski Functionals - apart from the volume - are localized on the surface of the structure. They can therefore be calculated by adding up partial MFs. These can be determined by the local intersection of the Boolean spheres. The statistical weight of intersections of more than three spheres is identical to zero, therefore we only take into account intersection circles of two spheres and intersection points of three spheres (triple points). [Since we avoid boundary effects by neglecting points near the boundary (i.e. twice the maximal Boolean radius) we don't have to determine any other intersection parameters.]
All in all, for a given point of the data set we calculate (for each Boolean radius)
a) the uncovered surface area of the Boolean sphere around that point,
b) the intersection circles of the Boolean sphere around that point with those of the neighbouring points,
c) the triple points of the intersection with the spheres around any two neighbours.
After determining the arc length (uncovered segment of the intersection circle) and the area portion of the intersection circles, we are now able to calculate the partial MFs by
a) v_1 = A/(4*pi*R^2), where A is the uncovered surface area of the sphere of Boolean radius R,
b) v_2 = A/(3*pi*R) + l*alpha/(6*pi), where l*alpha is the uncovered portion of the arc length segment,
c) v_3 = A/(4*pi*R^2) + d*R/(4*pi*rho) + epsilon/(4*pi), where rho is the radius of the intersection circle of two spheres and d is the distance of their centers; epsilon, which is called spherical excess, is calculated via the formula of l'Huilier and denotes the contribution of the triple points to the partial Euler characteristic v_3.
Since the volume of the Boolean structure is not localized on the surface of the structure we cannot calculate it in a similar way. We therefore throw randomly distributed points into the mask which was used for the given point data set. Next, we determine the neighbourlists which consist of "real" points (i.e. those of the given point data set) for these random points. Now, in a second Poisson process, we throw N random points into the points' neighbourhoods and determine whether the random point is covered by a sphere around any of the "real" neighbours or not. Thus we calculate the fraction of volume covered by Boolean spheres around "real" points in that area. Hence, we defined a partial MF for the volume similar to v_1 to v_3. We add up v_0 and normalize it by the overall volume of the observation mask to get the global volume of the structure. (NOTE: Of course, we have to take into account neglecting points near the boundary again, so we actually have to normalize by the volume of the new, smaller mask)
In addition there are also two other volume methods available.
One throws random Monte Carlo points into the spheres around each data point and determines the fraction of volume within the sphere that is contained in 1. only this sphere, 2. the intersection of this sphere with one other sphere, ... n. the intersection of the sphere with n other spheres. Summing the corresponding volumes weighted by the inverse number of spheres it belongs to (to avoid double counting) we get an estimate of the volume contained in the structure formed by all the spheres. Dividing by the full volume of the mask gives the volume fraction v_0.
The other method throws the Monte Carlo points directly into the full mask and determines the fraction of them that end up within the volume defined by the union of all spheres.
\* -------------------------------- *\
4) Technical remarks
- If you want to suppress status output on the console define SHUTUP in tools.h. If you want to suppress any other output (especially nondeadly error messages) define SILENT in addition.
- If needed you can increase the precision of the MF calculation by adjusting the parameter NMOPO in tools.h for the volume functional v_0 and the parameters of romberg in geometry.c for the other three functionals v_1-v_3.
- In tools.h you can also adjust the maximally allowed number of neighbours by modifying NEIGHBOURMAX. However, for realistic structures, there should be no need to do so. Usually, if there are more neighbours than that, you chose the maximal radius too large. This brings you into a region where the functionals are either zero (v_1-v_3) or one (v_0) and there is not much to be learned anyway because the balls fill up the full volume.