Introduction¶

The package pycube installed on Cube provides a number of functions that can be parameterized with little effort. These functions, whose identifiers all begin with the prefix par_, are documented in the next subsections. Below you find explanations how the parameterization of these functions basically works.

Regardless of whether par_ functions, other functions from pycube or your own code is used, the Cube UI helpers and the log function are useful features that are explained below.

If you want to combine pycube par_ functions with your own code, the chapter Cube h5 file handling is interesting.

General Parameters¶

Parameters of the Cube par_ functions can be set either in the “local” task calling the par_ function itself, or in a preceding task called “000_globalparameter” (typically the first task in a workflow). If identical parameters are set globally and locally, the local setting overwrites the global parameters, but only in this task.

All parameters of par_ functions are predefined in a parameter class. Import an instance of this class with

from pycube.param.parameter import param

Setting parameters automatically performs a type check and saves the parameters to file.

Example:

from pycube.param.parameter import param
from pycube.fileop.h5 import par_h5_merge


if __name__ == "__main__":
    param.task_source_list = ['010_task1', '020_task2']
    param.task_target = '030_h5merge'
    param.delete_source = False
    par_h5_merge()

Plot Parameters¶

Plot parameters are handled by the class PlotParameter documented below. Plot parameters are used by the function par_plot_powerpoint.

class pycube.reports.plotter.PlotParameter(param_ref=None)¶

Plot parameters for a single plot.

Create an instance of PlotParameter for each plot to create. Calling PlotParameter(existing_plot_parameter) creates a copy of the existing parameter set, and only the parameters to be modified must be set to the new values.

Example:

# Create a full and a zoomd plot of my_signal1, my_signal2 as png files (no PowerPoint)
from pycube.param.parameter import param
from pycube.reports.plotter import *


param.task_source = 'my_input_task'

# autoscaled plot of my_signal1, my_signal2
plot_param_list = []
plot_param1 = PlotParameter()
plot_param1.y_left_signals = ['my_signal1', 'my_signal2']
plot_param1.y_left_legend_labels = ['My S1', 'My S2']
plot_param_list.append(plot_param1)

# zoomed plot: plot_param1 is copied, and only the scaling parameters must be set
plot_param2 = PlotParameter(plot_param1)
plot_param2.y_left_scaling = [-1.0, 1.0]
plot_param2.x_scaling = [1.0, 2.0]
plot_param_list.append(plot_param2)

par_plot_powerpoint(plot_param_list)

fft_length: int = 1024¶: Length of time sequence segment for an FFT

fft_overlap_percent: int = 95¶: Overlap of time sequence segments, min. 0, max. 99 %

fft_window: str = 'hann'¶: Window for the time sequence segments, possible values: see scipy.signal.get_window, windows without parameters

heading: str = 'Heading Text'¶: Plot heading text

marker_size: int = 2¶: Marker size

phs_solid: bool = True¶: Phase plot as solid line if True, dots at datapoints only if False

plot_type: int = 0¶: Plot type: supported types are BASE (default), SPECTRUM, COMPLEX, COMPLEX_COH

size_mm: List[float] = [200.0, 160.0]¶: Width / height of the plot in mm (only effective if no PowerPoint is created)

transparent: bool = True¶: Background transparency of the plot, defaults to True

x_label: str = 'time / s'¶: Label for x-axis

x_marker: List[float] = []¶: List of x-axis marker line positions

x_scaling: List[float] = [0.0, 0.0]¶: Scaling of x-axis. Autoscale if both 0.0

x_type: str = 'linear'¶: x-axis type (‘linear’, ‘log’)

y_left_coh_threshold: float = 0.0¶: Coherence threshold value, values below will be masked

y_left_colors: List[str] = ['red', 'blue', 'green', 'orange', 'cyan', 'violet']¶: List of colors used for signals displayed on left y-axis

y_left_label: str = 'qty / unit'¶: Label for left y-axis

y_left_legend: bool = True¶: Plot legend if True

y_left_legend_labels: List[str] = []¶: Optional signal labels (list of str) to display in the legend. Names as in y_<left/right>_signals are used if empty

y_left_linestyles: List[str] = ['-', '-', '-', '-', '-', '-']¶: List of linestyles used for signals displayed on left y-axis

y_left_marker: List[float] = []¶: List of marker line positions used for signals displayed on left y-axis

y_left_marker_coh: List[float] = []¶: List of marker line positions used for signals displayed on left y-axis of the coherence plot (plot type COMPLEX_COH)

y_left_marker_phs: List[float] = []¶: List of marker line positions used for signals displayed on left y-axis of the phase plot (plot type COMPLEX)

y_left_scaling: List[float] = [0.0, 0.0]¶: Scaling of left y-axis. Autoscale if both 0.0

y_left_signals: List[str] = ['group1/signal1', 'signal2', 'signal3', 'signal4']¶: List of signals to be displayed on the left y-axis. ‘group1/signal1’ sets the current h5 group to ‘group1’ at the same time.

y_left_signals_coh: List[str] = []¶: List of coherence signals, used with COMPLEX_COH plot type only

y_left_symbols: List[str] = ['', '', '', '', '', '']¶: List of marker symbols used for signals displayed on left y-axis

y_left_type: str = 'linear'¶: Left y-axis type (‘linear’, ‘log’)

y_right_coh_threshold: float = 0.0¶: Coherence threshold value, values below will be masked

y_right_colors: List[str] = ['darkred', 'darkblue', 'darkgreen', 'darkorange', 'darkcyan', 'darkviolet', 'black']¶: List of colors used for signals displayed on right y-axis

y_right_label: str = 'qty2 / unit2'¶: Label for right y-axis

y_right_legend: bool = True¶: Plot legend if True

y_right_legend_labels: List[str] = []¶: Optional signal labels (list of str) to diosplay in the legend. Names as in y_<left/right>_signals are used if empty

y_right_linestyles: List[str] = ['-', '-', '-', '-', '-', '-']¶: List of linestyles used for signals displayed on left y-axis

y_right_marker: List[float] = []¶: List of marker line positions used for signals displayed on right y-axis

y_right_marker_coh: List[float] = []¶: List of marker line positions used for signals displayed on right y-axis of the coherence plot (plot type COMPLEX_COH)

y_right_marker_phs: List[float] = []¶: List of marker line positions used for signals displayed on right y-axis of the phase plot (plot type COMPLEX)

y_right_scaling: List[float] = [0.0, 0.0]¶: Scaling of right y-axis. Autoscale if both 0.0

y_right_signals: List[str] = []¶: List of signals to be displayed relative to the right axis. Empty list if no right axis.

y_right_signals_coh: List[str] = []¶: List of coherence signals, used with COMPLEX_COH plot type only

y_right_symbols: List[str] = ['', '', '', '', '', '']¶: List of marker symbols used for signals displayed on right y-axis

y_right_type: str = 'linear'¶: Right y-axis type (‘linear’, ‘log’)

Cube UI helpers¶

Cube provides a basic interface to script variables, see section Variables here: Cube Documentation

Following helper functions are useful if you have lists of variable length. Define for example a list with 10 entries as your input variable. The helper functions strip them down to just the filled fields.

pycube.param.cube_ui_var.numlist(strings, numtype=<class 'float'>)¶

convert list of strings to list of numbers, ignoring empty strings

Parameters:

strings (List[str]) – input list
numtype (Type) – number type (int, float)

Return type:

List[int | float]

Returns:

list of numbers

Example:

from pycube.param.parameter import param
from pycube.param.cube_ui_var import numlist


if __name__ == "__main__":
    ...
    order = ["", "", ""]  # cube_ui_var
    param.order = strlist(order)
    ...
    param.write()
    ...

pycube.param.cube_ui_var.strlist(strings)¶

remove empty strings from input list

Parameters:: strings (List[str]) – input list
Return type:: List[str]
Returns:: list without empty strings

Example:

from pycube.param.parameter import param
from pycube.param.cube_ui_var import strlist


if __name__ == "__main__":
    ...
    signals = ["", "", "", "", "", "", "",  "",  "",  ""]  # cube_ui_var
    param.signals = strlist(signals)
    ...
    param.write('parameter.json')
    ...

Logger¶

It is recommended to add a logger to each task script. Cube functions log messages to a logger that can be activated in your script with the following code:

Example:

from pyfluidon.utils import custom_logger
...


if __name__ == "__main__":
    log = custom_logger.get_logger(level=custom_logger.INFO)
    ...

Log level is typically set to INFO. The DEBUG level is available for developing scripts, but should be avoided for fully developed scripts to avoid unnecessary message load.