



TesseRACt 0.1.1 documentation

Welcome to TesseRACt’s documentation![¶](#welcome-to-tesseract-s-documentation "Permalink to this headline")

============================================================================================================

Contents:

Introduction[¶](#introduction "Permalink to this headline")

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

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)](http://arxiv.org/abs/1504.04307).

This package allows users to:

* perform Voronoi tessellation through access to [qhull](http://www.qhull.org/) routines

* measure particle distribution properties like concentration using different techniques including tessellation

* replicate the performance test presented in [Lang et al. (2015)](http://arxiv.org/abs/1504.04307)

Installation[¶](#installation "Permalink to this headline")

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

TesseRACt can be installed from either [PyPI](https://pypi.python.org/pypi/tesseract) or from the source distribution.

### Installing from PyPI[¶](#installing-from-pypi "Permalink to this headline")

The easiest way to install TesseRACt is using `pip`. If you have administrative privleges on the target machine, this is done using:

```

$ pip install tesseract

```

If you do not have admin privleges, simply install it locally using:

```

$ pip install tesseract --user

```

The TesseRACt package can then be updated to the most recent stable release using:

```

$ pip install tesseract --upgrade

```

### Installing from the Source Distribution[¶](#installing-from-the-source-distribution "Permalink to this headline")

The most recent TesseRACt source distribution can be obtained by either downloading or cloning the repository from Bitbucket. Using [Mercurial](https://mercurial.selenic.com/) this is done by issuing the following command:

```

$ hg clone https://[username]@bitbucket.org/[username]/tesseract

```

where `[username]` should be replaced with your Bitbucket username. The Bitbucket repository is currently private. If you would like access to this repository, please contact [Meagan Lang](mailto:cfh5058%40gmail.com).

Once you have the TesseRACt source distribution, move into the distribution directory:

```

$ cd tesseract

```

and use the standard [Distutils](https://docs.python.org/2/distutils/) command to build and install the distribution:

```

$ python setup.py install

```

If you do not have administrative privleges, this can be done using:

```

$ python setup.py install --user

```

### Testing the Install[¶](#testing-the-install "Permalink to this headline")

To test that everything was installed propertly. From the python prompt, import TesseRACt:

```

>>> import tesseract

```

and try to access the documentation:

```

>>> help(tesseract)

```

Additional tests can be found in [*Tutorials*](index.html#document-tutorials).

### The First Import[¶](#the-first-import "Permalink to this headline")

The first time you run `import tesseract`, a few things will happen. First, a user config file `.tessrc` will be created in your home directory. This file is used to control different aspects of TesseRACt which are explained in [*The Config File*](index.html#document-config). Second, you will be prompted to enter a directory in which [qhull](http://www.qhull.org/) will be installed. This directory will be added to the user configuration file, which can be changed at any time if you move [qhull](http://www.qhull.org/).

The Config File[¶](#the-config-file "Permalink to this headline")

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

The TesseRACt user config file .tessrc is created in your home directory when TesseRACt is first imported. It is initialized from the default configuration file 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.

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

### General Options[¶](#general-options "Permalink to this headline")

**outputdir**

Path to directory where TesseRACt output should be saved. If not provided, output will be saved in the current working directory.

### NFW Options[¶](#nfw-options "Permalink to this headline")

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)

### Voro Options[¶](#voro-options "Permalink to this headline")

Options for controlling how tessellation is performed and used to compute concentration.

**scale-conc-func**

String identifying what function should be used to scale concentrations computed using tessellation volumes to be on the same scale as concentrations computed using traditional techniques.

**scale-conc-param**

Series of float parameters for the scaling function **scale-conc-func**.

### Test Options[¶](#test-options "Permalink to this headline")

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[¶](#qhull-options "Permalink to this headline")

Options for controlling [qhull](http://www.qhull.org/).

**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.

Tutorials[¶](#tutorials "Permalink to this headline")

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

### Running Tests[¶](#running-tests "Permalink to this headline")

Included with TesseRACt are several example halo snapshots that can be used

to run a variety of tests. The primary function that should be used for running

tests is `tesseract.tests.run\_test()`. This function will create the necessary

files, perform the tessellation, and calculate the NFW parameters using different

techniques. For example, to test traditional fitting against tessellation based

concentration measurement on a c = 10 halo:

```

>>> tesseract.tests.run\_test(c=10,nfwmeth=['fitting','voronoi'])

```

You can also decrease the resolution by some factor:

```

>>> tesseract.tests.run\_test(c=10,nfwmeth=['fitting','voronoi'],decimate=10)

```

or change the shape of the halo:

```

>>> tesseract.tests.run\_test(c=10,nfwmeth=['fitting','voronoi'],squishz=0.3)

```

### Running Test Series[¶](#running-test-series "Permalink to this headline")

In addition to individual tests, you can also run a series of tests that vary

one parameter at a time using `tesseract.tests.run\_series()`. For example,

to test how tessellation based measurement of concentration is affected by how

prolate a c=50 halo is, run:

```

>>> tesseract.tests.run\_series('prolate',c=50,nfwmeth='voronoi')

```

The specific ‘prolateness’ values tested can be specified by either a list of values:

```

>>> tesseract.tests.run\_series('prolate',vlist=[0.3,0.4,0.5],c=50,nfwmeth='voronoi')

```

or a range and number.:

```

>>> tesseract.tests.run\_series('prolate',vlim=(0.3,0.5),Nv=3,c=50,nfwmeth='voronoi')

```

### Running TesseRACt On Your Data[¶](#running-tesseract-on-your-data "Permalink to this headline")

If your data is in one of the formats currently supported by TesseRACt,

measuring the concentration using tessellation is relatively simple.

#### Creating a Parameter File[¶](#creating-a-parameter-file "Permalink to this headline")

First you will need to create a parameter file either by hand or using

`tesseract.voro.make\_param()`.:

```

>>> parfile = '\full\path\to\parameter\file'

>>> tesseract.voro.make\_param(parfile,\*\*param)

```

where `param` contains all of the required keywords listed under

`tesseract.voro.\_paramlist`. If you do not wish to transform or

downsample your particles and the data does not have periodic boundary

conditions, you can autofill many of the parameters using

values from the provided example parameter file `tesseract.voro.\_example\_parfile`.:

```

>>> tesseract.voro.make\_param(parfile,basefile=tesseract.voro.\_example\_parfile,\*\*param)

```

In this case, the only parameters you will need to provide in `param` are

> 

> * **FilePrefix**: Prefix to add to file names.

> * **PositionFile**: Full path to file containing the particle data.

> * **PositionFileFormat**: An integer specifying what format the **PositionFile**

> 

> 

> is in (See `tesseract.io.read\_snapshot()` for a list of valid formats).

> \* **OutputDir**: Full path to directory where files should be saved.

> 

> 

> 

#### Running the Tessellation[¶](#running-the-tessellation "Permalink to this headline")

To run the actual tessellation, use `tesseract.voro.run()` with the

parameter file you created in the previous step.:

```

>>> tesseract.voro.run(parfile)

```

If you would like the output to be piped into a file rather than displayed,

provide an output file:

```

>>> tesseract.voro.run(parfile,outfile='/path/to/output/file')

```

If the error code returned is not 0, this means that there was a problem

with the tessellation. The most common reason for a failed tessellation is

a problem with the input snapshot.

#### Calculating the NFW Parameters[¶](#calculating-the-nfw-parameters "Permalink to this headline")

Once the tessellation is successful, NFW parameters can be computed from the

volumes using `tesseract.voro.get\_nfw()`:

```

>>> tesseract.voro.get\_nfw(parfile,method='voronoi')

```

Similarly, for using traditional fitting:

```

>>> tesseract.voro.get\_nfw(parfile,method='fitting')

```

or both:

```

>>> tesseract.voro.get\_nfw(parfile,method=['voronoi','fitting'])

```

### Creating Snapshots[¶](#creating-snapshots "Permalink to this headline")

If your data is in a format that is not currently supported by TesseRACt,

fear not! The `tesseract.io` module provides utilities for writing your

data to a format that is supported. Simply load the masses and positions for

your particles as numpy arrays and call `tesseract.io.write\_snapshot()`:

```

>>> print type(mass), mass.shape

(<type 'numpy.ndarray'>, (N,))

>>> print type(pos), pos.shape

(<type 'numpy.ndarray'>, (N,3))

>>> filename = '\path\to\new\snapshot.dat'

>>> format = 0 # This is a binary file containing just masses and positions

>>> tesseract.io.write\_snapshot(filename,mass,pos,format=format)

```

Then just set ‘PositionFile’ and ‘PositionFileFormat’ to the new file name and

format in your parameter file from above.

Code[¶](#code "Permalink to this headline")

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

Indices and tables[¶](#indices-and-tables "Permalink to this headline")

=======================================================================

* [Index](genindex.html)

* [Module Index](py-modindex.html)

* [Search Page](search.html)

### [Table Of Contents](index.html#document-index)

* [Introduction](index.html#document-intro)

* [Installation](index.html#document-install)

	+ [Installing from PyPI](index.html#installing-from-pypi)

	+ [Installing from the Source Distribution](index.html#installing-from-the-source-distribution)

	+ [Testing the Install](index.html#testing-the-install)

	+ [The First Import](index.html#the-first-import)

* [The Config File](index.html#document-config)

	+ [General Options](index.html#general-options)

	+ [NFW Options](index.html#nfw-options)

	+ [Voro Options](index.html#voro-options)

	+ [Test Options](index.html#test-options)

	+ [qhull Options](index.html#qhull-options)

* [Tutorials](index.html#document-tutorials)

	+ [Running Tests](index.html#running-tests)

	+ [Running Test Series](index.html#running-test-series)

	+ [Running TesseRACt On Your Data](index.html#running-tesseract-on-your-data)

	+ [Creating Snapshots](index.html#creating-snapshots)

* [Code](index.html#document-code)

### Related Topics

* [Documentation overview](index.html#document-index)

### Quick search

 Enter search terms or a module, class or function name.

 

 ©2015, Meagan Lang.

 

 |

 Powered by [Sphinx 1.3.5](http://sphinx-doc.org/)

 & [Alabaster 0.7.10](https://github.com/bitprophet/alabaster)

