Advanced Methods for Importing Files

This chapter describes the procedures for Importing files into Advanced Design System using the Netlist Translator from the command line. The methods described in this chapter are for advanced users who want to have the ability to manipulate their netlist within a translation.

Performing your translation via the command line provides you with more flexibility in the process and more control over the output. Some of the advantages of translating your Spectre or Spice file from the command line are listed below:

• It enables you to check for errors midway through the translation.
• It enables you to modify the intermediate file before the schematic is created
• It enables you to do batch processing with multiple files.
• It gives you access to advanced command line options not supported by the user interface.

The output of a Netlist Translator command line translation can be either an IFF file that is used to create an ADS Schematic or an ADS Netlist.

Understanding the Import Operation

This section describes how the Netlist Translator software works when performing an import operation. It may be helpful to understand these steps if you plan on importing your designs using the Netlist Translator from the command line.

When the Netlist Translator performs an import, the software runs an executable program called nettrans. The nettrans program reads the file and then writes either an IFF file, spice. iff , or an ADS netlist, spice.net , depending on the connection method defined when setting the import options. If an IFF file is created, Advanced Design System reads the IFF file and creates a schematic. If an ADS netlist is created, it is stored in ADS netlist format and placed in a pre-specified directory. Any errors that occur during the translation are written to a file called nettrans.log . This file records any components that could not be translated due to issues such as unrecognized syntax or incompatible models.

Running the nettrans program from the command line enables you to modify the contents of the spice.iff file before importing the file into Advanced Design System. Once you are comfortable with the output of the nettrans program, you can simply perform an IFF import into ADS. The IFF importer loads the spice.iff file, generates the schematic and writes any error messages or warnings to a log file called ifftolib.log. Alternatively, you could convert the output of the nettrans program to an ADS Netlist. For information on how the import options are controlled from the command line, refer to Executing the Nettrans Command.

For information on how the import options are controlled from the user interface, refer to Setting the Import Options.

For information on how the import options are controlled from the command line, refer to Executing the Nettrans Command.

Import Options shows the different import options available when using the Netlist Translator. Depending on your needs, you can choose between the various options for optimum translation results.

Import Options

With all methods of translation, you should compare your results against your original netlist if the size of the file permits. Once you are comfortable with your translation into ADS, place the appropriate stimulus and simulator control elements and simulate your design as described in Simulating the Translated Netlist.

Importing a File from the Command Line

This section describes the details of setting up and operating the Netlist Translator from the command line.

Note It is recommended that only advanced users attempt to import files from the command line since it requires knowledge of setting environment variables and working in a UNIX shell or DOS window.

Setting up the Nettrans Command

To set up the nettrans program for use from the command line:

For Windows platforms:

1. Open an MSDOS shell.
2. Set your $HPEESOF_DIR environment variable to your ADS installation directory. For example,
   set HPEESOF_DIR= <ADS_install_dir>
3. Set your PATH environment variable to include the $HPEESOF_DIR\bin directory. For example,
   set path=C:\AdvDesSys\bin;%path%
4. Set the appropriate library path for your operating system. For example,
   set shlib_path=$shlib_path:$HPEESOF_DIR\lib\win

For UNIX platforms:

1. Set your $HPEESOF_DIR environment variable to your ADS installation directory. For example, if using the Korn shell enter:

   export HPEESOF_DIR= <ADS_install_dir>

2. Set your PATH environment variable to include the $HPEESOF_DIR/bin directory. For example, if using the Korn shell enter:

   export PATH=$HPEESOF_DIR/bin:$PATH

3. Set the appropriate library path for your operating system. For example, if using the Korn shell.

For HP-UX operating systems (i.e. HP-UX 11 and 11i), enter the following:
SHLIB_PATH=$SHLIB_PATH:$HPEESOF_DIR/lib/hpux11

For SUN operating systems (i.e. Solaris 8 and 9), enter the following:
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HPEESOF_DIR/lib/sun58

For Linux operating systems, enter the following:
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HPEESOF_DIR/lib/linux_x86

Executing the Nettrans Command

The nettrans command uses the following general syntax:

nettrans input_filename output_filename -{s2|s3|p|h|pl} -{g|u|w} [-l] [-n]

For Spectre use the pl parameter followed by spectre . The following is command syntax specific to Spectre:

nettrans input_filename output_filename -pl spectre -{g|u|w} {-bc} [-l] [-n] {-ip}

Simply entering nettrans at the command line with no parameters displays a detailed nettrans usage message. Entering the nettrans -v command displays the translator version, while entering nettrans -adv displays the syntax for the advanced options. The following table displays a listing of all parameters and definitions used by the nettrans command.

Parameter Definitions for nettrans

Enter the appropriate nettrans command from the command line to translate your Spectre file. Once the nettrans command is complete you can view the output.

Additional Options Information

Using the -n Option

If the -n option is used, names are not mapped to the lower case. If case mixing was used in the file, the variable, instance and model names will not be converted to lower case. For more information on case sensitivity and name mapping, refer to Understanding Capitalization.

Using the -pp Option

ADS does not directly support parameter default values that reference values of other parameters passed into the subcircuit. This option will introduce logic in the translated netlist to manage reference values. See Example Spectre Subcircuit with Referenced Parameter Value for an example using the -pp option.

Using the -se Option

Without this option, any Spectre parameters that reference a previous parameter in the subcircuit list will be pulled out of the subcircuit list and treated as an ordinary equation in the subcircuit. This option allows you to keep these parameters in place. Some manually editing is required to allow the netlist to simulate without errors.

Using the -si Option

The -si <include_file> option will translate a Spectre netlist with only a portion of the netlist outputted.
The information in the include file is used by the translator for model type resolution and other post processing needs. The contents of that file will not be output in the translated ADS netlist.

Using the -models Option

An HSpice library or model file can consist of hundreds of models, defined within a .LIB section. Each .LIB section defines one model , which may consist of a complete subcircuit. If this library file is referenced by a SPICE circuit file, only the libraries that are used will be translated. However, the user may want to translate the complete model library to a set of ADS netlist files. The -models option is available for this purpose.

To translate the complete model library in a file called mix025.l, invoke the translator from a shell command line as shown in the following example.

nettrans mix025.l net -h -g -models

The HSpice file is read and, for every .LIB section found in the library file, one ADS netlist file is output. The name of the library which is specified in the .LIB statement becomes the name of the ADS netlist file. An extension is given on the command line when the translator is invoked, and this is appended to the file name. In this case, the file extension is net. A library designated by .LIB resistor will be translated to an ADS netlist file called resistor.net.

Using the -u2 Option

When the -u option is used, connections in a schematic are made by naming nodes. This is done by placing a node name on each pin. The translator makes these connections by reading a configuration file that contains pin locations for all the element symbols that the translator uses. Subcircuit symbols are plain boxes with the appropriate number of leads and pins on them.

If you have defined a custom symbol for any element, and the pins are not in the location expected by the translator, some of the pins may not be named. Unconnected pins show up as red diamonds in the schematic. This will most likely happen when a custom library part exists in ADS and is referred to in a file. The translator does not create the subcircuit but is expected to connect to it.

When the correct pin information is not available to the translator in the spctoiff.cfg file perform the following steps:

1. Use the -u2 option from the command line as shown in the following example.
   nettrans source_file .sp output_file .iff -h -u2
   The translator will output the IFF file output file_ .iff and another file named wireLabels.log.
2. Import the IFF file from the user interface (refer to, Importing an IFF File).
   This will create a schematic with no connections. To complete the connections, make sure the component placement is satisfactory. There should be sufficient room between each component to display the parameters and the node names.
3. Save all designs in which you made changes.
4. Make sure the file wireLabels.log is in your project directory and enter the following commands on the AEL command line:

load(strcat (HPEESOF_DIR, "links/spice/spcutil.ael"));
spctoiff_connect_pins("wireLabels.log")

When the macro has finished running, the pins will all be labeled with node names and all connections will be made as specified in the Spectre file.

Using the -ip Option

The -ip < include_file > option enables you to specify either an absolute or relative path to a file that is included in a Spectre netlist. You can specify multiple paths separated by commas ( , ).

Example

The test_ip.scs file:

library  test.cap_mim
section typ
  parameters cap_mim_scale=1
  include cap_mim.ckt
endsection
endlibrary

The included cap_mim.ckt file:

inline subckt cap_mim\(TOP BOT B\)
  parameters c=0 BPCap=0 BPArea=0 BPPerim=0
  cap_mim TOP BOT capacitor c=cap_mim4_scale\*c
  cp BOT B capacitor c=BPCap
ends cap_mim

Given the Spectre netlist files test_ip.scs_ and cap_mim.ckt_ above, if you run the nettrans command with the options shown below:

nettrans test_ip.scs test_ip.net -pl spectre -g -ip <path1> <path2>

nettrans will search for the file cap_mim.ckt in the following order:

1. present working directory
2. <path1>
3. <path2>

If you have a file in one or more of the above locations, then the first occurrence of the file cap_mim.ckt will be used.

The resulting ADS netlist test_ip.net would be created as follows:

;library  test.cap_mim
#ifdef typ
 cap_mim_scale=1

inline define cap_mim \( TOP BOT B\)
parameters  c=0 BPCap=0 BPArea=0 BPPerim=0
C:cap_mim TOP BOT C=cap_mim_scale\*c
C:cp BOT B C=BPCap
end cap_mim

#endif
;endlibrary

Checking the Netlist Translator Version Number

To determine the version of the Netlist Translator that you are running perform the following steps:

1. Open a UNIX or DOS shell.
2. Ensure your environment variables are set correctly. For more information on setting environment variables, refer to Setting up the Nettrans Command.
3. Enter the following command:

   nettrans -v

The Netlist Translator displays the version number.

Netlist Translator, version <version_number>

Where <version_number> is the actual version number of the translator.

Note ADS Netlist Translator version 170. xxx or higher is required to translate Spectre files.

Viewing the Translation Log

The Spectre or SPICE to IFF translation log (see Example Translation Log File (nettrans.log)) contains important information about the netlist translation, including any error or warning messages recorded during the import operation. The translation log can be viewed using any ASCII text editor. To view the translation log file, open your text editor and load nettrans.log.

If your log file displays any error or warning messages generated by the translator, refer to Troubleshooting. Using a combination of the information in the log file and the information provided in the troubleshooting section, edit your translated netlist and save the new netlist with your corrections.

Since the translation log is an ASCII based text file, you can easily save the file with a new name using the File > Save As command for future reference.

Note The netlist to IFF translation log file (nettrans.log) is over-written each time a new translation is performed. To avoid over-writing the log file, save it with a new file name.

Importing an IFF File

This section describes how to import Intermediate File Format (IFF) files, created by the nettrans command, into Advanced Design System. The IFF importer loads the spice.iff file, generates the new ADS Schematic and writes any error messages or warnings to a log file called ifftolib.log .
The Intermediate File Format (IFF) is an ASCII file that contains a simple, line-oriented command structure with a fairly rich set of constructs. The format is machine- and application-independent, thus simplifying design data transfer. For more information on Importing an IFF file, refer to " IFF Files " in the ADS Importing and Exporting Designs manual.

Accessing the Import Dialog

To import your IFF file,
Choose File > Import from the Main window.

The Import dialog box appears.

Specifying the File Name

In the Import dialog box, choose the type of file to import, specify the filename, and supply other basic information needed by the translator.

1. In the Import dialog box that appears, select IFF from the File Type drop-down list if it isn't already displayed.
2. To specify the path and filename of the file you want to import click Browse . The Import File Selection dialog appears.
3. Double-click as needed to locate the directory containing your IFF file or enter the full path and file name in the Selection field. By default, all files are listed that have the suffix appropriate for the chosen file format.
4. Select the IFF file you want to import and click OK . You are returned to the Import dialog box and the selected filename appears in the field labeled Import File Name (Source) .
   

Setting the Import Options

In the Import dialog box, click More Options to define the IFF import options. The Import IFF Options dialog box appears.

Note The Import IFF Options dialog box that appears is dependent upon where you execute the IFF import from (i.e ADS Main , Layout or Schematic window).

Set the Import Options:

1. Ensure the Remove IFF File After Import option is deselected. When selected, the IFF file is removed once it has been successfully imported. The default option is deselected.
2. Set the Log verbose messages as desired. When this option is selected, all translation information is recorded in the ifftolib.log file resulting in step-by-step description of what happened internally during your translation. This option is primarily intended to be used as a diagnostics tool. The default mode for this option is deselected. Note that error and warning messages will always appear in your status window regardless of this selection.
3. Ensure the Synchronize ports to symbol using node name option is deselected. This option resets the symbol pin numbers to match port numbers based on the node name of the schematic port. By default, symbol pin numbers are matched to schematic port numbers based on the port's instance name.
4. Check the Default Library Name for Library Parts field. This field is used for specifying the default library name. When the IFF file does not specify a library name for a component that needs to be created, the library name specified in this field is used. The IFF files that are created by the nettrans program specify the library SPICE INPUT, so the library name in this field will not change the outcome of the import.

   Note The Default Library Name For Library Parts field is identical to the field of the same name in the Export IFF Options dialog box. Changes made to this field will modify the contents of the field in the Export IFF Options dialog box.

5. Accept the default Trace setting within the Trace Handling field. This field is normally used to enable you to select how you want layout traces interpreted during a translation. Because the Netlist Translator does not support layout import and export, this field is not used.
6. Click OK to save your settings or Cancel to retain the default settings. You are returned to the Import dialog box and the selected filename appears in the field labeled Import File Name (Source) .
7. Click OK to import the IFF file into ADS. The IFF Importer performs the automatic translation of your IFF file into an ADS Netlist.

About Component Libraries

A component library in ADS consists of a collection of component definitions. Each primitive component has an associated component name, symbol and predefined component parameters that include relevant physical and electrical characteristics.

The IFF translator can be used as the initial step in creating an ADS component library; however, this topic is outside of the scope of this manual. Creating an ADS component library using IFF requires specialized tools and training. If you are interested in learning more about this topic, contact Agilent EEsof-EDA's Solution Services.

Adding the NetlistInclude Component

In Advanced Design System, you can insert a saved netlist file into an ADS simulation via an include statement by using the NetlistInclude component. The NetlistInclude component is used to link the netlist that was translated into an ADS netlist, to the ADS schematic capture environment at the time of simulation.

The NetlistInclude component enables you to accomplish the following:

• Add parameter definitions, equations, and special sub-circuits from your design to the Advanced Design System schematic.
• Initialize technology dependent model parameters or variables in a file that can then be automatically inserted into the ADS netlist.
• Allow sectional includes to handle corner case analysis.
  You can use a NetlistInclude in the following placements:
• In the top level of hierarchy, if the included file contains subcircuit definitions (it can contain an entire model library)
• In any circuit, if the included file contains only variables and/or model cards
  A NetlistInclude component referencing a file containing subcircuit definitions cannot be placed on a schematic that is not at the top level of hierarchy, unless you do the manual steps defined below.

Manual Translation and Placement of a NetlistInclude Component

Note For ADS 2004A and ADS 2003C, these steps are only necessary when doing manual translation and placement of the NetlistInclude component. When using the user interface for a translation to an ADS netlist, the ITEM_NOSUBNET_HEADER_EX field is set by the translator.

Suppose you have a top level design that includes a component abc and a DC simulation component. If the subcircuit named abc contains a NetlistInclude component that references a file with a subcircuit xyz , the resultant netlist would look like the following:

define abc (in out)
define xyz (input output)
parameters R1
R:R1 input output R=R1
end xyz
end abc

abc:x1 _net1 0 

DC: DC1

In ADS, the nested define statements ( xyz defined within the definition of abc ) would cause an error such as the following when simulated:

Error detected by HPEESOFSIM during netlist parsing.
        In file 'netlist.log' at, or just before, line 7.
                Syntax error in component call:
                define xyz (input output)
^

To avoid this situation, you must manually modify the AEL item definition for the subcircuit. Discussion of item definitions is beyond the scope of this manual. Please refer to the Advanced Design System AEL manual.

If you have a basic understanding of the item definition, you can proceed to modify the Extra item attribute, which is field 15 in the create_item() function. To find this function, go to the networks subdirectory of your project directory and edit the ael file that has the same name as the design ( abc in this example). This field needs to be set to ITEM_NOSUBNET_HEADER_EX. This tells the ADS netlister not to put the define and end statements around the contents of the subcircuit. This will cause another problem in that abc will not be defined at all now. To avoid this situation, abc should be defined in your original Spectre netlist.

Note If it is at all possible, avoid placing a NetlistInclude component that references a file containing one or more subcircuits anywhere other than the top level of your design hierarchy.

Placing a NetlistInclude Component

If you imported your netlist using the command line, you will need to insert a NetlistInclude component in your new schematic.

To place a NetlistInclude component in an ADS schematic:

1. Select the Data Items component palette from the ADS schematic window.
2. Click the NetlistInclude component to place the component on the schematic. An instance is attached to your cursor. Place the component instance on the schematic as desired (click to place).
   

   The NetlistInclude Component

3. You can continue to place component instances or choose the Cancel Command And Return To Select Mode icon to proceed with the next step.
4. To edit the netlist specifications choose Edit > Component > Edit Component Parameters or click the NetlistInclude component on the schematic.

A dialog box appears, enabling you to specify the parameters of the file to include. See the table Parameter Definitions for the NetlistInclude Component for a description of each parameter.

Note You can also click the line to be changed directly in the schematic instance and edit as desired.

Parameter Definitions for the NetlistInclude Component

Using a Custom Component

If you have created a custom component in Advanced Design System that you want the system to use in place of the default ADS component when it imports a Spectre netlist, you must create a translation table in the Import Netlist Options dialog box that specifies which custom component to use.

Creating a Translation Table

A translation table is simply a two column table that does the following:

• Specifies a standard ADS component (left-hand column) and the custom ADS component (right-hand column) used to replace it

• Specifies the standard ADS component parameters (left-hand column) and the custom ADS component parameters (right-hand column) used to replace them
  To create the translation table perform the following steps:

1. Begin your normal import operation. See Importing a Netlist File Using the User Interface.
2. When you are Defining Netlist Options using the Import Netlist Options dialog box, enter the translation table in the Element Replacement Table field.

Refer to the Example Translation Table for an example of how to format the information in the Element Replacement Table field.

Example Translation Table

# Standard ADS Component
# +Standard ADS Component Parameter
R
+R
+Tnom

Custom ADS Component
Custom ADS Component Parameter
MYR
Res
T

Comment Character - The system recognizes the pound sign ( # ) as a comment character. Note that the first two lines in Example Translation Table are comments used to describe the elements of the table.

Component - Both the standard ADS component ( R ) and the custom ADS component ( MYR ) are given in line 3 of Example Translation Table. On import, any time the translator would normally place the R component in ADS, the system will place a MYR component instead.

Note The component name ( R ) in the left-hand column is not the Spectre name. It is the ADS component that would be placed if the table were not used. Performing the import first, without the mapping, will allow you to see the name of the component to be replaced.

Component Parameters - Component parameter mappings are listed one per line following the component name. Each parameter line starts with the + character. List only the parameters that are unique to the custom component. It is not necessary to list the parameter names on the custom component that are the same as the ADS component; the translation automatically matches the correct parameters.

The only limitation on import is that new items have a similar symbol to the replaced component so that the placement and wiring of the schematic work correctly. This means that the custom symbol should be approximately the same size as the default component, and the pins must be in the exact location on the two symbols. If the pins are not in the same location, the -u2 option must be used. For more information on the -u2 option, refer to Executing the Nettrans Command.

To access the component mapping functionality while running the translator from the command line, use the -m option. You create the file from scratch or modify the spice.map file that is created in the project directory when an import is performed from the user interface. For more information on using the -m option, refer to Executing the Nettrans Command.

Example Netlist Translation

The following shows an example comparison of how the system might translate a SPICE netlist to an ADS netlist with or without the custom component defined in Example Translation Table.

Using the Example Spice Netlist in Netlist Comparison, if no custom component was defined, the translator would generate the ADS Netlist (without mapping). Using the translation table in Example Translation Table, the resultant ADS netlist would appear as in the ADS Netlist (using a translation table) in Netlist Comparison.

Netlist Comparison

Note If your file contains functions that are not Advanced Design System functions, refer to Using Non-ADS Functions.

Modifying the Translator Configuration File

The translator configuration file, spctoiff.cfg , is a file that is used when the translator creates a schematic. It is stored in $HPEESOF_DIR/config. This file contains pin locations and sizes for the symbols of all the components that the translator knows how to translate.

Since the Netlist Translator runs as a separate process from ADS (see Understanding the Import Operation), the translator cannot determine this information on the fly. Periodically, symbols will be updated but the translator configuration file will not be updated at the same time. In this case, you can manually modify the file if needed to avoid overlapping components in the schematic.

The file consists of a block of information for each component. The first component in the file is the Capacitor (C).

C 2 0 -0.625 0 .625 1.5 -3.25 0 0

There are four lines that start with C. The C is followed by an integer number which indicates the number of pins on the component. This is followed by an integer number that indicates the rotation in degrees of the component.

The next four fields define the *bounding box* of the symbol, calculated with the default settings for parameter visibility. If you choose to make all parameters visible while editing the schematic or if you make the font of the parameters larger than default, you may need to increase the size of the bounding box, or spread your components out on the schematic.

The final two coordinates on the first line are ignored.

The following two lines are the pin information.

0 0 180	Pin 1 is located at 0,0 on the symbol (the origin) and rotated to 180 degrees.
1 0 0	Pin 2 is located at 1,0 on the symbol and placed at 0 rotation.

In the rare case that this file needs to be modified, usually only the bounding box information would have to be modified. If there seems to be a problem with the file, you can request an updated file from Agilent EEsof-EDA Customer Support, or you can make a few simple changes yourself if it is needed urgently.

The file can be modified for your installation by a system administrator. For individual use, a copy of the file can be placed in the user's $HOME/hpeesof/config directory. The file located in the user's directory will take precedence over the system file. For command line execution or batch processing, the file can also be placed in the directory where the translator is running.

• The bounding box of a symbol is the technical term for the rectangular space occupied by a symbol on the schematic. The four coordinates given are the upper left corner and the lower right corner, when the origin of the component is placed at 0,0 on the schematic. The origin of the component is the position that is tied to the mouse when the drag image is visible. Where you click the mouse to place a component becomes the location where the origin of the component is placed. This hot-spot is usually pin 1.

Importing an HSpice File from Cadence after Parasitic Extraction

HSpice files output from Cadence have been observed to have syntax errors that will not be corrected by the translator. Some of these syntax errors need to be corrected manually before importing or they will cause the ADS simulation to fail. Others may be corrected after the translation and before simulation.

Make the following changes to your ADS netlist or schematic before starting the import:

• Expressions are usually enclosed in single quotes. Occasionally, expressions have been observed to be enclosed in double quotes, which are not valid. This must be corrected before the file can be translated or the translator will drop part of the expression.

Make the following changes to your ADS netlist or schematic after the import has completed:

• Values have been observed with non-matching pairs of parentheses. These will be passed through the translator but cause the simulator to fail. This can be fixed prior to translation or prior to simulation.

• Files have been observed with multiple declarations of the same variable. All will pass through the translator but cause an error in the simulator. Parameters should be declared only one time. Remove the extra parameters and re-simulate.

• Subcircuit calls have been seen with parameters that were not declared on the subcircuit when it was defined. Again, the translator will not check for this error but the simulator will halt with an error. Remove the extra parameters and resimulate.

Using Non-ADS Functions

If your file contains functions such as gauss() or pwr() or any other function that is not a built-in ADS function, the simulator will give an Unresolved reference error.

Look for the function in the supplied function file:

$HPEESOF_DIR/links/spice/spicefunction.net (for SPICE functions)

The function can be copied into the ADS netlist, placed in the schematic, or the whole file can be included by entering the following line in the ADS netlist:

#include "< path >/spicefunctions.net" (for SPICE functions)

Replace < path > with the correct location for your system.

For Spectre translations you do not need to do anything special. Any functions that are listed in the spectrefunc.rul file will automatically be substituted into the new ADS netlist after translation.