%$Id: print.tex,v 25.95 2006/08/26 01:26:53 al Exp $ -*- LaTeX -*-
% man commands print .
% 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 PRINT} command}
\index{print command}
\index{probe command}
\index{output selection}
\index{selection of output}
\index{nodes: output selection}
%------------------------------------------------------------------------
\subsection{Syntax}
\begin{verse}
{\tt print}\\
{\tt print} {\it mode points ...} ...\\
{\tt print} {\it mode + points ...} ...\\
{\tt print} {\it mode - points ...} ...\\
{\tt print} {\it mode} {\tt CLEAR}
\end{verse}
%------------------------------------------------------------------------
\subsection{Purpose}

Select points in the circuit for tabular output.  Select tabular output.
%------------------------------------------------------------------------
\subsection{Comments}

The `{\tt print}' command selects where to look at the circuit, or where to
hook the voltmeter (ammeter, watt meter, ohm meter, etc.) probe.

There are separate lists of probe points for each type of analysis.

To list the probe points, use the bare command `{\tt print}'.

On start-up, probes are not set.  You must do the command `{\tt print op
v(nodes)}' or put `{\tt .print op v(nodes)}' in the circuit file to get any
output from the {\tt op} command.

Syntax for each point is {\it parameter(node)}, {\it
parameter(componentlabel)}, or {\it parameter(index)}.  Some require a
dummy index.

You can access components in subcircuits by connecting the names with dots.
For example: {\tt R56.X67.Xone} is {\tt R56} in {\tt X67} in {\tt Xone}.
Some built-in elements, including diodes, transistors, and mosfets, contain
subcircuits with internal elements.  {\tt Cgd.M12} is the gate to drain
capacitor of mosfet {\tt M12}.

If the component does not exist, you will get an error message.  If the
component exists but the parameter is not valid for that type, there will be
no error message but the value printed will be obviously bogus.

The options {\tt plot} and {\tt noplot} on any analysis command turn
plotting on and off a single run.  The {\tt plot} command turns 
plotting on and tabular output off.  The {\tt print} command turns plotting 
off and tabular output on.

You can add to or delete from an existing list by prefixing with
{\tt +} or {\tt -}.  {\tt print ac + v(3)} adds v(3) to the existing
set of AC probes.  {\tt print ac - q(c5)} removes q(c5) from the
list.  You can use the wildcard characters {\tt *} and {\tt ?} when
deleting.

For AC analysis, by adding a suffix letter to the parameter, you can
get the magnitude {\tt M}, phase {\tt P}, real part {\tt R}, or
imaginary part {\tt I}.  Adding {\tt DB} gives the value in decibels,
relative to 1.  For example, {\tt VRDB(R13)} gives you the real part
of the voltage across R13, in decibels.
%------------------------------------------------------------------------
\subsection{Node probes}

Several parameters are available at each node.
%------------------------------------------------------------------------
\subsubsection{All modes}

\begin{description}

\item[{\tt v}] Voltage.

\end{description}
%------------------------------------------------------------------------
\subsubsection{All except Transient}

\begin{description}

\item[{\tt z}] Impedance looking into the node.

\end{description}
%------------------------------------------------------------------------
\subsubsection{Transient, DC, OP only}
\begin{description}

\item[{\tt logic}]
A numeric interpretation of the logic value at the node.  The value is
displayed encoded in a number of the form $a.bc$ where $a$ is the
logic state: $0 =$ logic $0$, $1 =$ rising, $2 =$ falling, $3 =$ logic
$1$.  $b$ is an indication of the quality of the digital signal.  $0$
is a fully valid logic signal.  Nonzero indicates it does not meet the
criteria for logic simulation.  $c$ indicates how the node was
calculated: $0$ indicates logic simulation.  $1$ indicates analog
simulation of a logic device.  $2$ indicates analog simulation of
analog devices.

\item[{\tt lastchange}]
The most recent time at which the logic state changed.

\item[{\tt finaltime}]
The scheduled time a pending logic state change will occur.

\end{description}
%------------------------------------------------------------------------
\subsubsection{AC only}

In addition to those listed here, you can add a suffix ({\tt M, P, R,
I} and {\tt db}) for magnitude, phase, real part, imaginary part, and
decibels, to any valid probe.

\begin{description}

\item[{\tt vi}] Imaginary part of the voltage.

\item[{\tt vdb}] Decibels relative to 1 v.

\item[{\tt zi}] Imaginary part of the impedance looking into the node.

\item[{\tt zp}] Impedance phase (angle between voltage and current).  

\end{description}
%------------------------------------------------------------------------
\subsection{Status probes}

There are several status variables that can be probed.
%------------------------------------------------------------------------
\subsubsection{All modes}

\begin{description}

\item[{\tt temperature(0)}] The simulation temperature in degrees Celsius.

\item[{\tt time(0)}] The current time in a transient analysis.  In AC
analysis it shows the time at which the bias point was set, 0 if it was set
in a DC or OP analysis, or -1 if it is the bias was not set (power off).

\end{description}
%------------------------------------------------------------------------
\subsubsection{Transient, DC, OP only}
\begin{description}

\item[{\tt generator}] The output of the ``signal generator''.  In a 
transient analysis, it shows the output of the signal generator, as set 
up by the {\tt generator} command.  In a DC analysis, it shows the DC
input voltage (not the power supply).  In an OP analysis, it shows the
DC input, normally zero.  

\index{iteration count}
\item[{\tt iter(0)}] The number of iterations needed for convergence for
this printed step including any hidden steps.

\item[{\tt iter(1)}] The number of iterations needed for convergence for
this printed step not including any hidden steps.

\item[{\tt iter(2)}] The total number of iterations needed since startup
including check passes.

\item[{\tt control(0)}] A number indicating why the simulator chose this
time to simulate at.
\begin{description}
\item{1} The user requested it.  One of the steps in a sweep.

\item{2} A scheduled discrete event.  An element required a solution
at this time.

\item{3} The effect of the ``{\tt skip}'' parameter.

\item{4} The iteration count exceeded {\tt ITL4} so the last step was
rejected and is being redone at a smaller time step.

\item{5} The iteration count exceeded {\tt ITL3} so the increase in
time step is limited.

\item{6} Determined by local truncation error or some other device 
dependent approximation in hopes of controlling accuracy.

\item{7} Determined by a movable analog event. An element required a
solution at this time.

\item{8} The step size was limited due to iteration count.

\item{9} This is an initial step.  The size was arbitrarily set to 1/100
of the user step size.

\item{10 + x} The previous step was rejected.

\item{20 + x} A zero time step was replaced by {\it mrt}.

\item{30 + x} The required step size less than {\it mrt}, so it was 
replaced by {\it mrt}.

\end{description}

\item[{\tt control(1)}] The number internal time steps.  (1 if all steps are
printed.  One more than the number of hidden steps.)

\end{description}
%------------------------------------------------------------------------
\subsection{Element probes}

Each element type has several parameters that can be probed.  In general,
the form is {\tt Parameter(element)}.  Wild cards are allowed in element
names to allow probing the same parameter of a group of elements.

For components in a subcircuit, the names are connected with dots.  For
example {\tt R12.X13} is {\tt R12} in the subcircuit {\tt X13}.

Most two node elements (capacitors, inductors, resistors, sources) and
four terminal elements (controlled sources) have at least the
following parameters available.  Others are available for some
elements.
%------------------------------------------------------------------------
\subsubsection{All modes}

\begin{description}

\item[{\tt v}] Branch voltage.  The first node in the net list is assumed
positive.  This is the same as ``output voltage''.

\item[{\tt vout}] Output voltage.  The voltage across the ``output''
terminals. 

\item[{\tt vin}] Input voltage.  The voltage across the ``input''
terminals.  For two terminal elements, input and output voltages are
the same.

\item[{\tt i}] Branch current.  It flows into the first node in the net
list, out of the second.

\item[{\tt p}] Branch power.  Positive power indicates dissipation. 
Negative power indicates that the part is supplying power.  Its value 
is the same as (PD - PS).  In AC analysis, it is the real part only.

\item[{\tt nv}] Nominal value.  In most cases, this is just the value
which is constant, but it can vary for internal elements of complex
devices. 

\item[{\tt ev}] The effective value of the part, in its units.  If the part
is ordinary, it will just show its value, but if it is time variant or
nonlinear, it shows what it is now.

\item[{\tt r}] Resistance.  The effective resistance of the part, in ohms.
In AC analysis, shows the magnitude of the self impedance.  In {\tt OP},
{\tt DC} or {\tt TRansient} analysis, shows its incremental resistance.  In
{\tt TRansient} analysis, it shows the effective Z-domain resistance of
inductors and capacitors.

\item[{\tt y}] Admittance.  $1/R$.

\end{description}
%------------------------------------------------------------------------
\subsubsection{All except Transient}

\begin{description}

\item[{\tt z}] Impedance at a port.  The port impedance seen looking
into the circuit across the branch.  It does not include the part
itself.  In transient analysis, it shows the effective Z-domain
impedance, which is a meaningless number if there are capacitors or
inductors in the circuit.

\item[{\tt zraw}] Impedance at a port, raw.  This is the same as ``Z'' 
except that it includes the part itself.

\end{description}
%------------------------------------------------------------------------
\subsubsection{Transient, DC, OP only}

These parameters are available in addition to the above.

\begin{description}

\item[{\tt pd}] Branch power dissipated.  The power dissipated in the 
part.  It is always positive and does not include power sourced.

\item[{\tt ps}] Branch power sourced.  The power sourced by the part.  
It is always positive and does not consider its own dissipation.

\item[{\tt f}] The result of evaluating the function related to the 
part.  It is the voltage across a resistor, the charge stored in a 
capacitor, the flux in an inductor, etc.

\item[{\tt input}] The ``input'' of the device.  It is the current
through a resistor or inductor, the voltage across a capacitor or
admittance, etc.  It is the value used to evaluate nonlinearities.

\item[{\tt ioffset}] The offset current in the device.  The current
through a nonlinear device can be considered to have two parts: a
passive part and an offset.

\item[{\tt ipassive}] The passive part of the current.

\end{description}
%------------------------------------------------------------------------
\subsubsection{AC only}

In addition to those listed here, you can add a suffix ({\tt M, P, R,
I} and {\tt DB}) for magnitude, phase, real part, imaginary part, and
decibels, to any valid probe.  Negative phase is capacitive.  Positive
phase is inductive.

\begin{description}

\item[{\tt pi}] Reactive (imaginary) power, volt-amps reactive.

\item[{\tt pidb}] Decibels relative to 1 va reactive.

\item[{\tt pm}] Volt amps, complex power.

\item[{\tt pmdb}] Decibels relative to 1 va.

\item[{\tt pp}] Power phase (angle between voltage and current).

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

\begin{description}

\item[{\tt print ac v(12) v(13) v(14)}] The voltage at nodes 12, 13, and 14
for AC analysis.

\item[{\tt print dc v(r26)}] The voltage across {\tt R26}, for DC analysis.

\item[{\tt print tran v(r83) p(r83)}] Voltage and power of {\tt R83}, for
transient analysis.

\item[{\tt print dc i(c8) p(r5) z(r5)}] The current through {\tt C8}, power
dissipated in {\tt R5}, and the impedance seen looking into the circuit
across {\tt R5}.

\item[{\tt print op v(nodes)}] The voltage at all nodes for the {\tt op}
command.

\item[{\tt print}] List all the probes, for all modes.

\item[{\tt print op}] Display the {\tt OP} probe list.

\item[{\tt print ac clear}] Clear the AC list.

\end{description}
%------------------------------------------------------------------------
%------------------------------------------------------------------------
