Building a Basic Script

This chapter describes how to setup and build a simple script to create a netlist and run a simulation using the design kit model verification tools. A tutorial example is provided that will help you understand the fundamental requirements for verifying a simple circuit.

The example commands given should run as is on supported unix systems or from within a cygnus shell on a PC, provided that the environment (see Configuring the Environment) and script headers (see Developing the Script Header) are correctly configured.

Quoting your string-variables

Within the perl scripts, it is required to use vertical quoted strings (' <string> ' or "<string>" ) wherever the chosen value happens to be a perl command, otherwise your script will not run correctly. Within the perl scripts, it is highly recommended that you quote all strings to reduce the possibility of generating errors. In perl, single quotes (' <string> ') represent text as is, with no variable substitution. Double quotes ( "<string>" ) perform variable substitution. For example, "$myVar" will be substituted by its value if it is in double quotes, while '$myVar' will just be equal to $myVar if it is in single quotes. Open quotes (` <string> ' or " <string> ") are not allowed for quoting strings in perl and vertical quotes (' <string> ' or " <string> ") should be used instead. While there is a very subtle difference in the appearance of the two styles, perl will not accept open quotes. Perl uses the open quote character for other applications.

The three main requirements to create and run a design kit model verification script are:

Understanding Templates
Understanding Parameters
Creating a Test Circuit

Understanding Items and Handles

A netlist is a succession of lines describing the test circuit. Each element (instance, analysis, parameter, etc.) of a circuit is referred to as an item in the design kit model verification tool. Generally speaking, each item corresponds to one line in a netlist file. In the design kit model verification tool, the context of an item has been generalized. For instance, dKit circuits, dKit parameters and dKit templates are also items. Therefore, the complete test circuit is also considered an item.

To create a netlist with the design kit model verification tool, a perl script is needed. Within the perl script, items are created by means of the call to a new() function. The return value of that function is called a handle. The implementation of the functions used in the design kit model verification tool reside in the design kit modules. Hence you get the following syntax:

$<handle> = <design_kit_module>->new(<arguments>);

For example, in perl syntax:

$myResistor = dKitInstance->new('R', 'R1');

In the example above, $myResistor is a handle to the item R1, (which is currently a non-connected resistor with an undefined resistor value).

Another example, in perl syntax:

$myCircuit = dKitCircuit->new("test1");

In this example, $myCircuit is a handle to an empty circuit, called test1.

Subsequent operations on this handle would then complete the definition of the item. For example:

$myCircuit->addInstance($myResistor);

would define $myResistor (R1) to actually belong to $myCircuit (test1).

Yet another example:

$myResistor->parameterValue('resistance', 10);

defines $myResistor to be a 10 Ohm resistor.

For detailed information on using items and handles, refer to Building an Advanced Script.

Developing the Script Header

The first step in creating your own perl script is to build a script header that will ensure that the correct modules are found by the script.
To begin developing your perl script header:

Open any ASCII text editor and copy the lines of code shown below to the beginning of your new file.

#!<myPath2perl>/perl  
BEGIN {  
    if ($ENV{DKITVERIFICATION} eq "") 
    { 
         if ($ENV{HPEESOF_DIR} eq "") 
        { 
             print "\nPlease set environment variable DKITVERIFICATION\nto point to the design kit 
model verification installation directory\n\n"; 
             exit 1; 
         } else 
         { 
             $ENV{DKITVERIFICATION} = 
"$ENV{HPEESOF_DIR}/design_kit/verification"; 
         } 
    } 
    $myLibPath = "$ENV{DKITVERIFICATION}/perl/lib"; 
    if ( ! -d $myLibPath) 
    { 
         if ($ENV{DKITVERIFICATION} eq 
"$ENV{HPEESOF_DIR}/design_kit/verification") 
         { 
             if ( ! -d "$ENV{HPEESOF_DIR}/design_kit/verification") 
             { 
                  print "\nERROR: Unable to find verification module 
directory\nVerification tool not installed at default\nlocation 
\$HPEESOF_DIR/design_kit/verification\n"; 
                  print "Please set environment variable DKITVERIFICATION to 
point\nto the design kit model verification installation directory\n\n"; 
             } else 
             { 
                  print "\nERROR: Unable to find verification module directory 
at\ndefault location \$HPEESOF_DIR/design_kit/verification/perl/lib\n"; 
                  print "Please set environment variable DKITVERIFICATION\nto 
point to the installation directory\n\n"; 
             } 
         } else 
         { 
                 print "\nERROR : Unable to find verification module directory 
\$DKITVERIFICATION/perl/lib\n\n"; 
                 print "Please set environment variable DKITVERIFICATION\nto 
point to the design kit model verification installation directory\n\n"; 
         } 
         exit 1; 
    } 
# To find the standard supplied libraries in the local path 
    use Cwd; 
    $curDir = cwd; 
} 
use lib "$myLibPath";  

use lib "$curDir";

Replace the first line in the file header shown above with the path to the perl interpreter. The default path is `/usr/bin/perl'; however, your path may be different.
Save this new file as header.pl so it can be copied and re-used in later scripts.

A sample script is included in the design kit model verification tool, at the location $HPEESOF_DIR/design_kit/verification/perl/header.pl

Understanding Templates

In a previous section, Understanding Items and Handles, it was shown that a test circuit in the design kit model verification tool consists of handles to items. When the netlist for the simulator needs to be created, the design kit model verification tool needs to know how to do this. This is where templates are used. A template, as such, can be seen as the set of rules for how to translate the handle in the perl test circuit script to a netlist segment for each of the different simulators. This means that one template is required for each type of component/analysis/... used in the test circuit. Different instances of the same component/analysis will use the same template.

Templates are made available to the design kit model verification tool by means of a perl database file dkitTemplateDB.pl. So if you do not see the file dKitTemplateDB.pl within your working directory, you have not installed any templates.

To view which templates are currently available:

Run the perl script dKitTemplateList.pl. This script will list all currently defined templates, with the enumeration of their nodes, parameters and simulator translation rules.
Alternatively, you can just look at the dKitTemplatesDB.pl file if you are a perl expert.

Installing the Default Templates

For standard components (R, L, C, M, Q, etc.), circuit parameters and standard analyses (DC, AC, Noise and S-parameter), the design kit model verification tool distribution includes a perl script that contains the standard template definitions. To install the standard templates, move to your working directory and issue the command:
dKitTemplateCreate.pl

This command creates the file dKitTemplateDB.pl with a set of standard templates for your design in your working directory. Once created, the dKitTemplateDB.pl file makes these templates available to be called by your test circuit perl script.

Note
This command deletes previously installed custom templates, so you will need to rerun your custom template scripts to reinstall the custom templates.

Creating Custom Templates

This section provides a step-by-step example for creating a simple custom component template. A custom component is any component that is not part of the standard component set provided with Advanced Design System. More in particular, a custom component is one that is using a model defined within the model library file. For custom components, the templates need to be created separately.

To define a custom component template:

Open a copy of the header.pl script that was created in Developing the Script Header.
Add the following line to the end of the header.pl script to initialize your custom template.
use dKitTemplate;
Start defining your custom component template by creating a handle for the template structure. For example, adding the following command will create a new design kit template with a handle of my_2p.
$my_2p = dKitTemplate->new('my_2p');

If the handle you created for your template already exists, a template already defined error will be reported when you try to re-run your script. To avoid template handle duplication errors, run the default design kit template creation script again before re-running your script. For more information on the default design kit template creation script, refer to Installing the Default Templates.
Alternatively, you can query to see if a template already exist before defining a new one, by adding the following lines to your script instead of just defining a handle.

if ( ! ($my_2p = dKitTemplate->getTemplate('my_2p')) )
{
$my_2p = dKitTemplate->new('my_2p')
} else
{
print "redefining my_2p\n";
}

Adding the code above will result in the my_2p handle being redefined if another instance of my_2p already exists. For more information on handles, refer to Understanding Items and Handles.

Once you have designated a handle for your template, you can start defining your template dialects. The following example shows a simple template using the handle created earlier in step 3.

$my_2p->netlistInstanceTemplate('ads', '<model>:#instanceName %n1 %n2 [[count=<count>]]'); 
$my_2p->netlistInstanceTemplate('spectre', '#instanceName %n1 %n2 <model> [[count=<count>]]'); 
$my_2p->netlistInstanceTemplate('hspice', '#instanceName %n1 %n2 <model> [[count=<count>]]');

The example above shows the itemType my_2p defined to be a component with two nodes n1, and n2 (see %n1, %n2), and 2 parameters, model and count (see <model>, <count>). The [ [ ... ] ] syntax means that the parameter count is optional. The #instanceName is an internal function which will return the name of the item.
This template could for instance be used to define a component with 2 nodes whose model name is <model> and has a parameter called <count>, defined in the model library files of the different simulators.

Note
The number of nodes and the name of the parameters used by the template is the number of nodes defined and the names of the parameters in the model library file. The number of nodes and the names of the parameters defined in the design kit customization files are ignored by the design kit model verification tool. The design kit customization files are the .ael files, which define the components (items) to be used on the schematic (item definition).

For more information on the template module, and a more rigorous explanation of the syntax, refer to Template Module.

Once you have completed all of your template definitions, add the following line as the last line of your test script:
dKitTemplate->createTemplateDatabaseFile;
This command will add your custom template definition to the default templates.

Save your new script as myTemplates.pl or some other appropriate name. An example of what your new script might look like is shown in below.

#!/usr/bin/perl 
# ADD SCRIPT HEADER from Table 3-1. 
### Initialize the new template. 
use dKitTemplate; 
### Query to check for template duplication errors. 
if ( ! ($my_2p = dKitTemplate->getTemplate('my_2p')) ) 
   { 
        $my_2p = dKitTemplate->new('my_2p') 
   } else 
   { 
        print "redefining my_2p\n"; 
   } 
### Set the template dialects. 
$my_2p->netlistInstanceTemplate('ads', '<model>:#instanceName %n1 %n2 [[count=<count>]]'); 
$my_2p->netlistInstanceTemplate('spectre', '#instanceName %n1 %n2 <model> [[count=<count>]]'); 
$my_2p->netlistInstanceTemplate('hspice', '#instanceName %n1 %n2 <model> [[count=<count>]]'); 
### Add the template definition to the default template. 
dKitTemplate->createTemplateDatabaseFile; 
### end of script

Run the new perl script to add your custom templates to the default templates in the file dKitTemplateDB.pl. You can now use your custom templates when creating your design kit test circuit.

Understanding Parameters

The parameters of devices in different simulators use different names. Ideally, you want the parameters of devices in your results file to have the same name. The design kit model verification tool includes a parameter module to map the different parameter names for the same parameter to one unique name.

Parameters are made available to the design kit model verification tool by means of a perl database file dKitParameterDB.pl. So if you do not see the file dKitTemplateDB.pl within your working directory, you have not installed any parameters.

To view which parameters are currently available, run the perl script dKitParameterList.pl . This script will list all currently defined parameters. Alternatively, you can just look at the dKitParameterDB.pl file if you are a perl expert.

Installing the Default Parameters

Again, there are default parameters defined. To install them into your working directory, enter the command:

dKitParameterCreate.pl

This command creates the file dKitParameterDB.pl with a set of standard templates for your design in your working directory. Once created, the dKitParameterDB.pl file makes these parameters available to be called by your test circuit perl script.

Note
This command deletes previously installed custom parameters, so you will need to rerun your custom parameter scripts to reinstall the custom parameters.

Creating Custom Parameters

Once your default parameters are installed, you can start creating your new design kit parameters in a perl file.
To create your new parameter file:

Open a copy of the header.pl script that was created in Developing the Script Header.
Add the following line to the end of the header.pl script to initialize your custom template.
use dKitParameter;

To define a custom parameter, you must create an instance and define the different instance parameters. For example:

$IDC = dKitParameter->new('Idc');			 # The dKit Parameter Name
$IDC->description("dc current");		 # Its description
	$IDC->dialectReference('hspice', 'dc'); 		# Its name in hspice
	$IDC->dialectReference('ads', 'Idc');		 # Its name in ads
	$IDC->dialectReference('spectre', 'dc'); 		# Its name in spectre
	$IDC->resultName("dc");				 # The name used for the results

The dKit Parameter Name is the name to use for device parameters within the test circuit perl script. The netlister will translate it to the simulator parameter name. For more information, refer to Parameter Module.

As with the templates, it is beneficial to add new parameter definitions to the default parameter definitions using the command:

dKitParameter->createParameterDatabaseFile;

Your new script should now appear similar to the example shown below. Run the script after entering this command to update the parameter information.

#!/usr/bin/perl 

# ADD SCRIPT HEADER (see "Developing the Script Header" above).

use dKitParameter;

### add the perl commands to create the parameters here.

$IDC = dKitParameter->new('Idc'); # the dKit Parameter Name
$IDC->description("dc current"); # its description
$IDC->dialectReference('hspice', 'dc'); # its name in hspice
$IDC->dialectReference('ads', 'Idc'); # its name in ads
$IDC->dialectReference('spectre', 'dc'); # its name in spectre
$IDC->resultName("dc"); # the name used for the results

dKitParameter->createParameterDatabaseFile;
### end of script

Creating a Test Circuit

Once your templates and parameters are defined and installed, you can start creating your design kit test circuit in a new perl file. This section provides examples for creating a simple test circuit.

The following example illustrates many of the issues typically encountered when building a test circuit. Each of the sections shown below discusses an aspect of creating the test circuit perl script. While all portions of the creation process may not be used in your script, each section should be addressed in the order given.

Setting up a Test Circuit
Adding Circuit Options
Adding Model Library Files
Creating Instances
Connecting Instances
Creating Analyses
Transient Analysis timeStepMethod Parameter
Defining the Simulators
Running the Test Circuit Script

Setting up a Test Circuit

To create a new test circuit perl script:

Open a copy of the header.pl script that was created in Developing the Script Header.
Add the following line to the end of the header.pl script. This line is used to initialize your new test circuit.
use dKitCircuit;
Create the circuit handle for the structure by adding the following function:
$Circuit = dKitCircuit->new(' <circuitName> ');

Where <circuitName> determines where to store the intermediate and final results. If the name contains slashes ( / ), subdirectories are created for storing the intermediate results and the final result ( <circuitName>.cti or <circuitName> _ <simulator>.cti) in CITI file format.
The dataset used to view the results in the ADS Data Display will be placed in the current directory. The ADS Data Display file name is in the form <circuitName> .ds or <circuitName> _ <simulator>.ds where the slashes ( / ) are replaced by underscores (). For example, if _<circuitName> equals myTests/test1 then all intermediate files are stored in the directory myTests, and will start with the prefix test1. The resulting dataset will be called myTests_test1.ds or myTests_test1_ <simulator>.ds. The _ <simulator> is added to the final results name if you request a simulation for only one simulator.
For more information on datasets (.ds) and CITI file (.cti) format, refer to Chapter 4 of the ADS "Using Circuit Simulators" documentation.
Save a copy of your new file as myCircuit.pl.

Adding Items

The content of your circuit is defined by adding items as needed to your script using the new() function.

To create a new item, use the function in the general form:

new(' <templateName> ', ' <itemName> ');

Each <itemName> should be a unique identifier. For more information on items, refer to Understanding Items and Handles.

Note
Item names are case sensitive. Therefore, Optional1 is not equal to optional1. Also, because Hspice translates everything to lower case in the results file, comparisons will be easier when only lower case itemNames are used.

Adding Circuit Options

The Options component makes it possible to set general simulation options related to convergence tolerances, warnings, global noise temperature and so on. To set an Option other than the standard circuit Options:

Create the Option handle.
Define the simulator parameter values.
Add the simulator option to the circuit.

The following example shows a typical simulator options setup.

$OPTION1 = dKitInstance->new('SIMULATOROPTION', "option1");
$OPTION1->parameterValue('adsOptions', "ResourceUsage=yes");
$OPTION1->parameterValue('spectreOptions', "save=lvlpub digits=10");
$OPTION1->parameterValue('hspiceOptions', "nopage acct=0 dccap=1 numdgt=10");
$Circuit->addSimulatorOption($OPTION1);

Temperature is handled somewhat differently than other options. For example, to set the circuit temperature at 20 degrees Celsius, you need the following:

$TEMP = dKitInstance->new('TEMPERATURE', 'T1');
$TEMP->parameterValue('temperature', 20);
$Circuit->addSimulatorOption($Temp)'

If you plan to do a temperature sweep, it is better to not add a default temperature option, as this might cause problems when doing Hspice simulations.
You can add multiple option instances; however, ensure that you give each option a unique name. For example, option1, option2, option3, etc.

Adding Model Library Files

The modelLibrary item enables you to build a list of model files that you want to include in your test circuit.
To add a modelLibrary item to your circuit:

Create a modelLibrary handle.
Add the path to the variables and equations data.
Set the path and Section parameters if needed (see Adding a Model Library Section Designator).
Add the modelLibrary to the circuit.

For each additional library or library Section, you must create and add a new model library handle. The following example shows a typical modelLibrary item setup.

$MODLIB1 = dKitInstance->new('MODELLIBRARY', "vars");
$MODLIB1->parameterValue('adsModelLibrary', "../models/ads/vars.net");
$MODLIB1->parameterValue('spectreModelLibrary',"../models/spectre/vars.scs");
$MODLIB1->parameterValue('hspiceModelLibrary',"../models/hspice/vars.hsp");
$Circuit->addModelLibrary($MODLIB1);

Note
When using relative paths, please note that the simulator actually changes the working directory to the <circuitName> directory before it starts the simulator. For more information, refer to Setting up a Test Circuit.

Adding a Model Library Section Designator

Each model file can have a Section designator. This enables you to include only a portion of a model file for corner analysis, provided your model file has been set up properly. The Section designator is optional; if it is left empty, the entire file will be included (provided it has no dependencies on needing a particular Section set up).

When a model library has different sections and the ADS model library file is adapted using #define statements, a library Section can be selected. For example, to select the section NORMAL:

$MODLIB1->parameterValue('adsSectionName', "NORMAL");
$MODLIB1->parameterValue('hspiceSectionName', "NORMAL");
$MODLIB1->parameterValue('spectreSectionName', "NORMAL");

Creating Instances

An instance in a design kit is typically a component definition that generally has similar netlist formats for each of the different simulators.
To start creating instances:

Create the instance handle.
Define the instance parameters.
Add the instance to the circuit.

For example, to create a circuit with two 1 volt DC voltage sources (V1 and V2) and a 10 ohm resistor (R1):

$V1 = dKitInstance->new('V', 'V1');
$V1->parameterValue('Vdc', 1);
$Circuit->addInstance($V1); 

$V2 = dKitInstance->new('V', 'V2');
$V2->parameterValue('Vdc', 1);
$Circuit->addInstance($V2); 

$R1=dKitInstance->new('R', 'R1');
$R1->parameterValue('resistance', 10);
$Circuit->addInstance($R1);

Note that the parameter values should be in engineering notation if they are real numbers, and should not contain units. For example, a capacitor of 1nF would use:

$C1=dKitInstance->new('C', 'C1');
$C1->parameterValue('capacitance', 1e-9);
$Circuit->addInstance($C1);

To know which parameters are defined for which instances refer to Defining and Retrieving the Parameter Values.

Connecting Instances

A circuit node is a connection of the terminals or pins between two or more instances. After all instances are added, you can connect them to each other using the nodeName() function supplied in the design kit model verification tool.

For example, to connect the internal node/pin/terminal nplus of Vds, the internal node/pin/terminal n1 of R1:

$Vds->nodeName('nplus', 'node1');
$R1->nodeName('n1', 'node1');

Where node1 is the name of the circuit node or connection point.

If you are working on a layout, you would probably use 'trace1' in place of 'node1 ', where 'trace1' would be the name of the trace connecting your components. For the design kit model verification tool, both nodes and traces are equivalent. However, the circuit node convention is generally used in the examples provided in this document.

For more information on node names for instances, refer to Defining and Retrieving Node Names.

Creating Analyses

Monte Carlo Analysis (MONTE) is supported by the design kit model verification tool; however, it is not a pure sweep as are the other analyses listed in this section. MONTE is more like a swept parameter. For more information, refer to Monte Carlo Analysis. The pure analyses that are currently supported by the design kit model verification tool are:

AC (ac analysis)
DC (dc analysis)
SP (S-parameter analysis)
NOISE (noise analysis)
TRAN (transient analysis)

All supported pure analyses require one SWEEP parameter to be defined and consequently a SWEEPPLAN, with the exception of the transient analysis. If the default output from the simulators is not adequate, an OUTPUTPLAN can be added to these analyses to enumerate the desired outputs. If more parameters need to be swept, a SWEEP analysis can be added as well.

Note
OUTPUTPLANs added to a S-parameter analysis will be ignored.

The following example shows how to set up a DC analysis with two swept parameters; the DC voltage of the voltage source V1 and the temperature.

In this example, there are two parameters that must be swept. Therefore, two analysis handles are required.
```
$SW1 = dKitAnalysis->new('SWEEP', 'SWEEP1');
$DC1 = dKitAnalysis->new('DC', 'DC1');
```
The analyses need to be cascaded with the Sweep analysis in front. To ensure that the Sweep analysis is first, the analysis is stacked using the addSubAnalysis() function.
```
$SW1->addSubAnalysis($DC1);
```
The defined Sweep parameters chosen in this example use the SWEEP analysis to sweep the DC voltage of V1, and the DC analysis to sweep the temperature.
```
$SW1->parameterValue('device', 'V1');
$SW1->parameterValue('parameter', 'Vdc');
$DC1->parameterValue('parameter', 'temp');
```
The sweep definition could be reversed if needed. For global parameters such as temp and freq, you do not need to specify the device.

To setup the SweepPlans for simulation results for:

Fifty-one voltages of V1.
Vdc equally spaced between 0 to 2.5V.

Temperatures of -40, 27, and 155 degrees Celsius
The following SWEEPPLANs are defined:

$SWEEPPLAN1 = dKitAnalysis->new('SWEEPPLAN_LIN', 'SWL1');
$SWEEPPLAN1->parameterValue('start', 0);
$SWEEPPLAN1->parameterValue('stop', 2.5);
$SWEEPPLAN1->parameterValue('numPts', 51);
$SW1->addSweepPlan($SWEEPPLAN1); 

$SWEEPPLAN2 = dKitAnalysis->new('SWEEPPLAN_PT', 'SWP1');
$SWEEPPLAN2->parameterValue('values', "-40 27 155");
$DC1->addSweepPlan($SWEEPPLAN2);

If you defined a DC or AC analysis, you should also add an OutputPlan; otherwise there will not be any output from Hspice.
Note
ADS and Spectre both generate a default OutputPlan if no plan is specified. For Noise and S-parameter analysis, a default outputplan is always added.

The most common output request is the value of the voltage at a certain node or trace. For this type of OutputPlan, you can use the OUTPUTPLAN_NODES default template. Using this template, you specify the nodes for which the voltage is desired as the value to the 'nodes' parameter. For example:
```
$OUTPUTNODES = dKitAnalysis->new('OUTPUTPLAN_NODES', "out1");
$OUTPUTNODES->parameterValue('nodes', "node1 node2");
$DC1->addOutputPlan($OUTPUTNODES);
```
To output the currents in a certain device, the default template OUTPUTPLAN_CURRENTS is provided. Using this template, you can specify the terminals of the devices for which you want the currents.

Note
Currently ADS does not allow any selection of currents. However, ADS outputs the current through terminal 1 of voltage sources by default.
```
$OUTPUTCURRENTS=dKitAnalysis->new('OUTPUTPLAN_CURRENTS', "out2");
$OUTPUTCURRENTS->parametervalue('deviceTerminals', "V1:1 V2:1");
$DC1->addOutputPlan($OUTPUTCURRENTS);
```
For DC only, the device operating points (DOP) can be saved using the default OUTPUTPLAN_DOPS template. Using this template, you can specify the desired operating points as the value of its deviceParameters parameter. The names used to specify the parameters are the names of the design kit parameters (see Understanding Parameters).
```
$OUTPUTDOPS=dKitAnalysis->new('OUTPUTPLAN_DOPS', "out3");
$OUTPUTDOPS->parameterValue('deviceParameters', "V2:i");
$DC1->addOutputPlan($OUTPUTDOPS);
```
Note
The ADS simulator only allows you to select whether or not to save device operating points. So for ADS, you will get all device operating points or none.
To add the defined circuit analysis to the test circuit, use the addAnalysis() function as shown in this example.
```
$Circuit->addAnalysis($SW1);
```

Transient Analysis timeStepMethod Parameter

There are three different values that the timeStepMethod parameter can be set to:

fixed
iteration
trunc (default)
Note If you are performing a transient analysis with a parameter sweep, the timeStepMethod parameter must be set to fixed. For example:

$TRAN1->parameterValue('timeStepMethod', "fixed");
Spectre only supports the truncation ( trunc ) timeStepMethod. Because of this, the step parameter uses the strobe capability of Spectre to emulate a fixed timeStepMethod.

Defining the Simulators

To define the simulators to run for ADS, Spectre, and Hspice, add the line:

$Circuit->simulate('ads', 'spectre', 'hspice');

Your new test circuit script should now appear similar to the example script shown below.

Example Test Circuit Script

#!/usr/bin/perl

BEGIN { 

    if ($ENV{DKITVERIFICATION} eq "")

    {

         if ($ENV{HPEESOF_DIR} eq "")

        {

             print "\nPlease set environment variable DKITVERIFICATION\nto

point to the design kit model verification installation directory\n\n";

             exit 1;

         } else

         {

             $ENV{DKITVERIFICATION} =

"$ENV{HPEESOF_DIR}/design_kit/verification";

         }

    }

    $myLibPath = "$ENV{DKITVERIFICATION}/perl/lib";

    if ( ! -d $myLibPath)

    {

         if ($ENV{DKITVERIFICATION} eq

"$ENV{HPEESOF_DIR}/design_kit/verification")

         {

             if ( ! -d "$ENV{HPEESOF_DIR}/design_kit/verification")

             {

                  print "\nERROR: Unable to find verification module

directory\nVerification tool not installed at default\nlocation

\$HPEESOF_DIR/design_kit/verification\n";

                  print "Please set environment variable DKITVERIFICATION to

point\nto the design kit model verification installation directory\n\n";

             } else

             {

                  print "\nERROR: Unable to find verification module directory

at\ndefault location \$HPEESOF_DIR/design_kit/verification/perl/lib\n";

                  print "Please set environment variable DKITVERIFICATION\nto

point to the installation directory\n\n";

             }

         } else

         {

                 print "\nERROR : Unable to find verification module directory

\$DKITVERIFICATION/perl/lib\n\n";

                 print "Please set environment variable DKITVERIFICATION\nto

point to the design kit model verification installation directory\n\n";

         }

         exit 1;

    }

# To find the standard supplied libraries in the local path

    use Cwd;

    $curDir = cwd;

}

use lib "$myLibPath"; 

use lib "$curDir";

### Initialize the new test circuit.

use dKitCircuit;

$Circuit = dKitCircuit->new('myCircuit');

### Set Simulator Options.

$OPTION1 = dKitInstance->new('SIMULATOROPTION', "option1");

$OPTION1->parameterValue('adsOptions', "ResourceUsage=yes");

$OPTION1->parameterValue('spectreOptions', "save=lvlpub digits=10");

$OPTION1->parameterValue('hspiceOptions', "nopage acct=0 dccap=1 
numdgt=10");

$Circuit->addSimulatorOption($OPTION1);

### Add Model Files.

### Note that model libraries are not needed here because default components

### are used.These lines have been commented out.

#$MODLIB1 = dKitInstance->new('MODELLIBRARY', "vars");

#$MODLIB1->parameterValue('adsModelLibrary', "../models/ads/vars.net");

#$MODLIB1->parameterValue('spectreModelLibrary',"../models/spectre/vars.scs"
);

#$MODLIB1->parameterValue('hspiceModelLibrary',"../models/hspice/vars.hsp");

#$Circuit->addModelLibrary($MODLIB1);

### Set the Library Section.

#$MODLIB1->parameterValue('adsSectionName', "NORMAL");

#$MODLIB1->parameterValue('hspiceSectionName', "NORMAL");

#$MODLIB1->parameterValue('spectreSectionName', "NORMAL");

### Create Instances and Define Their Parameters.

$V1 = dKitInstance->new('V', 'V1');

$V1->parameterValue('Vdc', 1);

$Circuit->addInstance($V1);

$V2 = dKitInstance->new('V', 'V2');

$V2->parameterValue('Vdc', 1);

$Circuit->addInstance($V2);

$R1=dKitInstance->new('R', 'R1'); 

$R1->parameterValue('resistance', 10);

$Circuit->addInstance($R1);

### Connect the Nodes.

$V1->nodeName('nminus', 0);

$V1->nodeName('nplus', 'node1');

$R1->nodeName('n1', 'node1');

$R1->nodeName('n2', 'node2');

$V2->nodeName('nplus', 'node2');

$V2->nodeName('nminus', 0);

### Create Analysis Handles.

$SW1 = dKitAnalysis->new('SWEEP', 'SWEEP1');

$DC1 = dKitAnalysis->new('DC', 'DC1');

### Stack the Analyses.

$SW1->addSubAnalysis($DC1);

### Define the SWEEP Parameters.

$SW1->parameterValue('device', 'V1');

$SW1->parameterValue('parameter', 'Vdc');

$DC1->parameterValue('parameter', 'temp');

### Define and Add the SWEEPPLANS.

$SWEEPPLAN1 = dKitAnalysis->new('SWEEPPLAN_LIN', 'SWL1');

$SWEEPPLAN1->parameterValue('start', 0);

$SWEEPPLAN1->parameterValue('stop', 2.5);

$SWEEPPLAN1->parameterValue('numPts', 51);

$SW1->addSweepPlan($SWEEPPLAN1);

$SWEEPPLAN2 = dKitAnalysis->new('SWEEPPLAN_PT', 'SWP1');

$SWEEPPLAN2->parameterValue('values', "-40 27 155");

$DC1->addSweepPlan($SWEEPPLAN2);

### Add the OUTPUTPLANS.

$OUTPUTNODES = dKitAnalysis->new('OUTPUTPLAN_NODES', "out1");

$OUTPUTNODES->parameterValue('nodes', "node1 node2");

$DC1->addOutputPlan($OUTPUTNODES);

$OUTPUTCURRENTS=dKitAnalysis->new('OUTPUTPLAN_CURRENTS', "out2");

$OUTPUTCURRENTS->parameterValue('deviceTerminals', "V1:1 V2:1");

$DC1->addOutputPlan($OUTPUTCURRENTS);

$OUTPUTDOPS=dKitAnalysis->new('OUTPUTPLAN_DOPS', "out3");

$OUTPUTDOPS->parameterValue('deviceParameters', "V2:i");

$DC1->addOutputPlan($OUTPUTDOPS);

### Add the Top Analysis to the circuit.

$Circuit->addAnalysis($SW1);

### Add the Simulation Command.

$Circuit->simulate('ads', 'spectre', 'hspice');

### List any missing parameter definitions.

 {{print dKitParameter->listMissingParameterDefinitions;
}} 
### End of script

Running the Test Circuit Script

If you did not initialize the template or parameter databases yet, i.e. you do not have a dKitTemplateDB.pl or dKitParameterDB.pl file in your working directory, you need to do it now.

To initialize the template database:

dKitTemplateCreate.pl

To initialize the Parameter database:

dKitParameterCreate.pl

Some more advanced default templates use subcircuits, (see Building an Advanced Script). If these templates are used within your circuit, you need to initialize the subcircuit database:

dKitSubcircuitCreate.pl

Alternatively, all of the above modules can be initialized at the same time using:

dKitSetupWork.pl

If you run the Example Test Circuit Script, your results should appear in a dataset ( <name> .ds) format.
You may receive several warning messages after running your script.

Please define parameter <param> using ...

This is to inform you that the dKit specific parameter <param> could not be translated to a simulator specific parameter, but kept its dKit Specific name. You may also have gotten the warning:

Please define a parameter using ... so that the <dialect> parameter <param> ...

This means that the <dialect> simulator specific parameter <param> could not be translated to a result name, but kept its simulator specific name. In this case you can freely choose the name of the dKit parameter.

If you want to list an overview of which parameters were not translated to a result name, add the following line to the end of your TEST CIRCUIT script after the line $Circuit->simulate('ads', 'spectre', 'hspice');

print dKitParameter->listMissingParameterDefinitions;

Viewing Your Results in a Data Display

Simulation results are stored in datasets (*.ds) and citifiles (*.cti). To view your results in an ADS Data Display:

Launch ADS and create a new project <adsproject> if necessary.
Copy all of your datasets to your ADS project's data directory ( <adsproject> /data).
Launch the ADS Data Display server from your ADS window. From the ADS Main window, choose Window > New Data Display.
Create a template to view your results. For more information, refer to "Using a Template in Your Display" in the ADS "Data Display" documentation.
Select the dataset to view the results. If your parameters have been defined correctly, you should be able to use the <dataset>. <simulator>. <parameter> to access the different results for the different simulators, with <simulator> equal to ads_sim, spectre_sim or hspice_sim.

For more information on datasets (*.ds) and citifiles (*.cti), refer to Chapter 4 of the ADS "Using Circuit Simulators" documentation.

For more information on simulation results, refer to Comparing Simulation Results.