%$Id: addmodel-compile.tex,v 25.95 2006/08/26 01:26:53 al Exp $ -*- LaTeX -*-
% man Tech addmodel-compile .
% 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{Using the model compiler}

This section is a first cut at documentation.  If you actually want to
install a model, please ask for more information.  Your questions will
help me write the more complete documentation.  (aldavis@ieee.org)

To create a model using this method, you create one file, with the
extension {\tt .model}.  A separate program, {\tt modelgen} processes
this file to generate the appropriate {\tt .cc} and {\tt .h} files.
The resulting files are equivalent to the subcircuit method of
creating models.

There are two primary sections, {\tt device} and {\tt model}.  Most
models have both, but a device can use several different {\tt model}s
as long as they are derived from a common base and designed to work
together.  It is standard practice to share like this.  For example,
all of the MOS models use the same {\tt device} section.

Any {\tt model} can inherit from another {\tt model}, thus reducing
the need for repetition when code or parameters are the same in
different models, and allowing several to use the same {\tt device}
section.

This model compiler has restrictions that will be removed in future
releases.  Not all device types can be fully done with it, due to
missing features.  Often, it is necessary to finish the job manually.
In this release (0.30), the diode fully uses it, but not the way I
want to.  The MOSFET uses the {\tt cc\_direct} to finish the job.  Two
functions {\tt do\_tr} and {\tt tr\_needs\_eval} must be provided this
way.  Code placed here is simply copied out.

As a general rule, when using the name = value form, the value is
delimited by whitespace, or possibly other tokens.  If you want blanks
in the value string, put it in quotes.  It is recommended to quote any
value string that is comprised of more than one word, even if there
are no blanks.
%------------------------------------------------------------------------
\subsection{Device section}

\begin{description}

\item[{\tt parse\_name}] (required)
This is the name of the device, to be recognized by the parser, in
Gnucap native format.  Example: {\tt diode}.

\item[{\tt id\_letter}] (required)
This is the letter used to identify the device, when the {\tt
parse\_name} is omitted (Spice format).  Example: {\tt D} identifies a
diode.

\item[{\tt model\_type}] (required)
This is the name of the model type associated with this device type.
It can be the name of the one matching type, or the name of a base
from which a family can be derived.

\item[{\tt circuit}] (required)
This is a subsection containing a netlist representing the internal
structure of the device.  See the section {\em circuit subsection} for
details.

\item[{\tt tr\_probe}] (optional)
This is a subsection containing a list of internal probes to be made
available to the user.  See the section {\em Tr\_probe subsection} for
details.

\item[{\tt device}] (required)
This is a subsection describing the non-shared data relating to the
device.  Information here is unique to this device.  It is primarily
state information.  See the section {\em Device subsection} for
details.

\item[{\tt common}] (optional)
This is a subsection describing the shared data relating to the device.
Information here may be shared between similar devices.  It is
primarily information that is read from the circuit description.  See
the section {\em Common subsection} for details.

\item[{\tt tr\_eval}] (optional)
This is a subsection which will eventually contain evaluation code for
the whole device.  For now, it is a stub, which is used as a flag.
See the section {\em Tr\_eval subsection} for details.  If this
subsection is omitted, it is considered to be a pure subcircuit.

\item[{\tt eval}] (optional)
There may be any number of {\tt eval} subsections, which are specific
evaluators for internal elements.  See the section {\em Evaluators}
for details.

\end{description}
% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
\subsubsection{Circuit subsection}

The circuit subsection has 5 parts, in order.

\begin{enumerate}

\item
The optional keyword ``{\tt sync}'' says that the entire subcircuit
representing the device must be evaluated synchronously.  Without this
keyword, it is treated as a subcircuit made of independent elements.

\item
The port list ``{\tt ports}'', which is a list of the nodes
interfacing to the outside.

\item
A list of local internal nodes, not visible outside.

Each local node may have two optional attributes:

\begin{description}

\item[{\tt short\_if}]
This specifies a conditional which if true will result in this node
being omitted.

\item[{\tt short\_to}]
This specifies another node which will be substituted for this node if
the {\tt short\_if} condition is true.

\end{description}

\item
Any number of named and typed {\tt args} sections.  Each section
contains name = value pairs which assign values to elements in the
subcircuit.  It is used only for more complex elements like diodes.

\item
A list of circuit elements that comprise the model.  Each has three
required fields, then a list of optional key = value pairs.

The required fields, in order, are:

\begin{itemize}

\item
The type of element.  This is usually one of resistance, capacitance,
admittance, or poly\_g, but can be any device type, including those
created by modelgen.

\item
The label, a string used to refer to it.

\item
A node list, in curly braces.

\end{itemize}

After that, optional fields are used to assign attributes.  Not all
are legal or appropriate with all element types.

\begin{description}

\item[{\tt value}]
This must evaluate to a constant, which is interpreted as the nominal
value of the element.

\item[{\tt eval}]
This is the name of an {\tt eval} section, which specifies nonlinear,
and depenndent characteristics.

\item[{\tt args}]
This refers to an {\tt args} section, described previously.  It is
used only for advanced element types, as those created by modelgen.

\item[{\tt reverse}]
This specifies an expression, that when evaluated will tell whether to
reverse the element.  If it evaluates to true, the node pairs are
interchanged.  If there are two nodes, they are interchanged.  If
there are four, the first pair are interchanged and the second pair
are interchanges.  The pattern repeats for as many nodes as there are.
This is used with diodes, which may be reversed depending on whether
the device being defined is N-type or P-type.

\item[{\tt omit}]
This specifies an expression, that when evaluated will tell whether to
omit the element.  If it evaluates to true, the element is omitted.

\item[{\tt state}]
This specifies a the name of a device state variable that is applied
to this element.  This state variable must be one of those defined
under {\tt calculated parameters}.  It is primarily intended for the
{\tt poly\_g} and {\tt poly\_cap} element types.  In the {\tt calculated
parameters} section, the following parameters are its derivatives.  If
the poly element has N node pairs, the following N parameters are the
derivatives, with respect to each voltage, in order.

\end{description}

\end{enumerate}
% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
\subsubsection{Tr\_probe subsection}

The {\tt tr\_probe} subsection is where you list the probes for
transient and DC analysis.  It is a list of name = value pairs, where
the value is an expression that calculates or looks up the value.

You can reference any device parameter directly, or others with the
appropriate struct prefixing.

You can reference probes on internal elements with the syntax ``{\tt
@}'', followed by the element label, followed by the probe name in
square brackets.  For example, ``{\tt @Cj[Capacitance]}'' refers to
the probe named ``Capacitance'' on the element ``Cj''.  It is your
responsibility to see that the element actually exists, and that it
has a probe with that name.

You can reference node voltages with the same syntax, but the
``device'' name is formed by prefixing the node name with ``{\tt
n\_}''.

You can also call functions, and make arbitrary expressions.  In
general, the code is just copied over, with the exception of the
probes, which are modified to the internal format.

The probe name in the generated model will be non-case-sensitive.  To
the model compiler, upper case letters must match exactly, and lower
case letters are optional.  For example, ``{\tt CGSOvl}'' in the model
file can be referred to as {\tt cgso}, {\tt cgsov}, or {\tt cgsovl},
or any variants differing only in case.
% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
\subsubsection{Device subsection}

This subsection defines information that is not shared between
instances.  In general, that which must be maintained as different,
even though devices are identical, is placed here.

\paragraph{Calculated\_parameters subsubsection}

This subsubsection lists all of the ``calculated parameters''.  In
this case, it means that which is calculated during simulation, the
state information.

The format for each item is: type, name, comment, attributes, semicolon.

The only attribute appropriate is ``{\tt default}'', which is the
default value set by the constructor.
% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
\subsubsection{Common subsection}

This section defines information that the simulator may share between
instances.  Most parameters specified by the user are placed here,
allowing the simulator to share data for identical devices.

\paragraph{Unnamed subsubsection}

You can designate one of the {\tt raw\_parameters} to be the
``value''.  When a number is given without a name, it is assigned to
this one.

\paragraph{Raw\_parameters subsubsection}

This subsubsection lists all of the ``raw parameters'', the parameters
supplied by the user on the instance line.  The format and available
attributes are described in the ``Parameter lists'' section, which
follows.

\paragraph{Calculated\_parameters subsubsection}

This subsubsection lists all of the ``calculated parameters'', the
parameters not supplied by the user on the instance line.  Instead,
the are calculated based on other input.  The format and available
attributes are described in the ``Parameter lists'' section, which
follows.
% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
\subsubsection{Tr\_eval subsection}

In this release, this section is a dummy.  Put a stub here if you
define a {\tt do\_tr} later.  Otherwise leave it out.  This will change
in a future release.
% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
\subsubsection{Evaluators}

The {\tt eval} sections are evaluators that turn the primitive
resistors and capacitors into advanced behavioral elements.

The body is the core of a C++ function, which is copied over directly
after attaching some headers.  Given some ``x'', this function
computes ``f(x)'' and its derivative with respect to x.  The primary
communication is through the structure ``{\tt d->\_y0}''.  The input is
``{\tt d->\_y0.x}''.  You must evaluate the function, and place the
result in ``{\tt d->\_y0.f0}'' and its derivative in ``{\tt
d->\_y0.f1}''.  The exact meaning of these values depends on what type
of element it is.

For the primitives ...

\begin{description}

\item[resistance]
x is current, y0 is voltage, y1 is resistance

\item[admittance]
x is voltage, y0 is current, y1 is admittance

\item[capacitance]
x is voltage, y0 is charge, y1 is capacitance

\item[inductance]
x is current, y0 is flux, y1 is inductance

\item[vccs]
x is voltage, y0 is current, y1 is transconductance

\end{description}

In addition, all relevant parameters are available with the
appropriate prefix.  See the section {\em accessing data in code
blocks}.  Most are read-only.

The prefix {\tt d->} refers to the element being processed.  This data
is read-write.
%------------------------------------------------------------------------
\subsection{Model section}

\begin{description}

\item[{\tt base}] (optional)
The keyword {\tt BASE} is used as a flag to say this is a base for
other models.  When the base flag is set, others can be derived from
it and used interchangeably with the same device type.

\item[{\tt dev\_type}] (required, all)
This is the name of the device type associated with this model type.

\item[{\tt level}] (optional, final only)
When several models are derived from a base, the numeric level is used
as a parameter to select which one to use.

\item[{\tt inherit}] (optional)
The model being defined inherits from the named base model.  There is
no limit to the depth if inheritance.

\item[{\tt keys}] (required for base, optional otherwise)
This is a list of the keywords that are used to identify the model,
and assign attributes.  See the section {\em Keys subsection} for
details.

\item[{\tt independent}] (optional)
This is a section describing parameters that are not dependent on size
or temperature.  See the section {\em Independent subsection} for
details.

\item[{\tt size\_dependent}] (optional)
This is a section describing parameters that are dependent on size.
See the section {\em Size\_dependent subsection} for details.

\item[{\tt temperature\_dependent}] (optional)
This is a section describing parameters that are dependent on
temperature.  See the section {\em Temperature\_dependent subsection}
for details.

\item[{\tt tr\_eval}] (required once in hierarchy)
This is a section containing evaluation code for the whole device.
See the section {\em Tr\_eval subsection} for details.

\end{description}
% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
\subsubsection{Keys subsection}

The {\tt keys} subsection consists of a number of keywords that are
used in the {\tt .model} statement to identify this model.  Different
keys can be used to represent variants, such as ``{\tt NMOS}'' and
``{\tt PMOS}'' to represent the N and P channel devices.  Each one is
followed by an assignment to be made when the key is present.

It is required, at least once in the hierarchy.  Additional keys can
be used to select a particular model, as an alternative to the {\tt
level} parameter.
% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
\subsubsection{Independent subsection}

The {\tt independent} subsection list all of the ``independent''
parameters supplied by the user in the {\tt .model} statement.

\paragraph{Raw\_parameters subsubsection}

This subsubsection lists all of the ``raw parameters'', the parameters
supplied by the user on the {\tt .model} line.  The format and
available attributes are described in the ``Parameter lists'' section,
which follows.

\paragraph{Calculated\_parameters subsubsection}

This subsubsection lists all of the ``calculated parameters'', the
parameters not supplied by the user.  Instead, they are calculated
based on other input.  The format and available attributes are
described in the ``Parameter lists'' section, which follows.

\paragraph{Override subsubsection}

This subsubsection lists parameters that have already been defined in
base classes, that need a change for this particular type.  You can
override most attributes, giving the benefit of defining it locally,
while retaining most from the base.  The format and available
attributes are described in the ``Parameter lists'' section, which
follows.

\paragraph{Code\_pre and Code\_post subsections}

These subsubsections define C++ code that is inserted into the
function that calculates values, scales, and checks limits.  The block
{\tt code\_pre} is inserted before the automatically generated code.
The block {\tt code\_post} is inserted after the automatically
generated code.
% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
\subsubsection{Size\_dependent subsection}

The {\tt size\_dependent} subsubsection is similar to the {\tt
independent} subsubsection except that it defines a base paramater and
scale factors so a custom value can be generated based on the device
size.

Every parameter in this subsubsection actually generates a set of
four.  The first is the base, as in the {\tt independent}
subsubsection.  In addition, the same name prefixed by ``{\tt L}'' is
the length dependency, the name prefixed by ``{\tt W}'' is the width
dependency, and the name prefixed by ``{\tt P}'' is the product
(length * width) dependency.

You must provide a {\tt code\_pre} section, which must declare and
define values for ``{\tt L}'' (length) and ``{\tt W}'' (width).

The actual value is calculated by: {\tt nom + ld/L + wd/W +
pd/(W*L);}, where {\tt nom} is the nominal value, {\tt ld} is the
length dependency (key name has the ``{\tt L}'' prefix), {\tt wd} is
the width dependency (key name has the ``{\tt W}'' prefix), and {\tt
pd} is the product dependency (key name has the ``{\tt P}'' prefix).
% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
\subsubsection{Temperature\_dependent subsection}

The {\tt temperature\_dependent} subsubsection contains a list of
parameters that are calculated based on temperature, and two code
blocks ({\tt code\_pre} and {\tt code\_post} to make the calculations.

This code is evaluated at run time, possibly every time step, whenever
temperature changes.  Some Spice models throw calculations not related
to temperature into the temperature block.  This is very bad practice.
In Gnucap, temperature is local and time variant.
% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
\subsubsection{Tr\_eval subsection}

The {\tt tr\_eval} subsubsection is the actual model evaluation code
for nonlinear DC and transient analysis.  This code must calculate all
state variables (data listed as ``{\tt calculated}'' in the {\tt
device} section, except those that are part of one of the subcircuit
elements.  Inputs and outputs are through the {\tt d->} structure.

This function only needs to fill in the {\tt calculated} data.  The
details, like differentiating charge in capacitors, is left to the
subcircuit elements.  It is also not necessary to check convergence.
This, too, is left to the subcircuit elements.
% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
\subsection{Accessing data in code blocks}

Most parameters are available, usually read-only, in any code block,
with the appropriate prefix:

\begin{description}

\item[{\tt p->}]
The parent device, usually the device being defined by the {\tt
.model} file.  This is usually the ``calculated parameters'' under
``device'' in the {\tt .model} file.

\item[{\tt c->}]
The ``common'' belonging to the parent device.  This consists of all
of the parameters in the {\tt common} section of the {\tt .model}
file.

\item[{\tt m->}]
This is the ``model'' parameters, all of the parameters in the {\tt
model} section of the {\tt .model} file, except those listed as ``size
dependent''.

\item[{\tt b->}]
This is the sized value of the size dependent parameters in the {\tt
model} section.  ``B'' is for ``bin'', which is derived from the
concept of ``binning'' of models.

\item[{\tt d->}]
This is the device parameters.  In evaluation functions, it is
read-write.

\item[{\tt t.}]
This is the device values, scaled by temperature.

\end{description}

% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
\subsection{Parameter lists}

The format for each item is: type, name, comment, attributes, semicolon.

The available attributes are:

\begin{description}

\item[{\tt name}]
This is the name to be used for input in the data file.  It is also
the name this parameter is listed as when the internal data is
printed.

\item[{\tt alt\_name}]
This is an alternate name used for input.

\item[{\tt default}]
This is the initial default value, set by the constructor.

\item[{\tt calculate}]
If no value is supplied, the program will calculate it using this
formula.

\item[{\tt quiet\_min}]
If the input or calculated value is less than this number, substitute
this number without warning.

\item[{\tt quiet\_max}]
If the input or calculated value is more than this number, substitute
this number without warning.

\item[{\tt final\_default}]
This is the final default value, supplied after all attempts to fill
or calculate it fail.

\item[{\tt offset}]
Add this number to the input value to get the value actually stored in
memory.  Example: {\tt double temperature ``'' offset=273;}.  This
sample allows data entry in degrees Celsius, but storage in Kelvin.

\item[{\tt scale}]
Multiply the input value by this number to get the value actually
stored in memory.  Example: {\tt double length ``'' scale=1e6;}.
This sample allows data entry in microns, but storage in meters.

\item[{\tt positive}]
This number is always positive.  The magnitude of the entered value is
stored.

\item[{\tt octal}]
The number read is interpreted as octal (base 8), instead of the usual
base 10.

\item[{\tt print\_test}]
This is a test to determine whether the value is printed in a standard
listing or not.  The value is printed only if this test evaluates to
true at run time.  If {\tt print\_test} is omitted, it is always
printed.

\item[{\tt calc\_print\_test}]
This is a test to determine whether the value is printed as a comment
in a standard listing or not.  The value is printed only if this test
evaluates to true at run time.  If {\tt calc\_print\_test} is omitted,
it is never printed.

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