FFT/THD¶

The FFTModule class provides methods to interact with FFT/THD modules.

Note

The FFT/THD module requires an instance of the ScopeModule in the project to acquire the data that it will process.

Creating and controlling an FFT/THD module¶

The following example demonstrates how to instantiate an FFT/THD module, configure the parameters of the FFT, run an acquisition, and export the resulting data:

# Create a Scope module
scope = project.modules.create(ModuleType.SCOPE)

# Create and configure an FFT/THD module
fft = project.modules.create(ModuleType.FFT_THD)
fft.add_variables(["Vg_a", "Vg_b", "Vg_c"])
fft.set_freq_resolution(freq_resolution_hz = 20)

target.enable_pwm()

# Tell the scope to start acquiring the data for FFT
fft.play()

# Wait until the Scope has acquired the data
cockpit.wait_until(scope.is_capture_done, timeout=15.0, interval=0.2)

target.disable_pwm()

# Export the FFT data in the CSV format
fft.export("C:/imperix/captures/data.mat")

# Reuse the acquired data to calculate the Total Harmonic Distortion (THD)
# w.r.t. a fundamental frequency of 50Hz
thd = fft.get_thd(fund_freq_hz = 50.0, variables = ["Vg_a", "Vg_b", "Vg_c"])
print(thd)

API Reference¶

class imperix.FFTModule(cockpit: Cockpit, data: dict[str, Any])¶

export(path: str | PathLike[str], *, plot: int = 0, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → None¶

Export acquired data from one plot to a CSV or MAT file.

Parameters:

path – Absolute path where the file will be written, as a string or Path. The file extension selects the export format. The supported extensions are .csv and .mat.
plot – Index of the plot to export. Defaults to 0 (the first plot).
timeout – Maximum time to wait for a response in seconds.

Raises:

InvalidStateError – If Cockpit cannot export the acquired data.

Example:

fft.export("C:/imperix/captures/scope_data.csv")

stop(*, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → None¶

Stops the acquisition.

Parameters:: timeout – Maximum time to wait for a response in seconds.
Raises:: InvalidStateError – If the acquisition cannot be stopped.

add_plot(*, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → int¶

Creates a new plot.

Parameters:: timeout – Maximum time to wait for a response in seconds.
Returns:: The index of the newly created plot.
Raises:: InvalidStateError – If Cockpit cannot create the plot.

Example:

# Add variables to the first plot
fft.add_variables(["Va", "Vb", "Vc])

# Create and add variables to a second plot
current_plot = scope.add_plot()
fft.add_variables(["Ia", "Ib", "Ic"], plot=current_plot)

remove_plot(plot: int, *, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → None¶

Deletes a plot.

Parameters:

plot – index of the plot to remove.
timeout – Maximum time to wait for a response in seconds.

Raises:

InvalidStateError – If this is the only remaining plot or Cockpit cannot remove it.

plot_count(*, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → int¶

Returns the current number of plots.

Parameters:: timeout – Maximum time to wait for a response in seconds.
Returns:: Number of plots in the scope.

list_variables(*, plot: int = 0, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → Any¶

Returns the list of variables in a plot.

Parameters:

plot – plot index. Defaults to 0.
timeout – Maximum time to wait for a response in seconds.

Returns:

A list of variable names on the given plot.

Example::: print(fft.list_variables(plot=0))

get_thd(*, variables: str | Sequence[str] | None = None, plot: int = 0, fund_freq_hz: float = 50.0, window_start_ms: float = 0, weighted: bool = False, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → dict[str, float]¶

Return the Total Harmonic Distortion (THD) for the selected FFT variables.

Parameters:

variables – Variable name or names to process. When omitted, every variable in the plot is processed.
plot – 0-based plot index. Defaults to 0.
fund_freq_hz – Frequency of the fundamental harmonic in Hertz.
window_start_ms – Start of the FFT window over which the harmonics will be calculated.
weighted – Selects whether to calculate the THD or the Weighted (WTHD) value.
timeout – Override the default timeout (seconds).

Returns:

A mapping from variable names to phase shifts in degrees.

add_variables(names: Sequence[str], *, plot: int = 0, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → None¶

Adds variables by name.

Parameters:

names – Name(s) of the variables to add.
plot – plot index to add them to. Defaults to 0 (the first plot).
timeout – Maximum time to wait for a response in seconds.

Raises:

InvalidStateError – If Cockpit cannot add the variables.

Example::: fft.add_variables([“Va”, “Vb”, “Vc”])

remove_variables(names: Sequence[str], *, plot: int = 0, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → None¶

Removes variables from an FFT module plot by name.

Parameters:

names – Name(s) of the variables to remove.
plot – plot index to remove them from. Defaults to 0 (the first plot).
timeout – Maximum time to wait for a response in seconds.

Raises:

InvalidStateError – If Cockpit cannot remove the variables.

set_window(*, window_ms: float, window_start_ms: float, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → None¶

Sets the FFT window duration and position.

Parameters:

window_ms – FFT window size in milliseconds.
window_start_ms – Start of FFT window within the Scope acquisition window in milliseconds.
timeout – Maximum time to wait for a response in seconds.

Raises:

InvalidStateError – If Cockpit cannot update the capture window.

set_freq_resolution(*, freq_resolution_hz: float, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → None¶

Sets the FFT spectrum resolution for all variables.

Parameters:

freq_resolution_hz – Frequency resolution in Hertz.
timeout – Maximum time to wait for a response in seconds.

Raises:

InvalidStateError – If Cockpit cannot update the frequency resolution.

play(*, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → None¶

Sends a signal to the scope to arm itself and wait for a trigger event.

Parameters:: timeout – Maximum time to wait for a response in seconds.
Raises:: InvalidStateError – If the scope cannot be armed.