[Runtime Parameters] Particles

Parameters described on this page: PAR_NPAR,   PAR_INIT,   PAR_FLAG_INIT,   PAR_IC_FORMAT,   PAR_IC_FLOAT8,   PAR_IC_INT8,   PAR_IC_MASS,   PAR_IC_TYPE,   PAR_IC_PUID,   PAR_INTERP,   PAR_INTEG,   PAR_TR_INTERP,   PAR_TR_INTEG,   PAR_TR_VEL_CORR,   PAR_IMPROVE_ACC,   PAR_PREDICT_POS,   PAR_REMOVE_CELL,   OPT__FREEZE_PAR,   OPT__PAR_INIT_CHECK  

Parameters below are shown in the format:   Name   (Valid Values)   [Default Value]

• PAR_NPAR   (≥0)   [none]

  • Description: Total number of particles.
  • Restriction: Must be set when PAR_INIT=1/3; must be consistent with the number of particles loaded from an initial condition file (e.g., for PAR_INIT=3 and test problems with their own particle initializers); useless when restarting from a snapshot (i.e., PAR_INIT=2); must be an integer.

• PAR_INIT   (1=function, 2=restart, 3=PAR_IC file)   [none]

  • Description: Initialization methods for particles. PAR_INIT=1: using a particle initialization function; see Setting IC from Analytical Functions — Particles. PAR_INIT=2: restarting from a simulation snapshot. PAR_INIT=3: loading a binary file named PAR_IC; see Setting IC from Files — Particles.
  • Restriction: It will be automatically reset to PAR_INIT=2 when adopting OPT__INIT=2.

• PAR_FLAG_INIT   (0=off, >0: must-refine particles, <0: can-refine particles, 9999: set manually)   [0]

  • Description: Automatically assign the refinement flags of all particles to PAR_FLAG_INIT when PAR_INIT=1/3. Refer to OPT__FLAG_PAR_TARGET for the definitions of must-refine and can-refine particles. Set PAR_FLAG_INIT=9999 to assign refinement flags manually, either by editing a particle IC function or by loading them from a particle IC file.
  • Restriction:

• PAR_IC_FORMAT   (1=[attribute][id], 2=[id][attribute]; row-major)   [1]

  • Description: Data format of the particle initial condition file PAR_IC used by PAR_INIT=3. See Setting IC from Files — Particles for details.
  • Restriction:

• PAR_IC_FLOAT8   (<0: same as --double_par, 0=single precision, 1=double precision)   [-1]

  • Description: Floating-point precision of the particle initial condition file PAR_IC.
  • Restriction:

• PAR_IC_INT8   (<0: same as --long_par, 0=32-bit integer (int), 1=64-bit integer (long))   [-1]

  • Description: Integer width of the particle initial condition file PAR_IC.
  • Restriction:

• PAR_IC_MASS   (≥0.0; <0.0 → off)   [-1.0]

  • Description: Assigning this particle mass to all particles when adopting PAR_INIT=3. Note that when enabling this functionality (by setting PAR_IC_MASS≥0.0), the particle initial condition file PAR_IC should not include the particle mass data. See also Setting IC from Files — Particles.
  • Restriction:

• PAR_IC_TYPE   (≥0; <0 → off)   [-1]

  • Description: Assigning this particle type to all particles when adopting PAR_INIT=3. Note that when enabling this functionality (by setting PAR_IC_TYPE≥0), the particle initial condition file PAR_IC should not include the particle type data. See also Setting IC from Files — Particles.
  • Restriction:

• PAR_IC_PUID   (0=off, 1=on)   [0]

  • Description: Flag indicating whether the particle initial condition file PAR_IC contains UID information. If this option is disabled, new particle UIDs will be assigned automatically. See also Setting IC from Files — Particles.
  • Restriction:

• PAR_INTERP   (1=NGP, 2=CIC, 3=TSC)   [2]

  • Description: Massive particle interpolation schemes: NGP=nearest-grid-point, CIC=cloud-in-cell, TSC=triangular-shape cloud. Accuracy: TSC > CIC > NGP. Performance: NGP > CIC > TSC. In general, NGP is not recommended.
  • Restriction:

• PAR_INTEG   (1=Euler, 2=KDK)   [2]

  • Description: Massive particle integration scheme. Euler integration is only first-order accurate and is generally not recommended.
  • Restriction:

• PAR_TR_INTERP   (1=NGP, 2=CIC, 3=TSC)   [3]

  • Description: Tracer particle interpolation schemes. See PAR_INTERP for details.
  • Restriction:

• PAR_TR_INTEG   (1=Euler, 2=RK2)   [2]

  • Description: Tracer particle integration scheme. Euler integration is only first-order accurate and is generally not recommended.
  • Restriction:

• PAR_TR_VEL_CORR   (0=off, 1=on)   [0]

  • Description: Tracer particle velocities will be corrected in regions of discontinuous flow. It may be used only for mapping velocity, used to correct tracer particle trajectories in discontinuous flows. See Section 2.2 and Equation 1 of Wittor et al. (2016) MNRAS, 464, 4
  • Restriction: Only applicable when adopting PAR_INTERP=2/3

• PAR_IMPROVE_ACC   (0=off, 1=on)   [1]

  • Description: Improve the force accuracy for particles close to the patch boundaries.
  • Restriction: Only applicable when adopting PAR_INTERP=2/3 and enabling the compilation option --store_pot_ghost.

• PAR_PREDICT_POS   (0=off, 1=on)   [1]

  • Description: Predict particle position during mass assignment to synchronize particles and grids.
  • Restriction:

• PAR_REMOVE_CELL   (≥0.0; <0.0 → set to default)   [depend]

  • Description: Remove particles too close to the simulation boundaries when adopting non-periodic boundary conditions. It is necessary because the force accuracy around the simulation boundaries may be deteriorated due to the potential extrapolation. Specifically, we remove particles located in the outermost PAR_REMOVE_CELL root cells in the simulation box. The default value is 1.0 ~ 2.0 depending on the adopted particle interpolation scheme (PAR_INTERP).
  • Restriction: Only applicable when adopting the isolated gravity boundary condition (i.e., OPT__BC_POT=2).

• OPT__FREEZE_PAR   (0=off, 1=on)   [0]

  • Description: Do not update particle position and velocity (except for tracer particles). It can be useful for evolving fluid in a static gravitational potential of particles.
  • Restriction:

• OPT__PAR_INIT_CHECK   (0=off, 1=on)   [1]

  • Description: Check particle initialization by calling Par_Aux_InitCheck() function after particle initialization (only works for PAR_INIT!=2). Disable this check when particles are initialized after setting grid fields, such as by Init_User_Ptr().
  • Restriction:

Remarks

Particle UID (PUID)

Valid particle UIDs should lie within [1, number of particles].

The particle UID assignment occurs during either initialization or on-the-fly creation in simulation (e.g., star formation). The particle UIDs can be inherited from PAR_IC (when PAR_INIT=3 and PAR_IC_PUID is enabled) or from a restart file. Except for these, the particle UIDs should be assigned internally via Par_SetParUID() in all other cases (e.g., PAR_INIT=1).

To ensure uniqueness and reproducibility, all particle UIDs should be assigned by Par_SetParUID() globally, rather than decided by individual MPI ranks. The particle UID must be first marked as PUID_TBA when the particle is created (e.g., in Par_Init_ByFunction_Ptr(), Par_Init_ByFile(), and src/StarFormation/SF_CreateStar_AGORA.cpp) before invoking Par_SetParUID() (e.g., at the end of Init_GAMER() and SF_CreateStar()). And Par_SetParUID() should be invoked after all the particle creation within a single routine is complete.

The assignment procedure of Par_SetParUID() follows:

First, we collect the PUIDs and positions of new particles from all ranks into a single array. Second, we sort the particles by their positions. Third, assign the particle UIDs according to the array index plus NextPUID. Finally, send the new particle UIDs back to all ranks.

Caution

If the particle positions are exactly the same (which should unlikely happen), the particle UID is determined by the sorting algorithm. Please check the implementation in Miscellaneous/Mis_SortByRows.cpp and Mis_Heapsort.cpp

Links

• Main page of Runtime Parameters
• Main page of Particles