Capsim TCL Scripting Support
Capsim V6 has scripting support using a built in TCL interpreter. A major goal of adding TCL scripting is to support iterative simulations, to support TCL command interface to numerical packages such as LAPACK and to script the built in Transmission Line Network Modeling package.
The TCL commands support all of the Capsim commands with the addition of new commands to refer to parameters by name and to change their value. Also Capsim blocks can return values from simulations via TCL variables.
Capsim's built in TCL interpreter supports commands for solving complex and real eigenvalue, singular value decomposition problems and solutions to least squares problems. The interpreter includes many other vector and matrix operations, among them, matrix inversion and QR factorization.
The Capsim TCL interpreter can plot images of matrices, manipulate color tables and produce plots of vectors including support for scripting of plots for complete automation.
Capsim runs at full throttle ( C based ) when controlled by scripts.
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.
The Global Arguments are shown below. Note the number of bits to simulate is arg 3.
In the TCL script below the Capsim TCL commands are shown in bold with larger font size.
#
# 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 (setsnr0)
# the current block. We then set the parameter
# using the Capsim TCL command parambynam
#
arg 3 int $numbits "number of bits"
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. The Figure below 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.
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
#make the sine0 block the current block
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
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
Silicon DSP Corporation
