User-defined Output Variables
Documentation/UserGuide/User Variables
New Variables added to .tab, .bin, .vtk, or image (.ppm or .pgm) outputs
Often it is useful to output a variable other than the pre-defined values accessed by the
<output>/out
parameter
(see Output Blocks). For example,
one might like to create ppm images of the current density, J=Curl(B). This
can be easily accomplished using the <output>/usr_expr_flag
parameter. The
following steps are required.
-
Write a function that computes the desired variable, and add it to the file that contains the problem generator. The function must be of type
Real
, and the argument list must contain theGridS
structure and the indices of the grid cell. (For details of the data contained in theGridS
structure, see the Programmer’s Guide.) The following example, taken from/athena/src/prob/field_loop.c
, computes the z-component of the current density at cell i,j,k.static Real current(const GridS *pG, const int i, const int j, const int k) { return ((pG->B2i[k][j][i]-pG->B2i[k][j][i-1])/pG->dx1 - (pG->B1i[k][j][i]-pG->B1i[k][j-1][i])/pG->dx2); }
-
Use the function
get_usr_expr()
in the problem generator file to set a pointer to this new function if the string in<output>/out
has the appropriate value. As an example, the following code sets the output variable to be the current density computed using the function given above if the<output>/out
string isJ3
ConsFun_t get_usr_expr(const char *expr) { if(strcmp(expr,"J3")==0) return current; return NULL; }
-
To create a movie of the current density, use an output block in the input file in which
<output>/out=J3
, and<output>/usr_expr_flag=1
, with the other valid parameters set as appropriate (to control, for example, the time interval between outputs, min/max scaling, etc.), for example<output3> out_fmt = ppm # ppm image out = J3 id = J3 usr_expr_flag = 1 palette = rainbow dt = 0.004 # time step between images dmin = -0.04 # min value for imaging J3 dmax = 0.08 # max value for imaging J3
Alternatively, one could output the current density as floating-point numbers in vtk format using out_fmt=vtk
, or as a formatted table using
out_fmt=tab
.
New Variables added to .hst dumps
It is also possible to add new volume-averaged quantities that are output as additional columns in history (.hst) dumps. To add a new, user-defined history variable, use the following steps.
-
Write a function that computes the desired variable, and add it to the file that contains the problem generator, identical to step 1 above for all other output types.
-
Enroll this new function by adding a call to
dump_history_enroll()
anywhere in the problem generator. This function has two arguments, the first is the name of the function created in step 1, the second is a string used as a header for the new column in the history file. For example, the following four lines of code in the problem generator enroll four new history variables.dump_history_enroll(hst_Bx, "<Bx>"); dump_history_enroll(hst_By, "<By>"); dump_history_enroll(hst_Bz, "<Bz>"); dump_history_enroll(hst_BxBy, "<-Bx By>");
These variables are computed by the user-defined functions hst_Bx()
, hst_By()
, hst_Bz()
, and hst_BxBy()
respectively,
and create new columns with headers <Bx>
, <By>
, <Bz>
, and <-Bx By>
respectively.