select¶

Select a subset of one or multiple datasets.

This subset can can be created by

• Choosing a cell along a direction (--z# with an integer).

• Choosing a range of cells along a direction (--z# with a slice).

• Choosing a specific component (-c), which may be an expansion coefficient, fluid moment or, if used along with interpolate, a vector component. Multiple components can be selected with a slice of floats or with comma-separated values.

• Evaluating the function at a specific coordinate in one direction (using interpolate and select --z# with a float) or segment in one dimension (using interpolate and select --z# with a slize of floats).

Command line¶

pgkyl select --help
  Usage: pgkyl select [OPTIONS]

    Subselect data from the active dataset(s). This command allows, for
    example, to choose a specific component of a multi-component dataset,
    select a index or coordinate range. Index ranges can also be specified
    using python slice notation (start:end:stride).

  Options:
    --z0 TEXT        Indices for 0th coord (either int, float, or slice)
    --z1 TEXT        Indices for 1st coord (either int, float, or slice)
    --z2 TEXT        Indices for 2nd coord (either int, float, or slice)
    --z3 TEXT        Indices for 3rd coord (either int, float, or slice)
    --z4 TEXT        Indices for 4th coord (either int, float, or slice)
    --z5 TEXT        Indices for 5th coord (either int, float, or slice)
    -c, --comp TEXT  Indices for components (either int, slice, or coma-
                     separated)

    -u, --use TEXT   Specify a 'tag' to apply to (default all tags).
    -t, --tag TEXT   Optional tag for the resulting array
    -h, --help       Show this message and exit.

Perhaps the two most common uses of select are to choose a vector component or to evaluate a function at a specific coordinate. Consider the data produced by a two stream instability Vlasov-Maxwell simulation. The file two-stream_field_0.bp contains 24 components per cell. That is because it contains 8 vector components (3 components of the electric and magnetic fields each and 2 correction potentials, see http://ammar-hakim.org/sj/maxwell-eigensystem.html) and 3 degrees of freedom per component (for piecewise linear basis in 1D). If we wish to only see \(E_x\) then we can select it and plot it with

pgkyl two-stream_field_0.bp interp select -c0  pl

which yields the following figure

We could also select multiple components with a comma-separated list

pgkyl two-stream_field_0.bp interp select -c0,3 pl -x '$x$'

which yields the following plot of \(E_x\) and \(B_x\)

Or we could select all the components of the magnetic field in all frames with

pgkyl "two-stream_field_[0-9]*.bp" interp select -c3:6 pl -f0 -x '$x$' --no-legend --nsubplotrow 1

to show that this is an electrostatic simulation.

As a demonstration of using select to evaluate functions at a given coordinate we could evaluate the above \(E_x\) at \(x=-\pi\), but that would yield a single number. We could instead load all the field data files, evaluate the \(x\)-component of the electric field at \(x=-\pi\) in each frame, collect all those points into a single dataset, and plot them as a function of time. This would be accomplished with the following command

pgkyl "two-stream_field_[0-9]*.bp" interp sel -c0 --z0 -3.14159 collect pl -x 'time' -y '$E_x(x=-\pi,t)$'

We will sometimes use the abbreviation sel instead of select for convenience. The resulting figure (above) shows how the amplitude of the electric field at this point drastically increases as the instability develops. There is an oscillatory behavior that is lost in this exponential growth; if one zoomed into the earlier times of this plot, such oscillations would become visible.

One can, and must, select coordinates at which to evaluate higher (than 2) dimensional datasets. Take the initial and final distribution functions of the electrons as an example; we can evaluate them at \(x=0\) and plot their variation along \(v_x\) with

pgkyl two-stream_elc_0.bp -l '$t=0$' two-stream_elc_100.bp -l '$t=50$' interp \
  sel --z0 0. pl -x '$v_x$' -y '$f_e(x=0,v_x)$' -f0

producing the following plot:

If we were interested in investigating the distribution function in a specific cell along \(x\), say the first (0th in 0-index), we could use

pgkyl two-stream_elc_100.bp sel --z0 0 interp pl -x '$x$' -y '$v_x$'

Notice that this produces a 2D colorplot because it takes the expansion coefficients in the 0th cell along \(x\) and all cells along \(v_x\), interpolates them onto a finer mesh and plots them (so the \(x\) extent of this plot is a single cell of the simulation). If we instead wanted a 1D plot of the distribution function along \(v_x\), we could first interpolate onto a finer mesh and then evaluate it at the 0th cell of the finer mesh using

pgkyl two-stream_elc_100.bp interp sel --z0 0 pl -x '$x$' -y '$f_e(x=-6.25046,v_x)$'

or interpolate it and evaluate it at the lower boundary of the domain along \(x\), which is located at \(x=-2\pi\), with

pgkyl two-stream_elc_100.bp interp sel --z0 -6.283185 pl -x '$x$' -y '$f_e(x=-2\pi,v_x)$'

These two commands are evaluating the distribution function at slightly different \(x\) coordinates (\(\Delta x/(p+1)/2\) apart to be precise, where \(\Delta x\) is the cell length of the simulation, and \(p\) the polynomial order of the basis). We can discern the difference between the two by plotting them together using the following command:

pgkyl two-stream_elc_100.bp -t fe interp sel -t zfl --z0 -6.283185 sel -u fe -t zint --z0 0 \
  pl -u zfl,zint -f0 -x '$v_x$' -y '$f_e$'

This commmand used tags to indicate which dataset to perform the interpolation on, and to name the interpolated datasets. The result is

Lastly, we show that the select command can also be used to restrict and interpolated dataset to a segement along one direction when the --z# flag is used with a slice of floats. For example, if one wants to plot the initial electron distribution function at \(x=0\) for positive velocities only, then one could employ

pgkyl two-stream_elc_0.bp interp sel --z0 0. --z1 0.: pl -x '$x$' -y '$f_e(x=0,v_x,t=0)$'

Script mode¶

Unlike for the partial load parameters (see :ref:), float point numbers can be specified instead of just integers. In that case, Postgkyl treats it as a grid value and automatically finds and index of a grid point with the closest value. This works both for the single index and for specifying a slice.

In order to use select in a Python script one must interpolate the nodal/modal dataset in-place (normally it produces a new dataset, i.e. out-of-place) and pass the original Gkeyll data to the select command. For example, in order to select the 0-th coordinate at the value 0.0 we would use:

import postgkyl as pg

pgData   = pg.GData(fileName)
pgInterp = pg.GInterpModal(pgData, polyOrder, basisType)
pgInterp.interpolate(overwrite=True)
x, f_z0eq0p0 = pg.data.select(pgData, z0=0.0)

where pg.data.select returns the new grid (x) and the new field (f_z0eq0p0).