tesseract 0.1.0

Tesselation based Recovery of Amorphous halo Concentrations

--------------------------------------------------------------------------------

INTRODUCTION
============

The tesseract package is designed to compute concentrations of simulated dark
matter halos from volume info for particles generated using Voronoi tesselation.
This technique is advantageous as it is non-parametric, does not assume
spherical symmetry, and allows for the presence of substructure. For a more
complete description of this technique including a comparison to other
techniques for calculating concentration, please see the accompanying paper
Lang et al. (2015).

This package includes:

* vorovol: a c program for computing the Voronoi tessellation for particle data in a number of formats including Gadget-2 snapshots, ascii, and binary files.
* routines for compiling, running, and parsing vorovol output
* routines for computing concentrations using particles volumes, traditional fitting to an NFW profile, and non-parametric techniques that assume
* routines and test halos for running many of the performance tests presented in Lang et al. (2015)

--------------------------------------------------------------------------------

INSTALLATION
============

Only installation through cloning the source code is currently supported.

The easiest way to install TesseRACt from the source code is to clone the repository using mercurial.

1. **Install mercurial if you don't have it.** This is easy to do via `pip install hg` (or `pip install hg --user` if you do not have admin privileges).
2. **Clone the TesseRACt repository.** Move to the directory where you want to install TesseRACt. Then issue the command `hg clone https://[username]@bitbucket.org/[username]/tesseract` where `[username]` should be replaced with your Bitbucket username.
3. **Run the setup script.** Move into the tesseract directory and run the setup script via `python setup.py install` (or `python setup.py install --user` if you do not have admin privileges).
4. **Test the installation.** Open python and import TesseRACt via `import tesseract`. Then run help(tesseract). The first time you import TesseRACt, a few things will happen. First, a user config file will be created at `~/.tessrc` that is used to control different aspects of TesseRACt (See section below for details). Second, you will be prompted to enter a directory in which qhull will be installed. This directory will be added to the tesseract user configuration file, which can be changed at any time if you move qhull.

--------------------------------------------------------------------------------

EXAMPLES
========



--------------------------------------------------------------------------------

THE CONFIG FILE
===============

The TesseRACT user config file `.tessrc` is created in your home directory when TesseRACt is first imported. It is initialized from the default configuration script `default_config.ini` and can be edited at any time to change different TesseRACt aspects. However, the default configuration file should NOT be edited directly in case new functionality is added. Any options not provided in `.tessrc` are initialized to the values in `default_config.ini`. Currently supported configuration file options include:

* `[general]` Options for controlling TesseRACT's general performance.
* `outputdir` - Path to directory where TesseRACT output should be saved. If not provided, output will be saved in the current working directory.

* `[nfw-options]` Options for controlling how NFW profile parameters are computed.
* `default-rhoc` - The default value used for the critical density of the universe in units of `Msol kpc**-3`. (`1.1845e2 Msol kpc**-3` by default)
* `default-delta` - The default value used to define the virial over-density. This is used to calculate the virial radius and mass of a halo. (200 by default)

* `[test-options]` Options for controlling the examples provided.
* `snapshot-format` - Code specifying the format of the test halo snapshots. This should not be edited unless you convert the test halo snapshots into another snapshot format. (0 by default)
* `halodir` - Directory containing test halo snapshots. If not provided, it is assumed to be the directory within the TesseRACt distribution.
* `copydir` - Directory containing copies of the test halo snapshots initialized with different random number seeds. As these snapshots are not provided with the public distribution, this option should not be used.
* `avail-conc` - List of concentrations of the test halo snapshots. The current version of TesseRACt includes test halos with concentrations of 5, 10, 25, and 50.
* `default-series` - String specifying test series that should be run by default when `examples.run_series` is called. ('conc' by default)
* `avail-series` - List of available test series. TesseRACt currently supports the following series which are described in the Examples section below: conc, oblate, prolate, triax, npart, substr_mass, substr_rsep, substr_conc, and substr_rho0.
* `nfw-methods` - List of methods for calculating NFW parameters that are used for each test by default. (voronoi, fit, rhalf, and vpeak by default)
* `default-conc` - Default concentration used for tests (10 by default)
* `default-subm` - Default mass of subhalo used for substructure tests in terms of the parent halo's virial mass (0.1 by default)
* `default-subr` - Default radius that subhalo is placed at for substructure tests in terms of the parent halo's virial radius (0.5 by default)
* `default-subc` - Default concentration of subhalo used for substructure tests. (50 by default)
* `default-subrho` - Default density of subhalo used for substructure tests in terms of the parent halo's central concentration (0.5 by default)
* `default-ellip` - Default ellipticity of halo for test which vary triaxiality. (0.5 by default)

* `[qhull]` Options for controlling qhull.
* `install-dir` - The directory under which qhull should be installed. This is initialized the first time that the TesseRACt package is imported. If this does not point to a valid qhull installation, TesseRACt will be unable to perform the Voronoi tessellation.

For additional details on configuration file syntax, please see the documentation for the [ConfigParser](https://docs.python.org/2/library/configparser.html) package.


--------------------------------------------------------------------------------

TODO
====
Things that are being worked on:

* liscense
* create example parameter file
* create straight forward tests
* add outputfile parameter to vorovol