Update documentation

docs/_downloads/008b6d00098622dbcbc376d01ebf6d6e/plot_obs_vhz_ctrl_syrm_7kw.py

@@ -3,8 +3,8 @@
 ======================
 
 This example simulates observer-based V/Hz control of a saturated 6.7-kW
-synchronous reluctance motor drive. The saturation is not taken into account
-in the control method (only in the system model).
+synchronous reluctance motor drive. The saturation is not taken into account in 
+the control method (only in the system model).
 
 """
 # %%
@@ -83,7 +83,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)
 
 # %%

docs/_downloads/08e838bf878827480241fb7f12fd06f3/plot_obs_vhz_ctrl_im_2kw.py

@@ -31,7 +31,7 @@
 mdl_par = InductionMachinePars.from_inv_gamma_model_pars(mdl_ig_par)
 machine = model.InductionMachine(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)
 
 # %%

docs/_downloads/0caf7e993f270b64263d3eed41903c63/plot_signal_inj_pmsm_2kw.py

@@ -29,7 +29,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)
 
 # %%

docs/_downloads/0e90ff21c9746465ac1c76f3266533b9/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)
 
 # %%

docs/_downloads/107fbc64ef11ee5f549b21d03ef04624/plot_vhz_ctrl_6step_im_2kw.py

@@ -36,7 +36,7 @@
 # Mechanics with quadratic load torque coefficient
 k = .2*nom.tau/(base.w/base.n_p)**2
 mechanics = model.StiffMechanicalSystem(J=.015, B_L=lambda w_M: k*np.abs(w_M))
-converter = model.Inverter(u_dc=540)
+converter = model.VoltageSourceConverter(u_dc=540)
 mdl = model.Drive(converter, machine, mechanics)
 mdl.pwm = model.CarrierComparison()  # Enable the PWM model
 
@@ -46,7 +46,7 @@
 par = InductionMachineInvGammaPars(R_s=0*3.7, R_R=0*2.1, L_sgm=.021, L_M=.224)
 ctrl = control.VHzControl(
     control.VHzControlCfg(
-        par, nom_psi_s=base.psi, k_u=0, k_w=0, six_step=True))
+        par, nom_psi_s=base.psi, k_u=0, k_w=0, overmodulation="six_step"))
 
 # %%
 # Set the speed reference and the external load torque.

docs/_downloads/1a902c1ab2092d406c661fb4146e7d95/plot_flux_vector_pmsm_2kw.ipynb

@@ -51,7 +51,7 @@
       },
       "outputs": [],
       "source": [
-        "mdl_par = SynchronousMachinePars(\n    n_p=3, R_s=3.6, L_d=.036, L_q=.051, psi_f=.545)\nmachine = model.SynchronousMachine(mdl_par)\nmechanics = model.StiffMechanicalSystem(J=.015)\nconverter = model.Inverter(u_dc=540)\nmdl = model.Drive(converter, machine, mechanics)"
+        "mdl_par = SynchronousMachinePars(\n    n_p=3, R_s=3.6, L_d=.036, L_q=.051, psi_f=.545)\nmachine = model.SynchronousMachine(mdl_par)\nmechanics = model.StiffMechanicalSystem(J=.015)\nconverter = model.VoltageSourceConverter(u_dc=540)\nmdl = model.Drive(converter, machine, mechanics)"
       ]
     },
     {

docs/_downloads/1f2e230a5b2e1a8d76335febf2031498/plot_gfl_dc_bus_10kva.py

@@ -0,0 +1,89 @@
+"""
+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. 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 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
+from motulator.grid.utils import FilterPars, GridPars, plot_grid
+
+# %%
+# Compute base values based on the nominal values.
+
+nom = NominalValues(U=400, I=14.5, f=50, P=10e3)
+base = BaseValues.from_nominal(nom)
+
+# %%
+# Configure the system model.
+
+# Grid parameters
+grid_par = GridPars(u_gN=base.u, w_gN=base.w)
+
+# Filter parameters
+filter_par = FilterPars(L_fc=.2*base.L)
+
+# Create AC filter with given parameters
+ac_filter = model.ACFilter(filter_par, grid_par)
+
+# AC-voltage magnitude (to simulate voltage dips or short-circuits)
+abs_e_g_var = lambda t: base.u
+
+# AC grid model with constant voltage magnitude and frequency
+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 = VoltageSourceConverter(u_dc=600, C_dc=1e-3)
+
+# Create system model
+mdl = model.GridConverterSystem(converter, ac_filter, grid_model)
+
+# %%
+# Configure the control system.
+
+# Control parameters
+cfg = control.GFLControlCfg(
+    grid_par=grid_par,
+    C_dc=1e-3,
+    filter_par=filter_par,
+    max_i=1.5*base.i,
+)
+# Create the control system
+ctrl = control.GFLControl(cfg)
+
+# Add the DC-bus voltage controller to the control system
+ctrl.dc_bus_volt_ctrl = DCBusVoltageController(p_max=base.p)
+
+# %%
+# 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
+
+# Set the external DC-bus current
+mdl.converter.i_ext = lambda t: (t > .06)*10
+
+# %%
+# Create the simulation object and simulate it.
+
+sim = Simulation(mdl, ctrl)
+sim.simulate(t_stop=.1)
+
+# %%
+# Plot the results.
+
+# By default results are plotted in per-unit values. By omitting the argument
+# `base` you can plot the results in SI units.
+
+plot_grid(sim=sim, base=base, plot_pcc_voltage=True)

docs/_downloads/21731b590e0867945f65a12bf576eef4/plot_gfl_10kva.py

@@ -0,0 +1,89 @@
+"""
+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
+synchronize with the grid, a current reference generator, and a PI-based
+current controller.
+
+"""
+
+# %%
+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
+# 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.
+
+nom = NominalValues(U=400, I=14.5, f=50, P=10e3)
+base = BaseValues.from_nominal(nom)
+
+# %%
+# Configure the system model.
+
+# Grid parameters
+grid_par = GridPars(u_gN=base.u, w_gN=base.w)
+
+# Filter parameters
+filter_par = FilterPars(L_fc=.2*base.L)
+
+# Create AC filter with given parameters
+ac_filter = model.ACFilter(filter_par, grid_par)
+
+# AC grid model with constant voltage magnitude and frequency
+grid_model = model.ThreePhaseVoltageSource(
+    w_g=grid_par.w_gN, abs_e_g=grid_par.u_gN)
+
+# Inverter with constant DC voltage
+converter = VoltageSourceConverter(u_dc=650)
+
+# Create system 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 configuration parameters
+cfg = control.GFLControlCfg(
+    grid_par=grid_par, filter_par=filter_par, max_i=1.5*base.i)
+
+# Create the control system
+ctrl = control.GFLControl(cfg)
+
+# %%
+# 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
+
+# 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.
+
+sim = Simulation(mdl, ctrl)
+sim.simulate(t_stop=.1)
+
+# %%
+# Plot the results.
+
+# By default results are plotted in per-unit values. By omitting the argument
+# `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, base)
+plot_grid(sim, base, plot_pcc_voltage=True)

docs/_downloads/25d1238a73e8b59c79b698bd00e5ad03/plot_obs_vhz_ctrl_pmsyrm_thor.ipynb

@@ -87,7 +87,7 @@
       },
       "outputs": [],
       "source": [
-        "# Create the machine model\nmdl_par = SynchronousMachinePars(\n    n_p=2, R_s=.2, L_d=4e-3, L_q=17e-3, psi_f=.134)\nmachine = model.SynchronousMachine(mdl_par, i_s=i_s, psi_s0=psi_s0)\n# Magnetically linear PM-SyRM model\n# mdl_par = SynchronousMachinePars(\n#     n_p=2, R_s=.2, L_d=4e-3, L_q=17e-3, psi_f=.134)\n# machine = model.SynchronousMachine(mdl_par)\n# Quadratic load torque profile (corresponding to pumps and fans)\nk = nom.tau/(base.w/base.n_p)**2\nmechanics = model.StiffMechanicalSystem(J=.0042, B_L=lambda w_M: k*np.abs(w_M))\nconverter = model.Inverter(u_dc=310)\nmdl = model.Drive(converter, machine, mechanics)"
+        "# Create the machine model\nmdl_par = SynchronousMachinePars(\n    n_p=2, R_s=.2, L_d=4e-3, L_q=17e-3, psi_f=.134)\nmachine = model.SynchronousMachine(mdl_par, i_s=i_s, psi_s0=psi_s0)\n# Magnetically linear PM-SyRM model\n# mdl_par = SynchronousMachinePars(\n#     n_p=2, R_s=.2, L_d=4e-3, L_q=17e-3, psi_f=.134)\n# machine = model.SynchronousMachine(mdl_par)\n# Quadratic load torque profile (corresponding to pumps and fans)\nk = nom.tau/(base.w/base.n_p)**2\nmechanics = model.StiffMechanicalSystem(J=.0042, B_L=lambda w_M: k*np.abs(w_M))\nconverter = model.VoltageSourceConverter(u_dc=310)\nmdl = model.Drive(converter, machine, mechanics)"
       ]
     },
     {

docs/_downloads/2a8735a75a47cb0897acb78102cddd78/plot_obs_vhz_ctrl_syrm_7kw.ipynb

@@ -4,7 +4,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "\n# 6.7-kW SyRM, saturated\n\nThis example simulates observer-based V/Hz control of a saturated 6.7-kW\nsynchronous reluctance motor drive. The saturation is not taken into account\nin the control method (only in the system model).\n"
+        "\n# 6.7-kW SyRM, saturated\n\nThis example simulates observer-based V/Hz control of a saturated 6.7-kW\nsynchronous reluctance motor drive. The saturation is not taken into account in \nthe control method (only in the system model).\n"
       ]
     },
     {
@@ -69,7 +69,7 @@
       },
       "outputs": [],
       "source": [
-        "mdl_par = SynchronousMachinePars(n_p=2, R_s=.54)\nmachine = model.SynchronousMachine(mdl_par, i_s=i_s, psi_s0=0)\n# Magnetically linear SyRM model for comparison\n# mdl_par = SynchronousMachinePars(\n#     n_p=2, R_s=.54, L_d=37e-3, L_q=6.2e-3, psi_f=0)\n# machine = model.SynchronousMachine(mdl_par)\nmechanics = model.StiffMechanicalSystem(J=.015)\nconverter = model.Inverter(u_dc=540)\nmdl = model.Drive(converter, machine, mechanics)"
+        "mdl_par = SynchronousMachinePars(n_p=2, R_s=.54)\nmachine = model.SynchronousMachine(mdl_par, i_s=i_s, psi_s0=0)\n# Magnetically linear SyRM model for comparison\n# mdl_par = SynchronousMachinePars(\n#     n_p=2, R_s=.54, L_d=37e-3, L_q=6.2e-3, psi_f=0)\n# machine = model.SynchronousMachine(mdl_par)\nmechanics = model.StiffMechanicalSystem(J=.015)\nconverter = model.VoltageSourceConverter(u_dc=540)\nmdl = model.Drive(converter, machine, mechanics)"
       ]
     },
     {

docs/_downloads/321b0e8f049c7151d7ee6120ccff1890/plot_obs_vhz_ctrl_pmsm_2kw_two_mass.py

@@ -34,7 +34,7 @@
 machine = model.SynchronousMachine(mdl_par)
 mdl_mec_par = TwoMassMechanicalSystemPars(J_M=.005, J_L=.005, K_S=700, C_S=.01)
 mechanics = model.TwoMassMechanicalSystem(mdl_mec_par)
-converter = model.Inverter(u_dc=540)
+converter = model.VoltageSourceConverter(u_dc=540)
 mdl = model.Drive(converter, machine, mechanics)
 
 # %%

docs/_downloads/32b0d0b5a5953f003c957fd40639cf0f/plot_obs_vhz_ctrl_pmsyrm_thor.py

@@ -98,7 +98,7 @@ def i_s(psi_s):
 # Quadratic load torque profile (corresponding to pumps and fans)
 k = nom.tau/(base.w/base.n_p)**2
 mechanics = model.StiffMechanicalSystem(J=.0042, B_L=lambda w_M: k*np.abs(w_M))
-converter = model.Inverter(u_dc=310)
+converter = model.VoltageSourceConverter(u_dc=310)
 mdl = model.Drive(converter, machine, mechanics)
 
 # %%

docs/_downloads/33c3e58b193eb317d00dc39d7c8aea3c/plot_vector_ctrl_pmsm_2kw.py

@@ -28,7 +28,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)
 
 # %%

docs/_downloads/3a0268e3c6ff58e6137b770236599e4d/plot_vhz_ctrl_im_2kw_lc.py

@@ -33,8 +33,8 @@
 # Quadratic load torque profile (corresponding to pumps and fans)
 k = 1.1*nom.tau/(base.w/base.n_p)**2
 mechanics = model.StiffMechanicalSystem(J=.015, B_L=lambda w_M: k*np.abs(w_M))
-converter = model.Inverter(u_dc=540)
-lc_filter = model.LCFilter(L=8e-3, C=9.9e-6, R=.1)
+converter = model.VoltageSourceConverter(u_dc=540)
+lc_filter = model.LCFilter(L_f=8e-3, C_f=9.9e-6, R_f=.1)
 mdl = model.DriveWithLCFilter(converter, machine, mechanics, lc_filter)
 mdl.pwm = model.CarrierComparison()  # Enable the PWM model
 

docs/_downloads/3b85a2a28df68a21ae1317e13158dde6/plot_vector_ctrl_syrm_7kw.py

@@ -28,7 +28,7 @@
     n_p=2, R_s=.54, L_d=41.5e-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)
 
 # %%

docs/_downloads/40a1743246f42299b8096717d9571612/plot_obs_vhz_ctrl_pmsm_2kw.ipynb

@@ -51,7 +51,7 @@
       },
       "outputs": [],
       "source": [
-        "mdl_par = SynchronousMachinePars(\n    n_p=3, R_s=3.6, L_d=.036, L_q=.051, psi_f=.545)\nmachine = model.SynchronousMachine(mdl_par)\nmechanics = model.StiffMechanicalSystem(J=.015)\nconverter = model.Inverter(u_dc=540)\nmdl = model.Drive(converter, machine, mechanics)"
+        "mdl_par = SynchronousMachinePars(\n    n_p=3, R_s=3.6, L_d=.036, L_q=.051, psi_f=.545)\nmachine = model.SynchronousMachine(mdl_par)\nmechanics = model.StiffMechanicalSystem(J=.015)\nconverter = model.VoltageSourceConverter(u_dc=540)\nmdl = model.Drive(converter, machine, mechanics)"
       ]
     },
     {

docs/_downloads/413262ad79b6f6e486efc1754ad5e05d/plot_signal_inj_pmsm_2kw.ipynb

@@ -51,7 +51,7 @@
       },
       "outputs": [],
       "source": [
-        "mdl_par = SynchronousMachinePars(\n    n_p=3, R_s=3.6, L_d=.036, L_q=.051, psi_f=.545)\nmachine = model.SynchronousMachine(mdl_par)\nmechanics = model.StiffMechanicalSystem(J=.015)\nconverter = model.Inverter(u_dc=540)\nmdl = model.Drive(converter, machine, mechanics)"
+        "mdl_par = SynchronousMachinePars(\n    n_p=3, R_s=3.6, L_d=.036, L_q=.051, psi_f=.545)\nmachine = model.SynchronousMachine(mdl_par)\nmechanics = model.StiffMechanicalSystem(J=.015)\nconverter = model.VoltageSourceConverter(u_dc=540)\nmdl = model.Drive(converter, machine, mechanics)"
       ]
     },
     {

docs/_downloads/4b900cbf3baa72eac7ddc3463d10efb3/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)
 
 # %%

docs/_downloads/4cbdc04e08950a0a4c3fdc370e5c6f89/plot_flux_vector_pmsyrm_5kw.ipynb

@@ -105,7 +105,7 @@
       },
       "outputs": [],
       "source": [
-        "mdl_par = SynchronousMachinePars(n_p=2, R_s=.63)\nmachine = model.SynchronousMachine(mdl_par, i_s=i_s, psi_s0=psi_s0)\n# Magnetically linear PM-SyRM model for comparison\n# mdl_par = SynchronousMachinePars(\n#     n_p=2, R_s=.63, L_d=18e-3, L_q=110e-3, psi_f=.47)\n# machine = model.SynchronousMachine(mdl_par)\nmechanics = model.StiffMechanicalSystem(J=.015)\nconverter = model.Inverter(u_dc=540)\nmdl = model.Drive(converter, machine, mechanics)"
+        "mdl_par = SynchronousMachinePars(n_p=2, R_s=.63)\nmachine = model.SynchronousMachine(mdl_par, i_s=i_s, psi_s0=psi_s0)\n# Magnetically linear PM-SyRM model for comparison\n# mdl_par = SynchronousMachinePars(\n#     n_p=2, R_s=.63, L_d=18e-3, L_q=110e-3, psi_f=.47)\n# machine = model.SynchronousMachine(mdl_par)\nmechanics = model.StiffMechanicalSystem(J=.015)\nconverter = model.VoltageSourceConverter(u_dc=540)\nmdl = model.Drive(converter, machine, mechanics)"
       ]
     },
     {

docs/_downloads/575fba068cfee95663babe7799456a42/plot_obs_vhz_ctrl_im_2kw.ipynb

@@ -51,7 +51,7 @@
       },
       "outputs": [],
       "source": [
-        "# Configure the induction machine using its inverse-\u0393 parameters\nmdl_ig_par = InductionMachineInvGammaPars(\n    n_p=2, R_s=3.7, R_R=2.1, L_sgm=.021, L_M=.224)\nmdl_par = InductionMachinePars.from_inv_gamma_model_pars(mdl_ig_par)\nmachine = model.InductionMachine(mdl_par)\nmechanics = model.StiffMechanicalSystem(J=.015)\nconverter = model.Inverter(u_dc=540)\nmdl = model.Drive(converter, machine, mechanics)"
+        "# Configure the induction machine using its inverse-\u0393 parameters\nmdl_ig_par = InductionMachineInvGammaPars(\n    n_p=2, R_s=3.7, R_R=2.1, L_sgm=.021, L_M=.224)\nmdl_par = InductionMachinePars.from_inv_gamma_model_pars(mdl_ig_par)\nmachine = model.InductionMachine(mdl_par)\nmechanics = model.StiffMechanicalSystem(J=.015)\nconverter = model.VoltageSourceConverter(u_dc=540)\nmdl = model.Drive(converter, machine, mechanics)"
       ]
     },
     {

docs/_downloads/5c5462abbacc47f76538a5bef10a227e/plot_vector_ctrl_im_2kw.py

@@ -42,7 +42,7 @@ def L_s(psi, L_su=.34, beta=.84, S=7):
 # mdl_par = InductionMachinePars.from_inv_gamma_model_pars(par)
 machine = model.InductionMachine(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)
 # mdl.pwm = model.CarrierComparison()  # Try to enable the PWM model
 # mdl.delay = model.Delay(2)  # Try longer computational delay