FITS generation of Bifrost output data¶

Mats Carlsson, Viggo Hansteen

General principles¶

Database files should be in a format similar to IRIS level 2: 3D cubes of data (x,y,z) with one variable per file. One extension containing the z-grid.

Naming convention¶

Files should have names BIFROST_runname_variable_snap.fits

where runname is the name of the run, variable is the Bifrost variable name as defined in osc_data__define snap is a three-digit snapnumber starting from 000. Above 999 it becomes four digits, etc

Naming convention for the run: $id$size$dx{_tag1,}{_tag2,}...

$id$ is a two-character description of the region/magnetic field topology modelled. This is chosen from a set of defined values where new values need to be decided upon by the Bifrost consortium. So far, these have been defined: * qs quiet sun * ch coronal hole * en enhanced network * ar active region * um umbra

$size$ is size in Mm for the longer dimension and $dx$ is resolution in km. Both are padded with zeros from the left to always be three digits. Examples: * en024048 (aka cb24bi) * en024048_hion (aka cb24bih)

024 is size in Mm 048 is resolution in km _hion shows it is including hion

tags can be freely constructed to increase the precision of the runname. Note that Bifrost snapnames can be different from runname (although a convergence is aimed for). In order to ensure traceability in joblog files it is an advantage NOT to rename all snap-files to conform to a possibly evolving naming convention but instead keep the snapname and just update the runname.

Centering, handedness and units¶

All variables should be cell centered on a right-handed system with z increasing upwards. This means that cubes first should be cell centered and then with flipped z-axis. We also need to flip the y-axis (we could have chosen to flip the x-axis instead but have here chosen the y-axis). Vector quantities along z and y axes need to have flipped sign as well. Index should run the same way as the axis which means that z[0] is at the bottom and z[nz-1] at the top. Compared with the Bifrost snapshots we achieve this by:

x=d->getx()
y=d->gety()
z=-reverse(d->getz())
dum=zup(d->getvar(‘bz’,snap))
bz=-reverse(reverse(dum,3),2)

All units should be SI and given in FITS keywords (Mm, m/s, kg*m/s, T, W/m^3, nm, etc)

FITS keywords¶

keywords marked with *** are non-standard and subject to discussion

'INSTRUME','Bifrost',' Data generated by the Bifrost code'
'OBJECT  ',run_name,‘ Bifrost run name’
'BTYPE   ',cvar,‘ Data variable’
'BUNIT   ',bunit,‘ Data unit’
'CDELT1  ',d->getdx(),' [Mm] x-coordinate increment'
'CDELT2  ',d->getdy(),' [Mm] y-coordinate increment'
'CDELT3  ',d->getdz(),' [Mm] (non-uniform) z-coordinate increment'
'CRPIX1  ',1,' Reference pixel x-coordinate'
'CRPIX2  ',1,' Reference pixel y-coordinate'
'CRPIX3  ',1,' Reference pixel z-coordinate'
'CRVAL1  ',0.0,' [Mm] Position pixel 1 x-coordinate'
'CRVAL2  ',0.0,' [Mm] Position pixel 1 y-coordinate'
'CRVAL3  ',-(d->getz(iz[nz-1])),' [Mm] Position pixel 1 z-
           coordinate'
'CTYPE1  ','x',' [Mm] Label for x-coordinate’
'CTYPE2  ','y',' [Mm] Label for y-coordinate'
'CTYPE3  ','z',' [Mm] Label for z-coordinate'
'CUNIT1  ','Mm',‘ Unit for x-coordinate’
'CUNIT2  ','Mm'.‘ Unit for y-coordinate’
'CUNIT3  ','Mm',‘ Unit for z-coordinate’
*** 'ELAPSED ',d->getsnapt(),' [s] Time of snapshot
*** 'DATA_LEV' ,2, 'Data level'
'ORIGIN' ,'ITA/Oslo', 'Origin of data'

here follows all variables from the Bifrost .idl file. Variables with more than 8-characters or variables that have a name identical to a standard FITS keyword have an 8-character keyword version. The original .idl variable name is always written as a comment to the keyword. $Id$ string comments from the .idl file are also copied as FITS comments.

Extension 1: z-axis

'EXTNAME ',’Z axis’,‘ Extension name’
‘BTYPE   ‘,’z’,’ Data variable’
'BUNIT   ',’Mm’,‘ Unit for z-coordinate’

possible additional keywords

*** ‘OBSERVER’
*** ‘DATE_OBS‘  could be used such that sorting in the data-base looks
            OK. Use data for first snapshot and add ELAPSED?

A number of keywords are defined for IRIS that could also be of use for Bifrost. Among them are the keywords describing the range of the data: DATAMIN, DATAMAX, DATAMEAN, DATAMEDN, DATAP01, DATAP10, DATAP25, DATAP75, DATAP90, DATAP98, DATAP99, DATARMS. Should these be included also from Bifrost?

What other data would be useful for search-purposes? Horizontal mean of unsigned magnetic flux and signed magnetic flux at z=0 comes to mind.

Where should the name of the variable be stored? Have not found a FITS standard for this. Since BUNIT is used for the unit and we have the pair CUNITn, CTYPEn for axis unit and name/label it seems logical to use BTYPE for the variable name. DATA_LEV was used for Hinode but it seems IRIS will use LVL_NUM instead. What should be used? Both are now going to be in IRIS headers

level 2 files are made with br_make_fits,snapname,it,cvar,id=id

Level 3 files¶

level 3 files have four-dimensional cubes to be used with crispex. There is a need for speed so it is possible to choose limited height-range and even data scaled to 16 bit integer or byte. Also log of a variable is possible. Cubes will be large so it is not possible to keep the full cube in memory.

Crispex uses [x,y,lambda,t] and [lambda,t,x,y] cubes. For Bifrost variables this corresponds to [x,y,z,t] and [z,t,x,y]. level 3 files are made from level 2 files with br_make_fits_level3,run_name,it,cvar

Extra keywords for im-file:

'CDELT4  ',dt,' [s] (non-uniform) t-coordinate increment'
'CRPIX4  ',1,' Reference pixel t-coordinate'
'CRVAL4  ',t[0],' [s] Time pixel 1 t-coordinate'
'CTYPE4  ','t',' [s] Label for t-coordinate'
'CUNIT4  ','s',‘ Unit for t-coordinate’

Keywords added if scaling

‘BZERO   ‘   true_value = BZERO + BSCALE*array_value
‘BSCALE  ’

Changed keywords

‘DATA_LEV’,3,‘ Data level’
‘ELAPSED ’ not used
‘BTYPE   ’ gets ‘lg ‘ prepended if log variable is asked for
            if scaling is combined with log then “true_value”
            is the log value

Extension 2: t-coordinate

'EXTNAME ',’t axis’,‘ Extension name’
‘BTYPE   ‘,‘time’,‘ Data variable’
'BUNIT   ',’s’,‘ Unit for t-coordinate’

Extension 3: snap-coordinate

'EXTNAME ',‘isnap axis’,‘ Extension name’
‘BTYPE   ‘,‘snap number’,‘ Data variable’
'BUNIT   ',’ ’,‘ Unit for t-coordinate’

sp-file is made from transposing im-file using routine br_transpose_fits_level3.pro