
    Cadence Analog Design Environment Integration for WRspice
    ---------------------------------------------------------
                       Whiteley Research Inc.
                            7/23/2017


This directory contains files needed to integrate WRspice into the
Cadence Virtuoso Analog Design Enviroment created using the Cadence
OASIS Integration toolkit.

The present release contains all interface files, including the
source needed to build the simulator context, etc. using Virtuoso.
It also provides a pre-built context consistent with the present source,
generated in October 2015.

Read the OasisCustomer.pdf file for general information about
simulator integration into Cadence ADE.  Note that a special license
key

  (32100) Virtuoso(R) Analog Oasis Run-Time Option

will be required to use the interface.  One will need additional
licensing to rebuild the context, such as to add features incorporated
into the source Skill files, or to fix bugs.

=========================================================================
=========================================================================
*  Whiteley Research Inc.  no longer has the licensing and tools needed
*  to maintain and develop this code.  It is provided here "as-is" with
*  no guarantees whatsoever.  This code is provided free for any lawful
*  use.  Users are requested, but not required, to share any
*  improvements, bug fixes, etc.  with Whiteley Research and other users.
=========================================================================
=========================================================================


I.  Preliminaries

This interface is applicable only to the following operating system
releases:
LinuxRHEL6_64
LinuxRHEL7_64

The WRspice executable in these releases contains support for the
Cadence PSF data format for plot output, see section IV below.

In these releases, this directory is installed from the normal
distribution files into the WRspice installation area, typically in
/usr/local/xictools/wrspice/cadence-oasis (starting with
wrspice-4.2.17).  Users who have the needed licensing and wish to
develop the interface further should copy the files to a private work
area.

Shell scripts are provided in this directory to perform various tasks.
See the comments in these files for more information.

mkcx
This builds a "context file" for WRspice:  WRspice.cxt (32 and 64-bit
versions).  It uses Virtuoso to generate these files, and requires an
OASIS development license to run.  You don't need to run this unless
you are modifying to interface.

mkcdsenv
This builds an "environment file" for WRspice:  WRspiceCdsenvFile.  It
uses Virtuoso to create this filem and requires an OASIS development
license to run.  If should be run after mkcx.  You don't need to run
this unless you are modifying the interface.

makeAnalog
This script must be run to create an "analogLib" device library which
functions with WRspice.  See instructions below.  Every user will
need to run this once.

makeWrs
This script is used to add a WRspice view to the Josephson junction
schematic symbol provided.  This has already been done, so there is no
need to run this script unless the user adds new symbols or modifies
the JJ symbol in the WRspiceDevs library.


II.  Installation

There are probably various ways to install the interface, experienced
Cadence maintainers may choose a different approach than that
described here.  If you have a better approach, particularly that
avoids moving files into the Cadence installation directory tree,
please provide this feedback!

The "$CDSHOME" indicates the path to the Cadence installation
directory.  This environment variable is expected to be set, to the
directory that contains the "tools" link in a Cadence installation.
This is used in the makeAnalog script, so either set the variable
in the environment or modify the script.

The "$CDS_WRSPICE_HOME" indicates the path to this directory
("cadence-oasis") which contains this README and the other files. 
This can be located anywhere, for example
/usr/local/xictools/wrspice/cadence-oasis, to which CDS_WRSPICE_HOME
should be set.  You can set this in your shell startup file.

These operations will require permission to create files and
directories in the Cadence installation area.

1.  Create the directory $CDSHOME/tools/dfII/local if necessary.
      mkdir $CDSHOME/tools/dfII/local
    Create $CDSHOME/tools/dfII/local/menus if necessary.
      mkdir $CDSHOME/tools/dfII/local/menus
    Create $CDSHOME/tools/dfII/local/WRspice.
      mkdir $CDSHOME/tools/dfII/local/WRspice

2.  Copy WRspiceCdsenvFile into the local/WRspice directory as ".cdsenv".
      cp -f WRspiceCdsenvFile $CDSHOME/tools/dfII/local/WRspice/.cdsenv
    Copy WRspice.menus into the local/menus directory
      cp -f WRspice.menus $CDSHOME/tools/dfII/local/menus

3.  Change directory to $CDSHOME/tools/dfII/etc/tools, and create a
    symbolic link to $CDSHOME/tools/local/WRspice
      pushd $CDSHOME/tools/dfII/etc/tools
      ln -s ../../local/WRspice
      popd

4.  Creaste the directory $CDSHOME/tools/dfII/src/artist/WRspice.
    Copy the simInfo.il file from here to the new WRspice directory.
      mkdir $CDSHOME/tools/dfII/src/artist/WRspice
      cp -f simInfo.il $CDSHOME/tools/dfII/src/artist/WRspice

5.  Add empty files, the OASIS manual says to do this, I don't know
    why or if this is really necessary.

    touch $CDSHOME/tools/dfII/etc/skill/hnl/WRspice.ile
    touch $CDSHOME/tools/dfII/etc/skill/si/caplib/WRspice.ile

This completes the modifications to the Cadence installation source
tree.  The remaining tasks apply to user directories.

6.  In the present directory ($CDS_WRSPICE_HOME) You will need to create
    a new analogLib that has WRspice views.  to do this, run the
    makeAnalog script.

    ./makeAnalog

    This will copy your existing analogLib from Cadence, and run
    Virtuoso in text mode to perfrom the manipulations.

7.  Have a look at the WRspiceInit.il file.  This can be customized, if
    necessary.

    The file, or a copy, should be called from a load command in your
    .cdsinit file.  For example, assume that the file is ok as-is,
    Then one can add

    load( strcat( getShellEnvVar( "CDS_WRSPICE_HOME") "/WRspiceInit.il"))

    to the local configuration part of your, or the site-wide, .cdsenv
    file.

6.  Append the following lines to your cds.lib file.

    UNDEFINE analogLib
    DEFINE analogLib $CDS_WRSPICE_HOME/analogLib
    DEFINE WRspiceDevs $CDS_WRSPICE_HOME/WRspiceDevs
    DEFINE iftest $CDS_WRSPICE_HOME/iftest

    The custom analogLib that we built earlier provides the WRspice
    views necessary to use the devices for WRspice simulation.

    The WRspiceDevs library contains the Josephson juction device.  It
    can be used just like the devices in the AnalogLib.

    The iftest library contains some examples that can be used to test
    the interface.  This can be commented out or deleted when no longer
    needed.

This completes the installation.  If you want to remove the interface,
just remove all that was created above.


III.  Testing

After installation, one can test the interface, using the following
procedure.

1.  From your work area, start virtuoso.  Bring up the Library Manager
    from the Tools menu.

    You should see the analogLib, WRspiceDevs, and iftest libraries
    listed in the left panel.

    In this and following steps, there should be no errors reported
    in the CIW.

2.  Select iftest in the left panel.  Select ift4 in the middle panel. 
    Select Open in the File menu.  The Schematic Editor will appear,
    displaying a schematic consisting of two subcircuits plus sources
    and other components.

3.  From the Launch menu of the Schematic Editor, start ADE L.  The
    ADE window will appear.

4.  In ADE, click Simulator/Directory/Host in the Setup menu.  A panel
    will appear, with WRspice listed as the simulator.  You can change
    the project directory if necessary, this is where ADE will write
    netlist files.

    Click OK if you change anything, Cancel otherwise.

    Note that in the lower-right corner of ADE there is a "Simulator:
    WRspice" indication.

5.  Click Choose on the Analysis menu.  The panel is configured for
    transient analysis by default.

    Enter the following values.
    Start Time  0
    Stop Time   200p
    Step        0.1p
    Max Step    (leave blank)

    Click OK,

6.  The next step is to define some outputs for plotting.

    By default, there are no outputs defined (the Outputs window is
    blank) however WRspice will generate an output file that contains
    all node voltages, and branch currents for voltage sources and
    inductors.

    The point/click selection doesn't work well (Outputs menu, To Be
    Plotted then Select On Design).  Clicking on a wire will select
    the corresponding node.  Clicking on a red terminal box will try
    to obtain a current into the owning device.  This will work only
    for voltage sources and inductors.  So how do you select a node
    when there is no wire?  One way is to use Setup in the Outputs
    menu.

    One apparently can't just enter the node name, that doesn't seem
    to work.  Entering something like VT("netname") appears to
    work.

    Anyway, by some means select a couple of things to plot, say
    net2 and out.  You will see these listed in the Outputs window.
    The Plot boxes should be checked.

    The Save feature, with corresponding check boxes, at this point
    appears to do absolutely nothing.  Eventhally this will generate
    .save lines in the input file.

    It should be possible to plot things in subcircuits, but at
    present I haven't a clue how.

7.  OK, we should be set.  Click on Netlist and Run in the Simulation
    menu, or the green Run button on the right side of ADE.  If all
    goes properly, a large plot window should appear in a few seconds,
    displaying one nice sharp pulse (/out), and one ugly truncated
    pulse (/net2).

8.  Next, try and create your own schematic with JJs.  The JJ device
    is found in the WRspiceDevs library.  There are two required
    parameters:  model and area.  The models are defined in the
    models.scs file in the models subdirectory.  This file can be
    customized, presently it contains Hypres devices.  The model
    parameter should be set to one of the model names in this library,
    such as "jj2" or "jjr".

    The area is a scale factor that sets the critical current.  An
    area of 1.0 corresponds to Ic = 1.0mA.  The parameter is only a
    scale factor and not a physical area (but is proportional to
    physical area).

9.  Have fun.  Over time the interface will improve, your feedback
    is important.


IV.  PSF Support in WRspice

Supported Releases:
LinuxRHEL6_64
LinuxRHEL7_64

Supported Analyses
Transient
AC
DC (one dimensional, i.e., one source varying)

WRspice can generate the Cadence Paramater Storage Format (PSF) files
that ADE expects to find after a simulation is performed.  This is
currently not documented within WRspice.  Only the WRspice
distributions listed above contain this support.

PSF output consists of a directory, into which are generated files of
particular names and formats in accord with the specifications.  To
obtain PSF output, one must provide a "rawfile" name in a particular
format:

  psf[@path]

The "psf" is literal,  The square brackets mean "optional", the '@' is
literal, and the path is a path to a directory.

If only "psf" is given, then a directory named "psf" is created (if
necessary) in the current directory, and output files are placed in
this directory.  If the optional '@' and path appear, the output files
go instead to this directory.  For example, "psf@." would create the
files in the current directory, "psf@/home/joe/work/output" would put
the files in the output directory (which will be created if it doesn't
exist) under /home/joe/work.  In the path, all ancestor directories
must exist and have permissions set to allow the operation, or output
will not be written.

This form can be used when giving the "rawifle" name in the write
command, or on the wrspice command line following the -r option, or
when setting the rawfile variable.

Normally, when running in ADE, this is all automatic.  The setting
is required only when WRspice is used directly, and one wishes to
generate output that can be read into ADE.

