There are a few basic concepts of using
pgkyl in a command
line. Together, they allow to quickly and easily create quite complex
diagnostics, which would otherwise require writing custom
Note that there are often multiple ways to achieve the same thing. Sometimes, they are analogous, othertimes, one is superior. This page makes an attempt to explain these key concepts to allow user to choose the best solution for each situation.
Each data file which is loaded creates a dataset. Additionally, some commands can create new datasets during the flow.
When files are loaded using wildcard characters, each match creates
its own dataset. Therefore, assuming there are two files,
file2.bp, located in the current directory, the two following
commands will have the same result; both will create two datasets:
pgkyl file1.bp file2.bp pgkyl file?.bp
The info command with the
-c flag is useful to list
all available datasets.
pgkyl file1.bp interpolate file2.bp
file1.bp is loaded first, its DG expansion coefficients
are then interpolated on a finer uniform mesh, and, finally,
file2.bp is loaded. interpolate will not be
file2.bp. This particular example can be used, for
example, to simultaneously work with finite-element and finite-volume
Commands that should not be applied on all the datasets can be further controlled using tags and by designating some datasets as inactive. Note that there are some commands, e.g., collect, which switch their inputs to inactive themselves.
It is worth noting that there is no limit on how many commands can be chained. See, for example, the particle balance section the the gyrokinetic quickstart page.
In addition to specifying tags, the flow
pgkyl command chain can be controlled by activating and deactivating
datasets. By default, all loaded datasets are active. This can be
changed with the pair of activate/deactivate and
pg_cmd_deactivate commands. In addition, commands that create a
new dataset, e.g., collect, leave only the output
active. The motivation behind this is that these commands change the
nature of data and user would typically want to keep working only with
the result. The aforementioned collect turns
N-dimensional data to (N+1)-dimensional data. With the inputs
inactive, commands can be easily chained, e.g.,
pgkyl 'file*.bp' collect plot
activate/deactivate can either take in indices, tags, or both. When no inputs are specified, everything is activated. The two following commands provide yet another way to to achieve the same result as in the tag example above:
pgkyl file1.bp -t f1 file2.bp -t f2 activate -t f1 interpolate activate plot pgkyl file1.bp file2.bp activate -i 0 interpolate activate plot
In both cases only the
file1.bp is active and, therefore, the
interpolate command is applied only on the first
file. The second activate then reactivates the second file again so
the plot command is going to plot both.
The info command can be useful when working with
multiple active/inactive datasets. Its
--compact option shows only
identifiers for each dataset, thus removes some clatter, and
--allsets adds even the currently inactive datasets.
There are two basic ways commandsinteract with inputs. The first type modifies its inputs and pushes data down the chain. A typical example is the interpolate command, which takes expansion coefficients of DG finite-element data and interpolates them on a finer uniform mesh, essentially creating finite-volume like data.
pgkyl file1.bp interpolate plot
In this case the original information is lost after the interpolate command (lost within this command chain, nothing happens to the data file itself).
The other type does not overwrite its inputs but rather creates a new dataset. As a rule of thumb, these are commands that take (or can take) multiple inputs and/or change the nature of data. Note that these commands often make the result the only active dataset to simplify the flow. A typical example is the ev command:
pgkyl file1.bp file2.bp ev 'f f -' plot
There are instances when user does not want to overwrite the
inputs. For example, when we want to use select to
create multiple slices of data. For this purpose, the commands that
would normally overwrite data have the optional
which instead creates a new dataset with specified tag. Note that in
this case, the resulting dataset will not be the only one active.
pgkyl file1.bp -t input select -u input --z0 -1. -t planes \ select -u input --z0 1. -t planes plot -u planes