Running a Zoom Simulation

Very little extra is needed to run a zoom simulation. All you need is the command line option, a set of zoom initial conditions, and the ZoomRegion parameter file block. Each of these is described below.

Command Line Option

To tell SWIFT to run with a zoom region you simply include --zoom (or -z) at runtime. This option can be combined with almost all other options, i.e. to run a zoom with the eagle model and 128 threads you can invoke swift --zoom --eagle -t 128 <path/to/params.yml>.

Initial Conditions

The initial conditions should have all hydrodynamic particles stored under PartType0 and all high resolution dark matter particles should be stored under PartType1. All background dark matter particles should be stored under PartType2. For further details on the initial conditions see their docs. No extra data is needed in the initial conditions to run a zoom beyond the background particles.

Parameter File

The ZoomRegion parameter block is used to define the properties of the zoom region and background. An example is shown below.

ZoomRegion:
  region_pad_factor:          1.1
  bkg_top_level_cells:        16
  zoom_top_level_depth:       2
  buffer_top_level_depth:     0
  neighbour_max_tree_depth:   2
  bkg_subdepth_diff_grav:     3

The top 4 parameters here control the construction of the cell hierarchy enabling the efficient division of a zoom calculation (see the cell docs for more information), while the latter 2 control the construction of tasks within the cell tree.

Below is a description of each of these parameters.

region_pad_factor

The extent of the zoom region is defined as the extent of the high resolution particle distribution mutliplied by region_pad_factor. This is not to be confused with any padding applied during initial condition generation, that is naturally included in the high-resolution particle distribution. The region_pad_factor should be selected to be as small as possible while still providing a sufficient padding when running with hydrodynamics (see Zoom Hydrodynamics <zoom_hydrodynamics). If the padding is set too large then the zoom region will be poorly resolved and performance will be sub-optimal.

It’s important to note that the value of region_pad_factor eventually used during the simulation will be modified slightly during cell construction to ensure the zoom region tesselates the parent volume correctly. The padding factor after tesselation is reported by the code if run with verbosity enabled (-v 1 at runtime). Should the requested cell geometry lead to a substantial increase in the padding factor then an error will be thrown, at which point you should review the parameters you have set. You probably need to increase the background resolution and/or modify the cell depths (more below).

bkg_top_level_cells

This replaces Scheduler:max_top_level_cells (which is ignored when running a zoom simulation). It defines the number of background cells along each axis of the whole box.

This value is always respected during cell construction (although it can be later modified in a regrid if the maximum smoothing length in the zoom region demands it).

zoom_top_level_depth

This defines the depth of the zoom cells in a single background cell (inside the cell tree). For instance, a zoom cell depth of 4 would mean a single background cell will contain 2**4 = 16 zoom cells at the leaves of its cell tree.

This value is always respected during cell construction (although it can be later modified in a regrid if the maximum smoothing length in the zoom region demands it and increasing the number of background cells isn’t sufficient).

buffer_top_level_depth

This parameter is only required when the zoom region is small relative background cells and buffer cells are needed to pad the space inbetween the background cell boundaries and the zoom region. This defines the depth of the buffer cells in a single background cell (inside the cell tree). For instance, a buffer cell depth of 2 would mean a single background cell will contain 2**2 = 4 buffer cells at the leaves of its cell tree. By default it is 0 and the code will error and tell you if you need to define a non-zero value and haven’t. buffer_top_level_depth must always be less than zoom_top_level_depth.

This value is always respected during cell construction and is not modified during a regrid.

neighbour_max_tree_depth

This parameter controls the maximum depth neighbour cells will be forced to split to. Splitting neighbour cells deeper can enable better division of interactions across the zoom region boundary. Note that this only controls how far neighbour cells will be forced to be split to if they weren’t going to be split anyway, if a neighbour cell naturally needs splitting beyond this depth because of the number of particles it contains that will still be split.

bkg_subdepth_diff_grav

This defines the difference between the depth of the cell leaves and the level at which we will define gravity tasks for background and buffer cells. In a normal simulation this is controlled by cell_subdepth_diff_grav, but in a zoom simulation its useful to differentiate this parameter for background and zoom cells. The normal cell_subdepth_diff_grav parameter is used for zoom cells while this one covers all other cell types.