global.data Explained

Arguably the most important data file in AstroBEAR 2.0, global.data contains global domain and solver data. This data is broken up into several namelists, which are read in by different sections of the code.

GlobalData

The GlobalData namelist contains global parameters. These parameters hold for the entire problem domain, and many of them actually describe it.

• nDim: The number of dimensions in the problem. For AstroBEAR, this should be either 2 or 3, since AstroBEAR only does 2D and 3D problems. A 1D problem can be approximated with a long, narrow 2D problem domain.

• MaxLevel: The maximum refinement level for this simulation. MaxLevel is the number of refinement levels over the base grid (so a MaxLevel of 0 is fixed-grid). This value can never be less than 0, and if it is greater than 0 then the problem is an AMR problem.

• MinimumGridPoints: The minimum number of cells per dimension that a grid can have. Since a grid must have at least one cell, MinimumGridPoints should never be less than 1. A low MinimumGridPoints allows AstroBEAR to create smaller grids, which lets it refine more efficiently. Low MinimumGridPoints values also run the risk of creating a lot more grids, which will boost administrative and communication costs.

• nDomains: The number of domains comprising the problem domain. Multiple domains are useful if you want to impose different physical processes in different regions of your problem domain (i.e., different cooling curves), but most problems do not require this degree of complexity. Unless you have a specific reason for wanting multiple domains in your problem, it is best to leave this set to 1.

• lRestart: Should be set to T if you intend to restart a simulation from a Chombo file, or F if you intend to start the simulation from the beginning. You must have a Chombo file in your problem's out/ directory if you want to use this option, and it's index must match that of the RestartFrame variable (see below).

• RestartFrame: The chombo frame number from which the code will restart. In order to use this, you must have a Chombo file of the same frame number in your problem's out/ directory (for example, RestartFrame 5 will crash unless the file out/chombo00005.hdf is present). Regardless of its value, the RestartFrame variable does nothing if the lRestart and the lPostProcess flag is set to F. To automatically restart (or postprocess) from last printed frame, set RestartFrame to -1. To postprocess from frame 0, remove the frame.data from the run directory if it is present and turn lPostProcess=T and lRestart = F.

• start_time: The start time in computational units. This quantity is used to calculate the time per frame within a simulation, and should not be changed even if you are restarting the job.

• final_time: The final time (end time) in computational units. Needless to say, this should be greater than start_time.

• GmX: This is a three-integer array, with each element representing the number of cells in the domain along the given dimension. Thus, the total domain size in cells is GmX(1) * GmX(2) * GmX(3). This array is subject to the following constraints:
  • All elements must be integers.
  • All elements must be greater than or equal to MinimumGridPoints.
  • If nDim = 2, then the third GmX entry must be 1.

• GxBounds: This is a double-precision array with six values. The first three values set the lower spatial bounds of the problem domain, and the last three values set the upper bounds. For instance, the problem domain's boundaries along the x-axis are set by the first and fourth elements in GxBounds. The GxBounds array has three constraints:
  • GxBounds(1) < GxBounds(4) (i.e., they must define a legitimate x interval).
  • GxBounds(2) < GxBounds(5) (i.e., they must define a legitimate y interval).
  • IF nDim = 3, then GxBounds(3) < GxBounds(6). Otherwise, GxBounds(3) and GxBounds(6) must equal zero.
• Gmthbc: A six-integer array defining the boundary conditions along the edges of all three dimensions. If nDim = 2, then Gmthbc(3) and Gmthbc(6) should both be set to 1. The other boundary conditions can be chosen from one of the following options:
  • 1 — Extrapolated boundaries.
  • 2 — Periodic boundaries.
  • 3 — Reflecting boundaries.

• initial_maxspeed: The maximum initial wave speed; essentially, the maximum rate at which information can propagate across the grid. The higher the maximum initial wave speed, the smaller the initial timestep will be. Timesteps are adaptive in AstroBEAR, so in general it is a good idea to give yourself a higher maximum initial speed than you think you'll need—if the initial speed is too high, the system will adjust. An initial_maxspeed of about 30.d0 is common.

• iThreaded: Turns threaded execution on or off. Threading is not fully implemented in AstroBEAR 2.0, so this flag should be left at 0.

LevelData

The LevelData namelist contains values that are local to a given level. Every grid on a given level n will have the same LevelData attributes, but the values for level j != n might be substantially different.

All LevelData variables are multi-element. The data file should have values for every level from 0 to MaxLevel (see the GlobalData namelist above).

• CoarsenRatio: The refinement ratio for grids on that level. A CoarsenRatio of 2 on level n means that an i*j*k cell refined region on level n will produce a 2i*2j*2k grid on level n+1. Virtually all of our simulations use CoarsenRatios of 2. The CoarsenRatio values should always be integers.

• qTolerance: These tolerances are used within SetErrFlags() to determine whether or not to flag a cell for refinement. The higher the tolerance, the more extreme the variable gradients have to be to warrant refinement. The qTolerance variables are double-precision and must be greater than 0.d0, but a wide range of values is possible. 1.d-3 and 1.d-5 are common choices.

• DesiredFillRatios: Single or double precision values between 0 and 1. The desired fill ratio determines what fraction of the cells in a new subgrid must be flagged for refinement. If a potential subgrid's fill ratio is below its parent grid's DesiredFillRatios value, then AstroBEAR will attempt to break it into smaller grids with higher fill ratios. Problems with low fill ratios will refine more cells than they need to, but will likely use fewer grids to do so. It becomes a trade-off between the cost of additional refinement and the cost of grid management and communication. Typical fill ratios range between .5 to .99 (although .99 can be extremely slow).

See Changing qTolerance and DesiredFillRatios for more details and examples.

IOData

The IOData namelist contains control flags that affect the way input and output are processed/produced.

• iDataFileType: Indicates the kind of output file AstroBEAR should produce. We currently only support Chombo-formatted ​HDF5 files, so this flag should be left at 0.

DomainData

Contains information about the various user-defined domains in AstroBEAR. AstroBEAR stores domain info in Domain objects which it reads in from this namelist. For most problems, only one domain is necessary, so there will be only one Domain object.

IMPORTANT: As of 6/5/2011, multi-domain setups have not been thoroughly tested, and boundary conditions are not fully implemented for multi-domain problems. Use more than one domain at your own risk.

• Domain%mGlobal: The global cell indices for a domain. For a single-domain problem, Domain%mGlobal should be 1, 1, 1, GmX(1), GmX(2), GmX(3). A two-domain, 64 x 64 x 64 problem might have mGlobals of [1, 1, 1, 64, 32, 64 and 1, 33, 1, 64, 64, 64.

For two-dimensional problems, Domain%mGlobal(3) and Domain%mGlobal(6) should always be set to 1.

• Domain%mthbc: The boundary condition tags for a domain. For a single-domain problem, Domain%mthbc will be the same as Gmthbc (see GlobalData, above). For a multi-domain problem, however, the there will be some domains who share a common boundary. For these domains, you use the internal boundary condition code of 999.

Again, for two dimensional problems, Domain%mthbc(3) and Domain%mthbc(6) should be set to 1.

PoissonData

This namelist will only be present in elliptic problems. PoissonData contains variables that control the behavior both of the elliptic solver and the underlying ​hypre library.

• solver: An integer flag that specifies the type of ​hypre solver to use. We currently have two options implemented for solver:
  • 1 -- PCG Solver: The PCG solver is the faster of the two solvers we have implemented. It is not guaranteed to converge, but is still the best default choice.
  • 2 -- GMRES solver: The GMRES solver uses a Krylov approximation to converge to a solution. Unlike PCG, GMRES is guaranteed to converge, given enough time and memory. Such convergence can, however, be computationally infeasible, and GMRES is slower than PCG on problems that PCG can handle. If you are in doubt, try PCG (solver = 1) first.

• tolerance: A floating point value indicating the tolerance within which you would like your solver to converge. This tolerance affects the accuracy of your approximation; a lower tolerance gives a more accurate answer, but usually takes more iterations to achieve. Most problems should do fine with a tolerance value of 1e-4 to 1e-6.

• printlevel: A hypre parameter that controls the information printed out by hypre's solver during the course of execution. There are four options for printlevel:
  • 0 — No printout.
  • 1 — Print solver setup information only.
  • 2 — Print solve information only.
  • 3 — Print setup and solve information.

The hypre solver can be pretty verbose; it's recommended that printlevel be set to 0 unless you are debugging.

• MaxIters: The maximum number of iterations hypre may step through to converge the solution. If the solution does not converge within MaxIters iterations, then it will fail with an error message. Multigrid solvers often experience diminishing returns over many iterations, so increasing MaxIters is not necessarily going to make your solution converge. Conversely, too few iterations will cause your problem to fail where it might have succeeded.

100000 is a good initial guess for MaxIters. This number can be lowered to force convergence failures to occur earlier, or it can be raised if you think a few more iterations will make a difference.

• hVerbosity: The amount of detail AstroBEAR prints about its hypre operations. This is a higher-level form of reporting than printlevel; hVerbosity prints out what hypre routines AstroBEAR is calling.
  • 0 -- off: No printouts.
  • 0 -- on: AstroBEAR prints information about the hypre routines it is calling to standard output.

• mthbc: These boundary condition codes are similar to the ones explained in GlobalData above, except here ZEROSLOPE=0,REFLECTING=1,PERIODIC=2,MULTIPOLE_EXPANSION=3,USERSPECIFIED=4.

TimestepData

These variables control the timesteps the simulation takes.

• cfl_vars: This is a three-element array of floating point numbers. Each one has a different function:
  • cfl_vars(1) -- Max CFL: The maximum allowable ​CFL number the system can have. If cfl_vars(1) is exceeded, then the simulation will restart the current step with a smaller timestep. The maximum CFL value should be between 0 and 1. The most common value for the maximum CFL is 1.
  • cfl_vars(2) -- Target CFL: The target ​CFL number. Lower CFLs produce more accurate results, but also require more timesteps. Target CFL values of .2 to .3 are common for 3D problems, whereas 2D problems can go as high as .4.
  • cfl_vars(3) -- CFL relaxation: A coefficient between 0 and 1 that limits the degree to which the timestep size can change from one step to the next. This prevents extreme timestep variations which could otherwise kick the CFL down to 0 or above the maximum. A CFL relaxation parameter of 1.0 is basically the same as having no relaxation parameter.