path: root/macros/latex/contrib/sfg/sfg-doc.tex

\documentclass[pagesize=auto, parskip=half]{scrartcl}

\usepackage{fixltx2e}
\usepackage{etex}
\usepackage{lmodern}
\usepackage[T1]{fontenc}
\usepackage{textcomp}
\usepackage{amstext}
\usepackage[utf8]{inputenc}
\usepackage[svgnames]{xcolor}
\usepackage{listings}
\usepackage{microtype}
\usepackage{hyperref}

\newcommand*{\mail}[1]{\href{mailto:#1}{\texttt{#1}}}
\newcommand*{\pkg}[1]{\textsf{#1}}
\newcommand*{\cs}[1]{\texttt{\textbackslash#1}}
\makeatletter
\newcommand*{\cmd}[1]{\cs{\expandafter\@gobble\string#1}}
\makeatother
\newcommand*{\meta}[1]{\text{\textlangle\textsl{#1}\textrangle}}
\newcommand*{\marg}[1]{\texttt{\{}\meta{#1}\texttt{\}}}

\addtokomafont{title}{\rmfamily}

\lstset{%
  language=[LaTeX]TeX,%
  columns=flexible,%
  upquote=true,%
  numbers=left,%
  basicstyle=\ttfamily,%
  keywordstyle=\color{Navy},%
  commentstyle=\color{DimGray},%
  stringstyle=\color{SeaGreen},%
  numberstyle=\scriptsize\color{SlateGray}%
}

\title{The \pkg{sfg} package\thanks{This manual corresponds to \pkg{sfg}~v0.91, dated~22.\,08.\,2007.}}
\author{Hanspeter Schmid\thanks{\mail{schmid@isi.ee.ethz.ch}, \url{http://www.isi.ee.ethz.ch/\~schmid/}}\and Herbert Voß}
\date{22.\,08.\,2007}


\begin{document}

\maketitle


\section{Documentation}

This style file defines some commands to draw signal flow graphs using
\LaTeXe\@.  Signal flow graphs (\textsc{sfg}) are used by electrical and
electronics engineers and graph theorists.  If you haven't heard of
\textsc{sfg}s before, then \pkg{sfg.sty} is probably not useful for you.

If you really want to know what a signal flow graph is, you might read
one of the references given below.

The package sfg requires the packages `\pkg{pstricks}' and `\pkg{fp}'.  It
therefore requires \LaTeXe\ and a reasonably fast machine.

To draw a signal flow graph, you should proceed as follows:
%
\begin{enumerate}
\item Insert \verb|\usepackage{pstricks,sfg}| in your \LaTeXe-file.
\item Draw your \textsc{sfg} on graph paper\footnote{I mean the paper with a 4\,mm, 5\,mm or 1/8\,in grid on it\dots} and determine the size of the 
  picture in units (squares).
\item Set the unitlength using \cmd{\sfgsetunit}.
\item Set the arrowlength, node radius and label offsets using \cmd{\sfgsetsize}.
\item In a \LaTeX\ picture environment of the size you determined above,
  \begin{itemize}
  \item first draw all paths using \cmd{\sfgbranch} and \cmd{\sfgcurve},
  \item then draw all nodes using \cmd{\sfgnode} and \cmd{\sfgtermnode}.
  \end{itemize}
\end{enumerate}


\section{Setting the Controlling Parameters}

\begin{description}
\item[\cmd{\sfgsetunit}\marg{length}]
  sets \cmd{\unitlength} and the PS unit to \meta{length}, and
  defines the default \pkg{pstricks} linewidth as 0.4\,pt.  This has an
  influence on \emph{all} ps-tricks commands that are used afterwards.

\item[\cmd{\sfgsetsize}\marg{nr}\marg{al}\marg{no}\marg{ao}]
  sets the node radius to \meta{nr} units, the
  arrow\-length to \meta{al} units, the offset of the nodes' labels to
  \meta{no} units and the offset of the arrows' labels to \meta{ao} units.
  All four parameters are numbers.

\item[\cmd{\sfgsetangle}\marg{an}]
  sets the incidence angle of sfgcurves \meta{an} degrees.
  Default value: 60 degrees.

\item[\cmd{\sfgsetarrowloc}\marg{mid}]
  sets the location of the sfgbranch's arrow.  0.5
  means in the middle, 0.1 means 10\,\% of the branch length from
  the first node.
  Default value: 0.5

\item[\cmd{\sfgsetlines}\marg{li\_len}\marg{lii}\marg{liii}]
  sets the line thickness \cmd{\sfg@Li} (used
  for all lines) to \meta{li\_len}, the thickness \cmd{\sfg@Lii} (used for
  terminal nodes) to $\meta{lii} \times \meta{li\_len}$, and the thickness \cmd{\sfg@Liii}
  to $\meta{liii} \times \meta{li\_len}$.  It also resets the default pstricks
  linewidth to the new \cmd{\sfg@Li}.

  Default values:
  \begin{tabular}[t]{l@{~=~}l}
    \cmd{\sfg@Li}   & 0.40\,pt                    \\
    \cmd{\sfg@Lii}  & $1.80 \times \cmd{\sfg@Li}$ \\
    \cmd{\sfg@Liii} & $3 \times \cmd{\sfg@Li}$    \\
  \end{tabular}
\end{description}


\section{Drawing signal flow graph (SFG) branches}

\begin{description}
\item[\cmd{\sfgbranch}\marg{dx}\marg{dy}\marg{pos}\marg{text}]
  draws a straight \textsc{sfg} branch from $(0,0)$
  to $(\meta{dx},\meta{dy})$. An arrow is placed in the middle of the branch,
  and a label \meta{text} is typeset near the arrow. The parameter
  \meta{pos} is explained below (see \cmd{\sfgnode}).

  The distance of the label from the arrow's centre as well as
  the arrow's length can be set using \cmd{\sfgsetsize}.

  The location of the arrow can be changed using
  \cmd{\sfgsetarrowloc}.

\item[\cmd{\sfgcurve}\marg{dx}\marg{dy}\marg{off}\marg{pos}\marg{text}]
  draws a curved \textsc{sfg} path from $(0,0)$
  to $(\meta{dx},\meta{dy})$. The arrow's position is \meta{off} units left of the
  middle of the path (\meta{off} can be negative to put the arrow
  right of the path). The curve leaves the endpoints in an angle
  of 60~degrees (this value can be changed using \cmd{\sfgsetangle})
  if possible. If the arrow is too far away from the straight
  path, the angle is increased to guarantee a ``nice'' curve,
  and a warning message is issued.
\end{description}


\section{Drawing Nodes}

\begin{description}
\item[\cmd{\sfgnode}\marg{pos}\marg{text}]
  draws a node with label \meta{text}. \meta{pos} decides
  where the label is typeset. It is a number between~0 and~7.
  After the command
%
\begin{verbatim}
\sfgsetcompass
\end{verbatim}
%
  eight macros named after compass directions can be used.

  \begin{tabular}{rcl}
    3 & 2 & 1 \\
    4 & . & 0 \\
    5 & 6 & 7
  \end{tabular}
  %
  \quad or\quad
  %
  \begin{tabular}{rcl}
    \cmd{\NW} & \cmd{\N} & \cmd{\NE} \\
    \cmd{\W}  & .        & \cmd{\E}  \\
    \cmd{\SW} & \cmd{\S} & \cmd{\SE}
  \end{tabular}

  The distance of the label from the node's centre as well as the 
  node's radius can be set using \cmd{\sfgsetsize}.

\item[\cmd{\sfgtermnode}\marg{pos}\marg{text}]
  draws a terminal node (black circle filled white).
\end{description}


\section{Example:}

\begin{lstlisting}
\documentclass[11pt,a4paper]{article}
\usepackage{pstricks,sfg}
\pagestyle{empty}
\setlength{\parindent}{0pt}

\begin{document}
\sfgsetunit{0.5cm}
\sfgsetsize{0.12}{0.4}{0.5}{0.3}
\sfgsetcompass
\begin{picture}(27,4)
                                % branches related to node 2
  \put(6,2){\sfgbranch{3}{0}\S{$\frac{1}{R_1}$}}
  \put(9,2){\sfgbranch{3}{0}\N{\boldmath $Z_2$}}
  \put(18,2){\sfgcurve{-9}{0}{2}\S{$\frac{1}{R_2}$}}
  \put(24,2){\sfgcurve{-15}{0}{-2}\N{$sC_1$}}
                                % branches related to node 3
  \put(12,2){\sfgbranch{3}{0}\N{$\frac{1}{R_2}$}}
  \put(15,2){\sfgbranch{3}{0}\N{\boldmath $Z_3$}}
                                % input, voltage gain, output
  \put(0,2){\sfgcurve{6}{0}{2}\N{$1$}}
  \put(18,2){\sfgcurve{6}{0}{-2}\S{$\alpha_{\mathrm{V}}$}}
  \put(24,2){\sfgbranch{3}{0}\S{$1$}}
                                % nodes
  \put(0,2){\sfgtermnode\S{$V_{\mathrm{in}}$}}
  \put(3,2){\sfgnode\S{$I_1$}}
  \put(6,2){\sfgnode\S{$V_1$}}
  \put(9,2){\sfgnode\S{$I_2$}}
  \put(12,2){\sfgnode\S{$V_2$}}
  \put(15,2){\sfgnode\S{$I_3$}}
  \put(18,2){\sfgnode\S{$V_3$}}
  \put(21,2){\sfgnode\S{$I_4$}}
  \put(24,2){\sfgnode\S{$V_4$}}
  \put(27,2){\sfgtermnode\S{$V_{\mathrm{out}}$}}
\end{picture}
\end{document}
\end{lstlisting}


\section{References}

\setlength{\leftmargini}{1em}
\addtokomafont{descriptionlabel}{\normalfont}

\begin{description}
\item[{[Chen, 1995, Chapters 7, 8 and 18]}]\leavevmode\\
  Wai-Kai Chen. The Circuits and Filters Handbook. CRC Press,
  Inc.,\ 1995.
\end{description}
%
or have a look at the original papers by Samuel Mason:
%
\begin{description}
\item[{[119]}]\leavevmode\\
  Samuel J. Mason. Feedback theory --- some properties of signal 
  flow graphs. Proceedings of the Institute of Radio Engineers,  
  41(9):1144--1156, September 1953. 

\item[{[120]}]\leavevmode\\
  Samuel J. Mason. Feedback theory --- further properties of
  signal flow graphs. Proceedings of the Institute of Radio
  Engineers, 44(7):920--926, July 1956.
\end{description}

\end{document}



%@(#) sfg.sty: Signal flow graphs
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% This is the style file sfg.sty for drawing signal flow graphs in LaTeX2e.
%
%               Version 0.9, 1.7.1998, Hanspeter Schmid
%               Version 0.91, 22.08.2007 hv scalebox->\psscalebox
%
% If you find an error, or if you want me to implement some more 
% functions, want me to include more references to books on sfgs,
% or if you just want to say `hello thank you, I find you package
% useful', please don't hesitate and contact me:
%
%   Hanspeter Schmid, schmid@isi.ee.ethz.ch, 
%                     http://www.isi.ee.ethz.ch/~schmid/
%
%% This program can be redistributed and/or modified under the terms
%% of the LaTeX Project Public License Distributed from CTAN
%% archives in directory macros/latex/base/lppl.txt.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% History: (Version numbers are going towards 3/pi.  
%           sfg.sty is not good enough yet to be called v1.0)
%
% created: 26.1.96, hps, (v0)
% modified for submission to CTAN: 1.7.98, hps, (v0.9) 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Plans:   - make a proper dtx-file out of this mess.  I'll do this if
%            and when I find the time to do it.
%          - include an sfg branch which has snake form, e.g. \sfgsnake
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% SEE DESCRIPTION AFTER THE \endinput
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%