SimAn: Simulation Analysis Library

Deprecation

Important: SimAn will soon be deprecated in favour of pynbody which I'm developing as part of a community effort. Pynbody will bring much of the philosophy of SimAn in a lighter-weight, more standards-compliant python package. At the moment, pynbody does not have anything like the range of features of SimAn, so you may still wish to continue with SimAn, but within a few months we hope that pynbody will encompass most of the relevant functionality.

I still intend to put together a SimAn 0.31 package as a final release.

Quick Reference

If you need to get/install/configure siman, read the page you're on already. Otherwise you probably want to read Getting Started Interactively (python).

What is SimAn?

SimAn is a library for analysing astrophysical SPH simulations (with particular emphasis on cosmological simulations). Currently it has no support for Eulierian-based simulations, but this may be incorporated in the future.

SimAn incorporates a visualisation class which allows for real-time high frame rate rendering of data sets with particles number limited only by available memory(left).

SimAn is a python module and, if you're familiar with python, you can just import siman at the top of your code and run with it. It also comes with the script visiman.py which, assuming you compile with visualisation support, opens a view of your simulation in an OpenGL window and allows further interaction through an IPython shell (if IPython is available) or just a plain python prompt.

Availability

Coming soon version 0.31 (November 2010) with better numpy support, delayed evaluation (allowing arbitrary array manipulation without calculating memory-intensive intermediate steps), automatic gzipping/gunzipping of files at load/save time, and many other features and bug fixes. Apologies that the 'release' of the new version keeps slipping back — ask for git access if you want the bleeding edge.

Currently available — version 0.30 (26 Aug 09) with pilot NumPy integration and multi-file support in visualiser. Also many improvements under the hood. Download here.

Installation on Mac OS X Intel

Binary version for 10.5 now available; see the download page.

Under 10.6, please compile from source. Unfortunately SimAn visualization makes use of the wx toolkit which currently only runs in 32-bit mode. (This is likely to be solved shortly.) SimAn analysis code runs just fine under 64-bit, but if you need the visualizer you will need to set the appropriate environment variable:

export VERSIONER_PYTHON_PREFER_32_BIT=yes
visiman.py sim_file

As stated above, this is only a temporary situation while the wx toolkit 64-bit compatible builds stabilize.

Installation on Other UNIX/Linux

Installing SimAn is now much simpler thanks to python's distutils:

Download and extract the SimAn tar
If you don't already have the boost libraries, download them and extract the boost_1_xx_y folder to siman/.
You do not need to perform any build steps on boost, just make it available.
(The installer also respects BOOST_ROOT environment variable if you already have a boost installation.)
For visualisation, you need a GLUT distribution (including development headers) and a Python WX distribution. With a modern linux distribution such as ubuntu it's actually pretty straight forward: just open a terminal before starting the SimAn build and type
```
sudo apt-get install python-wxgtk2.8
sudo apt-get install freeglut
sudo apt-get install freeglut-dev 
```

Open a terminal and type

python setup.py build
sudo python setup.py install

That's it. Change out of the installation directory (otherwise python will get confused when you first try to load siman) and read the introduction to using siman.

More on the Dependencies

SimAn is fully cross-platform. You should be able to compile it on any machine. However, life isn't always that simple; the libraries have most recently been developed on Mac OS X and Linux machines, and if you have something else you may have to tweak some files. If you find yourself doing this, please let me know so your changes can be incorporated into later releases.

SimAn minimally depends on the boost C++ libraries and Python 2.4 or higher. If either of these are not installed on your target system, it's worth asking your system administrator to do so. (Although you can build your own versions without having root access). Python is a very common interpreted language; the Boost libraries provide an excellent extension to the already useful STL included with all modern C++ compilers. SimAn also makes use of the bjam/boost.build system which is included with boost distributions.

For visualisation, you'll need an OpenGL compatible video card and drivers plus (currently) an implementation of GLUT and also wxPython. (That you require both of these libraries is an unfortunate historical accident, and to be fixed in a future release. However, note that you no longer require freeglut: any flavour of GLUT will do fine.) To enable use on as wide a range of platforms as possible, the visualisation module is entirely optional. If the installer can't find the required dependencies, it'll simply leave out the visualisation and compile everything else.

More on SimAn

Two Frequently Asked Questions

Doesn't tipsy already do this, and do it better?. The answer is no. Tipsy and SimAn are very different: the former does a great deal more "out of the box", whilst the latter is an extensible programming framework with interactive extras. In addition, SimAn benefits from being written more recently, and therefore being able to take advantage of the increasingly ubiquitous 3d acceleration hardware.

Will SimAn get a more extensive GUI? SimAn is intended primarily as a programming library, not an interactive tool. However, if time permits, I will add an interactive toolbox to access the most common functions.

Design Considerations

SimAn is designed to be a quick, flexible way of analysing simulations. It is written in C++ and can either be included as a set of libraries for further C++ development or, more likely, used directly from Python.

Its main aim is to isolate the details from the fundamental processing being performed. It does this in three major ways:

Data abstraction - the data is accessible via an abstract base class (SimSnap). This can represent a file of any implemented format (currently Gadget or Tipsy files), or a subset of a loaded file, or a file with some transformation performed on it, or a generated set of particles. Your analysis routines never need to be aware of the source of the data.
Comprehensive unit conversion (Unit) - specify the units of your input files in human-readable form. Then your procedures can query conversion factors to any other unit of their choice. Or request the underlying data is entirely converted to a new scheme of units (convertUnits).
Removal of loops over particles - by providing general schemes to transform data, fewer loops are required which clarifies code and speeds up execution from interpreted languages.

In addition to these three fundamental ideas:

SimAn is fully scriptable using Python. You can query simulation data at any level (individual particles to full-simulation operations) on-the-fly without the hassle of recompiling any C++ code.
SimAn includes a powerful visualisation engine which can display arbitary size files - limited only by the size of RAM available - on any computer with an OpenGL-compliant graphics accelerator (which includes the vast majority of computers sold in the last 5 years). Many operations such as rotations, translations, zooming, transparency changes are performed in real-time at high frame rates to allow you to explore your data totally intuitively.
SimAn is designed to be fully portable, using only cross-platform libraries.

Simulation Types

SimAn currently only supports particle-based simulations. Depending on time and need, I may eventually implement Eulerian support. If this happens, SimSnap will turn into SPHSimSnap, derived from a more general SimSnap interface which will continue to support higher-level functions (e.g. getTotalMass())

Formats

SimAn currently understands GADGET and TIPSY binary formats. The interpreters for both these formats detect and compensate for inconsistent endianness in the files (which may occur when transferring files from one system to another). It is written to be easily extensible to understand other formats, by deriving a class from SimSnap. If you write a file handler, please send it to me for inclusion in later versions, since other people are likely to find it useful!

Credits

If you make extensive use of SimAn libraries or visiman in work which leads to publication, I would be most grateful for a citation; for instance "The simulations were analysed with the aid of SimAn (http://www.ast.cam.ac.uk/~app26/siman/)".

Contact

Contact me at app26@ast... (remainder of domain name supressed to save me from spam).