HTTPS SSH
GSnap -- A galaxy snapshot analysis and manipulation application.


Currently, GSnap can...

   * Read and write GADGET type 1 snapshot files (Springel-type).

   * Compute the mass-weighted velocity dispersion of any particle type using a
     diffraction slit (mask) of arbitrary dimensions from an arbitrary
     direction.

   * Compute the mean, maximum, minimum, and standard deviation of the
     mass-weighted line-of-sight velocity dispersion over a set of random
     viewing directions (1000 directions, by default).

   * Measure the stellar velocity dispersion of stars in a specified age range.  

   * Arbitrarily shift particle positions (i.e., shift the origin of
     the coordinate system independently for each type of particle).

   * Rotate the particle positions and velocities (i.e., rotate the
     coordinate system independently for each type of particle).

   * Compute the center of mass of any particle type or combinations
     of particle types.

   * Create simple visualizations of a snapshot. Images can be saved
     to disk as PNG images or the system can be viewed interactively
     (rotated, shifted, and zoomed).

   * Interactively compute stellar velocity dispersion by placing a slit 
     over the interactive preview.

   * Create high quality visualizations of the gas component using a volume
     rendering algorithm and SPH smoothing.

   * Create high quality visualizations of the stars---including a model
     for dust reddening and new star formation.

   * Interpolate particle positions between snapshot files using a
     3rd-order interpolation scheme. This is primarily for the purpose
     of creating movies of the merger simulations.

   * Display information about a snapshot (simulation time, number of
     each type of particle, total masses of each particle type).

   * Modify the ages of particles and convert among particle types. For
     instance, disk star particles an be converted to new star particles.

   * Interpret ECMASripts written by the user in order to extend the 
     functionality.

We plan to add the ability to...

   * Separately measure the velocity dispersion of stars that
     dynamically "belong" to the disk as opposed to stars that can be
     dynamically identified as bulge stars.

   * Read and write files from the Gasoline simulation code.

   * Perform other types of visualization, such as velocity maps, vector plots,
     and streamline plots. 

We may ultimately add the ability to...

   * Read and write snapshots in HDF5 format.

   * Read and write type 2 snapshots.

   * Convert among the three formats: HDF5, types 1, and type 2.

   * Read and analyze snapshots from other codes such as Enzo and Arepo.


COMPILING:

   To compile GSnap, first make sure that you have a valid installation
   of Qt-4.6 (or later). The Qt development tools (qmake, moc, and uic)
   are essential. OpenMP is also recommended. If you do not wish to use
   OpenMP, you will have to edit the gsnap.pro file, removing references
   to '-fopenmp'. A compiler supporting the majority of C++11 features is also
   required. The preferred compiler is g++ 4.7 or later. Using a compiler 
   other than g++ may require the code or the project file to be modified.

   Enter the src/ directory and issue the command:

   $ ./build.sh

   That's all there is to it at this point! 

   Once again, if you are not using g++ (GCC) to compile GSnap, you will likely
   have to edit the gsnap.pro file in order to compile successfully. You may 
   also have to remove several GCC-specific statements in the code. Consult 
   your compiler documentation for performance-enhancing compiler flags.
   Eventually, pre-processor directives will be included in order to ease the
   process of using another compiler. 


INSTALLING:

   On Unix-like systems, the code can be installed by issuing the following 
   command with root privileges

   $ make install


UNINSTALLING:

   On Unix-like systems, the code can be uninstalled using

   $ make uninstall


USAGE:

   Usage instructions can be found in the documentation at:

   src/HTML/html/Home.html

   If you are using GSnap from the command line in a Unix or Unix-like 
   software environment, then you can take advantage of GSnap's BASH auto-
   completion functionality. After installing GSnap, open a new instance 
   of BASH and type 

   $ gsnap -[TAB][TAB]

   Pressing the [TAB] key twice after the dash "-" will display all of the 
   possible command line options. Typing

   $ gsnap --vi[TAB]

   will automatically complete the command name "--view", since this is the 
   only command that begins with "--vi." Furthermore, typing

   $ gsnap --view [TAB][TAB] 

   will provide you with a list of all possible --view options. Then, typing

   $ gsnap --view i[TAB]

   would automatically auto-complete to "gsnap --view interactive" since 
   "interactive" is the only view option that begins with "i". 

   in general, typing [TAB][TAB] after any command will display a list of 
   likely appropriate input. Typing

   $ gsnap --script [TAB][TAB]

   will display a list of script files (ie.e files ending with ".js" or 
   ".qs") along with the names of subdirectories (because the subdirectories
   may contain scripts). Suppose the current directory contains files named
   my_script.qs and my_other_script.js as well as hundreds of snapshot files
   and image files. After pressing [TAB][TAB], only the two script files would 
   be listed as the next possible command line arguments. Other commands work 
   similarly.


CODE DOCUMENTATION:

   To generate detailed source documentation, first make sure that you have
   Doxygen, LaTeX, and GraphViz installed. Then enter the src/ directory and
   issue the command:

   $ doxygen

   This will generate documentation in the Documentation/ directory.
   To view the HTML version of the documentation, open the file

   Documentation/html/index.html

   with your browser of choice. 


CONTRIBUTING:

   * A Git repository containing the source code is available on BitBucket:

     https://bitbucket.org/idius/gsnap

     You can create a fork and make a pull request. If your contributions are
     frequent or significant, you may be given access to the master repository.

   * Do not edit the HTML help files directly. Instead, use the Zim wiki
     software (http://zim-wiki.org/) to edit the source. Then generate HTML
     files by running

     $ ./src/HTML/build_help.sh

ADDING A FORMAT READER / WRITER:

   Adding a new format is a fairly straightforward process. Suppose you want to
   add input/output routines for a snapshot file format named "dreamy."

   Step 0: Add an enumerator named "dreamy" to the snap_format enumeration in
   Core/global.h.

   Step 1: Add a header and source file for the dreamy format in the IO/
   directory. The file names should be dreamy.h and dreamy.cc. In these files,
   declare a class named dreamy_header to store your header data and a class
   named dreamy_io to store your snapshot data and methods. Notify the build
   system of these files (if your IDE hasn't already done this for you) by
   adding dreamy.h to the HEADERS section of gsnap.pro and creamy.cc to the
   SOURCES section of the same file.

   Step 2: Design dreamy_header and dreamy_io so that they can contain all of
   the data stored in the dreamy snapshot format. The class dreamy_io should
   contain a member of type dreamy_header, named "header". Remember to #include
   "Core/global.h" and "IO/basic_io.h" in dreamy.h. Also, include dreamy.h in
   io.cc.

   Step 3: Examine the generic_header structure and the meta_particle structure
   to see if there are any kinds of data that are stored in dreamy that can't
   be stored in the existing structures. If necessary, modify the generic_header
   and meta_particle structures to accommodate your data.

   Step 4: In your dreamy_io class, implement public methods named save_as(),
   load(), check_format(), to_snapshot(), and from_snapshot() with the same call
   signatures and general behaviors as the corresponding members of the
   gadget_io class (Note: studying the gadget_io implementation is very
   instructive). One of the constructors of dreamy_io should be

       dreamy(char* fname);

   where fname is the name of a file that will immidiately be loaded. It is also
   important to note that the check_format methods are static:

       static snap_format check_format(char* fname);

   Step 5: In snapshot::deduce_format() (located in io.cc), write code that will
   uniquely identify an arbitrary file as a dreamy snapshot. Return
   snap_format::dreamy when the file appears to be a dreamy file.

   Step 6: In snapshot::check_format() add:

       else if (fmt == snap_format::dreamy)
       {
           return dreamy_io::check_format(fname);
       }

   to the else if chain.

   Step 7: Compile.

   Step 8: Test the code extensively! If possible, include a URL to a sample
   snapshot and write test code.

   Step 9: Make a pull request.

REPORTING PROBLEMS:

   To report an issue, visit GSnap's page on BitBucket, click the "Issues" link,
   and describe the problem along with as many details as possible.


TODO:

   * Redesign the graphical user interface.

   * Compute gas temperatures and pressures.

   * Include a version of the volume renering scheme that is optimized for
     rotations and interpoliation.

   * Show streamlines / velocity vectors of particles.