CSIM Examples Directory:

Included in all CSIM installations are sets of examples which are a good starting point for learning to use the tools and develop new models. The examples are located in the csim/demo_examples directory.

Under the demo_examples directory are several CSIM example/demonstration models.

Sub-Directories:

	First_Simple_Model - A simplest example.  Two boxes of the same type
		send messages to each other.  First_Simple_ModelLike a "HelloWorld" example.
		This model merely illustrates basic concepts and does not model any real system.

	HwSw_Architecture_72_processors - Performance model of 72-processor system.
		It models a software application running on the model of a hardware architecture.
		This model uses a simplified version of CSIM 's HwSW library models.
		The application is SAR High-resolution classification processing system.

	Math_Algorithm_Model - Purely algorithmic model example.  This example
		shows how complex number vector models can be used under CSIM 
		to do purely mathematical simulation.  It shows how to 	use some of the
		graphing and image-display gadgets.

	Math_Algorithm_wSliders - A variant of the basic Math_Algorithm_Model
		above.  This one includes interactive slider-controls in the models.

	HwSw_Architecture_81_processors - An example performance model of an 81
		processor mesh-connected system, with a hierarchical application flow-graph. 
		This model uses a simplified version of CSIM 's HwSW library models.

	HwSw_Architecture__122_processors - Another example performance model.
		This models a system containing 122 processors through a switched backplane.  
		Uses same software application flow-graph as HwSw_Architecture_81_processors,
		which illustrates how parallel software can be quickly re-mapped onto
		different architecturs.

	Heatbug_Agent_Model - This is a simple example model of a biologically
		motivated computing. This artificial-life model is based on SWARM concepts from
		Univ. Santa Fe.  Simple agents interact and move about the screen.

	Lesson_Models_for_HwSw_Performance_Modeling - Student examples to be used
		with the Tutorial on Hardware / Software Modeling.
		Delves deeper into parallel software mappings on different hardware architecturss.

	Lesson_Models_for_Queueing - Student examples to be used from the CSIM course.
		Shows how to reference existing models, and describe a simple queueing system by
		starting a new diagrams from scratch.

	Lesson_Models_for_IteratorTool - Student examples to be used from the CSIM course.
		Files demonstrate how CSIM's Iterator tool can be used to iteratievly run multiple
		simulations, with different values in each run.  Automatically collects and plots results.

	Link_Bundle_Examples - Four simple examples showing how to use 
		bundle-links.

	WF3dExamples - WinFrame-3D file examples.  Demonstrates CSIM's 3D viewer.
                See the "Readme.txt" file in that directory.
	
The examples are not necessarily listed in the best viewing order.


General Instructions:

All the demos generally fall into the following basic pattern.
Please see the specific instructions for each demo further below.

In general, to explore the examples, do the following:

  • If you are using CSIM's graphical launcher:
     1. Double-click the CSIM-Launcher icon on your desk-top.
     2. Navigate to the selected demo-directory by pressing the Navigate to Directory button.
     3. Click the Start CSIM GUI button, and open the main .sim file specified in the particular demo.
    
  • Otherwise, if you want to use CSIM from your textual command-line:
     1. Perform the necessary setup for your system.
        This sets the needed environment variables for your current 
        session for where your CSIM tools were installed.
        From a Bash-shell or C-Shell:
    	Source CSIM's setup file.  The setup file is 
    	in the "csim/tools" directory.
    		source {path/csim}/tools/setup
    	(Replace "{path/csim}" with installation directory.)
         Or from a DOS CMD window type:
    		{path\csim}\setup.bat
     2. Copy the respective demo directory to your own area.
    	This contains the ".sim" and perhaps ".dfg" files for the
    	respective demo model.
    	For example, you could make a copy of all the demo's by:
    		  mkdir /tmp/test
    		  cp -r $CSIM_ROOT/demo_examples/demo* /tmp/test
     3. Move to the respective simulation directory.
    	Example:	cd First_Simple_Model
           For the examples, you generally need to be in the directory where the models are.
     4. Invoke the GUI and open the model.
    	Either:		gui model.sim
    	Or:		gui
    			(then use file/open/open-new-file to open model.sim)
    	Where "model.sim" is whatever the model is called. See specifics below.
    
Once you open a demo in the GUI:
 1. Peruse or edit the model.  (First time, best to do nothing.)

 2. Build the simulation, by clicking  Tools / Build Simulation  under the Tools menu.

    For HwSw-Architecture Performance demo's which have separate software application diagrams:
	Build the routing table:
	  2b. Select  Tools / Build-Routing-Table.
	Schedule the DFG by:
	  2c. Open the DFG under the  File / Open  menu.
	  2d. Build the software under the  Tools / Build-SW  menu.

 3. Run the simulation, by clicking  Tools / Run  under the Tools menu.
      	A simulation control panel will appear, and you can run the
	simulation, change viewing options, etc.

    For HwSw-Architecture demos, they produce time-line history files
	that you should view them by selecting: 
		Tools / Proc-Timeline   and  Tools / Proc+Comm-Timeline.


Specific instructions for each demo:


 First_Simple_Model - The model is called: "test.sim". 
	It is a very simple two-box model.
	 Move to the First_Simple_Model directory:
		cd /xx/yy/First_Simple_Model
	 Build it:
		- Invoke GUI on test-file:      gui  test.sim
		- Select under the menu:        Tools / Build Simulation
	 Run it.  
		- Select under the menu:	Tools / Run Simulation

	 The simulation control panel will appear.  

	 Click  RUN/Continue.

	 You will see the boxes and links flash as the simulation runs.
	 Text printouts from the models will appear in your text window.  
	 (This model does not produce timelines.)



 HwSw_Architecture_72_processors - This is a model of an actual system
	 containing hardware and software.  The main hardware model is called: 
		"Hardware_Arch.sim".
	 It references behavior models in a subdirectory.
	 The Software Application DFG is called: "Software_App.dfg".
	 (This DFG is very simple and contains no hierarchy.)

	 Move to the HwSw_Architecture_72_processors directory:	
		cd ../HwSw_Architecture_72_processors
	 To Build:
		Invoke GUI:	gui Hardware_Arch.sim
		Select:		Tools / Build Simulation
		Select:         Tools / Build Routing Table
		Open DFG:	File / Open / Open New File
		Select:			Software_App.dfg.dfg
		Select:		Tools / Build DFG SW
		(Optional:	Tools / Plot Ideal Timeline )

	   (Subsequent builds need re-do only changed section (HW or SW)).

	  To Run:
		Select: 	Tools / Run Simulation

	 The simulation will be invoked and the control panel will appear.
	 Press Run.

	 While the simulation is running, you can navigate the box hierarchy 
	 to see what activities are happening down inside hierarchical boxes.
	 However, we recommend flattening the hierarchy of some or all of 
	 the boxes by selecting boxes (clicking or dragging a rubber-band 
	 around them so they are selected with tick-marks), and then clicking 
	 menu:  View / Flatten-Selected-Subgraphs  or  ^f. 

	 After running the simulation (or even during), you can view the
	 resulting processing-activity timeline by:
		Select:		Tools / Plot Proc Timeline
	 Or, to see communication events superimposed:
		Select:		Tools / Plot Com+Proc Timeline



 Math_Algorithm_Model - This is a purely functional model 
	 (no-hardware/software distinction).   The main model is called:
		"Algorithm_diagram.sim".
	 It includes library files for the complex-math and vector library elements.
	 Build the simulation and run it.  You can navigate the hierarchy as it runs.

	 Move to the Math_Algorithm_Model directory:	cd ../Math_Algorithm_Model
	 To Build:
                Invoke GUI:     gui Algorithm_diagram.sim
		Select:		Tools / Build Simulation
	 To Run:
		Select: 	Tools / Run Simulation

	 The simulation will be invoked and the control panel will appear.
		Click:		RUN/Continue

	 (This model does not produce timelines.)



 Math_Algorithm_wSliders - This is an interactive purely functional model.
	 It contains no distinction between hardware or software elements.
	 It is like the example above, but includes interactive controls.
	 The main model is called: Algorithm_wSlide_Controls.sim.
	 It includes models the complex-math and vector library elements.
	 Build the simulation and run it.  Grab the slider conttrols in the diagram, and move
	 them to see the output change, while running the simulation.


	 Move to the Math_Algorithm_wSliders directory:
		cd ../Math_Algorithm_wSliders
	 To Build:
                Invoke GUI:     gui Algorithm_wSlide_Controls.sim.sim
		Select:		Tools / Build Simulation
	 To Run:
		Select: 	Tools / Run Simulation

	 The simulation will be invoked and the control panel will appear.
		Click:		RUN/Continue

	 You can interact with the model as it runs by moving the slider
	 controls.  These will vary the frequencies of the waveform generators.
	 You will see this reflected in the oscilloscope displays.
	 (This model does not produce timelines.)



 HwSw_Architecture_81_processors - The hardware model is called:  
		"Hw_Arch_81mesh.sim".
	 It contains topology and behavior descriptions all in one file.
	 There are three alternative Software Application diagrams to show how
	 different software applications can be conveniently mapped and tested on a 
	 given hardware architecture.  The first Software Application DFG is called: 
		"Sw_App_A.dfg".
	 Unlike the 72-proc example, these Data Flow Diagrams contain multiple levels
	 of hierarchy.

	 Alternate variations of the basic DFG are included in files:
		"Sw_App_B.dfg"  and  "Sw_App_C.dfg".
	 These basically have more iterations of data and produce more interesting
	 visualizations because the simulations driven by them run longer.

	 Move to the HwSw_Architecture_81_processorsdirectory:
		cd ../HwSw_Architecture_81_processors
	 To Build:
		Invoke GUI:	gui Hw_Arch_81mesh.sim
		Select:		Tools / Build Simulation
		Select:         Tools / Build Routing Table
		Open DFG:	File / Open / Open New File
		Select:			Sw_App_A.dfg
		Select:		Tools / Build DFG SW
		(Optional:	Tools / Plot Ideal Timeline )
	   (Subsequent builds need re-do only changed section (HW or SW)).

	 Alternate variations of the basic DFG are included in files:
	 "Sw_App_B.dfg" and "Sw_App_C.dfg".  These basically have more
	 iterations of data and produce more interesting visualizations
	 because the simulations driven by them run longer.

	 To Run:
		Select: 	Tools / Run Simulation

	 The simulation will be invoked and the control panel will appear.
		Click:		RUN/Continue

	 After running the simulation (or even during), you can view the
	 resulting processing-activity timeline by:
		Select:		Tools / Plot Proc Timeline
	 Or, to see communication events superimposed:
		Select:		Tools / Plot Com+Proc Timeline



 HwSw_Architecture__122_processors - The main hardware model is called:
		"Hw_Arch_122.sim".
	It references simplified versions of the processor and bus models
        under a self-contained subdirectory.
        The application DFG is called:
                "Sw_App1.dfg".
         This model contains special calls to animate special events on
         the links and in the boxes.  The architecture was pre-flattened for 
         demonstration purposes, so you do not have to flatten this one.

	 Move to the HwSw_Architecture__122_processors directory:
		cd ../HwSw_Architecture__122_processors
	 To Build:
		Invoke GUI:	gui Hw_Arch_122.sim
		Select:		Tools / Build Simulation
		Select:         Tools / Build Routing Table
		Open DFG:	File / Open / Open New File
		Select:			Sw_App1.dfg
		Select:		Tools / Build DFG SW
		(Optional:	Tools / Plot Ideal Timeline )
	   (Subsequent builds need re-do only changed section (HW or SW)).

	  To Run:
		Select: 	Tools / Run Simulation

	 The simulation will be invoked and the control panel will appear.
		Click:		RUN/Continue

	 This model contains special calls to animate special events on
	 the links and in the boxes.  So you do not have to change the
	 animation modes.  The architecture was pre-flattened for 
	 demonstration purposes, so you do not have to flatten this one.

	 Because of the crowdedness of the architecture, you will want to
	 turn-off the port-names.  Select:  View / Show-Port-Names.

	 Explanation of link animation:
	  In this model of a packet-switched network, the modeler 
	  chose to show new attempts for connections through the network
	  by lighting links along a requested path in yellow.  (They are
	  normally violet when unused.)  If the requested path is successfully
	  granted, the links are turned green to indicate the presence of
	  data flowing through them.  If the requested path cannot be
	  granted because of contention with another ongoing communication
	  on a link, the contented link will be high-lighted red to indicate
	  contention, the requested path will be returned to violet until
	  the next re-try.  

	  As the simulation model runs, you will see the links blinking, 
	  changing colors, data flowing, and occasional red flashes as 
	  contentions occur.  If you stop the simulation, or step through it
	  by a small amount, perhaps 10 or 20 time-units at a step, you can
	  catch individual communications being made, contented, and broken
	  as they complete.

	 After running the simulation (or even during), you can view the
	 resulting processing-activity timeline by:
		Select:		Tools / Plot Proc Timeline
	 Or, to see communication events superimposed:
		Select:		Tools / Plot Com+Proc Timeline


 Heatbug_Agent_Model - The main model is called:
		"heat_bugs.sim".
	 This is a simple example model of the SWARM-inspired "heat-bug".
	 It is an artificial-life experiment motivated by Univ. Santa Fe.
	 The heat-bugs operate independently according to their own rule-set.
	 When placed in a population with other heat-bugs, they interact so
	 as to optimize their own individual goals.
	
	 The "heat-bug" is an independent agent that "desires" a specific
	 temperature set_point, for example, 10-degrees.  Each heat-bug
	 generates a small amount of heat.  To reach the desired temperature,
	 the heat-bugs need to cluster near each other to gain heat from
	 their neighbors.  However, if they get too close, they get too
	 warm.  So they must achieve a proper distance to regulate their
	 heat.  
 
	 Their initial rule-set is simple.  If too cold or warm, i.e.
	 if satisfaction is low, then move in a random direction.
	 If the move resulted in a satisfaction improvement, then keep
	 it.  Otherwise, reverse the move.

	To use this model:
	        1. Copy it to your own directory.
	        2. Follow comm-line or GUI instructions below.

	From Command-line:
	        To Build Sim:
	                csim heat_bugs.sim
	        To Run:
	                sim.exe

	From GUI:
	        First, go into GUI:
	                gui heat_bugs.sim
	        To Build Sim:
	                Click: Tools / Build Sim
	        To Run:
	                Click: Tools / Run Sim


 Lesson_Models_for_Queueing - Student example models from the CSIM course.
	This document: Instructions, takes you through a series of steps to
	building some simple models.


 Link_Bundle_Examples - Four examples of using bundles.
	Use as:
	        gui bundle_example1.sim
	         /Tools/Build
	         /Tools/Run
	etc.

	When looking at these examples in the GUI, try double-clicking on 
	the bundle to see inside it.

	Note:  These are super-simple examples, having only a few bundles, and making use of
	really only one strand within the bundle.  


 WF3dExamples - This directory contains several examples for the WF3d Viewer.
	See the Readme.txt file in the directory.


Further:

The above examples show how to run previously created models (I.E. canned demonstrations). For help in learning how to create your own models from scratch, using the Performance Model Library for Hardware/Software modeling, as shown in demos 1, 3, and 4, please see: Learning to use Perf. Mod. Lib - A New User's Guide to Creating a Model

Short-Cuts
You don't have to use the GUI to do everything. Some find it easier to build and run simulations from the command-line or from a script-file. See Quick Textual Short-cuts to find how to do the same thing from your keyboard.