Subset block

This block contains configuration for filters which can be used to modify the data to be output. See EPOCH input deck for more information on the input deck.

It is possible to restrict the number of particles written to file according to various criteria. For example, you can now output the momentum of all particles which have a gamma lower than 1.8 or the positions of a randomly chosen subset of a given species.

A new input deck block named “subset” is defined which accepts the following parameters:

• name - The name given to this subset. This is used to identify the subset in the output block and is also used when labelling the data in the SDF files.
• include_species - Add the given particle species to the set of particles that this subset applies to. By default, no particle species are included.
• dumpmask - The dumpmask to use when considering this subset in an output block. This takes the same form as the output block dumpmask. The default value is “always”.
• random_fraction - Select a random percentage of the particle species. This is a real value between zero and one. If 0 is specified, no particles are selected. If 1 is specified, all the particles are selected. If 0.2 is specified, 20% of the particles are selected.
• {px,py,pz,weight,charge,mass,gamma}_min - Select only the particles with momentum, weight, charge, mass or gamma which is greater than the given value.
• {px,py,pz,weight,charge,mass,gamma}_max - Select only the particles with momentum, weight, charge, mass or gamma which is less than the given value.
• {x,y,z}_min - Select only the particles whose position lies above the given value.
• {x,y,z}_max - Select only the particles whose position lies below the given value.
• id_min,max - Select only the particles whose “id” is greater than or less than the given values. The “id” field is explained below.
• skip,skip_{x,y,z} - Integer parameter for subsampling output. If set to a positive integer then all grid-based variables using the subset restriction will be reduced when being written to file. This is achieved by skipping by the specified number of cells in each of the specified directions. The “skip” parameter provides a quick method for setting the same number of cells to skip in all directions. This currently only applies to grid-based variables and is ignored for data averages. The default value is “0”.

Once a subset has been defined, the subset name can then be used in place of (or in addition to) the dumpmask in an “output” block (see also here). For example:

begin:subset
   name = background
   random_fraction = 0.1
   include_species:electron
   include_species:proton
end:subset

begin:subset
   name = high_gamma
   gamma_min = 1.3
   include_species:electron
end:subset

begin:output
   particles = background + high_gamma + always
   px = background + high_gamma
   py = background
   pz = always
end:output

In this example, three “px” blocks will be written: “Particles/background/electron/Px”, “Particles/background/proton/Px” and “Particles/high_gamma/electron/Px”. The “background” blocks will contain 10% of the each species, randomly selected. The “high_gamma” block will contain all the electrons with a gamma greater than 1.3.

There will also be “Particles/background/electron/Py” and “Particles/background/proton/Py” block containing y-momentum for the same 10% random subset of particles. Finally, the “Particles/All/electron/Pz” and “Particles/All/proton/Pz” will contain the z-momentum for all particles.

The final selection criteria given in the list above is “id_min” and “id_max”. As of EPOCH version 4.0, the code can now assign a unique ID field to every particle in the simulation. This can be useful for tracking specific particles as they move through a simulation. As this field adds extra memory requirements to the particles, it is disabled by default and must be compiled in using the -DPARTICLE_ID compiler flag.

Particle IDs can be written to file using the “id” variable name in the “output” block. Eg.

begin:output
   particles = always
   id = always
end:output

Subsets of fields

Subset blocks can be applied to per-species variables such as current and temperature. Only particles within the given momentum ranges and of the selected species are included in the calculations. In addition, subset blocks can now be applied to field or grid variables. This allows you to output spatial sections using the {x,y,z}_max,min restrictions. The output data will be trimmed to the selected ranges and a corresponding restricted grid included in the output. Note that specifying an empty range will lead to output of the entire domain. For example, the following snippet will output an ex_c_centre variable restricted to the centre 1/3rd of the domain with a corresponding grid grid_centre:

begin:subset
   name = centre
   x_min = x_min + (x_max - x_min) / 3.0
   x_max = x_min + 2.0 * (x_max - x_min) / 3.0
end:subset

begin:output 
   ...
   ex = always + centre
end:output

Persistent subsets

Persistent subsets are subsets that capture a set of particles once, given a specified set of parameters, and then track those particles permanently. Persistent subsets use the same blocks as normal subsets and take the same parameters as normal subsets (except the skip parameters which only apply to fields). Subsets are marked as persistent by setting either

• persist_start_time - Time at which to record the list of particles to be tracked. Throughout the rest of the simulation this recorded list will be used whenever requesting output for this subset. “persist_after_time” is accepted as an alias. Set to 0 to record from the start of the simulation.
• persist_start_step - Similar to persist_start_time except this specifies a simulation step number to use instead of time. “persist_after_step” is accepted as an alias.

If the input deck is edited on restart to add a new persistent subset then it must be added after existing persistent subsets or problems may occur on restart.