motulator_impedance.grid ======================== .. py:module:: motulator_impedance.grid .. autoapi-nested-parse:: Output admittance of grid converters. The output admittance of the converter at the point of common coupling (PCC) is measured from simulations by a frequency sweep [#Maa2026]_: the PCC voltage is imposed by a stiff source, and small-signal voltage excitations are injected in the d- and q-axes one frequency at a time. The admittance is the basis of impedance-based stability analysis, e.g., through its passivity. .. rubric:: References .. [#Maa2026] Määttä, Kukkola, Seppänen, Hinkkanen, "Open-source Python tool for grid converter output admittance identification," 2026, https://arxiv.org/abs/2607.10653 .. !! processed by numpydoc !! Classes ------- .. autoapisummary:: motulator_impedance.grid.MeasurementCfg motulator_impedance.grid.OutputAdmittance Functions --------- .. autoapisummary:: motulator_impedance.grid.measure_output_admittance motulator_impedance.grid.plot_operating_point motulator_impedance.grid.plot_output_admittance Module Contents --------------- .. py:class:: MeasurementCfg Configuration of the output admittance measurement. :param abs_u_e: Magnitude of the voltage excitation (V) at the first frequency. :type abs_u_e: float :param freqs: Excitation frequencies (Hz, in dq-coordinates), defaults to 100 logarithmically spaced frequencies from 1 Hz to 10 kHz. :type freqs: ndarray, optional :param amplitude_multiplier: Excitation magnitude at the last frequency relative to the first one, defaults to 5. The magnitude changes linearly over the frequency array. Use 1 for a constant magnitude. :type amplitude_multiplier: float, optional :param t0: Stop time for initial simulating to the operating point (s), defaults to 1.0. Should be set large enough to reach steady-state. A time-varying grid frequency must be constant over the last `n_periods_init` periods. :type t0: float, optional :param t1: Additional simulation time for reaching sinusoidal steady-state during signal injection (s), defaults to 0.05. :type t1: float, optional :param N_eval: Number of evenly spaced data points the solver should return for each integration interval, i.e., for each sampling period or, if carrier comparison is used, for each switching interval, defaults to 10. More points are used at high excitation frequencies, so that each excitation period has at least 10 points. :type N_eval: int, optional :param n_periods_excitation: Number of excitation signal periods used in calculating the DFT, defaults to 4. At least 3 are needed if `use_window` is True. :type n_periods_excitation: int, optional :param n_periods_init: Number of fundamental periods to include for calculating operating-point vectors, defaults to 1. :type n_periods_init: int, optional :param multiprocess: If True, the frequencies are simulated in parallel using all available CPU cores, defaults to True. The model and the control system are copied to the worker processes, which can require pickling them. Lambda functions and nested functions (e.g., as references) cannot be pickled, but module-level functions can. In a script, call the measurement under `if __name__ == "__main__":`, as in the examples. :type multiprocess: bool, optional :param use_window: Whether to use window function for calculating DFT, defaults to True. :type use_window: bool, optional .. !! processed by numpydoc !! .. py:class:: OutputAdmittance Measured output admittance. Contains fields for excitation signal frequency `f_e`, elements of the output admittance matrix `[Y_dd, Y_qd; Y_dq, Y_qq]`, and the following operating-point vectors (in synchronous coordinates aligned with the PCC voltage): grid current `i_g0`, grid voltage `e_g0`, PCC voltage `u_g0` and converter voltage `u_c0`. The results can be saved, e.g., by ``scipy.io.savemat(path, dataclasses.asdict(res))``. .. !! processed by numpydoc !! .. py:function:: measure_output_admittance(mdl, ctrl, cfg) Measure the output admittance of the converter. The system is first simulated to the operating point. Then, the output admittance of the converter is measured at the PCC: the PCC voltage is imposed by a stiff voltage source, whose magnitude and frequency equal those of the operating point, and small-signal voltage excitations are injected in the d- and q-axes. The grid impedance of `mdl` as well as any time variation and negative-sequence component of its source only affect the operating point, whose grid frequency is that of the source at `t0`. A DC bus of `mdl` is included in the measurement. :param mdl: Continuous-time system model. :type mdl: GridConverterSystem :param ctrl: Discrete-time control system. :type ctrl: GridConverterControlSystem :param cfg: Measurement configuration. :type cfg: MeasurementCfg :returns: Admittance matrix elements and the operating point. :rtype: OutputAdmittance .. rubric:: Notes With carrier-comparison PWM, background switching harmonics can bias the measured admittance at the excitation frequency. Results near switching harmonics and their sidebands may depend strongly on the excitation amplitude and its phase relative to the carrier, even when the numerical solution has converged. .. !! processed by numpydoc !! .. py:function:: plot_operating_point(res, base, latex = False) Plot the converter voltage, PCC voltage, grid voltage, and grid current vectors of the operating point. :param res: Output admittance with the operating point. :type res: OutputAdmittance :param base: Base values for per-unit conversion. :type base: BaseValues :param latex: Use latex for plots, defaults to False. :type latex: bool, optional .. !! processed by numpydoc !! .. py:function:: plot_output_admittance(res, form = 're_im', passivity_index = True, latex = False) Plot the elements of the output admittance matrix. :param res: Output admittance. :type res: OutputAdmittance :param form: Form of the elements, defaults to "re_im". Options are: - "polar": magnitude and phase - "re_im": real and imaginary parts :type form: Literal["polar", "re_im"], optional :param passivity_index: Plot also the input feedforward passivity index computed from the admittance matrix, defaults to True. :type passivity_index: bool, optional :param latex: Use latex for plots, defaults to False. :type latex: bool, optional .. !! processed by numpydoc !!