summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/sfg/sfg-doc.tex
blob: e126cfa12918a18a0993afd83cf81cbd29bee045 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
\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
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%