Simplification in the code and comments, renaming a few files and classes. Deleting some extra features in grid converter control. Implementation of the frequency converter with diode bridge is partly reverted to the earlier version for its simpler usage. (#138)

Author: mhinkkan

docs/source/conf.py

@@ -73,6 +73,8 @@
         "../../examples/obs_vhz",
         "../../examples/flux_vector",
         "../../examples/signal_inj",
+        "../../examples/grid_following",
+        "../../examples/grid_forming",
     ]),
 }
 

docs/source/model/converters.rst

@@ -1,19 +1,19 @@
 Converters
 ==========
 
-Inverter
---------
+Voltage-Source Converter
+------------------------
 
-The figure below shows a three-phase two-level inverter and its equivalent model, where ideal switches  are assumed. In the equivalent model, each changeover switch is connected to either negative or positive potential of the DC bus. The switching phenomena are assumed to be infinitely fast. The inverter model is provided in the class :class:`motulator.drive.model.Inverter`. 
+The figure below shows a three-phase two-level voltage-source converter and its equivalent model, where ideal switches are assumed. This converter can operate both as an inverter and a rectifier, depending on the direction of the power flow. In the equivalent model, each changeover switch is connected to either negative or positive potential of the DC bus. The switching phenomena are assumed to be infinitely fast. The converter model is provided in the class :class:`motulator.drive.model.VoltageSourceConverter`. 
 
 
 .. figure:: figs/inverter.svg
    :width: 100%
    :align: center
-   :alt: Three-phase two-level inverter
+   :alt: Three-phase two-level voltage-source converter
    :target: .
 
-   Three-phase two-level inverter: (left) main circuit; (right) equivalent model. The DC-bus voltage and currents are :math:`u_\mathrm{dc}` and :math:`i_\mathrm{dc}`, respectively.
+   Three-phase two-level voltage-source converter: (left) main circuit; (right) equivalent model. The DC-bus voltage and currents are :math:`u_\mathrm{dc}` and :math:`i_\mathrm{dc}`, respectively.
 
 Six-Pulse Diode Bridge
 ----------------------
@@ -31,12 +31,12 @@ The figure below shows a six-pulse diode bridge rectifier, where the inductor :m
 Carrier Comparison
 ------------------
 
-The figure below shows an inverter equipped with a generic three-phase load. In pulse-width modulation (PWM), carrier comparison is commonly used to generate instantaneous switching state signals :math:`q_\mathrm{a}`, :math:`q_\mathrm{b}`, and :math:`q_\mathrm{c}` from duty ratios :math:`d_\mathrm{a}`, :math:`d_\mathrm{b}`, and :math:`d_\mathrm{c}`. The duty ratios are continuous signals in the range [0, 1} while the switching states are either 0 or 1.
+The figure below shows a converter equipped with a generic three-phase load. In pulse-width modulation (PWM), carrier comparison is commonly used to generate instantaneous switching state signals :math:`q_\mathrm{a}`, :math:`q_\mathrm{b}`, and :math:`q_\mathrm{c}` from duty ratios :math:`d_\mathrm{a}`, :math:`d_\mathrm{b}`, and :math:`d_\mathrm{c}`. The duty ratios are continuous signals in the range [0, 1} while the switching states are either 0 or 1.
 
 .. figure:: figs/pwm_inverter.svg
    :width: 100%
    :align: center
-   :alt: Inverter and carrier comparison
+   :alt: Voltage-source converter and carrier comparison
    :target: .
 
    Instantaneous switching states are defined by the carrier comparison. In this example, the switching states are :math:`q_\mathrm{a}=1`, :math:`q_\mathrm{b}=0`, and :math:`q_\mathrm{c}=0`.

docs/source/usage.rst

@@ -11,7 +11,7 @@ After :doc:`installation`, *motulator* can be used by creating a continuous-time
    from motulator.drive.utils import plot  # Example plotting functions
 
    # Continuous-time model for the drive system
-   converter = model.Inverter(u_dc=540)
+   converter = model.VoltageSourceConverter(u_dc=540)
    machine = model.InductionMachineInvGamma(
       R_s=3.7, R_R=2.1, L_sgm=.021, L_M=.224, n_p=2)
    mechanics = model.StiffMechanicalSystem(J=.015)

examples/flux_vector/plot_flux_vector_pmsm_2kw.py

@@ -25,7 +25,7 @@
     n_p=3, R_s=3.6, L_d=.036, L_q=.051, psi_f=.545)
 machine = model.SynchronousMachine(mdl_par)
 mechanics = model.StiffMechanicalSystem(J=.015)
-converter = model.Inverter(u_dc=540)
+converter = model.VoltageSourceConverter(u_dc=540)
 mdl = model.Drive(converter, machine, mechanics)
 
 # %%

examples/flux_vector/plot_flux_vector_pmsyrm_5kw.py

@@ -152,7 +152,7 @@ def i_s(psi_s):
 #     n_p=2, R_s=.63, L_d=18e-3, L_q=110e-3, psi_f=.47)
 # machine = model.SynchronousMachine(mdl_par)
 mechanics = model.StiffMechanicalSystem(J=.015)
-converter = model.Inverter(u_dc=540)
+converter = model.VoltageSourceConverter(u_dc=540)
 mdl = model.Drive(converter, machine, mechanics)
 
 # %%

examples/flux_vector/plot_flux_vector_syrm_7kw.py

@@ -56,7 +56,7 @@ def i_s(psi_s):
 #     n_p=2, R_s=.54, L_d=37e-3, L_q=6.2e-3, psi_f=0)
 # machine = model.SynchronousMachine(mdl_par)
 mechanics = model.StiffMechanicalSystem(J=.015)
-converter = model.Inverter(u_dc=540)
+converter = model.VoltageSourceConverter(u_dc=540)
 mdl = model.Drive(converter, machine, mechanics)
 
 # %%

examples/grid_following/plot_grid_following_control_grid_converter_10kVA.py renamed to examples/grid_following/plot_gfl_10kva.py

@@ -1,6 +1,6 @@
 """
-10-kVA grid-following converter, power control
-==============================================
+10-kVA converter
+================
     
 This example simulates a grid-following-controlled converter connected to a
 strong grid. The control system includes a phase-locked loop (PLL) to
@@ -10,20 +10,14 @@
 """
 
 # %%
-import numpy as np
-
-from motulator.common.model import (
-    CarrierComparison,
-    Inverter,
-    Simulation,
-)
-from motulator.common.utils import (
-    BaseValues,
-    NominalValues,
-)
+from motulator.common.model import VoltageSourceConverter, Simulation
+from motulator.common.utils import BaseValues, NominalValues
 from motulator.grid import model
 import motulator.grid.control.grid_following as control
-from motulator.grid.utils import FilterPars, GridPars, plot_grid, plot_voltage_vector
+from motulator.grid.utils import FilterPars, GridPars, plot_grid
+# from motulator.grid.utils import plot_voltage_vector
+# from motulator.common.model import CarrierComparison
+# import numpy as np
 
 # %%
 # Compute base values based on the nominal values.
@@ -38,32 +32,30 @@
 grid_par = GridPars(u_gN=base.u, w_gN=base.w)
 
 # Filter parameters
-filter_par = FilterPars(L_fc=0.2*base.L)
+filter_par = FilterPars(L_fc=.2*base.L)
 
 # Create AC filter with given parameters
-grid_filter = model.GridFilter(filter_par, grid_par)
+ac_filter = model.ACFilter(filter_par, grid_par)
 
 # AC grid model with constant voltage magnitude and frequency
-grid_model = model.StiffSource(w_g=grid_par.w_gN, e_g_abs=grid_par.u_gN)
+grid_model = model.ThreePhaseVoltageSource(
+    w_g=grid_par.w_gN, abs_e_g=grid_par.u_gN)
 
 # Inverter with constant DC voltage
-converter = Inverter(u_dc=650)
+converter = VoltageSourceConverter(u_dc=650)
 
 # Create system model
-mdl = model.GridConverterSystem(converter, grid_filter, grid_model)
+mdl = model.GridConverterSystem(converter, ac_filter, grid_model)
 
 # Uncomment line below to enable the PWM model
-#mdl.pwm = CarrierComparison()
+# mdl.pwm = CarrierComparison()
 
 # %%
 # Configure the control system.
 
 # Control configuration parameters
 cfg = control.GFLControlCfg(
-    grid_par=grid_par,
-    filter_par=filter_par,
-    i_max=1.5*base.i,
-)
+    grid_par=grid_par, filter_par=filter_par, max_i=1.5*base.i)
 
 # Create the control system
 ctrl = control.GFLControl(cfg)
@@ -72,13 +64,13 @@
 # Set the time-dependent reference and disturbance signals.
 
 # Set the active and reactive power references
-ctrl.ref.p_g = lambda t: (t > 0.02)*(5e3)
-ctrl.ref.q_g = lambda t: (t > 0.04)*(4e3)
+ctrl.ref.p_g = lambda t: (t > .02)*5e3
+ctrl.ref.q_g = lambda t: (t > .04)*4e3
 
-# Uncomment lines below to simulate a nonsymmetric fault (add negative sequence)
-#mdl.grid_model.par.e_g_abs = 0.75*base.u
-#mdl.grid_model.par.e_g_neg_abs = 0.25*base.u
-#mdl.grid_model.par.phi_neg = -np.pi/3
+# Uncomment lines below to simulate a unbalanced fault (add negative sequence)
+# mdl.grid_model.par.abs_e_g = 0.75*base.u
+# mdl.grid_model.par.abs_e_g_neg = 0.25*base.u
+# mdl.grid_model.par.phi_neg = -np.pi/3
 
 # %%
 # Create the simulation object and simulate it.
@@ -93,6 +85,5 @@
 # `base` you can plot the results in SI units.
 
 # Uncomment line below to plot locus of the grid voltage space vector
-#plot_voltage_vector(sim=sim, base=base)
-
-plot_grid(sim=sim, base=base, plot_pcc_voltage=True)
+# plot_voltage_vector(sim, base)
+plot_grid(sim, base, plot_pcc_voltage=True)

examples/grid_following/plot_grid_following_control_vdc_mode_grid_converter_10kVA.py renamed to examples/grid_following/plot_gfl_dc_bus_10kva.py

@@ -1,25 +1,17 @@
 """
-10-kVA grid-following converter, DC-bus voltage control
-=======================================================
+10-kVA converter, DC-bus voltage
+================================
     
 This example simulates a grid-following-controlled converter connected to a
-strong grid and regulating the DC-bus voltage at the same time. The control
-system includes a DC-bus voltage controller, a phase-locked loop (PLL) to
-synchronize with the grid, a current reference generator, and a PI-based
-current controller.
+strong grid and regulating the DC-bus voltage. The control system includes a 
+DC-bus voltage controller, a phase-locked loop (PLL) to synchronize with the 
+grid, a current reference generator, and a PI-type current controller.
 
 """
 
 # %%
-from motulator.common.model import (
-    CarrierComparison,
-    Inverter,
-    Simulation,
-)
-from motulator.common.utils import (
-    BaseValues,
-    NominalValues,
-)
+from motulator.common.model import VoltageSourceConverter, Simulation
+from motulator.common.utils import BaseValues, NominalValues
 from motulator.grid import model
 import motulator.grid.control.grid_following as control
 from motulator.grid.control import DCBusVoltageController
@@ -38,35 +30,33 @@
 grid_par = GridPars(u_gN=base.u, w_gN=base.w)
 
 # Filter parameters
-filter_par = FilterPars(L_fc=0.2*base.L)
+filter_par = FilterPars(L_fc=.2*base.L)
 
 # Create AC filter with given parameters
-grid_filter = model.GridFilter(filter_par, grid_par)
+ac_filter = model.ACFilter(filter_par, grid_par)
 
 # AC-voltage magnitude (to simulate voltage dips or short-circuits)
-e_g_abs_var = lambda t: base.u
+abs_e_g_var = lambda t: base.u
 
 # AC grid model with constant voltage magnitude and frequency
-grid_model = model.StiffSource(w_g=grid_par.w_gN, e_g_abs=e_g_abs_var)
-
-# DC-bus parameters
-C_dc = 1e-3
+grid_model = model.ThreePhaseVoltageSource(
+    w_g=grid_par.w_gN, abs_e_g=abs_e_g_var)
 
 # Inverter model with DC-bus dynamics included
-converter = Inverter(u_dc=600, C_dc=C_dc)
+converter = VoltageSourceConverter(u_dc=600, C_dc=1e-3)
 
 # Create system model
-mdl = model.GridConverterSystem(converter, grid_filter, grid_model)
+mdl = model.GridConverterSystem(converter, ac_filter, grid_model)
 
 # %%
 # Configure the control system.
 
 # Control parameters
 cfg = control.GFLControlCfg(
     grid_par=grid_par,
-    C_dc=C_dc,
+    C_dc=1e-3,
     filter_par=filter_par,
-    i_max=1.5*base.i,
+    max_i=1.5*base.i,
 )
 # Create the control system
 ctrl = control.GFLControl(cfg)
@@ -78,11 +68,11 @@
 # Set the time-dependent reference and disturbance signals.
 
 # Set the references for DC-bus voltage and reactive power
-ctrl.ref.u_dc = lambda t: 600 + (t > .02)*(50)
-ctrl.ref.q_g = lambda t: (t > .04)*(4e3)
+ctrl.ref.u_dc = lambda t: 600 + (t > .02)*50
+ctrl.ref.q_g = lambda t: (t > .04)*4e3
 
 # Set the external DC-bus current
-mdl.converter.i_ext = lambda t: (t > .06)*(10)
+mdl.converter.i_ext = lambda t: (t > .06)*10
 
 # %%
 # Create the simulation object and simulate it.

examples/grid_following/plot_grid_following_control_LCL_grid_converter_10kVA.py renamed to examples/grid_following/plot_gfl_lcl_10kva.py

@@ -1,24 +1,17 @@
 """
-10-kVA grid-following converter with LCL filter, power control
-==============================================================
+10-kVA converter, LCL filter
+============================
     
 This example simulates a grid-following-controlled converter connected to a
 strong grid through an LCL filter. The control system includes a phase-locked
 loop (PLL) to synchronize with the grid, a current reference generator, and a
-PI-based current controller.
+PI-type current controller.
 
 """
 
 # %%
-from motulator.common.model import (
-    CarrierComparison,
-    Inverter,
-    Simulation,
-)
-from motulator.common.utils import (
-    BaseValues,
-    NominalValues,
-)
+from motulator.common.model import VoltageSourceConverter, Simulation
+from motulator.common.utils import BaseValues, NominalValues
 from motulator.grid import model
 import motulator.grid.control.grid_following as control
 from motulator.grid.utils import FilterPars, GridPars, plot_grid
@@ -32,40 +25,35 @@
 # %%
 # Configure the system model.
 
-# Grid parameters
+# Grid and filter parameters
 grid_par = GridPars(u_gN=base.u, w_gN=base.w)
-
-# Filter parameters
-filter_par = FilterPars(L_fc=0.073*base.L, L_fg=0.073*base.L, C_f=0.043*base.C)
+filter_par = FilterPars(L_fc=.073*base.L, L_fg=.073*base.L, C_f=.043*base.C)
 
 # DC-bus parameters
-grid_filter = model.GridFilter(filter_par, grid_par)
+ac_filter = model.ACFilter(filter_par, grid_par)
 
 # AC-voltage magnitude (to simulate voltage dips or short-circuits)
-e_g_abs_var = lambda t: grid_par.u_gN
+abs_e_g_var = lambda t: grid_par.u_gN
 
 # AC grid model with constant voltage magnitude and frequency
-grid_model = model.StiffSource(w_g=grid_par.w_gN, e_g_abs=e_g_abs_var)
+grid_model = model.ThreePhaseVoltageSource(
+    w_g=grid_par.w_gN, abs_e_g=abs_e_g_var)
 
 # Inverter model with constant DC voltage
-converter = Inverter(u_dc=650)
+converter = VoltageSourceConverter(u_dc=650)
 
 # Create system model
-mdl = model.GridConverterSystem(converter, grid_filter, grid_model)
+mdl = model.GridConverterSystem(converter, ac_filter, grid_model)
 
 # Uncomment line below to enable the PWM model
 #mdl.pwm = CarrierComparison()
 
 # %%
 # Configure the control system.
 
-# # Control parameters
+# Control parameters
 cfg = control.GFLControlCfg(
-    grid_par=grid_par,
-    filter_par=filter_par,
-    on_u_cap=True,
-    i_max=1.5*base.i,
-)
+    grid_par=grid_par, filter_par=filter_par, max_i=1.5*base.i)
 
 # Create the control system
 ctrl = control.GFLControl(cfg)
@@ -74,8 +62,8 @@
 # Set the time-dependent reference and disturbance signals.
 
 # Set the active and reactive power references
-ctrl.ref.p_g = lambda t: (t > .02)*(5e3)
-ctrl.ref.q_g = lambda t: (t > .04)*(4e3)
+ctrl.ref.p_g = lambda t: (t > .02)*5e3
+ctrl.ref.q_g = lambda t: (t > .04)*4e3
 
 # %%
 # Create the simulation object and simulate it.