Kameleon Grid Tutorial
This document details usage of the grid.py command line tool.
All Python examples will eventually have a full-fledged command line interface to make it easier for users to leverage the powerful post-processing tools offered by Kameleon. The grid.py example is a good start. Navigate to python examples
cd <path_to_kameleon>/bin/ccmc/examples/python
Interrogating global metadata from a file
If you want to see what global information is stored in the file, run
python grid.py /path/to/ccmc/output/file.cdf -ginfo
This will yield all the global parameters: model name, run type, run time, etc.
To list all variables in the file, type:
python grid.py /path/to/ccmc/output/file.cdf -lvar -v
The -v verbose flag will also print variable metadata. You can use -vv for “very verbose” to get even more info.
Querying variable metadata
To get information on a specific variable, type:
python grid.py /path/to/ccmc/output/file.cdf -vinfo variable-name
where variable-name could be rho for density:
rho [ amu/cm^3 ]
valid_min : 0.0
valid_max : 9.99999995904e+11
units : amu/cm^3
grid_system : grid_system_1
mask : -1.09951162778e+12
description : atomic mass density, limit may bee exceeded in dense atmosphere; solar corona 2e8
is_vector_component : 0
position_grid_system : grid_system_1
data_grid_system : grid_system_1
actual_min : 0.0992666035891
actual_max : 25.3303718567Choosing variables for interpolation
To set which variables are to be interpolated, use
python grid.py /path/to/ccmc/output/file.cdf --variables var1 var2 var3
where you could use rho p bx by bz in place of var1 var2 var3
You will get an error if you try to choose a variable that does not exist.
Setting interpolation positions
The positions will depend on the coordinate system of the underlying model. For magnetospheric runs, this usually means SM coordinates. Unfortunately, finding out which coordinate system is not yet documented!
There are three ways to set your interpolation positions:
- Specifying a single position at command line
- Specifying a rectilinear cartesian grid
- Specifying an input file in columnar x,y,z format
Specifying a single position
This is useful for verifying that you are in the right coordinate system and the results match what you would expect for your domain.
python grid.py /path/to/ccmc/output/file.cdf --variables var1 var2 var3 -p -30 0 0
This returns the following table (actual values/variables depend on input):
rho[amu/cm^3] p[nPa] bx[nT] by[nT] bz[nT]
0.121 0.060 8.351 -0.824 -0.655Interpolating outside the bounds of the model will result in junk data, most likely a large negative value. You can also format the output of this using c-style syntax:
python grid.py /path/to/ccmc/output/file.cdf --variables var1 var2 var3 -d '\t' -f "12.3f" -p -30 0 0
Results in:
rho[amu/cm^3] p[nPa] bx[nT] by[nT] bz[nT]
0.121 0.060 8.351 -0.824 -0.655Specifying a grid
A grid may be generated in cartesian (or spherical?) coordinates. Parameters for specifying the grid are as follows:
- -res <ni> <nj> <nk> Grid resolution in each dimension
- -x <xmin> <xmax>. Inclusive range of x. If not specified, a constant value of x-intercept = 0 will be used.
- -xint <x-intercept> overriedes default x-intercept. Ignored if -x is set.
- -y <xmin> <xmax> -yint <y-intercept> -z <zmin> <zmax> -zint <z-intercept> same as above.
- -order 'F' for Fortran-style column major. Positions will be in row major by default.
Example 1 - Planar output
This command computes variables on a 2 x 3 plane at x = -30 with fortran ordering:
python grid.py /path/to/ccmc/output/file.cdf -xint -30 -y -10 10 -z -10 10 -order 'F' -res 1 2 3 -vars rho p bx by bz
Returns:
x y z rho[amu/cm^3] p[nPa] bx[nT] by[nT] bz[nT]
-30.000 -10.000 -10.000 0.463 0.005 -14.188 -3.648 -1.768
-30.000 10.000 -10.000 0.130 0.001 -14.626 0.292 -2.098
-30.000 -10.000 0.000 0.522 0.055 9.560 1.758 0.508
-30.000 10.000 0.000 0.397 0.043 10.131 -3.109 1.361
-30.000 -10.000 10.000 0.504 0.006 14.860 -0.025 -0.062
-30.000 10.000 10.000 0.191 0.003 15.025 -2.743 1.391Example 2 - Volume output
Computing variables on a 2 x 2 x 2 grid in the tail with C ordering:
python grid.py /path/to/ccmc/output/file.cdf -x -10 -50 -y -10 10 -z -10 10 -res 2 2 2 -vars rho p bx by bz
Returns:
x y z rho[amu/cm^3] p[nPa] bx[nT] by[nT] bz[nT]
-10.000 -10.000 -10.000 0.956 0.020 -26.503 -12.704 -3.907
-10.000 -10.000 10.000 0.651 0.011 29.393 8.146 -4.921
-10.000 10.000 -10.000 0.366 0.007 -28.422 9.572 -6.825
-10.000 10.000 10.000 0.361 0.010 29.279 -10.665 0.849
-50.000 -10.000 -10.000 0.444 0.004 -10.964 -2.785 -2.127
-50.000 -10.000 10.000 0.723 0.007 11.192 -0.474 0.179
-50.000 10.000 -10.000 0.134 0.001 -11.449 -0.635 -2.087
-50.000 10.000 10.000 0.243 0.003 11.774 -2.202 0.056Output Options
In the above examples, results were printed to console by default. Alternatively, you may specify an output file in which to store the results:
Exporting to ASCII
python grid.py /path/to/ccmc/output/file.cdf -x -10 -50 -y -10 10 -z -10 10 -res 2 2 2 -vars rho p bx by bz -o /tmp/output_file.txt
By default, the results are stored as column ascii data using the same format and delimitters as above.
Exporting to json
python grid.py /path/to/ccmc/output/file.cdf -p -30 0 0 -vars rho -o /tmp/results.json -ff json
Exporting to IDL (fits format)
python grid.py /path/to/ccmc/output/file.cdf -x -10 -50 -y -10 10 -z -10 10 -res 2 2 2 -o /tmp/fits_out -ff fits -vars rho p bx by bz
The results may be read into IDL. To print the global and variable metadata from the cdf file:
IDL> results = MRDFITS('fits_out', 0, header)
IDL> print, headerTo extract the results of the interpolation:
IDL> results = MRDFITS('fits_out', 1, header)
MRDFITS: Binary table. 8 columns by 8 rows.
IDL> help, results,/str
** Structure <131f5238>, 8 tags, length=32, data length=32, refs=1:
X FLOAT -10.0000
Y FLOAT -10.0000
Z FLOAT -10.0000
RHO FLOAT 0.955738
P FLOAT 0.0203208
BX FLOAT -26.5025
BY FLOAT -12.7045
BZ FLOAT -3.90678
IDL> print, results
{ -10.0000 -10.0000 -10.0000 0.955738 0.0203208 -26.5025 -12.7045 -3.90678}{ -10.0000 -10.0000 10.0000 0.650893 0.0111245 29.3928
8.14576 -4.92121}{ -10.0000 10.0000 -10.0000 0.365616 0.00686792 -28.4215 9.57153 -6.82492}{ -10.0000 10.0000 10.0000 0.361352
0.00967156 29.2788 -10.6648 0.849321}{ -50.0000 -10.0000 -10.0000 0.444090 0.00394465 -10.9637 -2.78490 -2.12730}{ -50.0000 -10.0000
10.0000 0.722521 0.00713427 11.1925 -0.474207 0.179418}{ -50.0000 10.0000 -10.0000 0.133836 0.00134037 -11.4489 -0.634802 -2.08698}{
-50.0000 10.0000 10.0000 0.242857 0.00283294 11.7740 -2.20208 0.0556372}More Options
Run the python code with -h or –help
python grid.py --help
The code will spit out a bunch of useful info:
usage: grid.py [-h] [-v] [-ginfo] [-lvar] [-vinfo var] [-vars var1 [var2 ...]]
[-pout positions_output_flag]
[-pfile /path/to/input/positions.txt] [-p px py pz]
[-x xmin xmax] [-y ymin ymax] [-z zmin zmax] [-res nx [ny ...]]
[-xint xint] [-yint yint] [-zint zint] [-order ordering]
[-t TRANSFORM TRANSFORM TRANSFORM] [-o path/to/output_file]
[-f <flags><width><.precision><length>specifier] [-d ' ']
[-ff fits [json ...]]
full/path/to/input_file.cdf
Interpolates variables onto grid.
positional arguments:
full/path/to/input_file.cdf
kameleon-compatible file
optional arguments:
-h, --help show this help message and exit
-v, --verbose verbosity of output
-ginfo, --global-info
print global attributes
variable options:
List and interrogate variables. Not all variables will have interpolator
support.
-lvar, --list-vars list variables in the file (use -v to print all
variable attributes)
-vinfo var, --variable-info var
print attributes for given variable
-vars var1 [var2 ...], --variables var1 [var2 ...]
list of variables to be interpolated
-pout positions_output_flag, --positions_out_flag positions_output_flag
pass interpolating positions to output
input positions file options:
File containing positions for interpolation
-pfile /path/to/input/positions.txt, --positions_file /path/to/input/positions.txt
file containing column positions x, y, z. Optional
separators: ' ' (default), <tab>, ','
point options:
interpolation options for a single point
-p px py pz, --point px py pz
point at which to interpolate variables
grid options:
interpolation options for a grid of points
-x xmin xmax, --x-range xmin xmax
range of x
-y ymin ymax, --y-range ymin ymax
range of y
-z zmin zmax, --z-range zmin zmax
range of z
-res nx [ny ...], --resolution nx [ny ...]
resolution of the grid along each axis
-xint xint, --x-intercept xint
fixes x for line or plane (ignores x-range)
-yint yint, --y-intercept yint
fixes y for line or plane
-zint zint, --z-intercept zint
fixes z for line or plane
-order ordering, --ordering ordering
sets ordering of output arrays. options: 'C' (default
- C-style row major) or 'F' (FORTRAN-style column
major)
-t TRANSFORM TRANSFORM TRANSFORM, --transform TRANSFORM TRANSFORM TRANSFORM
transformation matrix to apply to grid before
interpolating (not implemented yet)
ouput options:
where to store results of interpolation
-o path/to/output_file, --output_file path/to/output_file
output file name and location
-f <flags><width><.precision><length>specifier, --format <flags><width><.precision><length>specifier
c-sytle format of output variables (e.g. 12.3f)
-d ' ', --delimiter ' '
delimiter for ascii output (default is ' ')
-ff fits [json ...], --file_format fits [json ...]
File format for output. default: 'txt' for ASCII. Use
'fits' for binary IDL fits file (requires astropy), or
'json'