• Table of contents
• Python user guide, Reading data
  • Prerequisite
  • unsio module
• Reading data
  • Create/instantiate CunsIn object
  • Check valid file format
  • Loading data
  • Getting numpy array data
    • Getting floating arrays
    • Getting integer arrays
  • Getting value data
    • Getting floating value
    • Getting integer value
    • Table of possible values
  • Useful methods
  • A complete example

Python user guide, Reading data¶

Prerequisite¶

Install python wrapper using pip from your prefered python interpreter :

pip install python-unsio --user

unsio module¶

Unsio python wrapperis a module called unsio that you have to import to your python program. Example :

from unsio import *            

or

import unsio

Reading data¶

Reading UNSIO data from python language is pretty simple and is done in 3 steps:

1. UNSIO object instantiation
2. data loading
3. data extracting

Create/instantiate CunsIn object¶

Unsio python wrapper is based on C++ API with slight modifications to works with numpy arrays. Module py_unsio provides an easy way to access snapshot data from a set of methods implemented in CunsIn object. The first step is to instantiate a CunsIn object.

simname="/home/jcl/gtr119_1600" 
components="disk,gas,stars" 
times="all" 
verbose=False
uns = CunsIn(simname,components,times,verbose)

CunsIn constructor accept 4 parameters (4th is optional):

1. simname, is a string, which contain the input file you want to read (see the list of supported input files )
2. components, is a string, which contain the list of the component you want to load (see the list of components or range of particles )
3. times, is a string, which specify on which range of time data must be loaded
4. verbose, is a boolean to activate (True) / deactivate (False - default) some debugging information

Check valid file format¶

According to simname, unsio will detect automatically the simulation file format. Once object is instantiated, you can check that requested input file is supported by unsio. To do that use the following method:

 ok=uns.isValid() 

This method return True if the snapshot file format (simname) is supported by unsio, and return False otherwise.

Loading data¶

The next step consist to load a snapshot according to user requests (components and time range). To do that use the following method:

bits=""         # select properties, "" means all
ok=uns.nextFrame(bits)   # load data from disk

This function return True if a new snapshot has been successfully loaded, False otherwise
This function accepts an optional parameter, "bits", which is a string. Variable "bits" contains a list of all the data (positions, masses,velocities etc..) that the user want to load (see how to select data at loading)
This variable is used to speed up reading process in case the user does not want to load all the data but just only few of them. It can be really interesting when snapshot files are really big. If no parameter is passed to this function, then all data will be loaded.

Getting numpy array data¶

Unsio python interface provides several functions to get data stored in a snapshot. Arrays are treated as one dimensional numpy arrays. There are 2 functions which return arrays. These functions return a boolean first, then a numpy 1D array. Bolean is set to True if the requested array exist, otherwise False.

Getting floating arrays¶

Function getArrayF return two variables. First a boolean ( "true" in case of success, or "false" otherwise) and a 1D numpy array in floating format.

example:

comp="disk" 
prop="pos" 
# read positions for component disk
ok,pos = uns.getArrayF(comp,prop)  # pos is a 1D numpy array, it returns pos for disk component                                        

In the previous example, first argument 'comp' specify the component selected among gas, disk, halo, dm, stars, bulge, bndry and all. Second argument specify which properties of the component we want to get. Return array is a one dimensional numpy array.

Function getArrayF is overloaded and can accept also only one argument.

example:

prop="pos" 
# read positions for all components selected by user
ok,pos = uns.getArrayF(prop)  # pos is a 1D numpy array, it returns pos for all components selected                                         

In the above example, getArrayF has only one argument. Here we get positions data for all components requested by the user. This request occur during unsio instantiation object ( see here second parameter components )

To have a complete description of getArrayF() method, follow this link.

Getting integer arrays¶

Function getArrayI return two variables. First a boolean ( "true" in case of success, or "false" otherwise) and a 1D numpy array in integer format.

example:

comp="disk" 
prop="id" 
# read IDs for component disk
ok,id = uns.getArrayI(comp,prop)  # id is a 1D numpy array, it returns particles indexes                                       

To have a complete description of getArrayI() method, follow this link.

Getting value data¶

Unsio python interface provides several functions to get various values data stored in a snapshot.

Getting floating value¶

Function getValueF return two variables. First a boolean ( "true" in case of success, or "false" otherwise) and a value in floating format.

example:

prop="time" 
# get timestep of the current snapshot
ok,ndisk = uns.getValueF(prop)  #  

Getting integer value¶

Function getValueI return two variables. First a boolean ( "true" in case of success, or "false" otherwise) and a value in integer format.

example:

prop="nsel" 
# get #bodies selected for the current snapshot
ok,ndisk = uns.getValueI(prop)  #  

Table of possible values¶

tag value	value	description
ngas	integer	#gas particles
nhalo	integer	#dark matter particles
ndisk	integer	#old stars particles
nstars	integer	#stars particles
nbulge	integer	#bulge particles
nbndry	integer	#bndry particles
nsel	integer	#selected particles
time	real*4	snapshot time
nvarh	integer	#hydro arrays (RAMSES)

Useful methods¶

CunsIn reading class, from py_unsio module, has a set of useful methods which give information about the snapshot.

• uns.getInterfaceType(), returns a string which contains the interface type of the loaded snapshot. It can be Nemo, Gadget1, Gadget2 or Ramses.

• uns.getFileStructure(), returns a string which give information of the file structure of the snapshot. It can be range (for nemo snapshot), or component (for others snapshots)

• uns.getFileName(), returns snapshot file name.

A complete example¶

To see a complete example, follow this link.