CSIM 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:

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.
  

 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.

	 1. Navigate to the First_Simple_Model directory:
	    From the CSIM-LAUNCHER, click the Navigate to a Directory button.
	    In the file-browser that pops up, click the v button to the right of
	     the Select Directory form-box.
		- Select .../demo_examples.
		- Then double-click First_Simple_Model.
		- Then select test.sim and click the OK button.

	 2. Start the CSIM GUI:
	    In the CSIM-LAUNCHER, Click the Start CSIM GUI button.
	    The CSIM GUI will pop up with the two box model on the canvas.

	 3. Build the simulation:
	    In the CSIM GUI:
		- Select under the menu:        Tools / Build Simulation

	 4. Run it.  
	    In the CSIM GUI:
		- Select under the menu:	Tools / Run Simulation

	    The simulation control panel will appear.  
	    Click the RUN button.

	 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.)

	 1. Navigate to the HwSw_Architecture_72_processors directory:	
	    From the CSIM-LAUNCHER, click the Navigate to a Directory button.
	    In the file-browser that pops up, click the v button to the right of
	     the Select Directory form-box.
		- Select .../demo_examples.
		- Then double-click HwSw_Architecture_72_processors.
		- Then select Hardware_Arch.sim and click the OK button.

	 2. Start the CSIM GUI:
	    In the CSIM-LAUNCHER, Click the Start CSIM GUI button.
	    The CSIM GUI will pop up with the processing architecture diagram.

	 3. Build the simulation:
	    In the CSIM GUI:
		Select:		Tools / Build Simulation
		Select:         Tools / Build Routing Table

	 4. Build the Data Flow Graph to Software Programs:
		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)).

	  5. Run:
		Select: 	Tools / Run Simulation

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

	 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.

	 1. Navigate to the Math_Algorithm_Model directory:	
	    Use the CSIM Launcher to navigate to the .../demo_examples/Math_Algorithm_Model
	     directory, as in the prior examples.
	    Select the Algorithm_diagram.sim file.

	 2. Start the CSIM GUI:
             In the CSIM-LAUNCHER, Click the Start CSIM GUI button.
             The CSIM GUI will pop up with the Algorithm_diagram.sim diagram.

	 3. Build the simulation:
	     In the CSIM GUI:
		Select:		Tools / Build Simulation

	 4. 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.

	 1. Navigate to the Math_Algorithm_wSliders directory:
	    Use the CSIM Launcher to navigate to the .../demo_examples/Math_Algorithm_wSliders
	     directory, as in the prior examples.
	    Select the Algorithm_wSlide_Controls.sim file.

	 2. Start the CSIM GUI:
            In the CSIM-LAUNCHER, Click the Start CSIM GUI button.
            The CSIM GUI will pop up with the Algorithm_wSlide_Controls.sim diagram.

	 3. Build the simulation:
	    In the CSIM GUI:
		Select:		Tools / Build Simulation

	 4. 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.

	 1. Navigate to the Math_Algorithm_wSliders directory:
	    Use the CSIM Launcher to navigate to the .../demo_examples/HwSw_Architecture_81_processors
	     directory, as in the prior examples.:
	    Select the Hw_Arch_81mesh.sim file.

	 2. Start the CSIM GUI:
            In the CSIM-LAUNCHER, Click the Start CSIM GUI button.
            The CSIM GUI will pop up with the Hw_Arch_81mesh.sim diagram.

	 3. Build the simulation:
	    In the CSIM GUI:
		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.

	 4. 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.

	 1. Navigate to the HwSw_Architecture__122_processors directory:
	    Use the CSIM Launcher to navigate to the .../demo_examples/HwSw_Architecture__122_processors
	     directory, as in the prior examples.:
	    Select the Hw_Arch_122.sim file.

	 2. Start the CSIM GUI:
            In the CSIM-LAUNCHER, Click the Start CSIM GUI button.
            The CSIM GUI will pop up with the Hw_Arch_122.sim diagram.

	 3. Build the simulation:
	    In the CSIM GUI:
		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)).

	 4. 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. Navigate to the .../demo_examples/Heatbug_Agent_Model as in
		    the prior examples.
		2. Select the heat_bugs.sim file and open the CSIM-GUI.
		3. Build the simulation:
		    In the CSIM GUI:
			Select:		Tools / Build Simulation
		4. Run:
			Select: 	Tools / Run Simulation

		   The simulation will be invoked and the control panel will appear.
			Click:		RUN/Continue
		   You will see the heat-bugs evolve.


 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:

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.