Parameter Files

Summary

Parameter files contain the user-defined parameters important for a simulation. They are inputted into the simulation by passing the path to the parameter file to the first argument of the executable. For example, if the simulation executable is called mysim and the parameter file is named myparamfile.txt, then you simply execute the simulation as

./mysim myparamfile.txt

If you want to simply check the parameters are sensible without executing the full simulation, you can pass -check_params after the parameter file in the executable to perform a check of the parameters.

./mysim myparamfile.txt -check_params

The most important parameters that you should really pay attention to are

• output_path: the output directory for all simulation-related files
• max_level: sets the number of refinement levels of the grid. Severely affects memory usage!
• N_full and L_full: Sets the number of grid cells along a given edge and the coordinate size of the computational box, respectively. Severely affects memory usage!
• dt_multiplier: Sets the temporal timestep relative to the spatial resolution $\delta t = (\text{dt\_multiplier}) * \delta x$
• sigma: The Kreiss-Oliger dissipation coefficient. Determines the strength of high-frequency noise suppression.

Check out the Examples directory for different examples of parameter files.

See below for a more extensive description of the parameter options. Also see the GRChombo parameter guide for an alternative description.

Parameter Files

Parameter files are broadly broken up into 9 pieces:

File system

These parameters specify various filesystem-related flags that control where data should go and how often files should be created.

• verbosity = <0-infinity>

  • This controls the amount of information printed into the output files. 0 is the bare minimum where only the timestepping information will be printed. numbers higher than 5 print a huge amount of information useful for debugging, such as information related to the adaptive grid.
  • For production and high resolution, this should really be set to 0.

• output_path =

  • This tells GRBoondi where to put all the folders and file related to a specific simulation. This directory should exist on a large data-storage pool, since a larger amount of data is usually created, on the scale of terabytes.

• chk_prefix = and plot_prefix =

  • these are filename prefixes for checkpoint files and plot files.

• restart_file =

  • this is the restart filename to restart a simulation from. -Its the relative filename, so you dont need to generally set the absolute path, as long as you want to simulation to continue outputing to the output_path.

• checkpoint_interval = and plot_interval =

  • these are integers that tell GRBoondi how often to create checkpoint files and plot files. -Generally, you don't need to create checkpoint files often and you shouldn't since they are usually quit larger.

• num_plot_vars = and plot_vars =

  • plot_vars is a space-separated list of diagnostic variables you want to save to the plot files.
  • For example, plot_vars = Asquared rho rhoE EMtrace
  • num_plot_vars is the number of diagnostic variables in the plot_vars parameter

• hdf5_subpath, pout_subpath, and data_subpath

  • these are the folders located in output_path where GRBoondi should store the hdf5, pout, and data files, respectively.

• integrals_filename

  • this is the filename of the file that stores the results of integrals

• maxs_filename and mins_filename

  • These are the filenames of the files that store the maximum and minimum values of variables on the grid

• print_progress_only_to_rank_0

  • This is a flag that tells GRBoondi to only print the timestepping progress to the 0th MPI rank.
  • This is usefull if you want to minimize output

• pout_prefix =

  • This is the filename prefix for the processor outputs.
  • Default is 'pout'

• write_plot_ghosts =

  • this tells GRBoondi to write ghosts cells to the plot files.
  • Default is 0

Tagging parameters

These are flags specific to the tagging criteria. For example, if you want to tag cells based on some other quantity ,e.g magnitude of a diagnostic variable, these flags sets the behavior of these criteria

AMR parameters

These flags tell GRBoondi various things about the refinement hierarchy you want to build

• max_level =

  • What is the maximum number of AMR levels you want to setup

• regrid_interval =

  • How often you want to regrid on a specific level
  • generally, you dont need to regrid often on the coursest level
  • For example, if max_level = 4, you could set regrid_interval = 0 0 0 0 to never regrid on any level

• regrid_threshold =

  • What is the threshold value for the tagging criteria for a regrid to be executed.

Initial data

These are parameters used for setting up the initial data, such as black hole mass, Proca mass, initial amplitude, etc.

Grid parameters

These are parameters to tell GRBoondi about the sort of grid you wish to construct.

• N_full = or N1, N2, N3
  • N_full is the number of cells on the coarsest level in each dimension. This will need to be a multiple of the block_factor (see below)
  • Conversely to N_full, you can specify the number of cells in each direction of the computational box individually, using N1, N2, and N3 for each direction.
• L_full or L
  • L_full is the co-ordinate length of the longest side of the grid and ignores any symmetries
  • L is the length of the longest size of the grid
• max_box_size and min_box_size
  • this specifies the maximum and minimum number of cells along each dimension that the boxes can contain.
• tag_buffer_size
  • This is the number of additional cells added to a tagged region to smooth out the regridding
• grid_buffer_size
  • This is the number of cells between each AMR refined level. For larger values, the refinement boundaries are more spaced out, and vice versa.
• fill_ratio
  • the minimum proportion of cells in a box that need to be tagged for regridding to occur.
• num_ghosts
  • This is the number of ghosts cells in each direction at the refinement boundaries.
  • This number is important for the 4th order derivative stencils
• center
  • this is the center of the computational grid.
  • It can be overwritten if you want, for example, a black hole to not be placed at the center, but offset
• grid_scaling
  • This determines the overall size of the refinement levels.
  • This is really only relevant for fixed grid tagging, where for example a value of 2 doubles the size of each refinement level, increasing the number of cells by a factor of 8
• initial_ratio
  • This determines the initial size ratio between the coarsest level and the first refinement level.
  • This is also only relevant for fixed grid tagging

Boundary conditions

These are parameters that set various aspects of the boundaries of the computational box

• isPeriodic

  • This is a list of booleans that tell GRBoondi if the grid boundaries in each direction are periodic or not

• hi_boundary and lo_boundary

  • These are lists of integers that specify boundary properties in the z>0 and z<0 regions
  • Static boundary conditions correspond to 0
  • Sommerfeld boundary conditions correspond to 1
  • Reflective boundary conditions correspond to 2
  • Extrapolating boundary conditions correspond to 3
  • For example, If you want to use z-symmetry and only simulate the z>0 region, and set sommerfeld at all other boundaries, you would specify lo_boundary = 1 1 2 and hi_boundary = 1 1 1

• vars_parity

  • If you're using reflective boundary conditions, these variable is a list that specifies the symmetry of the various evolution variables. The order matters, so the convention is `vars_parity = phi Avec1 Avec2 Avec3 Evec1 Evec2 Evec3 Z'.
  • Normally, this is set to vars_parity = 0 1 2 3 1 2 3 0

• vars_parity_diagnostic

  • This is the reflection symmetry of all the diagnostic variables. The order follows the enum order in the DiagnosticVariables.hpp file.
  • For scalar quantities, these should all be zero and for vector quantities, the number should correspond to the x,y,z symmetry of the vector component

• num-nonzero-asympotic_vars

  • This is the number of non-zero asympotic variables and is only relevant for the Sommerfeld out-going radiation boundary condition

• extrapolation_order

  • This is the order of extrapolation used in Extrapolating boundary conditions

• num_extrapolating_vars

  • This is the number of variables to extrapolate at the boundary

• extrapolating_vars

  • this is a list of strings of variable names to use in the extrapolationg in the Extrapolating boundary condition

Evolution Parameters

These are parameters that specify the nature of the timestepping as well as spacial dissipatory parameters

• dt_multiplier

  • this multiplier sets the temporal step size relative to the spacial step size.
  • This should usually be less than 0.5 or so
  • For example, if the spacial resolution is 0.125 and dt_multiplier is 0.5, then the time stepping will occur on that level with a step size of 0.125*0.5 = 0.0625

• stop_time

  • This is the stop time of the simulation

• max_steps

  • This is the maximum number of coarse time steps so that the program doesnt run out of control

• nan_check

  • This flag tells GRBoondi whether it should check for nan values.
  • If this is turned on GRBoondi will halt the simulation if it encounters a nan

• sigma

  • This is the Kriess-Oliger dissipation factor for smoothing over errors introduced by the finite differencing algorithm

Excision Parameters

These are parameters that control aspects of the evolution and diagnostic excision routines

• evolution_excision_width

  • For black hole spacetimes, this is a multiplier which tells GRBoondi how far inside the outer horizon it should excise the evolution variables.
  • For example, evolution_excision_width=0.9 will excise all evolution variables within a radius of $r&lt;0.9*R_+$

• diagnostic_inner_boundary

  • This is a double which specifies the radius within which diagnostic variables should be excised

• diagnostic_outer_boundary

  • This is a double which specifies the radius outside which diagnostic variables should be excised

• diagnostic_excision_vars

  • This is a list of strings that specify which diagnostic variables should be excised in the excision zones specified by diagnostic_inner_boundary and diagnostic_outer_boundary
  • For example, if you want to excise Asquared and EMtrace, set diagnostic_excision_vars = Asquared EMtrace

Extraction Parameters

These are parameters that control various aspects about the extraction and integration

• activate_extraction
  • This flag tells GRBoondi if it should activate the spherical surface extraction, i.e. calculate fluxes across a black hole horizon or outside the computational domain
• activate_integration
  • This flag tells GRBoondi if it should activate the integration routine, where it integrates quantities across the entire computational domain
• activate_minmax
  • This flag tells GRBoondi if it should activate the minmax extraction routine, where it determines the minimum and maximum values of variables on the grid.
• num_extraction_radii
  • This is an integer specifying the number of extraction spheres
• extraction_radii
  • This is a list of numbers specifying the radii of all the extraction spheres
• extraction_levels
  • This is a list of numbers specifying on which refinement levels the extraction should take place.
  • You usually dont want to extract often, so this should be usually all 0's
• num_points_phi and num_points_theta
  • These are integers specifying the numbers of points to discretize the two angular coordinates with
  • The number of points on the sphere will be num_points_phi * num_points_theta
• extraction_vars
  • This is a list of strings specifying which diagnostic variables should be integrated over the spheres
  • For example, extraction_vars = Edot Jdot
• num_extract_vars
  • This is the number of variables that will be extracted
  • Should be equal to the length of extraction_vars
• integration_vars
  • This is a list of strings specifying which diagnostic variables should be integrated over the entire computational domain
  • For example, integration_vars = rho rhoE rhoJ EMsquared
• num_integration_vars
  • This is the number of variables that will be integrated
  • Should be equal to the length of integration-vars
• maximum_vars and minimum_vars
  • These are the variables whose minimum and maximum values will be extracted
• num_minimum_vars and num_maximum_vars
  • These are the number of variables whose min and max will be computed
  • Should be equal to the length of minimum_vars and maximum_vars, respectively.
• write_extraction
  • This is a flag telling GRBoondi whether it should write out the extraction data to a file.
  • The extraction data will consist of the extraction radius, the angular coordinate, and the value of the variable at that point
  • This is useful if you want to do postprocessing with the extraction data, beyond a simple integration
• extraction_subpath
  • This is the directory inside output_path where the extraction data will be stored