%$Id: functions.tex,v 25.95 2006/08/26 01:26:53 al Exp $ -*- LaTeX -*-
% man behavior functions .
% 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{Functions}

Gnucap behavioral modeling functions are an extension of the Spice source
time dependent values.
%------------------------------------------------------------------------
\subsection{The extensions}

They apply to all elements (primitive components).

All accept either Spice compatible order dependent parameters, or
easier keyword=value notation.

The syntax is identical for all supported components.
%------------------------------------------------------------------------
\subsection{Fixed sources}

Time dependent functions are voltage or current as a function of time.
They are mostly Spice compatible, with extensions.

Nonlinear transfer functions use time as the independent variable.
Some may not make sense, but they are there anyway.
%------------------------------------------------------------------------
\subsection{Capacitors and inductors}

Time dependent functions are capacitance or inductance as a function
of time.  They are voltage/current conserving, not charge/flux
conserving.

Nonlinear transfer functions are charge or flux as a function of input
(voltage or current).  Charge and flux are conserved, and can be
probed.
%------------------------------------------------------------------------
\subsection{Resistors and conductances}

Time dependent functions are resistance or conductance as a function
of time.

Nonlinear transfer functions are current or voltage as a function of
input (voltage or current).  Resistors define voltage as a function of
current.  Conductances define current as a function of voltage.
%------------------------------------------------------------------------
\subsection{Controlled sources}

Time dependent functions are gain (v/v, transconductance, etc)
function of time.

Nonlinear transfer functions are output (voltage or current) as a
function of input (voltage or current).
%------------------------------------------------------------------------
\subsection{Available functions}

\begin{description}

\item[{\tt COMPLEX}] Complex (re, im) value.
\item[{\tt EXP}] Spice Exp source.  (time dependent value).
\item[{\tt FIT}] Fit a curve with splines.
\item[{\tt GENERATOR}] Value from Generator command.
\item[{\tt POLY}] Polynomial (Spice style).
\item[{\tt POSY}] Posynomial (Like poly, non-integer powers).
\item[{\tt PULSE}] Spice Pulse source.  (time dependent value).
\item[{\tt PWL}] Piece-wise linear.
\item[{\tt SFFM}] Spice Frequency Modulation (time dependent value).
\item[{\tt SIN}] Spice Sin source.  (time dependent value).
\item[{\tt TANH}] Hyperbolic tangent transfer function.

\end{description}

In addition, you may name a ``function'' defined by a {\tt .model}
statement.  The following {\tt .model} types may be used here:

\begin{description}

\item[{\tt TABLE}] Fit a curve with splines.
\item[{\tt Cap}] Spice semiconductor ``capacitor'' model.
\item[{\tt Res}] Spice semiconductor ``resistor'' model.

\end{description}
%------------------------------------------------------------------------
\subsection{Parameters that apply to all functions}

These parameters are available with all functions.  Some may not make
sense in some cases, but they are available anyway.

\begin{description}

\item[{\tt Bandwidth} = {\it x}]
AC analysis bandwidth.  (Default = infinity.)  The transfer function
is frequency dependent, with a 3 DB point at this frequency.  There is
frequency dependent phase shift ranging from 0 degrees at low
frequencies to 90 degrees at high frequencies.  The phase shift is 45
degrees at the specified frequency.  AC ANALYSIS ONLY.

\item[{\tt Delay} = {\it x}]
AC analysis delay.  (Default = 0.) The signal is delayed by x seconds,
effectively by a frequency dependent phase shift.  AC ANALYSIS ONLY.

\item[{\tt Phase} = {\it x}]
AC analysis phase.  (Default = 0.)  A fixed phase shift is applied.
This is primarily intended for sources, but applies to all elements.
AC ANALYSIS ONLY.

\item[{\tt IOffset} = {\it x}]
Input offset.  (Default = 0.)  A DC offset is added to the ``input''
of the element, before evaluating the function.

\item[{\tt OOffset} = {\it x}]
Output offset.  (Default = 0.)  A DC offset is added to the ``output''
of the element, after evaluating the function.

\item[{\tt Scale} = {\it x}]
Transfer function scale factor.  (Default = 1.)  The transfer function
is multiplied by a constant.

\item[{\tt TNOM} = {\it x}]
Nominal temperature.  (Default = .option TNOM) The nominal values
apply at this temperature.

\item[{\tt TEMP} = {\it x}]
Actual temperature.  (Default = current global simulation temperature)
This is the actual device temperature.

\item[{\tt DTEMP} = {\it x}]
Temperature rise over ambient.  (Default = 0.)  The actual device
temperature is the global simulation temperature plus {\tt dtemp}.

\item[{\tt TC1} = {\it x}]
First order temperature coefficient.  (Default = 0.)

\item[{\tt TC2} = {\it x}]
Second order temperature coefficient.  (Default = 0.)

\item[{\tt IC} = {\it x}]
Initial condition.  An initial value, to force at time=0.  The actual
parameter applied depends on the component.  (Capacitor voltage,
inductor current.  All others ignore it.)  You must use the ``UIC''
option for it to be used.

\end{description}

Temperature adjustments and scaling use the following formula:
\begin{verbatim}
value *= _scale * (1 + _tc1*tempdiff 
              + _tc2*tempdiff*tempdiff)
\end{verbatim}
where {\tt tempdiff} is {\tt t - \_tnom}.

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