plothist

Use the plothist tool to plot the results of w_pdist. This tool uses an hdf5 file as its input (i.e. the output of another analysis tool), and outputs a pdf image.

The plothist tool operates in one of three (mutually exclusive) plotting modes:

  • ``evolution``: Plots the relevant data as a time evolution over specified number of simulation iterations
  • ``average``: Plots the relevant data as a time average over a specified number of iterations
  • ``instant``: Plots the relevant data for a single specified iteration

Overview

The basic usage, independent of plotting mode, is as follows:

usage:

$WEST_ROOT/bin/plothist [-h] [-r RCFILE] [--quiet | --verbose | --debug] [--version]
                        {instant,average,evolution} input ...

Note that the user must specify a plotting mode (i.e. ‘instant‘, ‘average‘, or ‘evolution‘) and an input file, input.

Therefore, this tool is always called as:

$WEST_ROOT/bin/plothist mode input_file [``other`` ``options``]

‘instant‘ mode

usage:

$WEST_ROOT/bin/plothist instant [-h] input [-o PLOT_OUTPUT]
                                [--hdf5-output HDF5_OUTPUT] [--text-output TEXT_OUTPUT]
                                [--title TITLE] [--range RANGE] [--linear | --energy | --log10]
                                [--iter N_ITER] 
                                [DIMENSION] [ADDTLDIM]

‘average‘ mode

usage:

$WEST_ROOT/bin/plothist average [-h] input [-o PLOT_OUTPUT]
                                [--hdf5-output HDF5_OUTPUT] [--text-output TEXT_OUTPUT]
                                [--title TITLE] [--range RANGE] [--linear | --energy | --log10]
                                [--first-iter N_ITER] [--last-iter N_ITER]                           
                                [DIMENSION] [ADDTLDIM]

‘evolution‘ mode

usage:

$WEST_ROOT/bin/plothist evolution [-h] input [-o PLOT_OUTPUT]
                                  [--hdf5-output HDF5_OUTPUT]
                                  [--title TITLE] [--range RANGE] [--linear | --energy | --log10]
                                  [--first-iter N_ITER] [--last-iter N_ITER]
                                  [--step-iter STEP]                                   
                                  [DIMENSION]

Command-Line Options

See the command-line tool index for more information on the general options.

Unless specified (as a Note in the command-line option description), the command-line options below are shared for all three plotting modes

Input/output options

No matter the mode, an input hdf5 file must be specified. There are three possible outputs that are mode or user-specified: A text file, an hdf5 file, and a pdf image.

Specifying input file

*``input``*
Specify the input hdf5 file ‘’input. This is the output file from a previous analysis tool (e.g. ‘pcpdist.h5’)

Output plot pdf file

``-o ‘’plot_output’‘, –plot_output ‘’plot_output’‘``
Specify the name of the pdf plot image output (Default: ‘hist.pdf’). Note: You can suppress plotting entirely by specifying an empty string as plot_output (i.e. -o '' or --plot_output '')

Additional output options

Note: plothist provides additional, optional arguments to output the data points used to construct the plot:

``–hdf5-output ‘’hdf5_output’‘``
Output plot data hdf5 file 'hdf5_output' (Default: No hdf5 output file)
``–text-output ‘’text_output’‘``
Output plot data as a text file named 'text_output' (Default: No text output file) Note: This option is only available for 1 dimensional histogram plots (that is, 'average' and 'instant' modes only)

Plotting options

The following options allow the user to specify a plot title, the type of plot (i.e. energy or probability distribution), whether to apply a log transformation to the data, and the range of data values to include.

``–title ‘’title’’ ``
Optionally specify a title, ``title``, for the plot (Default: No title)
``–range ‘’<nowiki>’</nowiki>LB, UB<nowiki>’</nowiki>’‘``
Optionally specify the data range to be plotted as “LB, UB” (e.g. ' --range "-1, 10" ' - note that the quotation marks are necessary if specifying a negative bound). For 1 dimensional histograms, the range affects the y axis. For 2 dimensional plots (e.g. evolution plot with 1 dimensional progress coordinate), it corresponds to the range of the color bar

Mutually exclusive plotting options

The following three options determine how the plotted data is represented (Default: '--energy')

``–energy ``
Plots the probability distribution on an inverted natural log scale (i.e. -ln[P(x)] ), corresponding to the free energy (Default)
``–linear ``
Plots the probability distribution function as a linear scale
``–log10 ``
Plots the (base-10) logarithm of the probability distribution

Iteration selection options

Depending on plotting mode, you can select either a range or a single iteration to plot.

``’instant’`` mode only:

``–iter ‘’n_iter’’ ``
Plot the distribution for iteration ''n_iter'' (Default: Last completed iteration)

``’average’`` and ``’evolution’`` modes only:

``–first-iter ‘’first_iter’’ ``
Begin averaging or plotting at iteration ``first_iter`` (Default: 1)
``–last-iter ‘’last_iter’’ ``
Average or plot up to and including ``last_iter`` (Default: Last completed iteration)

``’evolution’`` mode only:

``–iter_step ‘’n_step’’ ``
Average every ``n_step`` iterations together when plotting in 'evolution' mode (Default: 1 - i.e. plot each iteration)

Specifying progress coordinate dimension

For progress coordinates with dimensions greater than 1, you can specify the dimension of the progress coordinate to use, the of progress coordinate values to include, and the progress coordinate axis label with a single positional argument:

``dimension ``
Specify 'dimension' as ‘int[:[LB,UB]:label]‘, where ‘int‘ specifies the dimension (starting at 0), and, optionally, ‘LB,UB‘ specifies the lower and upper range bounds, and/or ‘label‘ specifies the axis label (Default: int = 0, full range, default label is ‘dimension int‘; e.g ‘dimension 0’)

For 'average' and 'instant' modes, you can plot two dimensions at once using a color map if this positional argument is specified:

``addtl_dimension ``
Specify the other dimension to include as 'addtl_dimension'

Examples

These examples assume the input file is created using w_pcpdist and is named ‘pcpdist.h5’

Basic plotting

Plot the energy ( -ln(P(x)) ) for the last iteration

$WEST_ROOT/bin/plothist instant pcpdist.h5

Plot the evolution of the log10 of the probability distribution over all iterations

$WEST_ROOT/bin/plothist evolution pcpdist.h5 --log10 

Plot the average linear probability distribution over all iterations

$WEST_ROOT/bin/plothist average pcpdist.h5 --linear

Specifying progress coordinate

Plot the average probability distribution as the energy, label the x-axis ‘pcoord’, over the entire range of the progress coordinate

$WEST_ROOT/bin/plothist average pcpdist.h5 0::pcoord

Same as above, but only plot the energies for with progress coordinate between 0 and 10

$WEST_ROOT/bin/plothist average pcpdist.h5 '0:0,10:pcoord'

(Note: the quotes are needed if specifying a range that includes a negative bound)

(For a simulation that uses at least 2 progress coordinates) plot the probability distribution for the 5th iteration, representing the first two progress coordinates as a heatmap

$WEST_ROOT/bin/plothist instant pcpdist.h5 0 1 --iter 5 --linear