Welcome to the wiki for Python analysis tools for analyzing PVP files! Here, we provide documentation for 2 utility functions; namely, readpvpfile and writepvpfile. This code has been tested using Python 2.7, Numpy 1.1, and scipy 0.16.1. If you run into any incompatibilities, please submit an issue letting us know the problem.

Setup

We need to let Python know where to look for the scripts. To do this, we have 2 options.

Option 1: We can append the utility folder to PYTHONPATH.

#At the end of your .bashrc
export PYTHONPATH=$PYTHONPATH:/path/to/OpenPV/python

Option 2: We can add the path within the script itself.

#Python analysis file
import os, sys
lib_path = os.path.abspath("/path/to/OpenPV/python/")
sys.path.append(lib_path)
#Import library
import pvtools as pv

#readpvpfile The api for readpvpfile is the following:

data = pv.readpvpfile(inputFilename, progressPeriod, lastFrame, startFrame, skipFrames)

• inputFilename: The filename of the pvp file. Required parameter
• progressPeriod: How often to print out progress of reading a pvp file. Defaults to "do not print", or 0
• startFrame, lastFrame, skipFrame: The frames to be read is equivalent to range(startFrame, lastFrame, skipFrame). Here, startFrame defaults is 0, lastFrame defaults is all frames, and skipFrames defaults to 1

The output of readpvpfile is a dictionary with 3 fields: "header", "time", and "values".

• The "header" field contains a dictionary of key-value pairs for various header fields. Please see here for more information on the header.
• The "time" field contains a 1D Numpy array with size [numFrames] corresponding to the simulation timestep of the frame.
• The "values" field contains data based on the type of the file being read.
  • Dense values: "values" field contains a 4 dimensional Numpy array; namely, [numFrames, ny, nx, nf]
  • Sparse values: "values" field contains a 2 dimensional Scipy csr_sparse array; namely, [numFrames, ny*nx*nf]
  • Weight values: "values" field contains a 6 dimensional Numpy array; namely [numFrames, numArbors, numKernels, nyp, nxp, nfp]

#writepvpfile The api for writepvpfile is the following:

pv.writepvpfile(outFilename, data, shape, useExistingHeader)

• outFilename: The path of the output pvp file
• data: A data object with at least the "time" and "values" field as explained above in readpvpfile. Here, however, sparse data does not have to be in the format of a coo_sparse array; rather, any format of sparse matrices within the package scipy.sparse will work.
• shape: An optional argument that is required only for sparse files. A 3 tuple that defines the shape of the layer as (ny, nx, nf).
• useExistingHeader: An optional argument that defaults to False. If true, the data dictionary must contain a "header" field that is used for the written pvp file. If false, will generate a header based on the data parameter.

#Example Here is a script to read in a sparse-values pvp file, change to a dense matrix, and write out as a dense pvp file.

import scipy.sparse as sp
import numpy as np
#Assuming the PYTHONPATH contains the directory
import pvtools as pv

sparseData = pv.readpvpfile("sparseData.pvp")

#Use the same time structure in new data
denseData = {}
denseData["time"] = sparseData["time"]

#Change sparse data to dense data
tmpDenseData = sparseData["values"].todense()

#Convert numpy matrix type to ndarray type
tmpDenseData = np.array(tmpDenseData)

#Grab shape
(numFrames, drop) = tmpDenseData.shape
ny = sparseData["header"]["ny"]
nx = sparseData["header"]["nx"]
nf = sparseData["header"]["nf"]

#Reshape second dimension of ny*nx*nf to it's own dimensions
tmpDenseData = np.reshape(tmpDenseData, [numFrames, ny, nx, nf])

#Fill denseData dictionary with the data
denseData["values"] = tmpDenseData

#Write out to new pvp file
pv.writepvpfile("denseData.pvp", denseData)