1 ## Copyright (C) 2023 Leonardo Araujo <leolca@gmail.

com>
2 ##
3 ## This program is free software: you can redistribute it and/or modify
4 ## it under the terms of the GNU General Public License as published by
5 ## the Free Software Foundation, either version 3 of the License, or
6 ## (at your option) any later version.
7 ##
8 ## This program is distributed in the hope that it will be useful,
9 ## but WITHOUT ANY WARRANTY; without even the implied warranty of
10 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 ## GNU General Public License for more details.
12 ##
13 ## You should have received a copy of the GNU General Public License
14 ## along with this program; see the file COPYING. If not, see
15 ## <https://www.gnu.org/licenses/>.
16
17 ## -*- texinfo -*-
18 ## @deftypefn {Function File} {@var{L} = } ismaxphase (@var{b}, @var{a})
19 ## @deftypefnx {Function File} {@var{L} = } ismaxphase (@var{sos})
20 ## @deftypefnx {Function File} {@var{L} = } ismaxphase (@dots{}, @var{tol})
21 ##
22 ## Determine whether a digital filter is maximum phase (maximum energy-delay).
23 ## The filter might be defined by the numerator coefficients, @var{b}, and the
24 ## denominator coefficients, @var{a}, or, alternatively, by a matrix of
25 ## second-order sections, @var{sos}. A tolerance @var{tol} might be given to
26 ## define when two numbers are close enough to be considered equal.
27 ##
28 ## Example:
29 ## @example
30 ## b = [1 2 4 4 2 1];
31 ## zplane (b);
32 ## ismaxphase (b)
33 ## @end example
34 ##
35 ## Ref [1] Oppenheim, Alan, and Ronald Schafer. Discrete-Time Signal Processing.
36 ## 3rd edition, Pearson, 2009.
37 ## @end deftypefn
38
39 function flag = ismaxphase (b, a, tol)
40 if (nargin < 1 || nargin > 3 )
41 print_usage;
42 endif
43
44 if (nargin == 2 && ( ! isrow (a) || ! isrow (b) ))
45 error ( "coefficient array should be a row vector" );
46 endif
47
48 if (nargin == 1 && isrow (b)), a = 1; endif
49
50 if nargin < 3,
51 tol = eps^(3/4);
52 elseif length (tol) > 1,
53 error ( "a scalar is expected as the tolerance value" );
54 endif
55
56 if (nargin > 1 && isrow (a) && isrow (b)) || (nargin == 1 && isrow (b))
57 zm = abs (roots (b));
58 pm = abs (roots (a));
59 % Zeros of a maximum phase filter are constrained to lie outside the unit
 circle.
60 % The filter should be stable (poles inside the unit circle).
61 flag = (all (zm > 1 + tol) || isempty (zm)) && (all (pm < 1 - tol) ||
isempty (pm));
62 elseif (nargin == 1 && all(size (b) > [1 1]))
63 [b, a] = sos2tf (b);
64 flag = ismaxphase (b, a, tol);
65 endif
66
67 endfunction
68
69 %!demo
70 %! f = ismaxphase (b, a)
71
72 %! ## test input validation
73 %!error n = ismaxphase ()
74 %!error n = ismaxphase (1, 1, 1, 1)
75 %!error n = ismaxphase (1, 1, 1, 1, 1)
76 %!error n = ismaxphase ([1:10]', 1)
77 %!error n = ismaxphase (1, [1:10]')
78 %!error n = ismaxphase ([1:10]', [1:10]')
79 %!error n = ismaxphase (1:10, 1:10, 1:10)
80 %!error n = ismaxphase (ones (3), ones (3))
81
82 %!test
83 %! z1 = [0.9*exp(j*0.6*pi), 0.9*exp(-j*0.6*pi)];
84 %! z2 = [0.8*exp(j*0.8*pi), 0.8*exp(-j*0.8*pi)];
85 %! b = poly ([z1 z2]);
86 %! a = 1;
87 %! f = ismaxphase (b, a);
88 %! assert (f, false)
89
90 %!test
91 %! z1 = [0.9*exp(j*0.6*pi), 0.9*exp(-j*0.6*pi)];
92 %! z2 = [0.8*exp(j*0.8*pi), 0.8*exp(-j*0.8*pi)];
93 %! b = poly ([1./z1 1./z2]);
94 %! a = 1;
95 %! f = ismaxphase (b, a);
96 %! assert (f, true)
97
98 %!test
99 %! z1 = [0.9*exp(j*0.6*pi), 0.9*exp(-j*0.6*pi)];
100 %! z2 = [0.8*exp(j*0.8*pi), 0.8*exp(-j*0.8*pi)];
101 %! b = poly ([z1 1./z2]);
102 %! a = 1;
103 %! f = ismaxphase (b, a);
104 %! assert (f, false)
105
106 %!test
107 %! z1 = [0.9*exp(j*0.6*pi), 0.9*exp(-j*0.6*pi)];
108 %! z2 = [0.8*exp(j*0.8*pi), 0.8*exp(-j*0.8*pi)];
109 %! b = poly ([1./z1 z2]);
110 %! a = 1;
111 %! f = ismaxphase (b, a);
112 %! assert (f, false)
113
114 %!test
115 %! [b, a] = butter (1, .5);
116 %! f = ismaxphase (b, a);
117 %! assert (f, false)
118
119 %!test
120 %! [b, a] = butter (8, .5);
121 %! f = ismaxphase (b, a);
122 %! assert (f, false)