erip.m version 12Jul24
(A tool for the design of optimal fir and iir digital filters)

Author: Paul Mennen
Email: paul@mennen.org

Overview

erip allows you to design optimal (equal ripple) linear phase FIR filters using the famous Parks-McClellan design algorithm which is based on the Remez exchange algorithm. Parks-McClellan is usually implemented using the firpm.m routine which is part of the Signal Processing Toolbox. However erip does not use firpm to avoid requiring any toolboxes. Instead erip uses the parks.m routine which is included in the pltSig toolbox. parks.m uses a different implementation of the Parks-McClellan algorithm that is somewhat simplified but produces similar results. It also runs faster than firpm; in fact about twice as fast for filter orders in the 35 to 70 range, with an even greater speed advantage for longer filters.

erip also allows you to design optimal IIR filters as well as non-linear phase FIR filters, but only if your copy of erip is registered.

If you attempt to design an IIR filter (or a non-linear phase FIR filter), then if you haven't yet registered erip you will see this dialog box requesting that you register. Although registering is free, I still apologize for this extra step. I'm asking you to register so I can judge the level of interest in erip to see if it is worthwhile to continue to add features and improvements to this application.

After entering the registration number you have received, the erip windows will close and you will see this message box. Assuming you have entered the number correctly, your copy of erip has been registered. After restarting erip you will be able to use it to design IIR filters and you will never see either of these messages again.

check mark indicates IIR capabilities	Windows OS	non-Windows OS (i.e. Unix based)
erip is NOT registered
erip is registered The DSP Toolbox is installed
erip is registered The DSP Toolbox is not installed

The checkmarks in this table show you when you can use erip to design IIR filters (as well as non-linear phase FIR filters).

When the DSP Toolbox is installed the iirlpnorm.m design algorithm is used to design IIR filters and firlpnorm.m is used to design non-linear phase FIR filters. Both of those routines are included with The DSP System Toolbox. However if you do not have that toolbox installed, erip will use an alternative design algorithm which has been compiled into a Windows application called iir.exe. Since executables are not allowed in Matlab toolboxes, iir.exe will be automatically created the first time it is needed from the included plt\sig\iir\iir.b64 base64 encoded file.

The checkbox in the lower right corner of the table is missing because iir.exe can't run in a Linux environment.

The Mathworks also has a tool (called filterDesigner) that serves the same purpose as erip. The most important differences between these tools is described in the table below.

filterDesigner	erip
This is part of the DSP System Toolbox, so you must have that toolbox installed to run filterDesigner Also, if you want to design an FIR filter, the signal processing toolbox is also required (because it uses the firpm.m (Parks-McClellan) function which is part of that toolbox.	This is part of the pltSig toolbox and you don't need any other toolboxes to run it. (Note the limitation mentioned above when using Unix-based operating systems.)
filterDesigner is primarily for the design of filters that fit into one of the 4 standard types (lowpass, highpass, bandpass, and bandstop). It is also capable of designing filters that don't fit into one of those categories (i.e. arbitrary magnitude response), but to do so you must specify the desired response by typing in the values of 4 vectors (Frequency, Edges, Magnitude, & Weight) but that process is anything but intuitive. Once you enter those vectors, filterDesigner doesn't produce any graphical representation of the shape that you specified making it difficult to know if you entered these vectors correctly.	erip allows you to enter a magnitude response graphically which is usually much easier. You may also enter these values numerically, but the response is always shown graphically as well so there will never be confusion about the design specification.
For the four standard filter types as well as when using an arbitrary magnitude response, you must specify the response in linear units. However, the frequency response of the filter that results from your specifications can't be displayed in linear units (it's always in dB). This makes it difficult to see how well the design spec was met, and for arbitrary magnitude specifications, it offers little feedback about whether the 4 vectors were typed in properly.	erip allows you to display the magnitude response of the design result in linear or logarithmic units (or both simultaneously). As an example of how important this is, look at the design result of the differentiator example with the linear result (trace 2) turned off and observe how difficult it is to see how faithfully the design result follows the specification as the filter order is varied.
A pole/zero editor is included which can be a powerful tool to help you gain an understanding of how the pole/zero locations affect the frequency response. However, the pole/zero plot occupies a small fraction of the figure window making the unit circle so small it is somewhat frustrating to use. Also, you can't precisely drag a zero onto the unit circle since mouse control doesn't offer enough precision for such a task. (Being exactly on the unit circle is often important because it allows the polynomial to be symmetric.)	erip displays the pole/zero editor in a separate resizable figure window, providing a much more useable editor. Additionally, erip displays only the top half of the unit circle, allowing this half circle to fill the figure window. This again makes the radius larger, making the editor more comfortable to use. And finally, erip provides an adjustable "snap-to" region around the unit circle making it easy to move a zero to the unit circle. erip provides another snap-to region around the x-axis allowing you to drag a root exactly onto the x-axis, turning a complex conjugate pair of roots into just a single root (another impossible task with filterDesigner).
A window is provided allowing you to view the filter coefficients, but it is so small that even with simple filters you need to use the scroll bar to see all the coefficients. Also, it is awkward that you can't view the coefficient window at the same time as the magnitude response or the pole/zero locations. So for example, after changing a filter design parameter, you can see how this affects the coefficients, the magnitude response, or the pole/zero positions, but you can't see all three (or even two) of these effects at the same time.	erip has separate figure windows for showing the filter coefficients, the magnitude/phase response, and the pole/zero locations. So after a design change, you can see the effects in all three windows simultaneously. Also, the coefficient window shows the coefficients more compactly, and the window is large enough to show all the coefficients without scrolling for even quite complex filters. Another advantage of erip's coefficient window is that it allows you to constrain the coefficients to fixed point precision with any desired number of bits.

You can learn a lot about gui programing using the plt toolbox by studying the erip.m source code, especially for learning how to integrate multiple figure windows and dealing with complex user interfaces and mouse interactions. However at 516 lines of code (not counting comment lines) erip is the longest and most complex of all the toolbox applications so it's certainly not one to start with if you are relatively new to gui programming. Instead you should begin with the programs and explanations in the GUI building with plt section and then move on to some of the other simpler applications.

Graphical interface

To start the erip graphical interface, simply type erip at the Matlab command prompt. This opens three windows similar to these:

Click on this thumbnail to see the full-resolution screen capture. The largest figure (upper left) could be thought of as the main erip figure since you will use it to define the characteristics of the filter design, and it also displays the frequency response of the resulting design. The figure on the upper right displays the locations of the poles and zeros of the resulting design and also allows you to move these root locations to improve the design or to gain an understanding of how the frequency response depends on the root locations. The wide (but not very tall) figure at the bottom is used to display the numerator and denominator polynomials of the resulting design and also allows you to modify these coefficients to see how this affects the frequency response and root locations.

The size of these figure windows depends on your computer's screen resolution. The coefficient window (bottom) will 1800 pixels wide if you have a display with at least that many horizontal pixels. For displays with less than 1800 horizontal pixels, the coefficient window will fill the entire width of the screen, and the two figures above it will be sized to match. The screen capture to the left was done on a system with 1400 pixels of available horizontal space. If your screen has fewer than around 1200 pixels horizontally, the figure sizes may be too small to be usable.

Coefficient figure

This figure displays the coefficients of the numerator and denominator polynomials. The top line of numbers is the numerator polynomial and the bottom line is the denominator. The first number starting at the left is the constant term (z⁰) followed by z^-1, z^-2, etc. In this example, both polynomials are displayed in a single line, but with more complex filters, they may extend to multiple lines - up to 2 lines for the denominator polynomial and up to 3 lines for the numerator. (And up to 5 lines may be displayed for the numerator for FIR filters.) If you change the width of the coefficient figure, each polynomial may occupy fewer or more lines of text. You may need to expand the width to the full width of the screen so that all the coefficients of a high-order filter are displayed cleanly. The color used to display each coefficient alternates between white and orange every 5 numbers to make it easier to identify specific coefficients. For example, we can quickly tell that the -152.44 near the end of the denominator polynomial is the 10th coefficient (z^-9) because it is the last number in yellow (the end of the 2nd group of five).

In this example, the top line of coefficients begins with these red characters: b(z)⁰⁶ = 2^-8 * where b(z) is the traditional letter used to represent the numerator polynomial of a transfer function. The 06 superscript indicates that this is a 6th-order polynomial (i.e. has 7 coefficients), and the 2^-8 * indicates that you have to multiply all the numbers to the right by 2^-8 to get the actual polynomial coefficients. This multiplier is chosen in an attempt to allow the filter coefficients to be displayed without using exponents which in turn allows the coefficients to be shown with higher precision in the small space allocated on the screen for these coefficients. Note that the exponent will not always be -8 as in this example but will be chosen to produce the most readable coefficient representations. Clicking on the b(z)⁰⁶ = 2^-8 * will change it to b(z)⁰⁶ = 10^-3 *. Again the -3 exponent will vary since it is chosen based on the particular coefficients being displayed. The numbers shown for the numerator polynomial are now all different than before but once you apply the multiplier shown you will find that the resulting coefficients haven't changed. Finally, clicking on these characters a third time will change it to b(z)⁰⁶ = indicating that there is no multiplier at all (i.e. the numbers shown are the actual filter coefficients). Usually, the decimal multiplier will be the most convenient, although if you are planning a hardware implementation, then the binary multiplier will often be the best.

In this example, the second line of coefficients begins with these red characters: a(z)¹¹ = 2^-8 * where a(z) is the traditional letter used to represent the denominator polynomial of a transfer function. As before the 11 superscript indicates that this is an 11th-order polynomial (i.e. 12 coefficients). As with the numerator polynomial, clicking on this text toggles between the 3 modes (binary multiplied, decimal multiplier, and no multiplier. Note that the constant term (z⁰) of the denominator polynomial is always one since that is necessary for the IIR filter implementation.

You may quantize the numerator polynomial by typing a number into the edit box labeled "Quantize b". For example, if you want to quantize the coefficients to the nearest hundredth, type in a value of 0.01 into the edit box. To round the coefficients to the nearest integer, type a value of 1 into the edit box. In this example you would then see the numbers 2 4 7 7 6 3 1, however, note that the polynomial coefficients themselves are not integers because of the 2^-8 multiplier. If the number you want to quantize by is already in the edit box, you don't have to enter it again because clicking on the "Quantize b" label will have the same effect. You can also change the value of any individual coefficient. So in this example, after quantizing by 1, if you click on the second coefficient (the "4") it will either increment or decrement by 1. (Clicking slightly to the right of the 4 increments and clicking slightly to the left of the 4 decrements.) Note that the amount that the coefficient increments or decrements is always the same as the value in the quantize edit box. You could also change this value independent of the quantize value. Simply right click on the "4", backspace to remove the 4 and then type in "3.9" (for example). As soon as you change a coefficient, either by typing in a new value, incrementing, decrementing, or quantizing - the pole/zero plot will update to show the new root locations and the main figure will update to show the new magnitude and phase response. You won't often design filters by fiddling with individual coefficients, but still, it can be educational to observe the effects of such changes. Any time you want to return to the coeffect values you had before any quantizing or coefficient editing, simply hit the "Run" button in the main figure. Of course, the same interactions are allowed with the denominator polynomial and the "Quantize a" edit box. The effects of entering a quantize value are temporary. For example, if you move one of the roots on the pole/zero plot, the filter coefficients will be updated as a result and again be stored with full 64-bit precision. So if you want the coefficients to continue to be quantized you would have to click on the appropriate "Quantize a/b" label after such changes.

If you check the "symmetric" checkbox, this will affect what happens when editing the coefficients of the numerator polynomial. For example, if you change the value of the first coefficient, the last coefficient will also change to the same value. Or if you change the value of the last coefficient, the value of the first coefficient will also change to the same value. A similar pairing will happen with the second coefficient and the next to last coefficient, etc. While the symmetric checkbox is checked, after any value is modified, the first half of the numerator polynomial is flipped and then copied to the second half of the polynomial ensuring that the whole polynomial is symmetric, not just the coefficient being edited. A point of confusion is that you might expect that checking the symmetric checkbox insures the design algorithm will produce a symmetric numerator polynomial. However that is not the case. As described below, the design algorithm insures a symmetric numerator polynomial only when the Pz parameter (number of poles) is set to -1. Also even with a symmetric design, if you drag a zero that is on the unit circle to any position that is not on the unit circle or the x axis, the numerator polynomial will become unsymmetrical. It may help to understand an interesting mathematical property of the roots of a symmetric polynomial, which is that if there is a complex root that is not on the unit circle, then there will also be another root at the same angle with its reciprocal magnitude. For example, if there is a root at 30 degrees with a magnitude of 0.8 there will also be a root at 30 degrees with a magnitude of 1.25. Thus you could say such roots occur in pairs - or quadruples if you are counting the complex conjugates of these roots (below the x axis). It is easy to verify this mathematical property by examining the pole/zero plot while editing the coefficients or conversely by viewing the coefficients while moving the zero locations on the pole/zero plot.

The final control to discuss in filter coefficient window is the DC gain edit box. After the run button in the main window is pressed, after a root is moved in the pole/zero plot, and after a coefficient is modified in the coefficient window, the DC gain edit box is updated to show the transfer function evaluated at z = 1 (i.e. the sum of the numerator coefficients divided by the sum of the denominator coefficients. This value will usually be close to 1.0 for a low pass filter but will be very small for a high pass filter. You can also edit the value in the DC gain edit box. Say for example the DC gain edit box contains the value 1.002. Suppose then we triple this value by typing the number 3.006 into the edit box. After doing so, you will see that all the coefficients of the numerator polynomial have tripled.

Pole/Zero plot

The zeros (o's) on this plot always show the roots of the b(z) polynomial depicted in the coefficient window and the poles (x's) show the roots of the a(z) polynomial. Each root shown on the x-axis, represents just a single root, whereas each complex root (i.e. not on the x-axis) represents a pair of roots. The other root of the pair is the complex conjugate. These complex roots must appear in pairs since the filter coefficients are limited to the real numbers. The complex conjugates are not shown on the plot to make the plot bigger, less cluttered, and easier to read. For example, suppose we click on the pole shown in this figure that is the one that is closest to the unit circle. The x and y edit boxes below the plot show that the pole is located at .262145 + .914289i (in rectangular coordinates) and right next to the x edit box you can see that in polar coordinates this pole has a magnitude of .951 at an angle of 74 degrees. The complex conjugate root is at .262145 - .914289i but this is not shown on the plot.

In the example shown here there are 11 poles. As you can see, 3 of these poles are real. (The fat green horizontal line is the x axis). The remaining 8 poles are complex and only four of those (above the real axis) are shown on the pole/zero plot. The other 4 poles are the complex conjugates which are below the x axis and are not shown on the pole/zero plot. This is done to save space on the plot, but of course you must assume that those other four poles are there. In this example there are six zeros (all complex) and only the three that are above the x axis are depicted.

But actually for a filter to be causal, there must be the same number of poles and zeros, so with this example, five extra zeros are needed at the origin. These extra zeros are not shown on the pole-zero plot since this would be difficult to depict since they are all on top of each other. But you should assume they are part of the z-plane representation. Whether these extra zeros are there or not will not change the magnitude response of the filter, but they do affect the phase response. The phase response shown in the main figure is calculated assuming these extra zeros are there. Suppose instead of 11 poles and 6 zeros, it was the other way around ... i.e. 11 zeroes and 6 poles. Then there would be 5 extra poles all at the origin to insure that the filter was causal (again not depicted on the pole-zero chart).

Note that when you clicked on the pole, a diamond shape cursor appeared around the pole. That cursor shape alerts you to the fact that you can now drag this pole around using the mouse. While you are dragging the pole, the complex conjugate pole is also being moved and the a(z) polynomial display in the coefficient window is being updated and the magnitude and phase frequency response is being updated in the main window. If you move the pole onto the x-axis, the order of the a(z) polynomial decreases by one since the pole no longer represents a complex-conjugate pair. If you later move the pole off the x-axis, the polynomial degree increases by one. Of course, moving a zero works the same way except that the b(z) polynomial is updated as you drag the zero.

When you click on the "new zero" or "new pole" button, a new root will be added at z = 0 (the origin of the unit circle) and then you can drag it to the desired location. To delete a root, simply click on the root and then left click on the "delete p/z" button. Then if you right click on the "delete p/z" button, it will undo that operation (i.e. restore the deleted root at its previous location). Continuing to right click on that button will restore more roots if you have deleted several. You probably won't often design filters by positioning the roots on the pole/zero plot in this manner, but you may still find it useful to gain an understanding of how the root positions affect the frequency response.

As mentioned before, dragging a root onto the x-axis has a special significance. However, a mouse operation like this doesn't have the precision to ensure that the imaginary component is exactly zero. To solve this problem there is a tolerance band around the x axis (shown with green shading) where the root will snap to the real axis whenever you drag the root inside the tolerance band. The default width of the tolerance band is usually acceptable, but you can adjust this width using the slider in the lower-left corner of the figure. (Moving the slider to zero disables the snap-to feature.) Also, we have mentioned before the significance of moving a zero onto the unit circle. (It results in a symmetric numerator polynomial, as well as linear phase if it is an FIR filter.) Again a snap-to region is necessary to give us the ability to move the zero exactly on the unit circle, and the green region around the unit circle shows this snap-to region. The slider mentioned before also controls the width of this snap-to region.

Main figure

The main figure allows you to specify the characteristics of the filter you want to design as well as to view the frequency response of the result. The white dashed line in the lower plot defines the desired filter magnitude response (linear) and you can modify that line graphically or numerically in this figure. The units for this specification are on the left edge of the plot. The thick green & grey line at the top edge of the lower plot shows the location of the transition bands if any (grey = don't care, green = do care). The upper plot (thin green trace) depicts the weighting curve and is also part of the filter specification. It defines how much emphasis to put on minimizing the error in each region. As with the white dashed line, you can modify the weighting curve graphically or numerically. (Both methods are described later.)

After clicking the Run button, the yellow trace of the lower plot will show the magnitude response (linear) of the resulting design, and ideally will closely follow the white dashed line in the do-care regions. The blue trace shows the magnitude response in logarithmic units (dB) which are shown on the right edge of the graph.

The gray box near the lower right corner of the figure is where you set the parameters of the filter design. To change any of these numbers, right click and then type in a new value. Pz, the last parameter on the right specifies the number of poles. In this example, 11 poles have been selected which means the denominator polynomial will have 12 coefficients. Note that the pole/zero plot only shows 7 poles. That's because 4 of the poles are complex, and the reflections of these poles below the x-axis (the complex conjugates) are not shown. In addition to changing Pz by right clicking and typing in a new value, you can also change its value using the increment/decrement method. Click near the right side of the current value (11) or in the space just to the right of the number and its value will change to 12 (i.e. increment). To change the value to 10 (i.e. decrement), click on the left side of the number. If you enter Pz = 0, then the denominator polynomial is simply 1 resulting in an FIR filter (finite impulse response). No special symmetries are forced on the numerator polynomial which implies that the filter will in general have a non-linear phase. If you want the resulting filter to have linear phase, enter Pz = -1. Of course, there are still no poles, but using -1 is just a way of specifying linear phase without needing an additional parameter. Normally in this case, even symmetry will be used, meaning the first and last numerator polynomial coefficient will be the same, and also the second and next to last coefficient will be identical, etc. (Specifying odd symmetry will be discussed later.) Note that on Unix-based operating systems, if you don't have the DSP System Toolbox installed, Pz will be automatically set to -1 because, without that toolbox, we must depend on the included parks.m filter design tool which designs linear phase FIR filters.

Often we do want to design a linear phase FIR filter, but sometimes allowing non-linear phase (i.e allowing a non-symmetric numerator polynomial) can be an advantage. As an example of this, select the Shape22 filter design (the last selection in the Saved Filters popup discussed below). Note that Pz is set to 0 indicating that this is an FIR filter but that non-symmetric polynomials are allowed. Now click on the left side of the "0" which will change it to a -1, now specifying that the polynomial must be symmetric. Notice how the filter shape (yellow trace) no longer follows the desired filter shape as closely. We could create a symmetric FIR filter that does as well as the original non-symmetric one, but we would have to approximately double the filter order.

Nz specifies the number of zeros. In this example, 6 zeros were selected, so the numerator polynomial has 7 coefficients. You can increment or decrement it in the same way described above. A new filter design will be calculated each time you modify Nz or Pz (as if you had pressed the Run button). This makes it easier to develop a feel for how the filter response is affected by the filter order.

The next parameter, Radius, applies only to IIR filters and specifies how close to the unit circle the poles can be placed. With the default value of 1, the poles are unconstrained and can be placed anywhere inside the unit circle. If for example, you change the Radius value to 0.97, then all the poles will be positioned inside a circle of radius 0.97 centered at the origin. This can be useful to ensure stability, especially when dealing with finite word length effects.

The remaining two parameters (Fs and Grid) are not really filter parameters, but they do affect the way the results are displayed. In this example, Grid is set to 400 (the default value) which means that the frequency response is calculated at 400 evenly spaced points between zero and the Nyquist frequency. (This is almost always sufficient). Fs specifies the sampling frequency. The x-axis limits of the frequency response plot will always be set to 0 and Fs/2. If you set Fs to 1 (as in this example), then the x-axis shows angular frequency.

To analyze the passband performance, you may have to zoom in many times before you can see the passband ripple (especially for high order filters). In that situation it can be difficult to return to a scaling allowing a view of the entire frequency response. To make that easy, you can click on the yellow defLim tag at the bottom of the menu box. This will reset the axis limits to the default values.

Saved Filters popup
As you are working on your filter designs, you may save any current filter specification by clicking on the "Save" button which adds the current filter spec to a file called erip.txt in the plt\ini\ folder. This file is initialized after installation to contain the specification of 10 different filters, so initially after clicking on the saved filter name Default just below the x-axis label (Frequency) a popup similar to this one will appear showing the names of all the saved filters stored in the file. These 10 filter specs were chosen to show you a variety of filter types. It's not expected that any of these 10 filters will be useful as is for one of your designs since the specified shapes are somewhat arbitrary, so at best they can be starting points for your own designs. But when starting a new design, you will find it easier if you start by selecting one of these 10 filter shapes which looks most similar to the filter you wish to create. If you delete the erip.txt file (perhaps accidentally or intentionally) then this popup will contain only the single item Default whose filter shape and parameters are defined in the erip.m source code.

When you select one of the filter specifications from this popup, the current filter shape and parameter set will be overwritten with the values associated with the name of the item in the popup list. For this reason, if there was anything you wanted to save from the current filter spec. you should always hit the save button before opening this popup. If you open this popup inadvertently, you can close it again without taking any action by clicking on the black "X" in the lower right corner of the popup menu.

In general, filter specification isn't affected by the name you choose to represent that specification, but there are two exceptions to that. If the name chosen begins with the three letters Dif or Hil (case sensitive) then the FIR design algorithm (parks.m) will be used to design the filter, and what's more, that design algorithm will be directed to produce an anti-symmetric filter. This means that the first and the last filter coefficients are negatives of each other, and the same for the second and next to last coefficient ... and so on. The same design algorithm is used for differentiators and Hilbert transformers. The only difference is that for the Hilbert transformer, the weighting function specified by the top graph is used directly whereas for the differentiator that weighting function is first divided by the angular frequency before being sent to the filter design algorithm. This causes the lower frequencies to be weighted much more strongly than the higher frequencies, which produces better-performing differentiators.

The data saved for each filter in this drop down list include:

The filter shape (i.e. the white dashed trace of the main figure's lower plot)
The weighting curve (i.e. the green trace of the main figure's upper plot)
The filter name (displayed below the x-axis label)
The values in the shaded parameter box below the x-axis (includes the filter name, Fs, Grid, Radius, Nz, Pz)
The current settings of the Quantize b and Quantize a edit boxes in the coefficient figure
The currently displayed coefficients in the coefficient figure. Usually these values are the same as what you will see after clicking on the Run button. However if the coefficients have been modified after the run (using the quantization controls or by editing the coefficients manually) then the modified coefficients are saved. You can see an example of this with the default erip.txt file when selecting the second filter in the list (LowPass). The coefficients were modified after the run button was pressed first by quantizing the result and then by directly editing the quantized coefficient values to reduce the errors caused by the quantization. You can examine the differences between the design algorithm results and the edited results by alternately clicking on the Run and Reload buttons.

Button Group
This group of buttons appears in the upper left corner of the figure window.

The Run button causes the design algorithm to execute (parks.m or iirlpnorm.m as appropriate) which will then update the magnitude and phase response as well as the coefficient display and the pole/zero plot (if those to figures are enabled). You don't have to press the Run button after changing the filter order (Nz or Pz) since changes to those two parameters will also immediately initiate the execution of the design algorithm.
When you are satisfied that the current design is worth saving so that you can recall it later, press the Save button. You will be prompted for a name to identify this filter specification. This is the name that will be added to the popup list described above. It's best to enter a unique name that you will later recognize, but if you leave the name field blank, erip will make up a name for you. For example, if the current filter name is "HighPass", then if you don't specify a new name, erip will use "HighPass-A". If the current name is already "HighPass-A", then it will use "HighPass-B", and then "HighPass-C", etc. Although it may lead to later confusion, you are allowed to use the same name for two different filter specifications in which case this name will occur twice in the saved filters popup. Sometimes, instead of creating a new name, you will want to overwrite the current filter spec. To do this, instead of left clicking on the Save button, use a right click. Doing this accidentally has the potential to overwrite a filter spec that you wanted to keep. Also when you select a new filter from the Saved Filters popup described above, and equivalent of a right click on the Save button is executed which will overwrite filter specifications in the file with any changes you have made. Usually this is what you intend, but sometimes not. To protect against these eventualities, whenever erip rewrites the erip.txt file (which contains all the filter specs and their names), it also back up the old erip.txt file using the name eripBAK.txt. This is only a single-level backup, so it will only help you if you recognize the problem right away. For this reason, you should create your own backups of the erip.txt file with different file names, perhaps numbered or including the date so you have a history of the work you have been doing.
The Saved Filter popup may get a bit unwieldy with more than a few dozen entries, so you probably will want to delete the filter specifications that you are no longer working on. This can be done by selecting the unneeded filter, and then clicking on the Remove button.
Sometimes when editing a filter specification you may find you want to revert to the previously saved filter shape. One way to do this is to simply exit erip and restart it. A faster way however is to click on the Reload button.
The main window is the only window you need to have open. The other two windows (Pole/Zero plot and the coefficient window) are optional. To remove the Pole/Zero plot window, click on the pzPlot button and to remove the coefficient window, click on the CoefFig button. Click on either button again to re-enable the respective figure window.
Left clicking on the fvtool button opens Matlab's filter visualization tool using the coefficients currently shown in the coefficient window. You may find fvtool useful because it graphs some information that is not shown in the previously shown erip figures, primarily:
1. impulse response
2. step response
3. unwrapped phase
4. group delay
5. phase delay
If you right click on the fvtool button the two windows shown at the right will appear displaying these same 5 items. (These are just thumbnails. Click on them to see the full image.) You may prefer the right click action, because these figures use the same cursoring, zooming, and panning methods that you have become familiar with from the other erip figures.) fvtool is part of the signal processing toolbox, so if that toolbox is not installed, left clicking on the fvtool button behave the same as the right click (i.e. the two figures shown at the right will appear).

Editing the desired filter shape
Starting from the default filter shape, suppose we want to make the notch in the middle of the passband deeper as well as add a flat region in that notch. The first step is to enable only the specification trace (the thick dashed white line). You could do this by clicking on "mag" in the TraceID box (turning the font to italic indicating the trace has been disabled) followed by clicking on "mag dB" to also disable that trace. A slightly faster way is to right click on "spec" in the TraceID box. That tells the plotting routine to enable the spec trace while disabling all others. When erip sees that the spec trace is the only one enabled in the lower plot, it assumes you want to edit the spec curve so it enters a special editing mode. First, let's click on the breakpoint in the middle of the notch. With the normal cursor mode, a "+" shaped cursor would appear at this breakpoint, but because we are in edit mode, the shape of the cursor is a diamond as you can see in this screenshot. The diamond indicates that we can now drag that point to anywhere we want in the coordinate system of the lower plot.

Suppose I drag this point to (0.05, 0.7). When I release the mouse button after dragging the point, the plot will now look like this (to the right). Notice the cursor has changed back to the regular (+ sign) cursor. However if you decide you didn't get it right and you want to move this point again, simply click on the plus sign and it will change back to the diamond which then can be dragged to a new point. However, this time let's right click on the plus sign cursor instead. As before, we will see the diamond cursor, but this time it will do something different. It will leave the point (.05, .7) where it is, and add a new point where ever it is we drag the diamond cursor to.

In this example, we drag the diamond cursor to (.15,.7), thus creating the desired flat region inside the passband notch. Notice the frequency shape is now defined by 6 points at x = [0 .05 .15 .2 .25 .5] whereas before the right click edit operation it was defined with only 5 points.

The thick green line at the top edge of the plot shows the "care" and "don't care" regions. Note that there are 6 square boxes on the green line at the 6 x coordinates defining the frequency shape (two endpoints and four interior breakpoints). After any edit operation that changes the number of defining x coordinates (such as our last edit operation), the entire region from the smallest x coordinate to the largest will be set to green, indicating all regions are "care" regions. If we now press the "Run" button, the design algorithm will do its best to match every dashed line segment. But suppose we don't need the filter to match the steep decline between 0.2 and 0.25 (i.e. a transition region).

So we simply click on the green bar anywhere between those two x coordinates, and that portion of the green bar will turn to gray as you see here, indicating that this is a "don't care" region. Note that it doesn't make sense to have two successive don't care regions. (In fact, erip won't let you do that.) Instead, simply remove the unneeded breakpoint in the middle of your intended don't care region. (To remove a point, drag it outside the plot area.) Likewise, you can't select the first or last region as a don't care region. Instead, just start the filter spec at the beginning of the first care region and end the filter spec at the end of the last care region. (Select the "Shape22" or "HilbertTransformer" filter shapes from the popup to see examples showing that the filter spec does not have to begin at 0 or end at Fs/2.)

Editing the desired filter weight
Editing the filter weighting function is similar to editing the filter shape. As before, first you have to enable only the spec trace on the lower plot. (This enables the editing mode for both the filter shape and the weighting function). Click on a weighting point you want to move. You will see the usual plus sign cursor change to a triangle shape. The triangle shape indicates that you will be able to drag the point to a new location but only vertically. Even if you try, erip will not allow you to move the point horizontally. (Remember that the editing cursor for the filter shape was a diamond, which indicates that you can move the point both horizontally and vertically). Also, erip won't allow you to remove the point from the graph. If you try, erip will move the point back onto the plot. This is because the weighting function must have the same x-coordinates as the filter shape.

At this point we have done enough work that it would be a good idea to hit the save button, assuming this is something we want to continue working with or modifying further. When it asked for a name, we could simply click "OK" without entering a name. Since we have been modifying the shape called "Default", erip will name the new shape "Default-A". If we continue to make incremental changes, we can follow up by right clicking on the save button, which will update the "Default-A" specification without adding yet another entry to the popup.

We've covered everything you need to know about how to graphically edit the filter shape and weighting function, but if you want to learn more about how to edit the plot data graphically, go to the 2d data editing section.

Editing the filter shape & weighting function numerically
Suppose while looking at the filter shape above (with the flat spot in the notch that we added) you click on the "Data" tag in the menu box (which is near the lower left corner of the figure). This figure window will appear showing the x and y coordinates of both the spec and Weight traces. Unlike with the graphical editing technique, you don't have to disable the mag and mag dB traces first. The data editing window will look the same whether those traces are enabled or disabled. (This window is also sometimes referred to as the "Cursor data window".)

Now suppose we want to make the transition band wider, ending at 0.3 instead of 0.25. Simply right click on the "0.25" in the X column, then backspace to get rid of the "25", type in a "3" and hit enter. (Another way is to hit the down arrow key which removes the "0.25" entirely and then you can type in ".3".) You could even type in a Matlab expression such as 3/10 or even round(pi)/10 and the result would be the same. As soon as you hit the enter key you will see the graphs of the spec and weight traces updated (as well as the don't care regions) to show that the x-coordinate has changed. Yet another way you could do this is to do a regular left click on the "0.25", but slightly to the right of center (or just to the right of the number). You will see that the 0.25 increased by a small amount (2 percent). But you can hold down the left click while this value slowly increases. You can watch the graph changing until you see what you like. Or of course, you can slowly decrease the value by clicking slightly to the left of center (or just to the left of the number).

Now suppose you want to make the flat spot in the middle of the notch deeper (.6 instead of .7). Right click on the first 0.7 under the "spec" column heading and change it to 0.6 and then do the same for the second 0.7 right below it. Again as you make these changes you will see the graph being updated every time you hit the Enter key. (Of course, you can use the move slowly left click method as well.)

Now suppose you want to increase the weight in the stop band from 10 to 15. Go to the two 10s in the weight column and change each of them to 15 using the methods already described. Note that the y-axis limits are automatically changed from [0 10] to [0 15] so you can see the whole trace. This is an advantage of the numerical editing method because, with the graphical method, you would have had to increase the upper y-axis limit manually (by right clicking on the y-axis and dragging down) before you were able to drag the "10" values up to "15".

To see more information about using the cursor data window, go to the Menu box section, and scroll down a page or two until you see the "data" heading. There it describes the use of the data cursor window in detail. There you will learn how to add and remove points which you will often need to do while using erip. You will also learn about the multi-level undo/redo feature (another advantage over graphical editing which only has a single-level undo, and no redo feature.) There you will also learn how to change the increment amount (to a different percentage or a fixed value) for the slower left click editing method.

Both the graphical and numerical editing methods described here have their relative strengths and weaknesses, but if you take the time to learn how to use both of them you will find that these editing methods are useful in many of the other applications in this toolbox. Also both these editing techniques with automatically be available to any application you may create using the plt plotting function.

The erip.txt file format
If you are spending a lot of time designing one or more filters, the erip.txt file is important since this is where your work will be saved when you click on the Save button or when you select a new filter type from the saved filter popup. Just like when you are editing a program or document, you should make regular backups of the erip.txt file using different file names so you can look at the history of your work, and to make sure you don't accidentally overwrite some work that you meant to keep. You don't normally need to know the file format of the erip.txt file but for completeness, this format is described below.

The first two lines of the erip.txt file will look something like this:

Fnum: 3
 Pos: 13 143 949 620    977 143 825 620    13 13 1790 92

The first line (filter number) indicates which filter is currently being viewed. In this case, since Fnum is 3 when you start erip it will start up showing the 3rd filter specification defined in the erip.txt file.

The next line shows the positions of the 3 figure windows that make up the erip application (The filter spec window, the pole/zero plot, and the filter coefficient window in that order). The one situation where you may want to edit the erip.txt file yourself (i.e. with a text editor) is when you want to reset these three window locations to the defaults. This is especially useful when you want to transfer the erip.txt file from one computer to another computer that has a different screen resolution, since in that situation these coordinates may be inappropriate. To do this, remove all 12 of the numbers on the Pos: line and replace them with a single zero so that the 2nd line of the file looks like this:

Pos: 0

The next 11 lines of the erip.txt file will contain the first filter specification and will look something like this:


******HighPass********************************
  Fs: 1000
   f: 0 200 350 500 
 des: 0 0 1 1
  wt: 10 10 1 1 
tran: 2 
grid: 400
 rad: 1
   b: .0282127542 -.068055835 .0904799506 -.067314998 .0274030873 
   a: 1.000000000 1.853755775 1.885164302 0.969992730 0.224312164 
 Qba: 0.1 0.1

Line 1	Name	The name of the filter design (ignoring the asterisks) as it appears in the saved filters popup.
Line 2	Fs	The sample rate.
Line 3	f	A list of frequency breakpoints for defining the desired filter shape and weighting function. This must be an increasing sequence of numbers between 0 and Fs/2.
Line 4	des	The desired filter shape. It must be the same size as f. plt(f,des) plots the desired filter shape.
Line 5	wt	The filter shape weighting function. (Higher weights indicate a region of more importance). plt(f,wt) plots the filter shape weighting function.
Line 6	tran	Identifies which bands are transition regions. In this example, the value "2" indicates that the band between frequencies f(2) and f(3) is a transition region. This can contain multiple elements when the filter specification includes multiple transition bands.
Line 7	grid	The value of the grid pseudo edit box (grid density)
Line 8	rad	The value of the radius edit box (which limits how close poles can approach the unit circle)
Line 9	b	The numerator polynomial (May be different than the optimal solution after clicking "run", if the values have been quantized or edited numerically or if the zeros have been moved on the pole/zero chart.)
Line 10	a	The denominator polynomial (May be different than the optimal solution after clicking "run", if the values have been quantized or edited numerically or if the poles have been moved on the pole/zero chart.)
Line 11	Qba	The two values from the Qb and Qa edit boxes (numerator and denominator quantization values respectively)

The next 11 lines will contain the second filter specification and continues in that pattern to include all the filters you have defined via the save button. Note that the number of lines in erip.txt will always be two more than a multiple of 11.

You can edit values in the erip.txt file with a text editor if you like, and these changes will take effect when you restart erip or when you click on the Reload button. However, usually it is easier and safer to make changes using the graphical or numerical methods described above as well as by entering new values into the various edit boxes.

Copyright © 2024
Paul Mennen

erip.m version 12Jul24 (A tool for the design of optimal fir and iir digital filters)