Problem Generators

Problem Generator File

When configuring the code, a problem generator must be specified using the --prob option. A list of available problem generators is given in the help message of the configuration script (use -h option).

Problem generators stored in src/pgen contain problem-specific functions and variables. This includes:

• Initial conditions
• User-defined boundary conditions
• User-defined physical source terms
• User-defined Mesh spacing functions
• User-defined mesh refinement criteria
• User-defined analysis functions
• etc...

It will probably be necessary to read the Programmer Guide in order to understand the data structures and Mesh in Athena++ well enough to write a new problem generator. The existing files in the /src/prob directory can be used as starting templates. In this section, we briefly explain the structure of problem generators.

A problem generator contains at least four functions:

• void Mesh::InitUserMeshProperties(ParameterInput *pin)
• void Mesh::TerminateUserMeshProperties(void)
• void MeshBlock::ProblemGenerator(ParameterInput *pin)
• void MeshBlock::UserWorkInLoop(void)

InitUserMeshProperties

This function is called at the beginning of a simulation (both the first run and restarting) for allocating and initializing global variables shared with all the MeshBlocks, and for enrolling user-defined functions. The following functions can be enrolled here:

• Boundary conditions (see Boundary Conditions)
• Mesh generator (mesh spacing) (see Coordinates)
• Source terms (see the Programmer Guid)
• Mesh refinement criteria (see Adaptive Mesh Refinement)

TerminateUserMeshProperties

This function is called at the end of the simulation for cleaning up the resources allocated in InitUserMeshProperties.

ProblemGenerator

This function sets the initial condition for the problem. For hydrodynamics, the cell-centered conservative variables (phydro->u) must be set here. The face-centered magnetic fields (pfield->bx1f, bx2f, and bx3f) also must be set for MHD.

For details, see the Programmer Guide and sample files in the src/pgen directory.

UserWorkInLoop

This function is called at the end of every timestep (note: it is not called at the half timestep). A user can do analysis in this function. This is intended only for analysis, and not for manipulating the data. In such a case, one should use a user-defined source term function and/or the boundary conditions.

Reading Parameters from the Input File

Users can read parameters from the input file in Mesh::InitUserMeshProperties(ParameterInput *pin) and MeshBlock::ProblemGenerator(ParameterInput *pin). For this purpose, the following functions are provided:

• int ParameterInput::GetInteger(std::string block, std::string name)
• Real ParameterInput::GetReal(std::string block, std::string name)
• std::string GetString(std::string block, std::string name)
• int ParameterInput::GetOrAddInteger(std::string block, std::string name, int value)
• Real ParameterInput::GetOrAddReal(std::string block, std::string name, Real value)
• std::string ParameterInput::GetOrAddString(std::string block, std::string name, std::string value)

The first three functions return a parameter with name in <block>. These functions fail when that parameter is not defined in the input file. The latter three functions are similar but with a default value. For example, in order to read a plasma beta parameter named "beta" in the <problem> block,

Real beta = pin->GetReal("problem", "beta");

And if you want to set a default value if no value is specified in the input file,

Real beta = pin->GetReal("problem", "beta", 1000.0);

For details, again, see the Programmer Guide and sample files in the src/pgen directory.