CapsimTMK TCL Scripting Support

 

 

Introduction

 

CapsimTMK V6 has  scripting support using a built in TCL interpreter. A major goal of adding TCL scripting is to support iterative simulations and to support TCL command interface to numerical packages such as LAPACK.

The TCL commands support all of the CapsimTMK commands with the addition of new commands to refer to parameters by name and to change their value. Also CapsimTMK blocks can return values from simulations via TCL variables.

 

TCL Script

 

The best way to see the power of TCL scripting is to review  a TCL script for creating a table of BER (bit error rate) versus SNR (signal to noise ratio) in the simulation of a QPSK digital link.

 

#
# TCL Script that tabulates the BER for various SNR's
# The sys-ete-ber.t topology implements a 
# QPSK digital communications link
# The number of bits is different for each SNR 
# The script demonstrates coupling of two different 
# paramters per simulation.
# The script stores the results of each run in a list.
# At the end of the iteration loop the results are
# tabulated.
#
# Author: Sasan Ardalan
# June 25th, 2006
#

new

set snr { -2 0 2 5  7 }

set bits { 10000 10000 100000 100000 10000000 }

capload sys-ete-snr.t

set berResults [list {}]

foreach snrVal  $snr numbits $bits {

    #
    # for each value of SNR $snr and corresponding
    # number of bits $bits set the parameters 
    # in the topology. The number of bits is a global 
    # parameter in arguments.
    # to change the SNR we first make the set SNR block
    # the current block. We then set the parameter 
    # using the Capsim TCL command parambynam
    #

    arg 3 int $numbits  "number of bit
    to setsnr0
    parambyname snr $snrVal
   run

    #
    # when the simulation is run, at the end of the 
    # simulation the ecountfap0 block stores the BER in
    # the TCL variable $ecountfap0_ber
    #

    puts -nonewline "$snrVal : $numbits "
    puts "BER=$ecountfap0_ber"

    # gather the results in a list for each simulation

    lappend berResults [list $snrVal $ecountfap0_ber ]

}

#
# Create a table of BER versus SNR
#

puts [ llength $berResults ]
puts -nonewline SNR
puts -nonewline "\t"
puts   BER

foreach value $berResults {
    puts  -nonewline [lindex $value 0]
    puts  -nonewline "\t"
    puts   [lindex $value  1]
}

 

In the above script the key points are that once a topology is loaded, sys-ete-snr.t in this case, we can access any block parameter by name. We can also access the topology arguments. Furthermore, once a simulation is run, blocks can store their results in TCL variables. In this case the BER is stored in the variable $ecountfap0_ber.

The results of the simulation are:

 

SNR  BER
-2   0.05677
0    0.023237
2    0.005626
5    0.000220
7    5.000000e-06

  Another important aspect of TCL scripts is that TCL commands including mathematical expressions can be used to set parameter  values prior to running a simulation.

 

Finally, using TCL scripting algorithms can be developed for optimization of designs. In addition, sensitivity studies can be performed where the sensitivity of overall system performance to parameter  variation  can be analyzed.

 

Here is another Capsim TCL script example. Figure 1 shows the topology for iirtest.t. A sine wave is generated and filtered by an IIR low pass filter. Its rms value is calculated using the stats block. The TCL script changes the frequency parameter in the sine block (freq), runs a simulation, and retrieves the measured RMS value of the filter output from the stats block. The stats0 block returns the RMS value as a TCL variable stats0_rms.

 

 

Figure 1 iirtest Topology

 

#
# TCL Script that iterates a number of simulations
# The iirtest topology is a sine wave filtered by a low pass IIR filter
# The filtered samples are processed by the "stats" block which computes the 
# RMS value.
# The script stores the results of each run in a list.
# At the end of the iteration loop the results are tabulated.
#
# Author: Sasan Ardalan
# June 25th, 2006
#

new
capload iirtest

#turn the printer probe off
to prfile0
parambyname control 0
set freq 0
to sine0

set results [list {}]

for { set i 0}  { $i < 10 } { incr i} {
   set freq [expr $freq+1000]
   puts $freq
   parambyname freq $freq
   run
   puts $stats0_sigma
   lappend results [list $freq $stats0_sigma] 

}

puts -nonewline Freq
puts -nonewline "\t"
puts   RMS

foreach value $results {

   puts  -nonewline [lindex $value 0]
   puts  -nonewline "\t"
   puts   [lindex $value  1]

}

The results of the simulation are:

 

Freq    RMS
1000    0.68096101284
2000    0.690733492374
3000    0.672446846962
4000    0.152041137218
5000    0.038574591279
6000    0.027747457847
7000    0.0252503212541
8000    0.0251301862299
9000    0.0249269343913
10000   0.0243778862059 

The iirtest.t topology is provided below. Note that the freq parameter that changes the frequency of the sine wave generator block is highlighted ( the TCL command parambyname is used to change the frequency):

 

arg -1 (none)                    

param int 128    num_of_samples   "total number of samples to output"
param float 1    magnitude   "Enter Magnitude"
param float 32000    fs   "Enter Sampling Rate"
param float 1000    freq   "Enter Frequency"
param float 0    phase   "Enter Phase"
param float 1    pace_rate   "pace rate to determine how many samples to output"
param int 128    samples_first_time   "number of samples on the first call if paced"
block sine0 sine                    

param file stdout    file_name   "Name of output file"
param int 1    control   "Print output control (0/Off, 1/On)"
param int 0    bufferType   "Buffer type:0= Float,1= Complex, 2=Integer"
block prfile0 prfile                    

param int 0    skip   "Points to skip"
param file stat.dat    stat_file   "File to store results"
block stats0 stats                    

param int 3    desType   "1=Butterworth,2=Chebyshev,3=Elliptic"
param int 1    filterType   "1=LowPass,2=HighPass,3=BandPass,4=BandStop"
param float 32000    fs   "Sampling Frequency, Hz"
param float 0.1    pbdb   "Enter Passband Ripple in dB's"
param float 35    sbdb   "Enter Stopband Attenuation in dB's"
param float 3400    fpb   "Passband Freq. Hz/LowPass/HighPass Only"
param float 4400    fsb   "Stopband Freq. Hz/LowPass/HighPass Only"
param float 220    fpl   "Lower Passband Freq. Hz/BandPass/BandStop Only"
param float 3400    fpu   "Upper Passband Freq. Hz/BandPass/BandStop Only"
param float 10    fsl   "Lower Stopband Freq. Hz/BandPass/BandStop Only"
param float 4400    fsu   "Upper Stopband Freq. Hz/BandPass/BandStop Only"
param file tmp    name   "Filter name"
block iirfil0 iirfil                    

connect sine0 0 iirfil0 0       
connect prfile0 0 stats0 0      
connect iirfil0 0 prfile0 0

2 Capsim TCL Command Summary

 

In the following summary of TCL commands, most commands  are exactly the same as the Capsim commands with the following exceptions:

 

To store a topology the TCL command is capstore instead of store.

To load a capsim topology the TCL command is capload instead of load.

The Capsim command info in TCL is getinfo. 

TCL Commands:

 

display                     [g or s]

block                       block_model,or block block_name block_model

replace                            block_model,or block block_name block_model

HBlock                           block_model, or HBlock block_name block_model

chp                                   [param number] [paramvalue]

connect                           blockNameSrc [port] blockNameDest [port]

disconnect                     blockNameSrc [port] blockNameDest [port]

run

new

to                                      path_to_block

capstore                         [file_name]

capload                          file_name

arg                                   argnum argtype argval "argprompt"

up

down

back

forward

setCellInc                      integer (number of cells allocated to increase buffer         FIFO)

setMaxSeg                     integer (Maximum number of cell increments, setting too high may cause memory over flow. Too low results in buffer over flow)

path                                 [sgd] thePath

remove

delete

insert                               <-,+> <specifiedBlockName> <i,o number>

signame                          name_to inNum sigName

inform                            field info

makecontig

state

getinfo

man                                 block

parambyname             name value