soft4pes.utils#

Reference frame transformations and reference sequence generation.

Submodules#

Classes#

`Sequence`	Sequence class can be used to generate a sequence of values over time.
`Plotter`	This class provides methods to plot system states, switching behavior, and control signals. It

Functions#

`abc_2_alpha_beta`(abc)	Convert a quantity from abc-frame to alpha-beta frame using the reduced
`alpha_beta_2_abc`(alpha_beta)	Convert a quantity from abc-frame to alpha-beta frame using the inverse
`alpha_beta_2_dq`(alpha_beta, theta)	Convert a quantity from alpha-beta frame to dq-frame. The common-mode
`dq_2_alpha_beta`(dq, theta)	Convert a quantity from dq-frame to alpha-beta frame. The common-mode
`dq_2_abc`(dq, theta)	Convert a quantity from dq-frame to abc-frame using the inverse reduced Park

Package Contents#

soft4pes.utils.abc_2_alpha_beta(abc)[source]#

Convert a quantity from abc-frame to alpha-beta frame using the reduced Clarke transformation. The common-mode component is neglected.

Parameters:: abc (1 x 3 ndarray of floats) – Input quantity in abc-frame.
Returns:: Quantity in alpha-beta frame.
Return type:: 1 x 2 ndarray of floats

soft4pes.utils.alpha_beta_2_abc(alpha_beta)[source]#

Convert a quantity from abc-frame to alpha-beta frame using the inverse reduced Clarke transformation. The common-mode component is neglected.

Parameters:: abc (1 x 3 ndarray of floats) – Input quantity in abc-frame.
Returns:: Quantity in alpha-beta frame.
Return type:: 1 x 2 ndarray of floats

soft4pes.utils.alpha_beta_2_dq(alpha_beta, theta)[source]#

Convert a quantity from alpha-beta frame to dq-frame. The common-mode component is neglected.

Parameters:

alpha_beta (1 x 2 ndarray of floats) – Quantity in alpha-beta frame.
theta (float) – Angle of the reference frame in radians.

Returns:

Quantity in dq-frame.

Return type:

1 x 2 ndarray of floats

soft4pes.utils.dq_2_alpha_beta(dq, theta)[source]#

Convert a quantity from dq-frame to alpha-beta frame. The common-mode component is neglected.

Parameters:

dq (1 x 2 ndarray of floats) – Quantity in dq-frame.
theta (float) – Angle of the reference frame in radians.

Returns:

Quantity in alpha-beta frame.

Return type:

1 x 2 ndarray of floats

soft4pes.utils.dq_2_abc(dq, theta)[source]#

Convert a quantity from dq-frame to abc-frame using the inverse reduced Park trasformation. The common-mode component is neglected.

Parameters:

dq (1 x 2 ndarray of floats) – Quantity in dq-frame.
theta (float) – Angle of the reference frame in radians.

Returns:

Quantity in abc-frame.

Return type:

1 x 3 ndarray of floats

class soft4pes.utils.Sequence(times, values)[source]#

Sequence class can be used to generate a sequence of values over time.

The time array must be increasing. The output values are interpolated between the data points.

Parameters:

times (n x 1 ndarray of floats) – Time instants is seconds.
values (n x m ndarray of floats) – Output values.

times#

Time instants is seconds.

Type:: n x 1 ndarray of floats

values#

Output values.

Type:: n x m ndarray of floats

__call__(kTs)[source]#

Interpolate the output.

Parameters:: kTs (float) – Current discrete time instant [s].
Returns:: Interpolated output.
Return type:: 1 x m ndarray of floats

class soft4pes.utils.Plotter(data, sys, t_start=0, t_end=None)[source]#

This class provides methods to plot system states, switching behavior, and control signals. It supports multiple reference frames (abc, alpha-beta, dq). The main functions of the class are: - plot_states: Plot system states in specified reference frames. - plot_control_signals_grid: Plot control signals for grid-connected systems (active/reactive

power, voltage magnitude).

plot_control_signals_machine: Plot control signals for electric machines (torque).
show_all: Display all generated plots.

Parameters:

data (SimulationData) – Simulation data containing system and controller results
sys (System) – System object with state mapping and configuration
t_start (float, optional) – Start time for all plots (default: 0)
t_end (float, optional) – End time for all plots (default: None, uses full simulation time)

Examples

>>> plotter = SystemPlotter(data, sys, t_start=0, t_end=0.2)
>>> plotter.plot_states(['vc', 'ig'], frames=['abc', 'alpha-beta'])
>>> plotter.plot_control_signals_grid(plot_P=True, plot_Q=True, P_ref=P_ref_seq)
>>> plotter.show_all()

plot_control_signals_grid(plot_P=False, plot_Q=False, plot_V=False, P_ref=None, Q_ref=None, V_ref=None)[source]#

Plot grid-connected system control signals (active/reactive power, voltage magnitude). The voltage magnitude corresponds to converter output voltage (no LCL filter) or capacitor voltage (with LCL filter).

Parameters:

plot_P (bool, optional) – Plot active power P (default: False)
plot_Q (bool, optional) – Plot reactive power Q (default: False)
plot_V (bool, optional) – Plot voltage magnitude (converter or capacitor) (default: False)
P_ref (Sequence, optional) – Active power reference trajectory
Q_ref (Sequence, optional) – Reactive power reference trajectory
V_ref (Sequence, optional) – Voltage magnitude reference trajectory

Notes

If both plot_P and plot_Q are True, they are plotted together
Voltage plots either converter voltage (if no capacitor) or capacitor voltage
Power is calculated as: P = vg_alpha*ig_alpha + vg_beta*ig_beta, Q = vg_beta*ig_alpha - vg_alpha*ig_beta

plot_control_signals_machine(plot_T=False, T_ref=None)[source]#

Plot machine control signals (electromagnetic torque).

Parameters:

plot_T (bool, optional) – Plot electromagnetic torque Te (default: False)
T_ref (Sequence, optional) – Torque reference trajectory

plot_states(states_to_plot, frames=None, plot_u_abc_ref=False, plot_u_abc=False)[source]#

Plot system states in specified reference frames. Moreover, the modulating signal u_abc_ref and/or the actual converter output can be plotted. In case modulator is not used, u_abc_ref=u_abc.

Parameters:

states_to_plot (list of str) – List of state names to plot (e.g., [‘vc’, ‘ig’, ‘i_conv’]). The existing states can be confirmed by checking the model class documentation.
frames (list of str, optional) – Reference frames for each state (‘abc’, ‘alpha-beta’, ‘dq’). If None, defaults to ‘alpha-beta’ for all states. The dq-frame is aligned with - the grid voltage for grid-connected systems - the rotor flux for induction machines - the rotor angle for PMSMs
plot_u_abc_ref (bool, optional) – Plot modulating signal u_abc_ref in one subplot (default: False)
plot_u_abc (bool, optional) – Plot actual converter output u_abc in separate subplots (default: False)

Examples

>>> plotter.plot_states(['vc', 'ig'], frames=['abc', 'alpha-beta'])
>>> plotter.plot_states(['i_conv'], frames=['dq'], plot_u_abc=True)

show_all()[source]#

Display all registered figures and keep them open.

This method should be called after creating all desired plots to display them simultaneously. Figures remain open until manually closed by the user.

calc_harmonics(signal, f_fund_SI=50.0, start_time=None, n_cycles=None)[source]#

Calculate harmonic magnitudes and Total Harmonic Distortion (THD) of one or multiple signals.

Parameters:

signal (ndarray) – Time-domain signal. Shape can be (N,) for single signal or (N, M) for M signals.
f_fund_SI (float, optional) – Fundamental frequency in Hz (default: 50.0).
start_time (float, optional) – Start time for harmonic analysis (default: self.t_start).
n_cycles (int, optional) – Number of fundamental cycles to include in analysis (default: None, uses full available time).

Returns:

Dictionary containing: - ‘orders’: Harmonic orders (1, 2, …, h_max) - ‘freqs_hz’: Frequencies of harmonics in Hz - ‘magnitudes’: Harmonic magnitudes - ‘ratio’: Harmonic magnitudes normalized to fundamental - ‘THD’: Total Harmonic Distortion

Return type:

dict

plot_spectra(states_to_plot=None, f_fund_SI=50.0, f_max_SI_plot=None, start_time=None, n_cycles=None, style='bar')[source]#

Plot harmonic spectra with frequency [Hz] on x-axis and vertical harmonic lines.

Parameters:

states_to_plot (list of str or str, optional) – State names to plot. If None, all states are plotted (default: None).
f_fund_SI (float, optional) – Fundamental frequency in Hz (default: 50.0).
f_max_SI_plot (float, optional) – Maximum frequency to plot in Hz (default: None, uses Nyquist limit).
start_time (float, optional) – Start time for harmonic analysis (default: self.t_start).
n_cycles (int, optional) – Number of fundamental cycles to include in analysis (default: None, uses full available time).
style (str, optional) – Plot style: ‘bar’ for vertical lines, ‘line’ for connected lines (default: ‘bar’).

Examples

>>> plotter.plot_spectra(states_to_plot=['ig', 'vc'], f_fund_SI=50.0, f_max_SI_plot=1000.0)
>>> plotter.plot_spectra(f_fund_SI=60.0, n_cycles=10, style='line')