%$Id: generato.tex,v 25.95 2006/08/26 01:26:53 al Exp $ -*- LaTeX -*-
% man  commands  generato  .
% Copyright (C) 2001 Albert Davis
% Author: Albert Davis <aldavis@ieee.org>
%
% This file is part of "Gnucap", the Gnu Circuit Analysis Package
%
% This program is free software; you can redistribute it and/or modify
% it under the terms of the GNU General Public License as published by
% the Free Software Foundation; either version 2, or (at your option)
% any later version.
%
% This program is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
% GNU General Public License for more details.
%
% You should have received a copy of the GNU General Public License
% along with this program; if not, write to the Free Software
% Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
% 02110-1301, USA.
%------------------------------------------------------------------------
\section{{\tt GENERATOR} command}
\index{Generator command}
\index{user defined transient input}
\index{user source}
\index{transient input}
\index{input: transient analysis}
\index{function generator}
%------------------------------------------------------------------------
\subsection{Syntax}
\begin{verse}
{\tt generator} \{{\it option-name}={\it value} ...\}
\end{verse}
%------------------------------------------------------------------------
\subsection{Purpose}

Sets up an input waveform for {\tt transient} and {\tt Fourier} analysis.
Emulates a laboratory type function generator.
%------------------------------------------------------------------------
\subsection{Comments}

This command sets up a singal source that is conceptually separate
from the circuit.  To use it, make the value of a component
"generator(1)", or substitute a scale factor for the parameter.

The SPICE style input functions also work, but are considered to
be part of the circuit, instead of part of the test equipment.

The parameters available are designed to emulate the controls on a function
generator.  There are actually two generators here: sine wave and pulse.  If
both are on (by setting non-zero parameters) the sine wave is modulated by
the pulse, but either can be used alone.

Unless you change it, it is a unit-step function at time 0.  The purpose of
the command is to change it.

This command does not affect {\tt AC} or {\tt DC} analysis in any way.  It
is only for {\tt transient} and {\tt Fourier} analysis.  In {\tt AC}
analysis, the input signal is always a sine wave at the analysis frequency.

Typical usage is the name of the control followed by its value, or just plain
{\tt Generator} to display the present values.

The actual time when switching takes place is ambiguous by one time step.  If
precise time switching is necessary, use the {\tt Skip} option on the
transient analysis command, to force more resolution.  This ambiguity can
usually be avoided by specifying finite rise and fall times.
\index{ambiguous time}
\index{switch time errors}
%------------------------------------------------------------------------
\subsection{Parameters}

\begin{description}

\item[{\tt frequency}]
The frequency of the sine wave generator for a transient analysis.
The sine wave is modulated by the pulse generator.  A frequency of
zero puts the pulse generator on line directly.

\item[{\tt amplitude}]
The overall amplitude of the pulse and sine wave.  A scale factor.  It
applies to everything except the {\it offset} and {\it initial}
values.

\item[{\tt phase}]
The phase of the sine wave, at the instant it is first turned on.

\item[{\tt max}]
The amplitude of the pulse, when it is `on'.  (During the {\it width}
time) If the sine wave is on (frequency not zero) this is the
amplitude of the sine wave during the first part of the period.  The
{\it max} is scaled by {\it amplitude}.

\item[{\tt min}]
The amplitude of the pulse, when it is `off'.  (After it falls, but
before the next period begins.)  Although we have called these {\it
min} and {\it max}, there is no requirement that {\it max} be larger
than {\it min}.  If the sine wave is on, this is its amplitude during
the second part of the period.  The {\it min} is scaled by {\it
amplitude}.

\item[{\tt offset}]
The DC offset applied to the entire signal, at all times after the
initial delay.  The {\it offset} is {\bf not} scaled by {\it
amplitude}.

\item[{\tt initial}]
The initial value of the pulse generator output.  It will have this
value starting at time 0, until {\it delay} time has elapsed.  It will
never return to this value, unless you restart at time 0.

\item[{\tt rise}]
The rise time, or the time it takes to go from {\it min} to {\it max},
or for the first rise, {\it initial} to {\it max}.  The rise is
linear.

\item[{\tt fall}]
The fall time.  (The time required to go from {\it max} back to {\it
min}.)

\item[{\tt delay}]
The waiting time before the first rise.

\item[{\tt width}]
The length of time the output of the generator has the value {\it
max}.  A width of zero means that the output remains high for the
remainder of the period.  If you really want a width of zero, use a
very small number, less than the step size.

\item[{\tt period}]
The time for repetition of the pulse.  It must be greater than the sum
of rise + fall + width.  A period of zero means that the signal is not
periodic and so will not repeat.

\end{description}
%------------------------------------------------------------------------
\subsection{Examples}

The generator command ...

\begin{description}

\item[{\tt gen}] Display the present settings.

\item[{\tt gen freq=1k}] Sets the sine wave to 1 kHz.  All other parameters
are as they were before.

\item[{\tt gen freq=0}] Turns off the sine wave, leaving only the pulse.

\item[{\tt gen ampl=0}] Sets the amplitude to zero, which means the circuit
has no input, except for possibly a DC offset.

\item[{\tt gen period=.001 freq=1m}] Sets the period back to 1 millisecond.
Applies 1 mHz modulation to the pulse, resulting in a pulsed sine wave.  In
this case, a 100 microsecond 10 volt burst, repeating every millisecond.
Between bursts, you will get 2.5 volts, with reversed phase.  The old
values, in this case from 2 lines back (above) are kept.  ({\tt Ampl 5 Rise
10u Fall 10u} ...)

\item[{\tt gen freq=60 phase=90 delay=.1}] The sine wave frequency is 60
Hertz.  Its phase is 90 degrees when it turns on, at time .1 seconds.  It
turns on sharply at the peak.

\end{description}

A component using it ...

\begin{description}

\item[{\tt V12 1 0 generator(1)}] Use the generator as the circuit
input through this voltage source.  The DC and AC values are 0.

\item[{\tt V12 1 0 tran generator(1) ac 10 dc 5}] Same as before, except
that the AC value is 10 and DC value is 5.

\item[{\tt Rinput 1 0 tran generator(1)}] Unlike SPICE, the functions
can be used on other components.  The resistance varies in time
according to the "generator".

\end{description}

%------------------------------------------------------------------------
%------------------------------------------------------------------------
