Enzo 2.2 documentation

Variable precision in Enzo

In order to provide some global control over variable precision, Enzo uses a set of macros that control how the code treats integer and floating-point precision by overriding the float and int data types, and by introducing the FLOAT macro. This is a major sticking point for new users to the code, and this page is an attempt to clarify the issue as much as possible.

Floating-point precision

There are two different kinds of floating-point quantities in Enzo, those that explicitly deal with positional information (grid edges/locations, cell sizes, particle positions, and so on), and those that deal with non-position information (baryon density, temperature, velocity, etc.) Any variables that deal with position information should be declared as the FLOAT data type. For example:

FLOAT xpos, ypos, zpos;

A quantity that deals with non-positional information would be declared using the float data type:

float cell_HI_density, cell_H2I_density, cell_temperature;

The actual precision of float and FLOAT are controlled by the Makefile system (see Obtaining and Building Enzo.) To set the non-positional precision to 64-bit (double), you would issue this command:

make precision-64

before compiling the code. Similarly, to set the positional precision to 64-bit (double), you would issue this command:

make particles-64

The allowable values for non-positional precision are 32 and 64 bits, and for positional precision are 32, 64, and 128 bits. It is not recommended that you use particles-128 unless you need more than 30 or so levels of AMR, since long double arithmetic generally requires software libraries and can be very slow. Also note that the 128-bit precision code is not terribly stable, and only works on some systems (and with some sets of compilers). Use this with extreme caution.

Mixing ``float`` and ``FLOAT``: One can mix the float and FLOAT data types, but some care is required since the two are not necessarily the same precision. Compilers will generally promote the variables to the higher precision of the two, but this is not always true. The Enzo developers have chosen to make the assumption that the precision of FLOAT is always the same as, or greater than, the precision of float. So, when precision is critical or when mixing float and FLOAT, we recommend that you always promote all variables to FLOAT. Regardless, it is a good idea to check that your code is producing sensible results.

Integer precision

There is only one commonly-used type of integer in Enzo, which is int. This is controlled by the the integers- makefile command. For example,

make integers-64

would force all ints to be 64-bit integers (long int). The allowable integer values are 32 and 64 bit. In general, the only time one would need 64-bit ints is if you are using more than 231 particles, since signed integers are used for the particle index numbers, and chaos will ensue if you have duplicate (or, worse, negative) particle indices.

Precision macros and printf/scanf

In order to keep the printf family of commands happy, Enzo uses several macros. ISYM is used for integers, FSYM and ESYM for float, and PSYM and GSYM for FLOAT (the latter of each pair outputs floats in exponential notation). Additionally, when writing FLOAT data to a file that will be read back in by Enzo (such as to the parameter or hierarchy file), it is wise to use GOUTSYM. In a printf or scanf statement, this macro will be replaced with the actual string literal statement.

An example of this usage macro in a printf statement to write out a float is:

printf("Hello there, your float value is %"FSYM".\n", some_float);

and to read in a set of three position coordinates using scanf out of a string named line:

sscanf(line,"PartPos  = %"PSYM" %"PSYM" %"PSYM, &XPOS, &YPOS, &ZPOS);

Note the somewhat counterintuitive use of quotation marks after the 3rd PSYM. For a large number of examples of how to use these macros, please refer to the files ReadParameterFile.C and WriteParameterFile.C in the Enzo source code.

The Fortran-C++ interface

It is critical to make sure that if you are interfacing Fortran and C/C++ code, the variable precision agrees between the two languages. Compilers do not attempt to ensure that calls from C/C++ to Fortran make any sense, so the user is manifestly on their own. To this end, when writing Fortran code you must ensure that your variables are declared with the correct type. Unlike Enzo’s C/C++ routines that overwrite the default float and int types with their single/double precision equivalents, Enzo’s Fortran routines do not overwrite the basic data types. Hence, we have created unique type identifiers for the Fortran routines that map to Enzo’s float, FLOAT and int types, as specified below:

Enzo C/C++ Enzo F/F90
float R_PREC
int INTG_PREC
FLOAT P_PREC

In addition, Fortran allows additional data types for both logical and complex variables. In Enzo, the precision of these variables may be chosen to match Enzo’s int and float values from C/C++ using the F/F90 types LOGIC_PREC and CMPLX_PREC respectively.

Moreover, unlike C/C++, hard-coded constants in Fortran routines default to single-precision values. This can be especially troublesome when calling a Fortran subroutine or function with constants as their inputs, or when writing complicated formulas using constants that must be of higher precision. To this end, we have defined four type-modifier Fortran suffixes, that can be used to declare constants of differing precision:

Variable Type Suffix
R_PREC RKIND
INTG_PREC IKIND
P_PREC PKIND
LOGIC_PREC LKIND

Note: since a complex number in Fortran is defined through a pair of real numbers, to create a complex constant of type CMPLX_PREC you would use the RKIND suffix on both components.

For example, the type specifiers and constant suffixes could be used in the following ways:

c     Declarations
      R_PREC     third, tenth
      INTG_PREC  one
      P_PREC     fifth
      CMPLX_PREC two_i
      LOGIC_PREC test

c     Calculations
      third = 1._RKIND / 3._RKIND
      tenth = 1.e-1_RKIND
      one   = 1_IKIND
      fifth = real(1, PKIND) / 5._PKIND
      two_i = (0._RKIND, 2._RKIND)
      test  = .true._LKIND

All of these type definitions are supplied in the file fortran_types.def and should be included within a Fortran routine within the scope of the function, after any implicit none declaration, and before declaring any variables, e.g.

      subroutine foo(a)
         implicit none
#include "fortran_types.def"
         R_PREC a

The Enzo build system will preprocess this file to include fortran_types.def at the specified location in the file, prior to compilation. Moreover, the spacing in this file is usable using either fixed-source-form or free-source-form Fortran files.

A word of warning: mismatching the data types between C/C++ and Fortran codes can cause misalignment in the data, and will often result in nonsense values that will break Enzo elsewhere in the code. This can be particularly tricky to debug if the values are not used immediately after they are modified!

If you need more details…

If you need more detailed information on this particular subject, there is no substitute for looking at the source code. All of these macros are defined in the Enzo source code file macros_and_parameters.h. Just look for this comment:

/* Precision-dependent definitions */

There are many examples of using the IO macros in ReadParameterFile.C and WriteParameterFile.C.

Also, please note that this set of macros may be replaced with a more robust set of macros in future versions.