• Table of contents
• Python user guide, Reading data
  • Prerequisite
  • unsio.input module for reading data
• Reading data
  • Create/instantiate CUNS_IN object
  • Loading data
  • Getting numpy array data
  • 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 -U

unsio.input module for reading data¶

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

import unsio.input as uns_in

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 CUNS_IN object¶

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

import unsio.input as uns_in

simname="/home/jcl/gtr119_1600" 
components="disk,gas,stars" 
times="all" 
float32=True
uns = uns_in.CUNS_IN(simname,components,times,float32)

CUNS_IN constructor accepts 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. float32, is a boolean to activate (True -default) for loading data in single precision / deactivate (False ) for loading data in double precision

According to simname, unsio will detect automatically the simulation file format.

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¶

CUNS_IN class provides one universal function to get data stored in a snapshot : CUNS_IN.getData(comp, tag)

CUNS_IN.getData(comp,tag)

Args:
    comp (str) : component or list of components separeted with a coma
                   example :
                      select="gas" 
                      select="gas,stars" 
    tag    (str) : array to get
                   example :
                      tag="pos" 
                      tag="acc" 
                      pos,vel,mass,rho...

    IMPORTANT : if 'tag' is None, then 'comp' is treated as 'tag' (see above)

Return :
    status,numpy_array       (if tag is not None)
    status,value             (if tag is None)
    in both case, status=1 if success, 0 otherwise

Arrays are treated as one dimensional numpy arrays.
This function returns a boolean first, then a numpy 1D array. Boolean is set to True if the requested array exist, otherwise False.

• example : getting positions from disk component

comp="disk" 
prop="pos" 
# read positions for component disk
ok,pos = uns.getData(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.

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

• example : getting id arrays

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

• example : getting time simulation value

# get timestep of the current snapshot
ok,timex = uns.getData("time")  #  

Useful methods¶

CUNS_IN reading class, from unsio.input 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.