.. _loaders:

Code-specific loaders
^^^^^^^^^^^^^^^^^^^^^

``Pynbody`` uses a number of different modules behind the scenes to take
care of loading files in different formats. Unfortunately not all of
these have the same capabilities; see below.

========= ========== ================= ========== ================= ===================================
Filetype  Can load?  Partial loading?  Can save?  Array-level save? Notes
========= ========== ================= ========== ================= ===================================
Tipsy     Yes        Yes               Yes        Yes
Gadget    Yes        No [1]_           Yes        Yes
Swift     Yes        Yes [6]_          No         Yes
GadgetHDF Yes        No [1]_           No         Yes                [2]_
Ramses    Yes        No [1]_           No         No 		    [3]_, [4]_
NChilada  Yes        Yes               No         No
GrafIC    Yes        Yes               No         No                [5]_

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



.. [1] Currently these modules do not support the standard partial
   loading mechanism. However they do allow you to load only certain
   CPU outputs. For instance if you wish to load CPU 3 data only, in
   ``Gadget`` or ``GadgetHDF``, you simply ask to load the
   specific file ``my_snapshot.003`` instead of the imaginary file
   ``my_snapshot``. In ``Ramses``, you add ``cpus=[3]`` to your load
   command, e.g. ``pynbody.load('output_00080', cpus=[3])``.

.. [2] Requires the ``h5py`` python module. You can determine whether
   you have this by typing ``import h5py`` into python. If you don't
   get an error, you have it. If you don't have it, see here
   `the h5py website <http://www.h5py.org>`_.

.. [3] Ramses gas cells are loaded and converted into ``gas`` particles,
   one at the centre of each maximally refined cell. You can ask to
   generate the particles at a higher level of refinement by passing
   in a ``maxlevel`` argument. For example,
   ``pynbody.load('output_00080', maxlevel=10)`` will place gas
   particles at refinement level 10 or (numerically) lower.

.. [4] Ramses loading is enormously speeded up if you enable the
   parallel loading facility, which splits the task of loading the
   multiple files and decoding the awkward format across multiple
   processes. To do this, you need to install the `posix_ipc
   <http://semanchuk.com/philip/posix_ipc/>`_ module which should be
   as simple as typing ``easy_install posix_ipc`` into your
   shell. See also important notes on :ref:`posix_ipc`.

.. [5] These are initial conditions generated by Bertschinger's
   `GrafIC <http://web.mit.edu/edbert/>`_ or Prunet et al's `MPGrafIC <ftp://ftp.iap.fr/pub/from_users/prunet>`_.

.. [6] Swift files can be partially loaded by specifying the cell IDs to load,
   passing ``take_swift_cells = [...]`` to the load command. This may be extended
   in future to support querying the cell geometry.

The end-user rarely needs to worry about the implementation of
different loaders, as all types of simulations are loaded with
:func:`pynbody.load` and the type is determined automatically.


.. automodule:: pynbody.snapshot.tipsy

.. automodule:: pynbody.snapshot.gadget

.. automodule:: pynbody.snapshot.gadgethdf

.. automodule:: pynbody.snapshot.swift

.. automodule:: pynbody.snapshot.nchilada

.. automodule:: pynbody.snapshot.ramses

.. automodule:: pynbody.snapshot.grafic
