% start.tex  94.02.18
% man start .
% Copyright 1983-1992   Albert Davis
%------------------------------------------------------------------------
\chapter{Introduction}
%------------------------------------------------------------------------
\section{What is it?}

ACS 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 (level 1, 2, and 3)
and diode are included in this release.  Other models (BJT) are in the
testing phase.

Since it is fully interactive, it is possible to make changes and re-simulate
quickly.  This makes ACS 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 ACS 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.

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

ACS 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, type and enter the command: {\tt acs}, from the command
shell.

The prompt {\tt -->} 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 examples section for further assistance.  There is a {\tt help} command,
in case you get lost.

To run in batch mode, use {\tt acs {\em file}}.  This will run the {\em
file} in batch mode.  If it ends with an {\tt .end} command, it will exit
when done, otherwise it will revert to command mode.
%------------------------------------------------------------------------
\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.

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

\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}

\index{short commands}
\index{abbreviations}
 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.

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.

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

\index{order: command}
 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.

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

\index{comment lines}
 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{abbreviated notation}
 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.

\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}

Files are written in this same format.  To write a file with standard
scientific notation, append the word {\tt Basic} to the command.
%------------------------------------------------------------------------
\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.

\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.  

\end{description}
%------------------------------------------------------------------------
\section{In case of difficulty}
\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.

I do not promise any kind of support or assistance to users.  However, I
plan to continue to improve it and keep it reliable, so please send me any
complaints and suggestions you have.  I will probably fix anything that is
clearly (to me) a malfunction.  I may make an improvement if I consider it
worth the effort, but you should not be surprised if I don't think I can
spare time for it.  The direction for enhancements is primarily driven by
research interests and funding.  I may provide some assistance to academic
users at no charge.

The latest version of the program and libraries is available from
the bulletin board at (716)272-1645.  Login as "guest".  It is also
available by anonymous ftp from cs.rit.edu, in pub/acs.  The full
source for the latest version is available along with any new models
or hints that may be available.  There are also executables for
several platforms.

You should register by sending your email address to atd@cs.rit.edu
or davis@ee.rochester.edu.  You will be notified by email of any
updates to the program and possibly of what work is being done.

If you have problems, questions or comments send email to atd@cs.rit.edu
or davis@ee.rochester.edu.  You can send paper mail to: Albert
Davis, 136 Doncaster Road, Rochester, NY 14623, or FAX to (716)272-1645.
%------------------------------------------------------------------------
%------------------------------------------------------------------------
