\documentclass[openany,12pt]{book}
%\usepackage{truetype}
\setlength{\paperwidth}{8.5in}
\setlength{\paperheight}{11in}
\setlength{\oddsidemargin}{0in}
\setlength{\evensidemargin}{0in}
\setlength{\topmargin}{0in}
%\setlength{\headheight}{0.25in}
%\setlength{\headsep}{0.25in}
\setlength{\textheight}{8.5in}
\setlength{\textwidth}{6.5in}
%\setlength{\footskip}{25pt}
%\renewcommand{\baselinestretch}{1.5}
\setlength{\parskip}{1.5ex plus 0.5ex minus 0.5ex}
\pagestyle{headings}
\setlength{\parindent}{0in}

%\usepackage{epsfig}
\usepackage{html}
%\usepackage{times}
\usepackage{amsmath,amssymb,amsfonts}
%Check if we are compiling under latex or pdflatex
\ifx\pdftexversion\undefined
  \usepackage[dvips]{graphicx}
\else
  \usepackage[pdftex]{graphicx}
\fi
\usepackage{color}
\usepackage{verbatim}

\newcommand{\matinput}[1]{\subsection*{#1.m}\verbatiminput{mfiles/#1.doc}}
\newcommand{\integers}{{\Bbb Z}}
\newcommand{\reals}{{\Bbb R}}
\newcommand{\vect}[1]{{\mathbf #1}}
\newcommand{\mat}[1]{{\mathbf #1}}
\newcommand{\firopt}{FIROpt}
\newcommand{\optseq}{\texttt{optSequence}}
\newcommand{\ogs}{\texttt{optGenSequence}}
\newcommand{\optarr}{\texttt{optArray}}
\newcommand{\optvec}{\texttt{optVector}}
\newcommand{\optqvec}{\texttt{optQuadVector}}
\newcommand{\optquad}{\texttt{optQuad}}
\newcommand{\process}{\texttt{Process}}
\newcommand{\lconstr}{\texttt{LinConstr}}
\newcommand{\sconstr}{\texttt{SOCConstr}}
\newcommand{\var}[1]{\texttt{#1}}
\newcommand{\defn}{\stackrel{\triangle}{=}}
\newcommand{\func}[1]{{\ttfamily \bf #1}}
\DeclareMathOperator{\atan}{atan}
\newcommand{\field}[1]{\mathbb{#1}}
\newcommand{\vv}[1]{\mathbf{#1}}
\newcommand{\matlab}{{\rm\textsc{matlab}}}
\newcommand{\opt}{\textsf{\small Opt}}
\newcommand{\optvar}[1]{{\color{red}\small\rm\textsf{#1}}}
\newcommand{\optfn}[1]{{\color{blue}\small\rm\textsf{#1}}}
\newenvironment{optsrc}{\begin{verbatim}}{\end{verbatim}}
\newcommand{\optitem}[1]{{\color{green}\textit{#1}}}
\newcommand{\ml}[1]{{\color{black}\small\rm\textsf{#1}}}
\newenvironment{code}{%
\begin{center}%
\begin{tabular}{@{}c@{$\mbox{}=\mbox{}$}l@{}}%
}{%
\end{tabular}%
\end{center}%
}

\newcommand{\rfig}[1]{Fig.~\ref{#1}}
\newcommand{\rfigs}[1]{Figs.~\ref{#1}}
\newcommand{\rFig}[1]{Figure~\ref{#1}}
\newcommand{\rFigs}[1]{Figures~\ref{#1}}
\newcommand{\req}[1]{(\ref{#1})}
\newcommand{\reqs}[1]{\req{#1}}
\newcommand{\rEq}[1]{Equation~(\ref{#1})}
\newcommand{\rEqs}[1]{Equations~(\ref{#1})}
\newcommand{\sm}[1]{\!#1\!}


\hyphenation{optVector optSequence sca-lar ele-ment let-ters NM sys-tems since en-hance-ment term col-umns}


%\input{setwmf}
%\input{seteps}

\begin{document}
\frontmatter
\title{{\Huge \bfseries \sffamily FIR Filter Optimization Toolbox} \\ User's Guide Version 2.0}
\author{Jeff Coleman \and Dan Scholnik \and Josef Brandriss}
\maketitle
\tableofcontents

\mainmatter
\chapter{Introduction}
\section{Overview}
This manual is a user's guide for the FIR Filter Optimization Toolbox
(OPT, version 2.0)


\subsection{OPT Directory Structure}
Your OPT disk possesses the following files and subdirectories:

\sffamily \begin{tabular}{ll}
@CTProcess & Continuous time random process source files \\
@CTProcess/private & Private functions for CTProcess class \\
Doc & Documentation files \\
examples & Example scripts \\
@LinConstr & Linear constraint source files \\
@optArray & Optimizable array source files \\
@optGenSequence & Optimizable non-uniform sequence source files \\
@optQuad & Optimizable quadratic source files \\
@optQuadVector & Optimizable quadratic vector source files \\
@optSequence & Optimizable sequence source files \\
@optVector & Optimizable vector source files \\
@Process & Discrete-time random process source files \\
@Process/private & Private functions for Process class \\
@SOCConstr & Second-order cone constraint source files \\
\end{tabular} \rmfamily

\section{Quick Reference}
Tables \ref{tab.OVops} through \ref{tab.OSops} summarize operators in \opt.

\begin{table}[htb]
  \centering
  \begin{tabular}{|c|c|}
    \hline 
    \textbf{notation} & \textbf{function} \\ \hline
    \texttt{a+b} & add  \\ \hline
    \texttt{a-b} & subtract  \\ \hline
    \texttt{a*b} & pointwise multiply \\ \hline
    \texttt{a/c} & pointwise divide  \\ \hline
    \texttt{a(n)} & extract \\ \hline
    \texttt{real(a)} & real part \\ \hline
    \texttt{imag(a)} & imaginary part \\ \hline
    \texttt{\func{conj}(a)} & complex conjugate \\ \hline
    \texttt{sum(a)} & element sum  \\ \hline
    % these return quadratics, not optVectors
%    \texttt{abs(a)} & absolute value & \small\optqvec \\ \hline
%    {\ttfamily a.\verb1^12} & square & \small\optqvec \\ \hline
  \end{tabular}
  \caption{Overloaded operators for objects of class \optvec.  
    \var{a} and \var{b} are of class \optvec, \var{c} is a constant vector,
    and \var{n} is an integer vector.}
  \label{tab.OVops}
\end{table}

\begin{table}[htb]
  \centering
  \begin{tabular}{|c|c|}
    \hline 
    \textbf{notation} & \textbf{function} \\ \hline
    \texttt{h.*g} & convolve  \\ \hline
    \texttt{h|M} & shift  \\ \hline
    \texttt{h./M} & interpolate  \\ \hline
    {\ttfamily h.\verb1\1M} & decimate  \\ \hline
    \texttt{h.'} & flip about origin \\ \hline
    \texttt{h'} & flip and conjugate  \\ \hline
  \end{tabular}
  \caption{Additional operators for objects of class \optseq. \var{g} 
    and \var{h} are of class \optseq\ and \var{M} is a positive integer.}
  \label{tab.OSops}
\end{table}

\section{Filter Design With OPT}

A \matlab\ session for \opt\ filter design typically takes the form in
Fig. \ref{optsession}. \optfn{InitOpt} is called once per session. An
optimization space is created by \optfn{newOptSpace}, which returns a
handle to a new set of optimization variables. A solution point in that
space can be obtained thereafter by passing its handle to
\optfn{minimize} with an \optitem{objective}, a list of
\optitem{constraints}, and name of a solver routine. Impulse response
variable \optvar{h}\ in \rfig{optsession} is an example of an \opt\
quantity that does not store numerical values but instead stores
relationships to optimization variables. Numerical values are
substituted into those relationships only when \optfn{optimal}\
evaluates the relationships at a solution point. This is the heart of
\opt:

\begin{quote}
\opt\ permits meaningful algebraic operations on quantities that,
because optimization has not yet taken place, have no numeric values.
\end{quote}

The last argument to \optfn{minimize} selects a solver. Here we use \\
\optfn{'sedumi'}\
\ml{(http://fewcal.kub.nl/sturm/software/sedumi.html)}, \\
 a
high-performance noncommerical (free) numeric solver for SOCPs. Other
options include the remarkably fast \optfn{'mosek'} \ml{(www.mosek.com)}
and \optfn{'loqosoclp'}, an SOCP/LP interface to the {\sc Loqo}
\ml{(www.princeton.edu/~rvdb)} package, which accepts a callback
function for plotting intermediate results.


\subsection{SOCP Specification}

The SOCP specification in Fig. \ref{optsession} generally takes this
form:
\begin{itemize}
\item specification of an \optitem{impulse response}
\item specification of the \optitem{constraints}
\item specification of the \optitem{objective}
\end{itemize}
The \optitem{objective}\ is often simple and is just defined in
\optfn{minimize}'s argument list. This is occasionally true of the
\optitem{constraints} also.

The SOCP \optitem{objective}\ and \optitem{constraints}\ in
\rfig{optsession} are generally functions of the \optitem{impulse
response} to be optimized. 
For information on specifying an impulse reponse, see chapter
\ref{chap.affine}.  


\subsubsection{Construction of Error Measures}

\paragraph{Frequency-Domain Grids}
\label{frequencygrids}

Ref. ??? discusses the use of SOC constraints, one for each frequency,
in a grid across a band of interest, to construct measures of
frequency-domain errors in the $L_\infty$ (or Chebyshev or minimax)
sense, in the $L_2$ (or mean squared error) sense, and in the $L_1$
(mean absolute error) sense. Those techniques begin here:
\begin{code}
\ml{f} & \ml{linspace(f1, f2, (f2-f1) * 20 * length(} \optvar{h} ) ) ; \\
\optvar{H} & \optfn{fourier}(\optvar{h}, \ml{f}) ; \\
\end{code}
\vfill
If \optvar{h} is an impulse response, \optvar{H} is the corresponding
frequency response ``evaluated'' on the \matlab\ vector \ml{f} of
frequencies. If \optvar{h} is optimizable then \optvar{H} is also, and
its samples remain indeterminant because they depend on impulse-response
coefficients that as yet have no numeric values. Here \matlab's
\ml{linspace} function creates a vector with elements stretching between
its first two arguments of length specified by the third argument, here
set high enough for typical FIR design work. Factor \ml{20} might be as
low as \ml{5} for quick experimentation or as high as \ml{50} or more
when the Fourier samples are to be used for precise approximation of an
$L_1$ norm.

If \optvar{h} is linear phase, so that \optvar{H} is real by
construction,
\begin{quote}
\begin{tabular}{rcl}
\optvar{C} = \{\ml{-10 $\wedge$ (-55/20) $<$} & \ml{real(}\optvar{H}\ml{)} & , ... \\
& \ml{real(}\optvar{H}\ml{)} & $<$\ml{10 $\wedge$ (-55/20)} \} ;
\end{tabular}
\end{quote}
sets \optvar{C} to a list containing two linear constraints for each
frequency sample to bound \optvar{H} between $-\epsilon$ and $\epsilon$,
where $20 \log_{10} \epsilon = -55 \:\mbox{dB}$. Taking the real part of
\optvar{H} eliminates computational noise in imaginary components (which
should be zero) in order that the ``$<$'' operator has real arguments as
required. If \optvar{h} is instead nonlinear phase, so that \optvar{H}
must be complex,
\begin{code}
\optvar{d} & \optfn{optVar}( \optvar{X} ) ; \\
\optvar{C} & \ml{abs}( \optvar{H} ) $<$ \optvar{d} ; \\
\end{code}
sets \optvar{C} to a list of SOC constraints, one for each sample in
\optvar{H}, that constrain the magnitute response by optimization
variable \optvar{d}. A 
constant bound would be valid, but here \optvar{d} can be passed as the
\optitem{objective} to \optfn{minimize} in order to minimize the peak
magnitude of the samples in \optvar{H}. (Using \ml{abs}( $\cdot$ )
would also work for the linear-phase case, but a degenerate second-order
cone would be used at each frequency instead of a linear-constraint pair
as before.) 

The forms just presented typically specify stopbands but apply to
passbands as well if, when \optvar{C} is defined, \optvar{H} is replaced
with (\ml{1} - \optvar{H}) to specify a desired complex passband gain of
unity. 


\paragraph{Random Processes as Drive Signals}

DSP often requires error measures of the form
\[ MSE = \int |H(f) - D(f)|^2 W(f) \: df , \]
where $H(f)$ approximates, with error weighting $W(f)$, some desired
function $D(f)$. If $\int W(f) \: df = 1$ with $W(f)$ taking only values
$\{ 0, \alpha \}$ for some $\alpha$, then this is the mean squared error
(MSE) between $H(f)$ and $D(f)$ in the support of $W(f)$. But if $W(f)$
is the power spectral density (PSD) of a zero-mean random process
driving filters $H(f)$ and $D(f)$, the integral is also the average
power in the output-error signal (the difference between the filter
outputs). An MSE specified as an error power  can be derived by \opt\
automatically and to machine precision.


%--------------------
\input{affine}
\input{region}
\input{process}
\input{design}
%--------------------

\chapter{OPT Reference}

\section{MATLAB Library}
\label{MATLABlib}
This section of the user's guide contains detailed descriptions of all
the MATLAB-callable functions. On-line help is also available --- if
you execute {\tt help} on one of the function names, MATLAB displays
an abbreviated version of the reference entry.

\newpage
\subsection{Engine Functions}
\input{topfcn}
\newpage
\subsection{Continuous-Time Processes}
\input{CTfcn}
\newpage
\subsection{Lattices}
\input{latfcn}
\newpage
\subsection{Linear Constraints}
\input{linfcn}
\newpage
\subsection{Multi-Dimensional Processes}
\input{ndpfcn}
\newpage
\subsection{Optimizable Arrays}
\input{oafcn}
\newpage
\subsection{Quadratic Optimizables}
\input{oqfcn}
\newpage
\subsection{Quadratic Optimizable Vectors}
\input{oqvfcn}
\newpage
\subsection{Optimizable Affine Sequences}
\input{osfcn}
\newpage
\subsection{Optimization Spaces}
\input{ospfcn}
\newpage
\subsection{Optimizable Vectors}
\input{ovfcn}
\newpage
\subsection{Discrete-Time Processes}
\input{procfcn}
\newpage
\subsection{Regions}
\input{regfcn}
\newpage
\subsection{Second-order Cone Constraints}
\input{SOCfcn}
\newpage
\subsection{Solutions}
%\input{solnfcn}



\end{document}
