Postgkyl key concepts¶

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 postpocessing scripts.

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.

Dataset¶

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, file1.bp and 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.

Command chaining¶

Commands are evaluated from left to right. Each command, by default applies to everything to the left of it. For example, this command chain combines loading data files and interpolate command:

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 applied on file2.bp. This particular example can be used, for example, to simultaneously work with finite-element and finite-volume data.

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.

Tags¶

During loading, optional flag, --tag or -t, can be used to assign a tag to the dataset(s).

The default behavior of most of the commands is agnostic to the tags. For example, the following two commands will lead to the same result:

pgkyl file1.bp file2.bp plot
pgkyl file1.bp -t 'f1' file2.bp -t 'f2' plot

However, most of the commands can take the --use or -u flag to limit them only to the datasets with the specified tag. Similar to the example above, this can be useful when working with different types of data:

pgkyl file1.bp -t 'f1' file2.bp -t 'f2' interpolate -u f1 plot

Here, interpolate will be used only on the file1.bp even though it follows loading both of the files. The plot command will then apply to both the datasets.

Note that multiple comma-separated tags can be used:

pgkyl file1.bp -t 'f1' file2.bp -t 'f2' file3.bp -t 'f3' interpolate -u f1,f2 plot

Additionally, there are some commands like collect or animate are by default tag-aware and separate datasets with different tags from each other.

When no tag is specified, the default tag is assigned.

pgkyl 'file?.bp' -t name

Active and inactive datasets¶

In addition to specifying tags, the flow of a 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.

Overwriting vs. new dataset¶

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[0] f[1] -' plot

As a result of this chain, there will be three datasets; however, only the result of ev will be active, so the plot command will create just one figure.

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 --tag or -t flag 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