Wim Vanderbauwhede > Simulation-Automate-1.0.1 > Simulation::Automate

Download:
Simulation-Automate-1.0.1.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 1.0.1   Source  

NAME ^

Simulation::Automate - A Simulation Automation Tool

The set of modules is called Simulation::Automate.

The tool itself is called SynSim, the command synsim.

REQUIREMENTS ^

SYNOPSIS ^

       use Simulation::Automate;

       &synsim();

DESCRIPTION ^

SynSim is a generic template-driven simulation automation tool. It works with any simulator that accepts text input files and generates text output (and even those that don't. See "EXAMPLES" for special cases). It executes thousands of simulations with different input files automatically, and processes the results. Postprocessing facilities include basic statistical analysis and automatic generation of PostScript plots with Gnuplot. SynSim is entirely modular, making it easy to add your own analysis and postprocessing routines.

INSTALLATION ^

1. Download and extract the archive

1. Download the gzipped tar file Simulation-Automate-0.9.5.tar.gz
2. Extract the archive:
        tar -zxvf Simulation-Automate-0.9.5.tar.gz

2. Simple local installation

This installation procedure will install the Simulation::Automate modules in a directory of your choice, and create a template directory structure for your SynSim project.

1. Run the local install script:

In the main directory of the distribution (i.e. the directory which contains the file local_install.pl), type:

   perl local_install.pl
2. Enter the installation directory

The install script asks for the name of the directory in which it will put SynSim:

   Local SinSym directory? [/local/home/wim/SynSim]:

If you enter just a name, the installer assumes that the directory is in your home directory. If you want to install SynSim outside your home directory, enter a full path.

3. Enter the project directory name

The install script asks for the name of directory where you will run SynSim:

    Simulation project directory? [SynSimProject]:

This directory is a subdirectory of the local SynSim directory.

That's it. Now you can go to your project directory and run the synsim script as a test:

    ./synsim

This will run a simple test. If the installation was succesful, it will display the follwing message:

    SynSim Installation Test
 
    Simulation::Automate version 0.9.6
 
    installed locally in /home/wim/SynSim/Test
 
    Finished SynSim run

3. Perl-style installation

This is the typical Makefile.PL-driven installation procedure. It is only required for system-wide installation, but it works for local installation as well.

1. Create the Makefile:
        cd Simulation-Automate-0.9.5
        perl Makefile.PL
2. Make Simulation::Automate:
        make
3. Test Simulation::Automate:
        make test
4. Install Simulation::Automate:

This requires you to be root:

        su
        make install

or

        sudo make install
5. For a local installation

This does not require you to be root:

        make localinstall

or

        perl -e "use Simulation::Automate;
                 &Simulation::Automate::localinstall();"
6. Setup your local SynSim project (

SynSim is the name for the tool contained in Simulation::Automate. This step creates the directory structure for your simulations:

        make setup
or

        perl -e "use Simulation::Automate;
                 &Simulation::Automate::setup();"

4. Archive structure

The archive structure is as follows:

        README    
        Makefile.PL       
        Automate.pm
        local_install.pl
        Automate/
                Remote.pm
                PostProcLib.pm
                Analysis.pm
                Dictionary.pm
                PostProcessors.pm

        eg/
                synsim  
                synsim.data
                ErrorFlags.data
                Histogram.data
                SweepVar.data
                Expressions.data
                gnuplot.data
                SOURCES/
                        bufsim3.cc
                        MersenneTwister.h
                TEMPLATES/              
                        test.templ
                        DEVTYPES/
                        SIMTYPES/
                                bufsim3.templ
                PLUGINS/                

CONFIGURATION ^

To configure SynSim for use with your simulator, you must create a set of files in your SynSim project directory structure. This paragraph gives an overview of the different types of files and their place in the SynSim project directory structure.

SynSim project directory structure

You can create a SynSim directory structure with perl local_install.pl or make setup (see "INSTALLATION" for details). If you already have an existing project, you can do this:

If you want to create it manually, this is the structure. Directories between square brackets are optional.

        YourProject/
                        synsim  
                        YourDataFile.data
                        [SOURCES/]
                        TEMPLATES/              
                                 YourSimTempl.templ
                                 [DEVTYPES/]
                                 [SIMTYPES/]
                                 [PLUGINS/]
        [Simulation/SynSim/]
                                [Dictionary.pm]
                                [PostProcessors.pm]                     

The synsim script is the actual script that runs the DOE. It contains the 2 lines from the "SYNOPSIS". The local Simulation/Automate modules are only required if you want to customize the postprocessing.

Source files

The directory SOURCES/ is optional. It should contain all files which are required "read-only" by your simulator (e.g. header files, library files, wrappers).

Template files

Template files are files in which simulation variables will be substituted by their values to create the input file for your simulator. They must be stored in the TEMPLATES/ directory, and have by convention the extension .templ.

SynSim variable format

The template file format is free, but the variables to be substituted by SynSim must be in uppercase and start with an underscore:

Examples:

        _VAR1
        _LONG_VARIABLE_NAME

To create a template file, start from an existing input file for your simulator. Replace the values of the variables to be modified by SynSim by a SynSim variable name (e.g. var1 = 2.5 => var1 = _VAR1). Put the template files in TEMPLATES.

Note: Relative paths to source files

SynSim creates a run directory ath the same level as the SOURCES and TEMPLATES directories. All commands (compilations etc.) are executed in that directory. As a consequence, paths to source files (e.g. header files) should be "../SOURCES/sourcefilename".

Note: The DEVTYPES/ and SIMTYPES/ subdirectories

SynSim can create an input file by combining two different template files, generally called device templates and simulation templates. This is useful in case you want to run different types of simulations on different devices, e.g. DC analysis, transient simulations, small-signal and noise analysis on 4 different types of operational amplifiers. In total, this requires 16 different input files, but only 8 different template files (4 for the simulation type, 4 for the device types). If you want to use this approach, device templates should go in TEMPLATES/DEVTYPES/ and simulation templates in TEMPLATES/SIMTYPES/. SynSim will check both directories for files as defined in the datafile. If a matching file is found in DEVTYPES, it will be prepended to the simulation template from SIMTYPES.

Datafile

The datafile is the input file for synsim. It contains the list of simulation variables and their values to be substituted in the template files, as well as a number of configuration variables. See "DATAFILE DESCRIPTION" for more information.

Postprocessing and Preprocessing (optional)

The PostProcessing.pm module contains routines to perform postprocessing on the simulation results (e.g. plotting, statistical analysis, etc). A number of generic routines are provided, as well as a library of functions to make it easier to develop your own postprocessing routines. See "POSTPROCESSING" for a full description).

Before the raw data are sent to the postprocessor, it is possible (and very easy) to preprocess the raw data. See "PREROCESSING" for more details.

Custom postprocessing and preprocessing routines can either be stored in the PLUGINS/ directory (preferred) or directly in the local PostProcessing.pm module (more intended for modified versions of the generic routines).

Dictionary (optional)

The Dictionary.pm module contains descriptions of the parameters used in the simulation. These descriptions are used by the postprocessing routines to make the simulation results more readable. See "DICTIONARY" for a full description).

DATAFILE DESCRIPTION ^

The datafile defines which simulations to run, with which parameter values to use, and how to run the simulation. By convention, it has the extension .data.

Syntax

The datafile is a case-sensitive text file with following syntax:

Comments and blanks

Comments are preceded by '#'. Comments, blanks and empty lines are ignored

Parameters

Parameters (simulation variables) are in UPPERCASE with a leading '_', and must be separated from their values with a '='.

Keywords

Keywords (configuration variables) are in UPPERCASE, and must be separated from their values with a ':'.

Lists of values

Lists of values have one or more items. The list separator is a comma ','.

Example:

        _PAR1 = 1,1,2,3,5,8,13

If a list has 3 elements START,STOP,STEP, then if possible this list will be expanded as a for-loop from START to STOP with step STEP.

Example:

       _NBUFS = 16,64,8 #  from 16 to 64 in steps if 8: 16,24,32,40,48,56,64
Section headers for multiple simulation types (optional)

These must be lines containing only the simulation type

Simulation variables

The main purpose of the datafile is to provide a list of all variables and their values to be substituted in the template files.

Default behaviour: combine values

A simulation will be performed for every possible combination of the values for all parameters.

Example:

        _PAR1 = 1,2
        _PAR2 = 3,4,5

defines 6 simulations: (_PAR1,_PAR2)=(1,3),(1,4),(1,5),(2,3),(2,4),(2,5)

Simulation results for all values in ','-separated list are stored in a separate files.

Alternative behaviour: group values

It is possible (See the keyword GROUP under "Configuration variables") to define groups of variables. For every parameter in a group, the value list must have the same number of items. The values of all variables at the same position in the list will be used.

Example:

        GROUP: _PAR1,_PAR2

        _PAR1 = 0;1;2;4
        _PAR2 = 3;4;5;6

defines 4 simulations: (_PAR1,_PAR2)=(0,3);(1,4);(2,5);(4,6)

Configuration variables

A number of configuration variables ("keywordsw) are provided to configure SynSim's behaviour. There is no mandatory order, but they must appear before the simulation variable. For the default order, see the "EXAMPLES". In alphabetical order, they are:

ANALYSIS

Alternative names: ANALYSIS_TEMPLATE, ANATEMPL

Name of the routine to be used for the result analysis (postprocessing). This routine must be defined in PostProcessors.pm or in a file in the PLUGINS/ directory. A number of generic routines are provided, see "POSTPROCESSING".

COMMAND

The command line for the program that runs the input file, i.e. the simulator command (default: perl). SynSim looks for the words INPUTFILE and <OUTPUTFILE> and substitutes them with the actual file names.

Examples:

        yoursim1 -i INPUTFILE -o OUTPUTFILE
        yoursim2 INPUTFILE > OUTPUTFILE
DEVTYPE (optional)

The name of the device on which to perform the simulation. If defined, SynSim will look in TEMPLATES/DEVTYPES for a file with TEMPL and DEVTYPE, and prepend this file to the simulation template before parsing. This keyword can take a list of values

EXT

Extension of input file (default: .pl)

Some simulators expect a particular extension for the input file. This can be specified with the keyword EXT.

GROUP (optional)

This keyword can be used to change the default behaviour of creating nested loops for every parameter. It takes as argument a list of parameters. The behaviour for grouped parameters is to change at the same time. All parameter lists in the group must have the same number of values. More than one group can be created.

Example:

        # First group: 2 parameters, each 4 values
        GROUP: _PAR_A1,_PAR_A2
        # Second group: 3 parameters, each 3 values
        GROUP: _PAR_B1,_PAR_B2,_PAR_B3
        # SynSim will run 4*3 simulations (default without groups would be 16*27)

        _PAR_A1 = 0;1;2;4
        _PAR_A2 = 3;4;5;6

        _PAR_B1 = -1;1;2
        _PAR_B2 = 3;4;7
        _PAR_B3 = 3;6;15
INCLUDE (optional)

If the value of INCLUDE is an exisiting filename, this datafile will be included on the spot.

NORMVAR (optional)

The name of the variable to normalise the results with. The results will be divided by the corresponding value of the variable.

NRUNS (optional)
OUTPUT_FILTER_PATTERN (optional)

A Perl regular expression to filter the output of the simulation (default : .*). Tis is very usefull for very verbose simulators. The results file will only contain the filtered output.

PREPROCESSOR (optional)

The name of a function which modifies @results before the actual postprocessing. Very usefull to "streamline" the raw results for postprocessing.

TEMPLATE

Alternative names: SIMULATION, SIMTEMPL, SIMTYPE

The name of the template file, with or without extension. By convention, this is the same as the type of simulation to be performed. If no extension is given, SynSIm checks for a TEMPLEXT keyword; if this is not defined, the extenstion defaults to .templ. SynSim will look for the template file in TEMPLATES/ and TEMPLATES/SIMTYPES/.

Note: Multiple simulation types

The value of SIMULATION can be a ','-separated list. In this case, SynSim will use the datafile for multiple types of simulations. Every item in the list can be used as a section header, demarkating a section with variables particular to that specific simulation.

TEMPLEXT (optional)

Extension of template files (default: .templ)

TITLE

The title of the DOE. This title is used on the plots, but typically it is the first line of the datafile and describes the DOE.

XVAR (optional)

Alternative name: SWEEPVAR

The name of the variable to be sweeped. Mandatory if the postprocessing routine is XYPlot.

The number of times the simulation has to be performed. For statistical work.

XCOL (optional)

The column in the output file which contains the X-values.

YCOL (optional)

Alternative name: DATACOL

The column in the output file which contains the simulation results (default: 2). Mandatory if using any of the generic postprocessing routines.

XLABEL, YLABEL, LOGSCALE, PLOTSTYLE, XTICS, YTICS, XSTART, XSTOP, YSTART, YSTOP (optional)

Variables to allow more flexibility in the customization of the plots. They are identical to the corresponding (lowercase) gnuplot keywords, see the gnuplot documentation for details. The most commonly used, XLABEL and YLABEL are the X and Y axis labels. LOGSCALE is either X, Y or XY, and results in a logarithmic scale for the chosen axis.

Expressions

The SynSim datafile has support for expressions, i.e. it is possible to express the value list of a variable in terms of the values of other variables.

Example:

    # average packet length for IP dist 
    _MEANPL = ((_AGGREGATE==0)?2784:9120)
    # average gap width 
    _MEANGW= int(_MEANPL*(1/_LOAD-1)) 
    # average load
    _LOAD = 0.1;0.2;0.3;0.4;0.5;0.6;0.7;0.8;0.9
    # aggregate 
    _AGGREGATE =  0,12000

The variables used in the expressions must be defined in the datafile, although not upfront. Using circular references will not work. The expression syntax is Perl syntax, so any Perl function can be used. Due to the binding rules, it is necessary to enclose expressions using the ternary operator ?: with brackets (see example).

RUNNING SYNSIM ^

The SynSim script must be executed in a subdirectory of the SynSim directory which contains the TEMPLATES subdir and the datafile (like the Example directory in the distribution).

The command line is as follows:

        ./synsim [-h -D -i -p -P -v -N ] [datafile] [remote hostname]

The synsim script supports following command line options:

        none: defaults to -f synsim.data
         -D : Create an empty SynSim directory structure in the current directory.
         -v : 'verbose'. Sends simulator output to STDOUT
         -i : interactive. Calls gv or ggv to display a plot of the results.
              Implies -p -v.  
         -p : plot. This enables generation of postscript plots via gnuplot. 
              A postprocessing routine is required to generate the plots.
         -P : Plot. This option can be used to display plots created with -p.
         -w : 'warnings'. Show warnings about undefined variables.
         -N : 'No simulations'. Performs only postprocessing.
         -h, -? : short help message

If [remote hostname] is provided, SynSim will try to run the simulation on the remote host.

The current implementation requires:

-ssh access to remote host

-scp access to remote host

-rsync server on the local host

-or,alternatively, an NFS mounted home directory

-as such, it will (probably) only work on Linux and similar systems

POSTPROCESSING ^

Postprocessing of the simulation results is handled by routines in the PostProcessors.pm module. This module uses the PostProcLib.pm and optionally Dictionary.pm and Analysis.pm.

Generic Postprocessors

SynSim comes with a number of generic postprocessing routines.

XYPlot

Required configuration variables: XVAR

Creates a plot using XVAR as X-axis and all other variables as parameters. This routine is completely generic.

CondXYPlot

Required configuration variables: XVAR,CONDVAR and CONDITION.

Creates a plot using SETVAR as X-axis; XVAR is checked against the condition COND (or CONDITION). The first value of CONDVAR that meets the condition is plotted. All other variables are parameters. This routine is completely generic.

XYPlotErrorBars

Required configuration variables: XVAR, NRUNS

Optional configuration variables: NSIGMAS

Creates a plot using XVAR as X-axis and all other variables as paramters. Calculates average and 95% confidence intervals for NRUNS simulation runs and plots error flags. This routine is fully generic, the confidence interval (95% by default) can be set with NSIGMAS. See eg/ErrorFlags.data for an example datafile.

Histogram

Required configuration variables: NBINS

Optional configuration variables: BINWIDTH, MIN, MAX

Creates a histogram of the simulation results. This requires the simulator to produce raw data for the histograms in a tabular format. When specifying logscale X or XY for the plot, the histogram bins will be logarithmic. See eg/Histogram.data for an example. The number of bins in the histogram must be specified via NBINS. The width of the bins can be set with BINWIDTH, in which case MIN and MAX will be calculated. When MIN or MAX are set, BINWIDTH is calculated. It is possible to specify either MIN or MAX, the undefine value will be calculated.

Preprocessing the raw results

All of the above routines have hooks for simple functions that modify the @results array. To call these functions, include them in the datafile with the PREPROCESSOR variable. e.g:

  PREPROCESSOR : modify_results

  All functions must be put in the PLUGINS folder or in the PostProcessors.pm module, and the template could be like this:

  sub modify_results {
  foreach my $results_line (@results) {
          #Do whatever is required
  }
  
  } # End of modify_results

DICTIONARY ^

The Dictionary.pm module contains descriptions of the parameters used in the simulation. These descriptions are used by the postprocessing routines to make the simulation results more readable. The dictionary is stored in an associative array called make_nice. The description of the variable is stored in a field called 'title'; Descriptions of values are stored in fields indexed by the values.

Following example illustrates the syntax:

        # Translate the parameter names and values into something meaningful
        %Dictionary::make_nice=(
        
        _BUFTYPE => {
        title=>'Buffer type',
                     0=>'Adjustable',
                     1=>'Fixed-length',
                     2=>'Multi-exit',
                    },
        _YOURVAR1 => {
        title=>'Your description for variable 1',
        },
        
        _YOURVAR2 => {
        title=>'Your description for variable 2',
'val1' => 'First value of _YOURVAR2',
'val3' => 'Second value of _YOURVAR2',
        },

        );

OUTPUT FILES ^

SynSim creates a run directory {SIMTYPE}-[datafile without .data]. It copies all necessary template files and source files to this directory; all output files are generated in this directory.

SynSim generates following files:

WRITING POSTPROCESSING ROUTINES ^

In a lot of cases you will want to create your own postprocessing routines. First of all, it is important to understand the SynSim output, so make sure you have read "OUTPUT FILES". Apart from that, there is a very simple API.

PostProcLib

In summary, following variables are exported:

                           %simdata             # contains all datafile variables 
                                                #and their values/value lists
                           @results             # memory image of the results file
                           %current_set_vals    # values for the current set 
                           $current_set_str     # same in string format 
                           $current_set_except_setvar_str
                           $results_file_name    
                           @all_results_file_names
                           $last                # indicates end of a sweep
                           $verylast            # indicates end of the DOE

An example of how all this is used:

        sub YourRoutine {
        
        ## Define your own variables.
        ## As every variable can have a list of values, 
        ## $simdata{'_YOURVAR1'} is an array reference.
        
        my $yourvar=${$simdata{'_YOURVAR1'}}[0];
        
        my @sweepvarvals=@{$simdata{$sweepvar}};
        
        ## $verylast indicates the end of all simulations
        if(not $verylast) {
        
        ## what to do for all simulations
        
        ## $last indicates the end of a sweep
        if($last) {
        # Do something at the end of every sweep  
          } # if last
        } else {
         ## On the very last run, collect the results into one nice plot
          &gnuplot_combined($firstplotline,$plotlinetempl);
        }
        
        } #END of YourRoutine()

Statistical analysis

A module for basic statistical analysis is also available (Analysis.pm). Currently, the module provides 2 routines:

calc_statistics():

To calculate average, standard deviation, min. and max. of a set of values.

Arguments:

$file: name of the results file. The routine requires the data to be in whitespace-separated columns.

$par: Determines if the data will be differentiated before processing ($par='DIFF') or not (any other value for $par). Differentiation is defined as subtracting the previous value in the array form the current value. A '0' is prepended to the array to avoid an undefined first point.

$datacol: column to use for data

$title: optional, a title for the histogram

$log: optional, log of values before calculating histogram or not ('LOG' or '')

Use: my $file="your_results_file.res"; my $par='YOURPAR'; my $datacol=2; my %stats=%{&calc_statistics($file,[$par, $datacol])};

        my $avg=$stats{$par}{AVG}; # average
        my $stdev=$stats{$par}{STDEV}; # standard deviation
        my $min=$stats{$par}{MIN}; # min. value in set
        my $max=$stats{$par}{MAX}; # max. value in set
build_histograms():

To build histograms. There are 3 extra arguments:

        $nbins: number of bins in the histogram
        $min: force the value of the smallest bin (optional)
        $max: force the value of the largest bin (optional)

use: my $par='DATA'; my %hists=%{&build_histograms("your_results_file.res", [$par,$datacol],$title,$log,$nbins,$min,$max)};

NOTE: Because the extra arguments are last, the $title and $log arguments can not be omitted. If not needed, supply ''.

EXAMPLES ^

Here are some examples of how to use SynSim for different types of simulators.

1. Typical SPICE simulator

Normal use: spice -b circuit.sp > circuit.out

With SynSim:

1. Create a template file

Copy circuit.sp to TEMPLATES/SIMTYPE/circuit.templ Replace all variable values with SynSim variable names.

e.g. a MOS device line in SPICE:

  M1 VD VG VS VB nch w=10u l=10u

becomes

  M1 VD VG VS VB _MODEL w=_WIDTH l=_LENGTH
2. Create a data file (e.g. circuit.data)
  TITLE: MOS drain current vs. length
  SIMTYPE : circuit
  COMMAND : spice -b inputfile > outputfile

  # Required for postprocessing 
  OUTPUT_FILTER_PATTERN : Id # keep only the drain current on the output file
  ANALYSIS_TEMPLATE : SweepVar # default template for simple sweep
  SWEEPVAR : _L # we sweep the length, the other variables are parameters
  DATACOL: 2 # first col is the name 

  _L = 1u,2u,5u,10u,20u,50u
  _W = 10u,100u
  _MODEL = nch

There are more possible keywords, cf. "DATAFILE DESCRIPTION".

3. Now run synsim
  ./synsim -p -i -v -f IDvsL.data

  -p to create plots
  -i means interactive, so the plots are displayed during simulation
  -v for verbose output
  -f because the filename is not the default name

SynSim will run 12 SPICE simulations and produce 1 plot with all results.

4. Results

All results are stored in the run directory, in this case:

  circuit-IDvsL

2. Simulator with command-line input and fixed output file

Normal use: simplesim -a50 -b100 -c0.7

Output is saved in out.txt.

With SynSim:

1. Create a template file

As simplesim does not take an input file, we create a wrapper simplesim.templ in TEMPLATES/SIMTYPE. This file is actually a template for a simple perl script:

 system("simplesim -a_VAR1 -b_VAR2 -c_VAR3");
 system("cp out.txt $ARGV[0]");
2. Create a data file (e.g. test.data)
  TITLE: simplesim test
  SIMTYPE : simplesim
  COMMAND : perl inputfile outputfile
3. Now run synsim
  ./synsim -f test.data

SynSim will run without any messages and produce no plots.

4. Results

All results are stored in the run directory, in this case:

  simplesim-test

3. Simulator without input file, configured at compile time

Normal use: Modify values for #if and #ifdef constants in the header file; then compile and run.

e.g.:

  vi bufsim3.h
  g++ -o bufsim3 bufsim3.cc
  ./bufsim3 > outputfile

With SynSim:

1. Put the source code (bufsim3.cc) in SOURCES
2. Create a template file

As bufsim3 does not take an input file, we create a wrapper bufsim3.templ in TEMPLATES/SIMTYPE. This file is actually a template for a perl script that writes the header file, compiles and runs the code:

  open(HEADER,">bufsim3.h");
  print HEADER <<"ENDH";
  #define NBUFS _NBUFS
  #define NPACKETS _NPACK
  #AGGREGATE _AGGREGATE
  ENDH
  close HEADER;

  system("g++ -o bufsim3 bufsim3.cc");
  system("./bufsim3 $ARGV[0]");
3. Create a datafile (e.g. Aggregate.data)
  TITLE: bufsim3 test (_NBUFS, _NPACK) # will be substituted by the values
  SIMTYPE : bufsim3
  COMMAND : perl inputfile outputfile
4. Run synsim
  ./synsim -w -v -f Aggregate.data

SynSim will run verbose and flag all variables not defined in the datafile.

4. Results

All results are stored in the run directory, in this case:

  bufsim3-Aggregate

4. Circuit simulator which produces binary files.

Normal use: spectre circuit.scs -raw circuit.raw

With SynSim:

1. Create a template file

Copy circuit.scs to TEMPLATES/SIMTYPE/circuit.templ Replace all variable values with SynSim variable names.

2. Create a data file

The .raw file is a binary file, so it should not be touched. SynSim creates output files with extension .out, and combines these with the headers etc. (cf. "OUTPUT FILES"). By keeping the extension .raw, the simulator output files will not be touched.

In the datafile:

  TITLE: Spectre simulation with SPF output
  EXT: .scs
  COMMAND: spectre inputfile -raw outputfile.raw > outputfile
3. Run synsim

SynSim will process outputfile, but not outputfile.raw.

4. Postprocessing

To access the binary files, you will have to write your own postprocessing routines. Most likely they will rely on an external tool to process the binary data. The files will be found in the run directory, and have names as described in "OUTPUT FILES", with the extra extension .raw.

WRAPPERS ^

If the simulator command line does not follow the format required by SynSim, a simple shell or perl wrapper is enough to make SynSim understand it. The wrapper script must be stored under SOURCES/; it should be written such that all relative paths are correct when it is executed under SOURCES/. That is because SynSim runs in a subdirectory fo the project directory. This means that, if the command line contains relative paths to a subdirectory, these paths must be prepended with '../'.

1. No is wrapper required if the simulator takes input from a file with an arbitrary name and sends output in any way to a file with an arbitrary name:

        $ simulator INPUTFILE OUTPUTFILE
        $ simulator --o OUTPUTFILE INPUTFILE 
        $ simulator -i INPUTFILE > OUTPUTFILE
        $ simulator < INPUTFILE > OUTPUTFILE

2. Simulators with fixed input file name:

Example:

        $ simulator sim.conf > sim.out

Wrapper:

        $ simulator_wrapper.sh INPUTFILE > OUTPUTFILE 

The file simulator_wrapper.sh contains 2 lines:

        mv $1 sim.conf
        simulator sim.conf

3. Simulator with a fixed output file name:

Example:

        $ simulator INPUTFILE

The outputfile is called output.txt.

Wrapper:

        $ simulator_wrapper.sh INPUTFILE OUTPUTFILE 

The file simulator_wrapper.sh contains 2 lines:

        simulator $1
        mv output.txt $2

4. Simulator takes input file from a subdirectory

Example:

        $ simulator ../Config/INPUTFILE > OUTPUTFILE

The Config directory is in this case at the same level of project directory.

Wrapper:

        $ simulator_wrapper.sh INPUTFILE > OUTPUTFILE 

The file simulator_wrapper.sh contains 2 lines. Note the '../' prepended to the paths:

        cp $1 ../../Config
        simulator ../../Config/INPUTFILE

5. Simulator produces output in a subdirectory

Example:

        $ simulator INPUTFILE OUTPUTFILE 

The OUTPUTFILE is generated in the Results subdirectory.

Wrapper:

        $ simulator_wrapper.sh INPUTFILE OUTPUTFILE 

The file simulator_wrapper.sh contains 2 lines. Note the '../' prepended to the path:

        simulator $1 $2
        cp ../Results/$2 .

6. Simulator with command-line input and fixed output file

        $ simulator -a50 -b100 -c0.7

Output is saved in out.txt.

In this case, there is no actual wrapper script. We will create a simple shell script simulator.templ in TEMPLATES/. This script will act as the input file.

Wrapper:

        $ bash INPUTFILE OUTPUTFILE 

We need the explicit call to bash because the INPUTFILE does not have the -x flag set.

The file simulator.templ in TEMPLATES/ contains 2 lines:

        simulator -a_VAR1 -b_VAR2 -c_VAR3
        cp out.txt $1

SynSim will create simulator.sh from this template file, and then will call bash to execute this shell script.

7. Simulator requires multiple input files

Example:

        $ simulator config.in topo.in > out.res

Wrapper:

        $ perl INPUTFILE OUTPUTFILE 

Again, there is no actual wrapper script. The INPUTFILE template is in this case a perl script which contains itself templates for both input files. The script will create both input files, then run the simulator.

A possible implementation of simulator.templ:

        #!/usr/bin/perl
        #Template for simulator with multiple input files
        my $config_templ=<<"ENDCONF";
        /* This is the config.in template */
        int var1 = _VAR1;

        ...

        ENDCONF

        my $topo_templ=<<"ENDTOPO";
        ;;This is the topo.in template
        var2 = _VAR2

        ...

        ENDTOPO

        open CONF,">config.in";
        print CONF $config_templ;
        close CONF;

        open TOPO, ">topo.in";
        print TOPO $topo_templ;
        close TOPO;

        system("simulator config.in topo.in > $ARGV[0]");
 
        #END of simulator.templ

SynSim will create simulator.pl and then will call perl to run the script

TO DO ^

This module is still Alpha, a lot of work remains to be done to make it more user-friendly. The main tasks is to add a GUI. A prototype can be found on my web site, it is already useful but too early to include here. The next version will also make it easier to create your own postprocessing routines.

AUTHOR ^

Wim Vanderbauwhede <wim\x40motherearth.org>

COPYRIGHT ^

Copyright (c) 2000,2002-2003 Wim Vanderbauwhede. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO ^

gnuplot http://www.ucc.ie/gnuplot/gnuplot.html

syntax highlighting: