Type-safe scripting with C++ (and other weird explorations)

The why and the what(-the-f***)

Let’s start this short tale with some background. 

For reasons unclear, I’ve started working on my n-th abandonable side-project. Much detail isn’t necessary here: it’s basically a C++ library for performing simple math operations— averaging, sum, standard deviation, autocorrelation and the like. Each operation is implemented as Functor: instantiate it, call it’s operator(), and done! For a concrete example, consider the SumFunctor below (ignore the inheritance for now), which offers overloads to sum two integers or sum (concatenate) two strings

However, there’s a catch: I also want to be able to invoke these functors from some sort of scripting language. The exact language isn’t relevant (though I have my eye on Tcl); suffices to say that it will, as usual, be dynamically typed. The goal here is to suffer be able to play around with these building blocks somewhat faster, potentially being able to integrate them more easily with other languages.  Ultimately, I want to be able to write something like the following: 

Now, here come the juicy questions:

  • since data types in the script will only be known at runtime (i.e., once the script is being executed), how can an hypothetical interpreter going over myscript.xyz dispatch the calls to the correct overloads in the C++ functor? And,
  • how can I make a functor’s operator()s invocable in the most type-safe way possible? 

Ideally, I’d like to have something akin to Qt‘s Q_INVOKABLE tag, but I most certainly don’t want to write a Meta-Object Compiler from scratch, and I’d like to avoid devilish macros as much as possible. So, strap in for some weird templated exploration.

Boundary conditions

To better understand where this is headed, let’s define some constraints and solidify some assumptions.

I want an hypothetical interpreter to transparently deal with available functors, regardless of their implementation specifics. Furthermore, I might want to load/unload functions dynamically, e.g. via some sort of import statement. This can be solved quite classically, by having all functors inherit from the same abstract base class (like the AbstractFunctor in the above snippet), which will provide a cohesive minimal API (OOP haters intensify).

How such interpreter accesses the functors isn’t relevant here: they might be stored in a map, vector, list, etc., from which the right one is picked and called. However, there needs to be a cohesive way to pass arguments to the functor, without knowing either their types nor quantities beforehand.  
To approach this, we can take some cues from Python: when writing custom C extensions, data is passed back and forth using PyObjects, which effectively work as containers for runtime data. This is not distant from Qt’s QVariant, — also a generic runtime data container — that appears quite often in the interface between Qt/C++ and QML/JS.
To avoid rolling our own polymorphic container at first, let’s start off by using C++17’s freshly added std::variant instead.

“But”, I hear you say, “std::variant is not runtime polymorphic; all possible types need to be known at compilation time!”. That’s right. std::variant indeed defines a compile-time sum-type. However, it allows for some limited runtime introspection and provides value semantics, all which come in handy. This will temporarily restrict the data types our functors can deal with, but that’s a constraint we shall lift later. For now, let’s define a simple variant_t,

that packages a value coming from the interpreter. Let’s start off by accepting ints, doubles and strings argument types, which shall be bundled in a vector.

Our AbstractFunctor is thus bound to have a method such as void AbstractFunctor::invoke(const std::vector<variant_t>&), through which it can be, well, invoked. Notice that the functors’ return values are being ignored (our invoke method is void, after all). That’s yet another temporary simplification. We’ll get to that. Eventually.

Verifying a variant vector’s veridical validity

At this point, a first step would be asking the question: given a list of arguments (std::vector<variant_t>) and a certain function signature (operator(A, B, C, ...)), how can we verify that the argument types match said signature? 

This turned out to be an interesting point, since it lies somewhere between compile-time constraints and run-time requirements. And, while I could likely concoct some solution exploiting typeid/type_info, I figured it’d make sense to explore a path using templates. That way, I could offload as much type-checking as possible to the compilation phase. 
So, for the SumFunctor::operator(int,int) above, I’d want to write something as matches<int, int>(arglist), which verifies if arglist contains two ints. We’re thus searching for something of the form

where our typename Args... statement makes use of C++11’s template parameter packs. So, strap in for a brief jump into recursive template meta-programming territory!

Tiny trip through templated territory

Template meta-programming is basically functional programming with a cumbersome syntax. In its recursive form, it follows the principles of mathematical induction quite closely: define a base case (a proof for an n = 0) and an inductive step (proof that n = k also holds for n = k + 1), and voilà, the compiler will do the expansions for you. 

For example: in a language better suited for such task, like Haskell, we could compactly define the recursive sum of a list of integers:

Calling something like sum [1, 2, 3] would essentially expand to 1 + sum [2, 3] -> 1 + 2 + sum [3] -> 1 + 2 + 3, unsurprisingly yielding 6. To write something similar in C++, we end up being a bit more verbose:

While the syntax is unfortunately less readable, the base/inductive case pattern is very recognizable. Calling sum(1, 2, 3) spits out 6 as expected. The added constexprs aren’t mandatory, but allow for compile-time computation when possible, which is very neat.
By expanding this C++ example a bit, the sum function can be made to work with basically any combination of types for which operator+ is defined:

Sure, this introduces C++14’s decltype(auto), adds an overkill noexcept for funsies, and throws some std::move and std::forward into the mix, but hey, you get to recursively add apples and oranges together at compile time*. Tasty**!

* Provided operator+(apple, orange) is defined. YMMV.
** Could’ve been even tastier if written with a fold expression, but let’s leave that aside. 


Ok, back to our main point.

Returning to the route of recursive random ramblings

In light of this recently acquired knowledge (and after banging my head against a wall for some time), a fleshed out bool matches<...>(...) function looks like the following:

First off, there is some syntactical sugar to address here: get_if allows me to check at runtime if an underlying std::variant contains a given type. Next, operator sizeof... returns the length of a template parameter pack — we can thus know how many Types were provided as template arguments. Last, but not least, if constexpr is a C++17 godsend, that enables proper conditional branching at compile-time

In the snippet, matches acts as an entry point for our recursive checkArgumentTypeAt, which, as the name indicates, checks if the element at the N-th position of the arglist has the expected type. The base case and inductive step mechanics are the same as the defined in the previous section. Note, however, that different from our recursive sum example, the First and Second types must be explicitly peeled off from the template parameter pack. This is because the signature of checkArgumentTypeAt is the same in both specializations,  and the compiler needs to be provided with enough information for the SFINAE rules to kick in correctly. If we instead had written

since typename... Types can be empty, a call such as checkArgumentTypeAt<1, int>(arglist) would’ve been ambiguous* — as GCC happily confirms:

* Some other type deduction rules are also lurking in the shadows here. For more, here’s a mandatory Scott Meyers talk.

Deterministically dispatching to designated definitions: dope!

Once the matches function verifies the argument list, I want to be able to dispatch it to a corresponding method. At this point, I figured it’d make sense to define the concept of a Dispatcher, i.e., an object responsible for calling a particular operator() overload on our target functor.

The Dispatcher can thus be templated according to the target functor and the signature of the operator() that will be called:

To please the OOP gods (and allow runtime polymorphism), Dispatcher inherits from an AbstractDispatcher with a minimal API. The matches and checkArgumentTypeAt from before are also present, now as const members functions.

Note that Dispatcher has a member f of type Functor. That allows storing the target functor however it is best suited: reference, pointer or RAII member (which provides support for lambdas!). Right below it is an operator(), which will basically invoke the Functor‘s operator() by correctly dereferencing f. In essence, Dispatcher::operator() is just an indirection to leverage C++’s static dispatch rules, and select the correct target Functor::operator() at compile time.

The missing piece of the puzzle is the elusive dispatch method. There are two problems here: 1) how can the N-th element in the arglist be converted to the correct type and, 2) how can Dispatcher::operator() be invoked with the right number of arguments?

Problem 1 is fairly straightforward. If the matches<...>(...) function returned true, it is known that the N-th element in the list has the same type as the N-th type in the Types... template pack. To extract it, one can leverage std::tuple in a very amusing way: 

This TypeAt expression wraps Types... in a  std::tuple, and uses std::tuple_element to fetch the type of the N-th entry — all at compile time. Now, within the Dispatcher, retrieving and converting the N-th argument in arglist is just a matter of writing std::get<TypeAt<N>>(arglist.at(N)). Neat!

A solution for problem 2 builds on top on problem 1, and our complete dispatch method takes form. Unfortunately, it ends up being way less elegant then desired:

Once again, we combine sizeof... and if constexpr to only evaluate the correct conditional branch at compilation time. Unfortunately, the total amount of supported arguments needs to be added by hand, which is rather disappointing. AFAIK, there’s no way to circumvent this (and the fact that even Qt has done something similar further convinces me of that.) If any bright soul sees a better alternative here, send a pigeon

Remaining remarks

Almost. I promise.

When developing a new functor, I’d like to define which methods will be “invocable” via the dispatcher-shenanigans conjured up in the last sections. The aforementioned mythical (but not forgotten) interpreter should see an invoke method that does all the black magic internally. So, let’s circle back to the first code snippet, and define how our AbstractFunctor could look like: 

Neat little detail: different from classes/structs, template parameter pack expansion rules for functions allow packs to appear anywhere in the list (so long as the function signature provides enough cues as to what-goes-where). This can be exploited to write a little makeInvocable helper method that doesn’t require manually specifying the Functor type.
I can then add it to the constructor of our old friend, SumFunctor:

Let’s finally put everything together:

This yields the very unsurprising — but exciting — output:

If you want to play around with this, check/modify/compile the full source-code at Wandbox (or check the GitHub Gist). Have at it!

Conclusions*

While this was a fairly long write-up, it ended up being a fairly shallow exploration in both C++ template madness and in the scripting problem outlined in the introduction. There are still quite a few open problems: how to deal with return values in the functors? How to circumvent the limitations of the introduced variant_t? Can we add support to default arguments? The list goes on. 

While a few of those I’ve got worked out already, others are widely unresolved. In any case, I’ll save all these ramblings for a post to come yet in this decade.

Edit: I absolutely cannot NOT mention ChaiScript, which is everything this post wishes to be when it grows up: a fully developed, type-safe scripting language for C++.  Absolutely fantastic code by Jason Turner & Co. If all this nonsense peaked your interest, take a look at their GitHub!

’til next time!

*Alas, additional alliterations aren’t available anymore. 

The VFD Series – Part 1: The ups and downs of SPWM

I’ve given up on trying to post periodically here. Let’s see if this brave act of reverse psychology has some effect on my productivity.

Introduction

Recently, I’ve started working on firmware for a three-phase frequency inverter. While this is absolutely no technological revolution on the grand scheme of things, it’s certainly new ground for me – and deserves some proper notetaking. So, before we dive into anything, let’s do a quick overview. What’s a frequency inverter? Very broadly, a frequency inverter, or Variable Frequency Drive (VFD), is a device that takes a periodic input signal with a certain frequency and generates a periodic output signal with a different, controllable frequency. 

Practically, we’ll be almost always dealing with sinusoidal (or sinusoidal-ish) input and output signals. The reason for that being that mains power is sinusoidal, and most loads we’re interested in (i.e., induction motors) require some form of rotating magnetic field that can be canonically generated by a superposition of sine waves.  Also, on a typical industrial context, mains power is three-phase AC (figure below, left). On this setup, you have three sinusoidal waves, 120º apart. There are a lot of inherent advantages to this arrangement, including a reduction in wire count and gauge, easier hookup to loads and so on. Three-phase AC is a whole world in and of itself, and since I’m not qualified to give you a tour of it, I’ll leave its further comprehension as an exercise to the reader (ElectroBOOM to the rescue).

Left: Three-phase AC power. Right: Simplified three-phase inverter diagram. (Source: switchcraft.org)

On the above figure, to the right, we see a simplified representation of a three-phase VFD: first, the input three-phase AC signal is rectified into a constant(-ish) DC potential; then, using some form of switching element (e.g., MOSFETs, IGBTs) an output three-phase signal with the desired frequency is generated by combining the output of the U, V and W legs of the circuit. This, in itself, is already the first challenge to be faced: T1, T2, ... T6 are most efficient when operating in the saturation region – i.e., as hard switches, either fully on, or fully off. So, how can we produce a sinusoidal output signal via elements with a binary behavior? 

Mathemagics: the sideways ZOH

First and foremost, by looking at the above diagram, it is very clear that no two switches on the same leg should be simultaneously active at any time – that would configure a short circuit, raise some magic smoke and probably pop a breaker. With that out of the way, we assume that each leg of the VFD can only be in one of two states: on (i.e., upper switch closed, bottom one open), or off (upper switched open, bottom one closed).  This means each phase’s output can be either tied to the DC bus’ voltage, or to the ground/reference potencial. 

So, we are interested in (re)constructing a signal using nothing but switches. Some quick googlin’ points us to a very commonly used technique for signal reconstruction, called Zero-Order Hold (ZOH). This technique allows us to create a continuous-time signal from a discrete-time signal (e.g., a series of numeric values), by holding constant each of its values for an interval T, as shown in the figure below. In a certain sense, this is akin to a Riemann sum, with the area under each sample acting as an approximation to the area under the original signal at that interval. By setting an appropriate T according to the Nyquist-Shannon sampling theorem, the output b_{zoh}(t) signal will contain the harmonic content of the original r(t). Of course, higher harmonics will be present due to the hard transitions between levels, but these should be filtered off. 

In this definition, the signal b_{zoh}(t) has arbitrary, non-discrete values (i.e., the sampled values of r(kT), k \geq 0). However, as mentioned before, the VFD we’re dealing with only allows each phase to be in two discrete states: fully on or fully off. How to circumvent this? While we can’t control the VFD’s amplitude, we can control how long we keep the signal on or off – that is, each pulse can have its width modulated (PWM). Thinking along the lines of the aforementioned Riemann sum, we can try “tipping” each sample of b_{zoh}(t) on its side. So, assume that on an instant t_0, our signal of interest r(t_0) = f_0 (figure below, left). Our reconstructed signal b_{zoh}(t) will hold the value f_0 during the interval T = t_1 - t_0, which results on an area A_0 = (t_1 - t_0)f_0 = Tf_0

Left: b_{zoh}(t) approximates r(t) in the interval [t_0, t_1]. Center: We compute t_s so that A_0 = A_s, assuming f_0 \approx f_sRight: By plotting the relationship between f_s and t_s, \forall r(t), 0 < r(t) < a, we get the sawtooth carrier wave c(t).

Since our VFD signal b_{pwm}(t) can only be 0 or the maximum amplitude a (figure above, center), we wish to find the instant t_s where the area A_s = (t_s - t_0)a approximately matches A_0. This can be written straightforwardly as

    \begin{align*}  A_s &= A_0 \\ a(t_s - t_0) &= f_0(t_1 - t_0) \\ t_s &=\frac{f_0}{a}(t_1 - t_0) + t_0 \end{align*}

By plugging the above expression for t_s into A_s = (t_s - t_0)a, we get A_s = Tf_s. For an adequate interval T, we can safely assume that f_0 \approx f_s, and thus, A_s \approx A_0. Hooray. Now, by also assuming that 0 < r(t) < a, \forall t, we can write the unsurprising relationship between t_s and f_s, in each interval T, as 

    \begin{align*} f_s = a\frac{(t_s - t_0)}{(t_1 - t_0)} && \forall t,  t_0 \leq t < t_1 \end{align*}

This relationship, copied-and-pasted over multiple T intervals, yields the sawtooth-shaped carrier waveform c(t), as drawn in the figure above, right. It now comes as fairly straightforward that b_{pwm}(t) = a when r(t) > c(t) and b_{pwm}(t) = 0 otherwise. With a bit of wit, we can now write b_{pwm}(t) generically as 

(1)   \begin{equation*} b_{pwm}(t) = a (\text{sign} [ r(t) - c(t) ]) \end{equation*}

Neat and compact. This form is also know as natural PMW (or naturally sampled PWM). And, in case you’re wondering: there’s this obscure thing called uniform PWM, but I won’t be touching that. Ever. 

Chop that sinewave… Julienne or Chiffonade?

By plugging the generic sinusoidal wave below

(2)   \begin{equation*} r(t) = R_0 + R_1 cos(2\pi f_1 + \theta_1) \end{equation*}

in our equation 1 above, we get this neat thing called Sinusoidal Pulse Width Modulation (SPWM). Following the intuition developed in the last section, SPWM generates a waveform with the harmonic content of the desired sine wave, as shown in the figure below. I mean, that PWM signal looks like a jumbled mess, but it has the harmonics we’re looking for, believe me. Low-pass-filtering the signal will reveal the modulated sine wave.

The very attentive may have noticed that, in the above picture, the carrier wave c(t) (in green), is not a sawtooth wave as previously defined, but a triangular wave.  In actuality, if we follow the intuition outlined in the previous section, we’ll notice that any triangle-shaped c(t) produces the same A_0 = A_s area equivalence. In practical applications, however, only three different carrier waveforms are used, which yield three basic PWM schemes:

  • Sawtooth: trailing-edge modulation, or left-aligned PWM (figure below, left
  • Triangular: double-edge modulation, or center-aligned PWM  (figure below, center)
  • Inverse sawtooth: leading-edge modulation, or right-aligned PWM (figure below, right)

PWM generation strategies. All waveforms are bipolar and have a 0.2ms period. Left: Left-aligned PWM (sawtooth carrier). Center: Center-aligned PWM (triangular carrier). Right: Right-aligned PWM (inverse sawtooth carrier).

When I faced this carrier-wave-palette for the first time, my initial question was, “ok, cool. So which one do I pick? Is there any difference?”. As it turns out, there’s always some debate over which one to use, but fairly little quantitative approaches to the issue. From an implementation perspective, a triangular carrier wave is a bit more of a hassle. On an MCU, a sawtooth wave can be tipically spawned by a counter that simply counts up and overflows. A triangular wave, on the other hand, requires said timer to go up, then down again. This means that, for a set carrier wave frequency, you have to either provide such counter with a clock signal twice as fast, or sacrifice one bit in the counter’s resolution. But beyond that, is there any modulation strategy that reduces undesired harmonics in the output signal?

This question is relevant for a couple reasons. First, VFD output isn’t usually filtered before it gets to the load – in fact, the load itself acts as a filter. In the case of an induction motor as load, the coils act as RL-filters, smoothing out the input current. Still, lots of undesired harmonic content in the signal might reduce efficiency, produce heat, and cause vibration and audible noise due to magnetostriction

… but if you judge a fish by its ability to modulate a wave …

Cool. So, at this point, the goal is very clear: evaluate the VFD output from different PWM schemes. But evaluate according to what? Let’s pick two neat ones: harmonic content and total harmonic distortion.

Harmonic Content

We are clearly interested in evaluating which harmonics appear on each PWM scheme. My first thought was to look at the C_n coefficients of the compact trigonometric Fourier series, as defined in equation 3 below. 

(3)   \begin{align*}  f(t) = C_0 + \sum_{n=1}^{\infty} C_n \text{cos}(n\omega_0t + \theta_n) \end{align*}

Unfortunately, things are a bit more hairy than that. If we take a look at the PWM equation 1 above, we see the obvious fact the function is periodic in both r(t) and c(t). To apply the Fourier definition above, we’d need to come up with a closed form for a single period of \text{sign} [ r(t) - c(t) ]), which is clearly algebraical masochism (or suicide). In order to analytically analyze the Fourier expansion for such a function, we need to introduce the Double Fourier Series Method: for any function f(x, y), periodic in both x and y, with a period of 2\pi in both axes* we can write:

(4)   \begin{align*} f(x, y) &= C_{00} + \sum_{n=1}^{+\infty}C_{0n} \text{cos}(ny+\theta_{0n})+ \sum_{m=1}^{+\infty}C_{m0}\text{cos}(mx + \theta_{m0}) \notag \\ &+ \sum_{m=1}^{+\infty}\sum_{n=\pm1}^{\pm\infty}C_{mn}\text{cos}(mx + ny + \theta_{mn}) \end{align*}

f_{\text{yo}}(\text{yo})

Well, first off, for all the math inclined folks out there: sorry, but I’m not touching this with a ten foot pole – I’ll be going down the numerical route. However, if you do wish to check out its analytical expansion for various PWM strategies, check this document. Regardless, looking at this expression does provide us with some neat insight about what we should expect to see: the first term on the right-hand side of equation 4 represents a DC component, while the second and third terms represent the harmonics of both y and x, respectively – these are identical to the one-dimensional Fourier Series in equation 3 above. More interesting, however, is the fourth term in that expression. It expresses the sideband frequencies that are generated as a result of the modulation process. We see that n assumes positive and negative integer values, thus yielding upper- and lower-sideband (USB and LSB) spectra around each main harmonic of the carrier frequency. 

*If we want 1 to fit this criterion, we could write it as b_{pwm}(t) = f(x, y) = \text{sign}[r(x) - c(y)], y = 2\pi f_1 + \theta_1, x = 2\pi f_c + \theta_c, where f_c is the carrier’s frequency and f_1 is the modulated sine’s frequency.

Total Harmonic Distortion

While the Fourier series gives us detailed information on the signal’s harmonics, the Total Harmonic Distortion (THD) factor gives us a handy ratio between the harmonics we care about, and the ones we do not. As mentioned, we are interested in producing a pure sine wave, and as such, we care about only a single fundamental harmonic – everything else may be properly labeled as distortion. Our THD can thus be expressed as 

(5)   \begin{equation*} \text{THD}_F = \frac{\sqrt{\sum_{n=2}^\infty v_n^2}}{v_1} \end{equation*}

where v_n is the amplitude of the n-th harmonic and the in “\text{THD}_F” stands for fundamental. Pure sine waves have a \text{THD}_F = 0, square waves have a \text{THD}_F = 48.3\% (percent is a common representation for THD), and higher factors indicate higher distortion – in our case, meaning that less power is going were it should. 

Three-sum

Naturally, we are interested in performing the aforementioned evaluations on the VFD’s output. To that end, our last missing ingredient is a means of properly combining the signals of the U, V and W legs into a single output signal.  As discussed in the introduction, we are interested in three-phase AC inputs and outputs. Such signals can be easily visualized as a phasor projected onto three base vectors, 120º degrees apart** – each projection representing an individual phase. Well, since a picture is worth a thousand words, let the shamelessly stolen GIF below talk for itself:

Vector and time representation of a three-phase system. Amazeballs GIF taken from switchcraft.orgcheck their article out!

In order to properly compute the magnitude of the rotating equivalent vector above (in black), we need to to represent it in an orthonormal basis (as we see above \{U, V, W\} only span \mathcal{R}^2, and hence do not fulfill the criteria for orthonormality). Let’s thus pick the \{\alpha, \beta\} vectors below as our new basis:

A periodic signal v(t) may be represented both in the three-phase \{U, V, W\} base, or in the orthonormal \{\alpha, \beta\} base.

The choice of \{\alpha, \beta\} is arbitrary (as long as they are orthonormal), but done to simplify upcoming calculations (since \alpha represents the real part of the signal, and \beta, its imaginary part).  Now, with a bit of trigonometry, we can represent a periodic signal v(t) shown above in our new base:

(6)   \begin{equation*} \begin{equation*} v(t) = \begin{bmatrix} v_{\alpha} \\ v_{\beta} \end{bmatrix} = %{ \Large \frac{2}{3} } { \small \begin{bmatrix} 1 & \text{cos}(120<span>^{\circ}</span>) & \text{cos}(-120<span>^{\circ}</span>) \\ 0 & \text{sin}(120<span>^{\circ}</span>) & \text{sin}(-120<span>^{\circ}</span>) \end{bmatrix} } = { \Large \frac{2}{3} } { \small \begin{bmatrix} 1 & -1/2 & -1/2 \\ 0 & \sqrt{3}/2 & \sqrt{3}/2 \end{bmatrix} } \begin{bmatrix} v_U \\ v_V \\ v_W \end{bmatrix}  \end{equation*}

This relationship is know as the Clarke transform, and is frequently used in the analysis of three-phase AC circuits. Let’s now assume that the U, V and W phases are each producing individual SPWM signals as per the equation 1, all 120º degrees apart from each other (figure below, right) – notice that the phases’ outputs were normalized to the [0, 1] range. We can now combine them via our definition 6 above, to produce the actual output signal of our VFD (real part \alpha drawn in the figure below, right):

Left: Individual phases of the VFD combined into the output signal via the Clarke Transformation. Each phase’s PWM signal is normalized, so that an off phase is 0, and a on phase is 1. Right: The real-valued part of the VFD’s output signal (\alpha axis).

It is worth noting how each phase is capable of producing only unipolar signals – i.e., signals ranging from 0V to the V_{DC} voltage of the VFD’s DC bus. Their combined output, however, yields true bipolar output. While this might be slightly counter-intuitive at first, imagine all three phases producing a steady PWM signal with a 50% duty cycle. This “balance point” produces zero output (since V_\alpha = 1*0.5 - 1/2*0.5 - 1/2*0.5 = 0, as per equation 6). From this state, by changing the value of one or more phases, we can produce arbitrary output vectors with magnitudes ranging from -2V_{DC}/3 to 2V_{DC}/3. For a bit more discussion on that topic, check this out.

**In case you’re wondering, this 120º offset between the phases is ultimately related to the physical placement of the stator windings inside three-phase motors and generators.

Last, but not least

We are finally ready to answer the question we posed several paragraphs ago: which PWM strategy is best? Left-aligned, right-aligned or center-aligned? 

First off, as we’ve discussed before, our evaluation tools only care about the frequency spectra of our signals. So, taking into account the time reversibility of the Fourier series, and noting that left- and right-aligned SPWM waveforms are mirror images of each other, we immediately know that they’re equivalent (for our intents and purposes). So, we’ll only compare trailing-edge and double-edge modulations. 

To generate the SPWM signals, I’ve implemented the SPWM definion (i.e., combining equations 1 and 2) in Matlab (Code!). Computing the Fourier single-sided amplitude spectrum (Code!), as well as computing \text{THD}_F (Code!) was also done in Matlab. [Any feedback on the correctness of these code snippets would be greatly appreciated] The generated plots are shown below. U, V, and W phases are modulating a 50Hz sinewave with an amplitude modulation index of 0.8, on a 5kHz carrier (identical as shown in the figure above, left), so the expected output amplitude waveform is 0.8*0.5 = 0.4:

Top and Bottom show Trailing- and Double-Edge Modulation schemes, respectively. Left: Time plots of the SPWM signals. Output is a 50Hz sine wave on a 5kHz carrier. Right: Single-sided power spectra for each signal, with added \text{THD}_F factor.

And, voilà. We immediately see that in both modulation schemes, the desired fundamental is there, almost perfectly in the desired amplitude (0.39 \approx 0.4) – yey! all that SPWM hassle does work after all. Now, interestingly, we have a rather curious result with the FFT spectra and the THD factors. At first, we see that Trailing-Edge modulation has a somewhat smaller distortion factor (70.13%), but its spectrum seems arguably more messy. Moreover, we can see that Double-Edge modulation seems to have much less harmonic content (in fact, it has exactly half of the sideband harmonics, as verifiable if we expand equation 4 analytically for each scenario, as seen here). On top of that, the fundamental switching harmonics (around 5kHz) have smaller amplitudes in the Double-Edge scheme. So, what gives?

It seems that the higher-order harmonics of the Double-Edge modulation tend to weight-in more heavily in the quadratic sum of the THD factor, yielding a higher overall distortion (88.94%). In practice, however, the RL-filter-characteristic of VFD loads will have a cutoff frequency around the hundreds of Hz, so realistically, harmonics above the switching frequency will have almost no effect***. So, we can confidently argue that, in practical applications, Double-Edge modulation – a.k.a. center-aligned PWM – does produce less harmonics, which seems to echo the faint opinions on the topic that float around the interwebs.

Now, of course: as the image above shows, the difference isn’t all that extreme, and as we’ve discussed above, there’s a bit more implementation effort associated with center-aligned PWM. So, once again – and slightly disappointingly – YMMV.

***Very broad and oversimplified generalization. Don’t sue me if you fry your setup testing something I’ve said. 

Disclaimer (& closing thoughts)

Well, let’s just make it very clear: this whole thing is a somewhat brief write-up of my latest incursions in what’s an unknown territory for me. I’ve been figuring stuff out on the fly, so if you spot anything wrong, please, let me know

Edit: In a recent conversation, a friend of mine and a literal master of all-things-electric, Julio, added some very relevant information to this mix. He confirmed that, in practical applications, the choice of carrier waveform is not of great impact. However, when implementing a VFD (e.g. on a MCU) with any kind feedback control loop, the peaks and valleys in the triangular carrier of the center-aligned PWM can be used to synchronize ADC samplings of the generated waveform (figure below). This ensures that the sampling doesn’t happen during switching, reducing measurement noise (and, in case of current measurements, providing that pulse’s average value). This article goes into more depth into that, and it’s worth taking a look. He also mentioned that sawtooth carriers (in trailing- and leading-edge modulations) essentially synchronize the switching in all phases. This increases output noise due do parasitics in the circuit/load (stuff that we did not capture in this write-up), and can be a real issue in high-power applications. Thanks for the insight, Julio! 

Using peaks and valleys of the triangular carrier to synchronize the ADC sampling of the PWM signal, as to avoid switching noise (since measurement happens exactly in the “middle” of an On or Off state). Image source: e2e.ti.com

’til next time. 

Minimalist low-pass filter library

So, the other day I needed to compute some low-pass filters on the fly on an Arduino Mega. By “on the fly” I mean that the filters’ parameters would eventually be recomputed mid-operation, so setting some equation with static const parameters would not cut it. Using a static filter, is, however, the most common application scenario. If that’s your case – and I insist – tweak the sh*t out of your filter with a decent tool then just add it to your code. If, on the other hand, you need to update your filter dynamically (or if you’re just plain lazy to compute poles and zeros), then this is for you.

I ended up putting together a minimalist library for that, libFilter (github!). Works with the Arduino IDE and as a regular C++ library (just uncommenting one #define does the trick).

Using two filter instances on a signal from a load cell getting punched.

Using two filter instances on a signal from a load cell getting punched.

For now it only implements low-pass filters based on  normalized butterworth polynomials, but who knows what necessity might add to it next. Let’s take a look at some ADC filtering:

’til next time!

P.S.: I just can’t avoid letting this page eventually fall into temporary ostracism. Geez.