Installing VicPyX

The vicpyx python module permits loading and saving of Vic-3D data files in python. This allows custom post-processing and data reduction algorithms to be implemented very quickly and efficiently. Since the python module can write results in Vic-3D’s native output format, the post-processing results can then be used in Vic-3D for visualization.

Moreover, the vicpyx modules powers the Extensions found in Vic-3D.

ATTENTION : The vicpyx module is not compatible with the old VicPy module. Scripts written for VicPy need to be updated for vicpyx. The new module introduces several optimizations, enabling users to write more efficient code that also executes faster. Users of the VicPy module are encouraged to update their scripts to take advantage of the new one.

Installation

The vicpyx module is available on The Python Package Index and can be installed with the following pip command:

pip install vicpyx

To get all the required packages for the Correlated Solutions supported extensions you can instead do:

pip install vicpy-extension-requirements

If you’d like to test the module, install the examples from this link: Python Examples. A short instruction file is in the ZIP.

Running vicpyx Scripts

1. If you are comfortable with the console you can simply use the console Python application to run .py and .pyw modules.
2. To run directly, you will have to associate .py and .pyw modules with the relevant applications. To do this, navigate to the file; right-click, and select Open with….
3. Select More apps.
4. Scroll all the way to the bottom, and select Look for another app on this PC
5. Navigate to the folder path\to\your\python.exe.
6. Select python.exe for .py files, and pythonw.exe for .pyw files. (For applications with a graphical interface, PYW files will show the application without the unnecessary console window.)
7. After this, if you double click on another script, it should run directly.

Example

To illustrate what can be done with the vicpyx module, here is a very simple example that loads a data file, computes the magnitude of the displacement for all data points, and saves the data file under a new filename.

import sys
from os import _exit as exit

import numpy as np
from vicpyx import *
if len(sys.argv) != 3:
    print(f"Usage: {sys.argv[0]} infile.out outfile.out\n")
    exit(-1)

dataset = VicDataSet()

if dataset.load(sys.argv[1]) == False:
    print("Could not load data set\n")
    exit(-1)

var_names = ["U", "V", "W"]
values = dataset.get_values(var_names)

D_values = np.sqrt(values["U"] ** 2 + values["V"] ** 2 + values["W"] ** 2)

vars = dataset.variables()

d_var = "D"
if d_var not in vars:
    d_var = dataset.add_variable("D", "Δ [mm]")

dataset.set_values({d_var: D_values})

if dataset.save(sys.argv[2]) == False:
    print("Could not save the dataset\n")
    exit(-1)

Breaking down the different parts of the script:

Imports

import sys
from os import _exit as exit

import numpy as np
from vicpyx import *

The beginning of the script imports the required modules for the script. The sys module provides access to the command-line arguments and the exit function is imported from the os module. The numpy module is imported so that the square-root function can be used and finally the vicpyx module is imported so that its classes become available for use.

Checking the arguments and loading the Dataset

if len(sys.argv) != 3:
    print(f"Usage: {sys.argv[0]} infile.out outfile.out\n")
    exit(-1)

dataset = VicDataSet()

if dataset.load(sys.argv[1]) == False:
    print("Could not load data set\n")
    exit(-1)

The program checks that an input and output file are specified on the command line and displays a usage message if not and then exits. If two arguments are given, a VicDataSet is created and the script attempts to read the specified input file. If an error occurs, the program displays an error message and exits.

Computing and adding the new variable to the Dataset

var_names = ["U", "V", "W"]
values = dataset.get_values(var_names)

D_values = np.sqrt(values["U"] ** 2 + values["V"] ** 2 + values["W"] ** 2)

vars = dataset.variables()

d_var = "D"
if d_var not in vars:
    d_var = dataset.add_variable("D", "Δ [mm]")

dataset.set_values({d_var: D_values})

Here, the values of the displacement on each axis are first retrieved from the dataset. Then the values for the new variable is calculated. This is done for all points in the dataset. Then, a check is performed to see if the dataset already contains a variable with the same name, and if not, it is then added. Note here, that the ‘add_variable’ method returns the name of the variable just added to the dataset. This ensures that all variable names in Vic data files remain be unique. The values for the new variable are then set in the dataset.

Writing the dataset

if dataset.save(sys.argv[2]) == False:
    print("Could not save the dataset\n")
    exit(-1)

Finally, the script saves the dataset in the output file specified on the command line.