17.6 Usage

17.6.1 Initialization

The initialization function of the Eos unit Eos_init is fairly simple for the two ideal gas gamma law implementations included. It gathers the runtime parameters and the physical constants needed by the equation of state and stores them in the data module. The Helmholtz EOS Eos_init routine is a little more complex. The Helmholtz EOS requires an input file helm_table.dat that contains the lookup table for the electron contributions. This table is currently stored in ASCII for portability purposes. When the table is first read in, a binary version called helm_table.bdat is created. This binary format can be used for faster subsequent restarts on the same machine but may not be portable across platforms. The Eos_init routine reads in the table data on processor 0 and broadcasts it to all other processors.

17.6.2 Runtime Parameters

Runtime parameters for the Gamma unit require the user to set the thermodynamic properties for the single gas. gamma, eos_singleSpeciesA, eos_singleSpeciesZ set the ratio of specific heats and the nucleon and proton numbers for the gas. In contrast, the Multigamma implementation does not set runtime parameters to define properties of the multiple species. Instead, the simulation Config file indicates the requested species, for example helium and oxygen can be defined as

SPECIES HE4
SPECIES O16

The properties of the gases are initialized in the file Simulation_initSpecies.F90, for example

subroutine Simulation_initSpecies()
  use Multispecies_interface, ONLY : Multispecies_setProperty
  implicit none
#include "Flash.h"
#include "Multispecies.h"
  call Multispecies_setProperty(HE4_SPEC, A, 4.)
  call Multispecies_setProperty(HE4_SPEC, Z, 2.)
  call Multispecies_setProperty(HE4_SPEC, GAMMA, 1.66666666667e0)
  call Multispecies_setProperty(O16_SPEC, A, 16.0)
  call Multispecies_setProperty(O16_SPEC, Z, 8.0)
  call Multispecies_setProperty(O16_SPEC, GAMMA, 1.4)
end subroutine Simulation_initSpecies

For the Helmholtz equation of state, the table-lookup algorithm requires a given temperature and density. When temperature or internal energy are supplied as the input parameter, an iterative solution is found. Therefore, no matter what mode is selected for Helmholtz input, the best initial value of temperature should be provided to speed convergence of the iterations. The iterative solver is controlled by two runtime parameters eos_maxNewton and eos_tolerance which define the maximum number of iterations and convergence tolerance. An additional runtime parameter for Helmholtz, eos_coulumbMult, indicates whether or not to apply Coulomb corrections. In some regions of the $\rho$-$T$ plane, the approximations made in the Coulomb corrections may be invalid and result in negative pressures. When the parameter eos_coulombMult is set to zero, the Coulomb corrections are not applied.

17.6.3 Direct and Wrapped Calls

The primary function in the Eos unit, Eos, operates on a vector, taking density, composition, and either temperature, internal energy, or pressure as input, and returning $\gamma_1$, and either the pressure, temperature or internal energy (whichever was not used as input). This equation of state interface is useful for initializing a problem. The user is given direct control over the input and output, since everything is passed through the argument list. Also, the vector data format is more efficient than calling the equation of state routine directly on a point by point basis, since it permits pipelining and provides better cache performance. Certain optional quantities such electron pressure, degeneracy parameter, and thermodynamic derivatives can be calculated by the Eos function if needed. These quantities are selected for computation based upon a logical mask array provided as an input argument. A .true. value in the mask array results in the corresponding quantity being computed and reported back to the calling function. Examples of calling the basic implementation Eos are provided in the API description, see Eos.

The hydrodynamic and burning computations repeatedly call the Eos function to update pressure and temperature during the course of their calculation. Typically, values in all the cells of the block need of be updated in these calls. Since the primary Eos interface requires the data to be organized as a vector, using it directly could make the code in the calling unit very cumbersome and error prone. The wrapper interface, Eos_wrapped provides a means by which the details of translating the data from block to vector and back are hidden from the calling unit. The wrapper interface permits the caller to define a section of block by giving the limiting indices along each dimension. The Eos_wrapped routine translates the block section thus described into the vector format of the Eos interface, and upon return translates the vector format back to the block section. This wrapper routine cannot calculate the optional derivative quantities. If they are needed, call the Eos routine directly with the optional mask set to true and space allocated for the returned quantities.