%$Id: start.tex,v 25.95 2006/08/26 01:26:53 al Exp $ -*- LaTeX -*-
% man start .
% 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.
%------------------------------------------------------------------------
\chapter{Introduction}
%HEVEA\cutdef[0]{section}
%------------------------------------------------------------------------
\section{What is it?}

Gnucap is a general purpose mixed analog and digital circuit simulator.
It performs nonlinear dc and transient analyses, fourier analysis, and
ac analysis linearized at an operating point.  It is fully interactive
and command driven.  It can also be run in batch mode.  The output is
produced as it simulates.  Spice compatible models for the MOSFET
(levels 1-7) and diode are included in this release.

Since it is fully interactive, it is possible to make changes and re-simulate
quickly.  This makes Gnucap ideal for experimenting with circuits as you might
do in an iterative design or testing design principles as you might do in a
course on circuits.

In batch mode it is mostly Spice compatible, so it is often possible to use
the same file for both Gnucap and Spice.

The analog simulation is based on traditional nodal analysis with iteration
by Newton's method and LU decomposition.  An event queue and incremental
matrix update speed up the solution considerably for large circuits and
provide some of the benefits of relaxation methods but without the drawbacks.

It also has digital devices for true mixed mode simulation.  The digital
devices may be implemented as either analog subcircuits or as true digital
models.  The simulator will automatically determine which to use.  Networks
of digital devices are simulated as digital, with no conversions to analog
between gates.  This results in digital circuits being simulated faster than
on a typical analog simulator, even with behavioral models.

Gnucap also has a simple behavioral modeling language that allows simple
behavioral descriptions of most components including capacitors and
inductors.

Gnucap is an ongoing research project.  It is being released in a preliminary
phase in hopes that it will be useful and that others will use it as a
thrust or base for their research.
%------------------------------------------------------------------------
\section{Starting}
\index{starting}

To run this program interactively, type and enter the command: {\tt
gnucap}, from the command shell.

The prompt {\tt gnucap>} shows that the program is in the command mode.  You
should enter a command.  Normally, the first command will be to {\tt build} a
circuit, or to {\tt get} one from the disk.  First time users should turn to
the tutorial section for further assistance. 

To run in batch mode, use {\tt gnucap -b {\em file}}.  It will run that
file then exit.

To load a file on starting, use {\tt gnucap {\em file}}.  This is
equivalent to starting with no arguments, then using the {\tt get}
command to load a file.
%------------------------------------------------------------------------
\section{How to use this manual}

The best approach is to read this chapter, then read the command summary at
the beginning of chapter 2, then run the examples in the tutorial section.
Later, when you want to use the advanced features, go back for more detail.

This manual is designed as a reference for users who are familiar with
circuit design, and therefore does not present information on circuit design
but only on the use of this program to analyze such a design.  Likewise, it
is not a text in modeling, although the models section does touch on it.

Throughout this manual, the following notation conventions are used:
\index{notation}
\index{syntax}

\begin{itemize}
\index{typewriter font}
\item {\tt Typewriter} font represents exactly what you type, or computer
output.

\item {\tt \underline{Underlined typewriter}} font is what you type, in a
dialogue with the computer.

\index{upper case}
\index{lower case}
\index{short commands}
\item Command words are shown in mixed UPPER and lower case.  The upper case
part must be entered exactly.  The lower case part is optional, but if
included must be spelled correctly.

\index{italics}
\item {\it Italics} indicate that you should substitute the appropriate name
or value.

\index{braces}
\item Braces  \{ \}  indicate optional parameters.

\item Ellipses (...) indicate that an entry may be repeated as many times as
needed or desired.

\end{itemize}
%------------------------------------------------------------------------
\section{Command structure}
\index{command structure}

Commands are whole words, but usually you only have to type enough of the
word to make it unique.  The first three letters will almost always work.
In some cases less will do.  The whole word is significant, if used, and
must be spelled correctly.
\index{short commands}
\index{abbreviations}

In files, commands must be prefixed with a dot (.).  This is done for
compatibility with other simulation programs, such as SPICE.

Command options should be separated by commas or spaces.  In some cases, the
commas or spaces are not necessary, but it is good practice to use them.

Upper and lower case are usually the same.
\index{upper case}
\index{lower case}
\index{case}

Usually options can be entered in any order.  The exceptions to this are
numeric parameters, where the order determines their meaning, and
command-like parameters, where they are executed in order.  If parameters
conflict, the last takes precedence.
\index{order: command}

In general, standard numeric parameters, such as sweep limits, must be
entered first, before any options.

Any line starting with {\tt *} is considered a comment line, and is
ignored.  Anything on any line following a quote is ignored.  This is mainly
intended for files.
\index{comment lines}

This program supports abbreviated notation for floating point numeric
entries.  `K' means kilo, or `e3', etc.  `M' and `m' mean milli, not mega
(for Spice compatibility).  `Meg' means mega.  Of course, it will also take
the standard scientific notation.  Letters following values, without spaces,
are ignored.
\index{abbreviated notation}

\begin{verse}
T = Tera = e12\\
G = Giga = e9\\
Meg = Mega = e6\\
K = Kilo = e3\\
m = milli = e-3\\
u = micro = e-6\\
n = nano = e-9\\
p = pico = e-12\\
f = femto = e-15
\end{verse}
%------------------------------------------------------------------------
\section{Standard options}
\index{standard options}

There are several options that are used in many commands that have a
consistent meaning.

\begin{description}

\index{quiet option}
\item[{\tt Quiet}] Suppress all unnecessary output, such as intermediate
results, disk reads, activity indicators.

\index{echo option}
\item[{\tt Echo}] Echo all disk reads to the console, as read from the disk.

\index{basic option}
\index{scientific notation}
\item[{\tt Basic}] Format the output for compatibility with other software
with primitive input parsers, such as C's {\em scanf} and Basic's {\em
input} statements.  It forces exponential notation, instead of our
standard abbreviated notation.  Any numbers that would ordinarily be
printed without an exponent are not changed.  It is the default when
the output of a command is directed to a file.

\index{pack option}
\item[{\tt Pack}] Remove extra spaces from the output to save space at the 
expense of readability.

\index{input file}
\index{< option}
\item[{\tt <}] Take the input from a file.  The file name follows in the
same line.

\index{disk file}
\index{output file}
\index{file option}
\index{> option}
\item[{\tt >}] Direct the output to a file.  The file name follows.  If the
file already exists, it will ask permission to delete the old one and
replace it with a new one with the same name.

\item[{\tt >>}] Direct the output to a file.  If the file already exists,
the new data is appended to it.

\item[{\tt |}] Pipe the output to a program.

\end{description}
%------------------------------------------------------------------------
\section{Getting help, and the Gnucap user community}
\index{problems}
\index{bugs}

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.

Probably the best source of current information is the web site: {\tt
http://www.gnu.org/software/gnucap}.  Here, you will find information
on the latest developments, including other work related to gnucap,
but not strictly part of it.

There are four mailing lists of interest to Gnucap users.
\begin{description}

\item[bug-gnucap@gnu.org]
This list is for bug reports and discussion about bugs in gnucap.

\item[help-gnucap@gnu.org]
This is a general user discussion list for gnucap. Discussions about
the use of gnucap, and sharing of ideas, models, and libraries, are
all welcome here.  Technical discussions should be light weight and
user oriented.

\item[info-gnucap@gnu.org]
This list is for announcements about gnucap. It is a moderated
list. All postings come from the administrator.

\item[gnucap-devel@gnu.org]
This list is for technical discussions relating to the development of
gnucap.  Technical discussions about simulator algorithms, modeling,
and interfacing are all welcome here.

\end{description}

The web site contains the archives of these lists, and allows you to
sign up for them.
%------------------------------------------------------------------------
\section{How to contribute}

There are a number of ways that you can contribute to help make Gnucap
a better system. Perhaps the most important way to contribute is to
write high-quality code for solving new problems, and to make your
code freely available for others to use.

You can add significant value by developing models, even macro models,
that can be distributed. Converting Spice models, publicizing which
ones already work, or documenting any features that Gnucap needs to
make it work, are all valuable contributions.

If you find Gnucap useful, consider providing additional funding to
continue its development. Even a modest amount of additional funding
could make a significant difference in the amount of time that is
available for development and support.

If you cannot provide funding or contribute code, you can still help
make Gnucap better and more reliable by reporting any bugs you find
and by offering suggestions for ways to improve Gnucap.

If you are a teacher, you are making a significant contribution simply
by using free software in your courses, and showing the students that
they really do have a choice in software. You can further the
contribution by encouraging student software projects that can be
released as free software. You can also further the contribution by
writing texts that use free software in the coursework, providing an
alternative to those texts that promote closed source commercial
software.

If you are an academic researcher, you can contribute by releasing
your own software under GPL, and collaborating with others who do. You
can help by using only open standards and avoiding proprietary
languages such as the modeling languages of some proprietary
simulators.

If you are a commercial user, you can help by giving financial support
or equipment to the developers. Often, (as is the case with Gnucap),
the principal developers are in the academic community, so by
supporting free software, you are also supporting academic research
and providing financial support for students.
%------------------------------------------------------------------------
\section{Licensing}
\input{copying.tex}	
%HEVEA\cutend
%------------------------------------------------------------------------
%------------------------------------------------------------------------
