%\documentclass [dvipdfm,12pt,cite]{isscc_sub}
%\documentclass [dvips,12pt,cite]{isscc_sub}
\documentclass [dvips,12pt,cite]{article}
\addtolength{\topmargin}{-.5in}  % repairing LaTeX's huge margins...
\addtolength{\textwidth}{1.1in}  % same here....
\addtolength{\oddsidemargin}{-.3in}
\addtolength{\evensidemargin}{-1in}
\setlength{\textheight}{9.5in}  % more margin hacking.  I have a large
                                % resume to fit on one page.
\renewcommand{\baselinestretch}[0]{1.3}   
\renewcommand{\textfraction}[0]{0.0}
\renewcommand{\topfraction}[0]{1.0}
\renewcommand{\bottomfraction}[0]{1.0}
\newcommand{\be}{\begin{equation}}
\newcommand{\ee}{\end{equation}}
\newcommand{\bi}{\begin{itemize}}
\newcommand{\ei}{\end{itemize}}
\newcommand{\bc}{\begin{center}}
\newcommand{\ec}{\end{center} \vspace{.2in}}
\newcommand{\bt}{\vspace{-.1in} \begin{tabbing} alter \= set \= set \= \kill}
\newcommand{\et}{\end{tabbing} \vspace{-.06in}}

\def \sd{$\Sigma$-$\Delta$ }

%\pagestyle{empty}

%\usepackage{endfloat}
%\usepackage{pslatex}
\usepackage{sdwfig}
\usepackage{lgrind}

\setcounter{secnumdepth}{1} % no subsubsection numbering
\setcounter{tocdepth}{1} % no subsubsections in table of contents
\begin{document}


\title{HSPICE Toolbox for Matlab and Octave \\(also for use with Ngspice)}
\author{Michael H. Perrott \\ http://www.cppsim.com/download\_hspice\_tools.html
\\ Copyright 1999 by Silicon Laboratories, Inc.}
\date{29 July 2011}
\maketitle

\vspace{-.3in}
\begin{center}
Note:  This software is distributed under the terms of the 
\\    GNU Public License (see the included COPYING file for more details), 
\\    and comes with no warranty or support.
\end{center}

The Hspice toolbox for Matlab and Octave is a collection of routines
that allow you to manipulate and view signals generated by Hspice or
Ngspice simulations within either the Matlab or Octave programs.  The
primary routine is a mex program called \verb|loadsig| that reads
binary output files of transient, DC, or AC sweep data generated by
Hspice or Ngspice into Matlab or Octave.  The remaining routines are
used to extract particular signals and view them.  For simplicity, we
will focus on Matlab in the remainder of this document, but the
instructions for use with Octave are identical.

We will begin this document by explaining how to include the Hspice
toolbox in your Matlab session. A list of each of
the current functions will then be presented.  Finally,
we will provide examples of
using these routines to view and postprocess signals from Hspice output files.

\section*{Setup}

To use the Hspice toolbox, simply place the included files
into a directory of your choice, and then add that directory to
your Matlab path.  For example, inclusion of the path
'/home/user/matlab/bin' in  Matlab can be done
by adding the line 
\[
\verb|addpath('/home/user/matlab/bin')|
\]
to the file \verb|startup.m| located in your home directory.
In addition, you can specify the plot background to be black
by adding another line to startup.m:
\[
\verb|colordef none;|
\]

Once you've made the above changes to \verb|startup.m|, start Matlab
as you normally would.  Matlab will automatically read \verb|startup.m|
from your home directory and execute its commands. 

\section*{Platform Compatibility}

All files should work across different computer platforms, though
the \verb|loadsig| mexfile should generally be recompiled.  It is 
currently compiled for 64-bit Redhat Linux and 64-bit Windows 7 machines.  
To compile the \verb|loadsig| function for a different
platform, go to the directory
containing loadsig.c within Matlab, and then type \verb|mex loadsig.c|
within Matlab.  Note that you can also compile \verb|loadsig| in Octave in the exact same manner since the \verb|loadsig.c| source code is compatible with both Matlab and Octave.

\section*{List of Functions}

The following functions are currently included in the Hspice toolbox:
\bi
\item \verb|x = loadsig('hspice_output_filename');|
  \bi
    \item Returns a Matlab structure into variable \verb|x| 
          that includes all of the signals that
          are present in the Hspice binary output file,
          \verb|hspice_output_filename|.
  \ei
\item \verb|lssig(x)|
  \bi
    \item Lists all of the Hspice signal names present in the
          structure \verb|x|.
  \ei
\item \verb|y = evalsig(x,'nodename');|
  \bi
    \item Pulls out the signal nodename from the structure \verb|x| and
          places into variable \verb|y|.  The string nodename
          can be an expression involving several Hspice signals.
          If you only performed one sweep
         in the simulation (as is common), then \verb|y| will contain one
          column.  If you performed several sweeps, \verb|y| will contain
          several columns that correspond to the data for each sweep.
          If you have set the global Matlab variable \verb|sweep| to a nonzero
          number, however, then
          \verb|y| will contain only one column corresponding to the
          value of \verb|sweep|. If \verb|sweep| equals zero,
          all the sweep columns are included in \verb|y|.
  \ei
\item \verb|plotsig(x,'plot_expression','optional_plotspec')|
  \bi
    \item Plots signals from the structure \verb|x|
           according to the expression given in \verb|plot_expression|.
          The string \verb|optional_plotspec| is used to create logscale
          plots; it can be specified as
          \verb|logx|, \verb|logy|, or \verb|logxy|. The string \verb|plot_expression| specifies
           the nodenames, and corresponding mathematical operations,
           that you would like to view.  In this expression, commas
           delimit curves to be overlayed and semicolons delimit
          separate subplots on the same figure.  All numeric node names
           should be prepended by '@' to distinguish them from constants.
          Some examples of using plotsig are:
      \bi
         \item \verb|plotsig(x,'v1,v2;v3')|:  overlays v1 and v2 on the
               same subplot, and plots v3 on a separate subplot.
         \item \verb|plotsig(x,'(v1+v2)^2; log(abs(v3))')|: plots the
               listed expressions on separate subplots.
         \item \verb|plotsig(x,'db(v1); ph(v1)','logx')|: plots the
               magnitude (in dB) and phase (in degrees) of v1
               on a semilogx axis.
         \item \verb|plotsig(x,'v1+@2+3')|:  plots the addition of
               node v1, node 2, and the constant 3.
         \item \verb|plotsig(x,'integ(TIME,v1); avg(TIME,v2)')|: plots
              the integral of v1 and average of v2 on separate subplots.
      \ei
  \ei
\item \verb|tzoom|
  \bi
   \item Brings up buttons on the plot to allow nice zooming functions.
        Type \verb|help tzoom| at the Matlab prompt for more info.
  \ei
\item \verb|figname|
  \bi
   \item Allows easy labeling of figure windows.  Type \verb|help figname|
      at the Matlab prompt for more info.
  \ei
\item \verb|xlima|
   \bi
   \item Sets the x-limits of all subplots in a figure.  Three
        options are possible:
       \bi
         \item \verb|xlima|:  sets all subplots to the same x-axis as the
               last subplot that was zoomed into,
         \item \verb|xlima([xs xe])|:  sets all subplots to the x-axis
              limits specified,
         \item \verb|xlima('auto')|:  resets all subplots back to autoscaling.
       \ei
   \ei
\item \verb|eyesig(x,period,start_off,'nodename')|
   \bi
   \item Creates an eye diagram for nodename contained in \verb|x| with
         the specified \verb|period|.
          All data samples prior to \verb|start_off|
         are ignored when creating the diagram (useful for removing
         the influence of transient effects from the eye diagram).
         The string \verb|nodename| can be an expression involving several
         variables for the CppSim version (\verb|eyesig|), but assumes
         a constant time step (which is invalid for Hspice simulations).
         NOTE: use instead \verb|eyesig_old| for Hspice simulations ---
         this version can only handle one variable
         and is more primitive than its CppSim counterpart, but does
          take into account
         the non-constant time step of Hspice simulations.
   \ei
\ei

\section*{Examples}

\subsection*{Viewing Signals Generated by Hspice}

  Use the Matlab command \verb|cd| to go to a directory containing
       either transient, DC, or AC sweep data within a binary file
       generated from Hspice.  We will assume a filename of
       \verb|test.tr0|, and now list a series of Matlab commands that
       will be used to display nodes \verb|q| and \verb|qb| in that
       file.
\begin{itemize}
  \item \verb|x = loadsig('test.tr0');  %% loads Hspice signals into x|
  \item \verb|lssig(x)  %% verify that nodes q and qb are present|
  \item \verb|plotsig(x,'q; qb; q-qb')  %% plot expressions of interest|
\end{itemize}

\subsection*{Viewing Signals Generated by Ngspice}

  Use the Matlab command \verb|cd| to go to a directory containing
       either transient, DC, or AC sweep data within a binary file
       generated from Ngspice.  We will assume a filename of
       \verb|simrun.raw|, and now list a series of Matlab commands
       that will be used to display nodes \verb|q| and \verb|qb| in
       that file.
\begin{itemize}
  \item \verb|x = loadsig('simrun.raw');  %% loads Ngspice signals into x|
  \item \verb|lssig(x)  %% verify that nodes q and qb are present|
  \item \verb|plotsig(x,'q; qb; q-qb')  %% plot expressions of interest|
\end{itemize}

\subsection*{Doing Postprocessing in Matlab}

  Use the Matlab command \verb|cd| to go to a directory containing a
       binary transient, DC, or AC sweep file generated from Hspice.
       We will assume a filename of \verb|test.tr0|, and now list
       a series of Matlab commands that will be used to postprocess
       nodes \verb|q| and \verb|qb| in that file.
\begin{itemize}
  \item \verb|x = loadsig('test.tr0');  %% loads Hspice signals into x|
  \item \verb|lssig(x)  %% verify that nodes q and qb are present|
  \item \verb|t = evalsig(x,'TIME'); %% loads time samples into Matlab variable t|
  \item \verb|q = evalsig(x,'q'); %% loads signal q into Matlab variable q|
  \item \verb|qb = evalsig(x,'qb'); %% loads signal qb into Matlab variable qb|
  \item \verb|qdiff = q-qb;  %% perform expressions in Matlab|
  \item \verb|plot(t,q,t,qb,t,qdiff) %% plot variables using Matlab plot command|
\end{itemize}

\end{document}
