bta,bta,bta,bta,bta,bta,bta,bta,bta,bta,bta,bta,bta,bta,bta,bta,bta
--------------------------------------------------------
Manual for S-Spice 1.0b (the help file doesn't work yet)
11/04/96
LVCAUWEN@EDUSERV.RUG.AC.BE
--------------------------------------------------------

Index : 1.Disclaimer
        2.Provided Examples
        3.Quick start
        4.Settings
        5.Creating your own components
        6.Limitation, errors and bugs
        7.Other important information

1.Disclaimer
============
   Users of S-Spice must accept this disclaimer of warranty: 

   "S-Spice is supplied as is.  The author disclaims all warranties,
   expressed or implied, including, without limitation, any
   warranties of merchantability and/or fitness for any purpose. The
   author assumes no liability for damages, direct or consequential,
   which may result from the use of S-Spice."  

   S-Spice 1.0b is a bta version and is provided at no charge to
   the user for evaluation.  Feel free to share it with your friends,
   but please do not give it away altered or as part of another
   system. The use of this bta version is limited in time.

   Anyone distributing S-Spice for any kind of remuneration must
   comply with the requirements set out in the file VENDOR.DOC
   accompanying this program.

   All the registered trademarks used in the S-Spice package are 
   registered to whoever it is that owns them. This notification 
   is given in lieu of any specific list of trademarks and their 
   owners. 


2.Provided Examples:
====================
  Editor files : 
    VB1.GEF 
    VB2.GEF
  Inputfiles :
    VB1.TXT
    VB2.TXT
  Outputfiles :
    VB1.OUT (Simulated with Berkley's Spice3e2, so use the header file BERKELY3E2.HDR)
    VB2.OUT (Simulated with the evaluation version of PSpice of september 1991, so use
             the header file PSPICE.HDR to open this )


3.Quick Start
=============

a) Designing
   ---------
  1.Intro

    For designing, you don't need any suplementary file than those who are provided
    in this package. Just extract all the files in one directory and start the 
    program SVCSPICE.EXE from within Windows.

  2.New document

    Select New from the file menu

  3.Adding components

    Select the desired component from the Component menu

  4.Changing component properties

    Dubbel click on the desired component. A dialog box appears. Fill in the new 
    settings and press the OK button.

  5.Drawing wires

    -Move the mouse to the starting point. 
    -Push de right mouse button down and hold it down.
    -Move the mouse to the destination point
    -Release the right mouse button

    When, while moving the mouse, the angle doesn't suit you : press the spac bar to
    clip the wires.

  6.(De)selecting objects

    -Selected objects are shown in red, unselected objects are in black.
    -To deselect all objects, click somewhere on the editor's workplace (where are 
     no components).
    -To deselect some of the objects, hold down the control key and point and click 
     the objects you want to deselect.
    -To select one object : 
             - deselect all objects
             - point and click the desired object
    -To select a group of objects in a rectangular field :
             - Move the mouse to the upper leftr corner of the rectangle
             - Push the left mouse button and hold it down
             - Move the mouse to the lower right corner
             - All objects that will be selected when you release the mouse 
               button appear in pink.
             - Release the left mouse button
       note :  rectangular selection can be used with the control key, so you don't 
               lose the previous selection

  7.Moving objects
    
    -Select the components and wires you want to move (step 6)
    -Point to one of the selected objects.
    -Click and hold down the left mouse button
    -Move the mouse
    -Release the mouse button when the position satisfies you

  8.Rotating objects

    -Select the GROUP of objects you want to rotate. This group must consist of all 
     components that are connected with one are more components from the group.
    -Point to one of the selected objects.
    -Click and hold down the left mouse button
    -Rotate in steps by pressign down the right mouse button
    -Release the left mouse button

  9.Saving a design

    -Choose the Save (or Save AS) menu from the File menu.
    -Design files are, by default, saved with the exsistension .GEF

  10.Opening an exsisting design

    -Choses Open from the File menu
    -Select the file you want to open and press the OK button
    
b) Simulating
   ----------
  1.Intro

    For simulating, you need an external simulator. Set up S-Spice for recognizing 
    your simulator (see settings )

  2.Supposing the settings are OK, and supposing you have your design file opened :
    - Chose the desired simulation from the Simulation menu (AC,DC or transient 
        simulation). Fill out the needed information and press the ok button.
    - Chose 'Start Simulation' from the 'Simulation' menu.
        A progress indicator pops up (Converting..). 
        After this, a dialog box appears which tells you the simulation is in
        progress. Press the 'show' button if you want to focus the simulator.
    - When the simulator has finished, and the 'autostart graph' checkbox was on, the
      postprocessor is started.

c) Postprocessor
   -------------
  1.Intro

    The postprocessor reads in spice output files. Make sure the S-Spice settings
    are OK to understand your spice output files. See settings for more information.

  2.Supposing the settings are OK :
    - When you just simulated your design, the postprocessor read in the outputfile
      automaticaly (when the 'autostart graph' checkbox is checked).
    - When you want to view an exsisting outputfile : 
         - Choose 'Open' from the file menu
         - Choose the file type 'Output files' to view the available outputfiles.
         - Select the file you want to view and press OK
       note : The example file vb1.out needs the BERKLEY3E2.HDR header file
              The example file vb2.out needs the PSPICE.HDR header file
              see settings for more information
    - The graphs from the outputfile are shown in a new window. In the upper right 
      corner of this window apears a small box with one or more checkmark buttons.
      Each checkmark represents a graph, with the name found in the outputfile.
    - To select the graph you want to view : check or uncheck these buttons.
    - The X-Axe can be lin or log. Select the view you want in the scale menu.
    - To copy the values from the selected graph (for use in a text editor or 
      spreadsheet), select 'Copy' from the 'Edit' menu. The values are now available 
      in text format in the clipboard.
    - To create a duplicate window, select 'Duplicate graph' in the 'Edit' menu.

4.Settings
==========

  S-Spice need to know the following things to be able to start the simulator
  and read in the outputfile :

  - The path and filename of the simulator program
  - The extension of the input files of your simulator
  - The extension of the output files of your simulator
  - The header file (see below) that describes the output files

  1.Input:
    ------
    S-Spice calls the simulator with the following command line:
      
      SIMUL INPUTFILE OUTPUTFILE
      
    with the following meaning:
      -SIMUL : the path and filename of the simulator
      -INPUTFILE : the path and filename of the inputfile
      -OUTPUTFILE: the path and filename of the outputfile
    When your simulator does not support this, you can use a batch file (which calls 
    the simulator). This batch file must then convert the parameters.
    eg : For Berkley's 3e2 version, I have a .BAT file with the following line
             SPICE -b -o %2 %1
    See your DOS manual for information on batch files, and your spice manual for 
    more information about the parameters that are accepted.
    
  2.Output : The S-Spice Header file
    ---------------------------------
   S-Spice need to know where the calculated values start. To do this, S-Spice uses
   a header file. To create a new header file, copy an exsisting one (with another
   name, but the extention must always be .HDR) to the S-Spice directory.

   Setting up your header file:
     - Select the desired header file from the settings dialog box (Menu File,Settings)
     - Press the button 'Edit layout'
     - A dialog box 'Postprocessor settings' appears :
          * Skip first column : Check this when the first column of your output files
                    does not contain a value, or a value that does not matter
                    ( eg: The 'Index' column from Berkley's 3e2 Spice )
          * Header layout : This is a unique line or set of lines, that ocures just 
                    before the columns with calculated values.
                    The following 'placeholders' are provided :

                       \var : Is a placeholder for a variable number of characters.
                              The \var line is restricted to the same line.
                              Examples for it use are : -placeholder for a page number
                                                        -placeholder for a title
                                                        -placeholder for a date
                                                        -...
                              This placeholder may be used more than once.

                        \titles : This is a placeholder for the titles of the columns.
                              This does not include the title of the column to
                              skip (if their is one to skip). S-Spice uses this 
                              placeholder to give the graphs in the postprocessor a 
                              name.
          * Printout in pages : Check this when the columns are not continous. 
                   Some simulators write each xx line a new header with a page 
                   number. Check this when your simulator does do this.
                   -Same header as first page: Check this when the header of a new 
                    page is the same as the one of the first page (the header layout).
                   -Other header : Same as Header layout, but for the new pages.
      - Select the OK button to accept the dialog box settings.
       
     Two example header files are provided

       PSPICE.HDR : header file for the exelent PSpice simulator (the evaluation 
                    copy of september 1991)
       BERKLEY3E2.HDR : Header file for Berkley's simulator version 3e2 (version 
                    TR3e2b1)

5.Creating your own components
==============================
  All used components have their defenition in the file svcspice.ini, so it is posible
  to create new ones.

  a).Keyword
     -------
     Add a keyword for your component to the 'Komponents' line in the [main] section 
     (all keywords in this line must be seperated with a comma). This keyword is the 
     name of the section where the component defenition will be placed, and is not 
     used for any other purpose. 
     As an example, we will create a PNP bipolair transistor. The keyword we choose is
     PNP.
     Create a new section with your keyword. In the example we add the following line 
     at the end of the file
     [PNP]
  b).Defenition
     ----------
     A defenition consist of 4 parts :

      1.The name : The text that will appear in the 'Components' menu
        In the example we add :
        Name=Bipol. Trans. PNP

      2.The layout : The layout consist of the statements 'Linenn=' and 'Arcnn='
          * The 'Linenn=' statement : "draw a line from ... to ..."
            Each line statement has a number (eg Line1=). The starting and ending
            coordinates are given as follows :
              Line1=x1,y1/x2,y2
            Where the point (x1,y1) is the coordinate of the starting point, 
            and (x2,y2) is the coordinate of the endding point. (in carthesian 
            coordinates)
          * The 'Arcnn=' statement : "draw an arc with as center ... and as radius ...,
                                      from angle ... to angle ..."
            Each Arc statement has a number (eg Arc1=). The parameters are given as 
            follows:
              Arc1=x0,y0,r,alfa1,alfa2
            Where the point (x0,y0) is the center, r the radius and alfa1 and alfa2 the
            start angle (from) and the end angle (to).
         The example so far is :
           [QPNP]
           Name=Bipol. Trans. PNP
           Line1=0,30/40,30
           Line2=40,10/40,50
           Line3=60,0/60,10/40,30/60,50/60,60
           Line4=43,24/40,30/46,27
           Arc1=50,30,22,0,360

      3.The connection points : the position and order of the nodes of the component.
        The statement is :
          Nodes=x1,y1 / x2,y2 / x3,y3 / x4,y4 ...
        Where the points (x1,y1), (x2,y2), (x3,y3), ... are the postions of the connections.
        There must be at least two connections.
        The nodes statement for the example is
          Nodes=60,60/0,30/60,0

      4.The defenition : How the component must appear in the spice input file
        This overall layout of the defenition statement is
          Def=X yyy \nodes yyy \model yyy \valuenn yyy \stringnn yyy \circuit yyy
        With the following meaning:
          * X : The first letter of the component name, the complete name will be put
                here when the spice inputfile is created.
          * \nodes : this is the position where all the node numbers will be put. This
                     may occure only once.
          * \model : this is the position where the model name will be put. The file
                     for the models must be given with a 'ModelFile=' statement. This 
                     may occure only ones. The model can be made optionel by adding 
                     a # sign ( \#model).
          * \circuit : this is the position where the circuit name will be put. The 
                       file for the circuits must be given with a 'CircuitFile=' 
                       statement.  This may occure only ones. The circuit can be made
                       optionel by adding a # sign ( \#circuit).
          * \valuenn : This is a value parameter. The description of the parameter must
                       be given in a coresponding 'valuenn=' statement (nn is a number).
                       The value can be made optional by adding a # sign (\#valuenn).
          * \stringnn : This is a string parameter. The description of the parameter
                        must be given in a coresponding 'stringnn=' statement (nn is 
                        a number). The value can be made optional by adding a # sign 
                        (\#stringnn).
          * yyy : A sequence of characters that does not correspond to one of those
                  mensionned above. The characters will be copied to the spice input
                  file.
        The Def statement for the example is :
          Def=Q \nodes \model
        
          Meaning : The name of the component must start with a 'Q', and their is a
                    model parameter which is not optional.

        Additional Defenition statements : 'Modelfile=' , 'CircuitFile='
                                           'Valuenn=' , 'Stringnn='
          * Valuenn and Stringnn : Those statements have the following layout:
                Valuenn=Name,Units,Prefix,Suffix
                Stringnn=Name,Prefix,Suffix
            Meaning : Name : the discription of the parameter that will appear in the
                             properties dialog box.
                      Units : Not used yet, but needed
                      Prefix : Used when the parameter is optional (using # character).
                               this prefix will be put in front of the parameter, only
                               when the parameter is used.
                      Suffix : Used when the parameter is optional (using # character).
                               this suffix will be put after of the parameter, only
                               when the parameter is used.
                      Prefix and suffix are optional. But when you want to use a suffix,
                      you need to specify als a prefix (can be blanco).
          *ModelFile and CircuitFile :
                ModelFile=FILE
                CircuitFile=FILE
           Where FILE is the filename (and pathname if needed) of the library file.

        The example needs only a ModelFile. eg:
          ModelFile=QPNP.LIB


6.Limitation, Errors, Bugs
==========================

  - I forgot to implement the 'Print' Menu item for the postprocessor. This will be 
    corrected in the next release.
  - The print dialog box for the grafic editor does not display the used printer. Use
    the 'printer setup' option instead. My intention is the fuse those two dialog boxes.
  - When selecting with the mouse a non focused child window, I get a message from 
    Windows, that the user pressed twice (a dubble click). This causes the unexpected
    maximazation of child windows(when you press the title bar), or the properties
    dialog box (when you press a component), or a beep. I have no idea what causes
    this. Can anyone help me with this ?
  - When zooming in or out : their meight be an offset error when scrolling the window.
    Don't ask me why, I don't know.
  - The help file is not implemented (except for some things). This is just for the 
    final release.


7.Other important information
=============================

For encouragement, sugestions, information, comment (positive or negative), but
also for bug report : just one e-mail adres 


        ==========================
        LVCAUWEN@EDUSERV.RUG.AC.BE
        ==========================

Those who contribute (sending me comment, sugestions, encouragement, bug report,...) 
will receive the final version of S-Spice 1.0 (without the 'b' sign), if they ask for
it.


End of document