The Iterator Tool enables you to:
For detailed information on the Iterator Tool itself and the files it uses, see Iterator.
The Iterator-GUI assists in creating Iterator control files, launching the recursions, and viewing the results. The Iterator-GUI is organized to guide you through the process in logical order from top to bottom. Accordingly, the Iterator-GUI is divided into three parts:
Figure 1 shows the main Iterator-GUI window.
There are several ways of using the Iterator-GUI. Some may use it merely for creating an initial iterator.control file, and then make future modifications with a text editor, and/or launch simulations from their own scripts. However, the Iterator-GUI can also be used to modify and maintain iterator.control files, as well as launch simulations without ever editing a file or generating a script. It is flexible.
The choices are listed for controlling parameters.
You can:
Usually these choices are not mixed, but rather, they select the kind of simulation recursions to be run. The additional buttons to the right of Sweep and Randomize apply specifically to those choices, respectively. The Next Outer Loop button adds a loop between swept variables. (Otherwise they step together.) The Seed button gives control of the random number generator's seed for randomized parameter (Monte Carlo) simulations. Finally, the List/Edit/Remove button enables reviewing, editing, or removing the prior entries.
Once a type of parameter setting is selected, a sub-menu pop-ups with the appropriate option fields. In most of the menus, the first item is the parameter name to be varied. A convenience button, called Names, lists the available attribute names from your simulation, assuming you have successfully built the simulation and you are in the same directory where you built it. (Iterator-GUI scans the top_tab.dat file to get the names.)
For example, Figure 3 shows the Sweep window.
Figure 4 shows the Randomize window.
Next is the run-command. By default, this is set as: sim.exe -batch, which is a good
setting for many applications. Remember that the simulation should be built as -nongraphical.
(The -batch option causes the textual simulator to come up running and quit when simulation is done.)
However, this may not apply to all simulations. So this option allows you to specify an alternate
run-command script, such as:
sim.exe < my_command.scrip
You may also use this line to set command-line options for the Iterator.
Figure 5 shows the Run Controls menu.
As documented in the Iterator Tool document, each run of your simulation should
produce a result.dat file containing one line, with result values in columns separated by
white space.
Example result.dat file:
34 21.0 92.8 212.1
The Result Collection menus ask you to specify collection of results from the result.dat file
in terms of the column-number of the values. Columns are assumed to be numbered starting at one (1).
Presently, there are three options for collecting/displaying results:
Figure 8 shows the Histogram submenu.
Finally, the List/Edit/Remove button brings up a menu that lets you review your collection selections, and edit or remove them. Figure 9 shows the List/Edit/Remove submenu.
(If you forget to save, the Iterator-GUI will remind you before you exit or attempt to simulate.)
From this window, it is customary to first review the iteration.control file that will be used. Do this be clicking Review Iterator Control File. A window showing the contents of the file will pop-up, such as Figure 12 shows. If you need to change anything, you have the opportunity to go back to the Set-Up section now, before beginning the simulation iterations.
Next, the middle of the window shows the command that will be used to launch the Iterator. This is useful to know in case you wish to launch the Iterator on your own, outside the Iterator-Gui, Or if you need to modify the command in any way. Otherwise, you can just ignore this line.
If everything appears satisfactory, then you can launch the Iterator by clicking -- Start Simulation Recursions --. The Iterator tool will then be invoked within a new Xterm window. The Xterm will automatically pop-up showing the Iterator progress. Large simulations with many recursions may take quite a while to run. Conversely, small simulations may finish their iterations so quickly, that you may barely notice the window popup and disappear.
To see any aggregated statistics you requested from the runs, as well as a general summary of the runs, click the List Results and iteration.log. This brings up a listing of the iteration.log file generated by the ITERATOR. You should see the mean, std.dev., min, and max. of any values you requested, as shown in Figure 14..
If you want to see the compilation of raw results produced from your simulation models, press the List Raw Results File. This lists the results_table.dat file. Each line corresponds to the output of a run. The i>results_table.dat file is produced by the ITERATOR by concatenating the result.dat files produced by each recursion. All plots and aggregations are calculated from the results_table.dat file.
To plot any results that you requested plots or histograms for, click the Plot Graphs button. You will see a list of the available plots, as shown in Figure 15. Select one and click Plot it. The requested plot should then appear.
If you wish to extract different information out of a given set of simulation runs, you do not need to re-run the simulation recursions, assuming the information is in the results_table.dat. For example, suppose, you wish to change a graph title, or plot a different column against another, or -- perhaps add a histogram of an existing result-column --, then request the modified observations in the Set-up / Results Collection/Plots section above, and then click the Re-Process Results button in the View menu. This will cause the ITERATOR to re-extract the new results from your existing results_table.dat, without re-running the simulations. Because this is very quick, you can do this iteratively many times, as you examine your data in various ways.
iterator_gui iteration.control
You can modify the command from CSIM's GUI under Tools/"Modify Commands",
or in your gui_setup file, or just type it on the command line.
This will bring up your previous selections.
This is the example used in the discusions above. It is a very simple (and pointless) one-box system model that contains a global attribute (in this case, a macro), called X. The model does nothing but write the result.dat file, each time it is run. It writes one line into the file. The line contains two values, X, and X squared.
The suggested example is to use the ITERATOR to sweep the X value from 1 to 10, by steps of one. And to plot the second column as a function of the first column. This should reveal the familiar Y equals X squared curve. A second aspect is to print the statistics of the second column (X^2), and a third would be to plot it's histogram. Suggested histogram parameters would be: range=0:100, #bins=5.
See: Detailed Instructions for Example.
.
| Q: | Is there a simple example for using Iterator? |
| A: | See Examples above. |
| Q: | How to use Iterator with performance models in "core_models" library? |
| A: |
You need to add some code that puts your results to a file called "results.dat",
usually at the end of your simulation. Normally you will also want to
save your independent variables (example: sweep parameter(s)) with your dependent
variable(s). For example, in the simple example above, X was the independent
variable, and X^2 was dependent on X. By saving both values to the results.dat file,
you can plot one versus the other.
If you are using the performance models (core_models), a good place to put your code would be in the "monitor.sim" model. That is a good "catch-all" model. There is a place toward the bottom of the model which waits for the end-of-simulation, and then does some closing chores. You could place code like the following there:
WAIT( &CSIM_EndofSim, &NONQUEUABLE ); /* This line is in monitor.sim */
/* Produce "results.dat". */
{
FILE *outfile;
char value[30];
float x;
outfile = fopen("results.dat","w");
if (outfile==0) printf("Error: Cannot open 'results.dat' for writing.\n");
else
{
/* Get the value of your independent variable or control attribute into x. */
CSIM_GET_ATTRIBUTE("your_control_attribute", value, 30);
if (sscanf(value,"%f",&x)!=1) printf("Error: bad attribute %s\n",value);
/* Send the values out to the file. */
fprintf(outfile,"%g %g\n", x, pk_mes_latency );
fclose(outfile);
}
}
The above example, saves the value of "pk_mes_latency" (which happens to be a
real variable) together with your control parameter to the results.dat file.
Rememember, this is just an example. You can do whatever you need, such as
saving multiple values, etc.. An example of saving four values, to make four-column
result files, would have an fprintf(...) like:fprintf(outfile,"%g %g %g %g\n", x, pk_mes_latency, last_proc_time, u_mes_latency/(float)(n_mesgs_recvd) );
|
