The stateless tools are the more polished; even if you are interested in doing experiments with state, it might be better to start with them.
The first thing to do is to overlay copies of the tool scripts into "TutoriaL". With "TutoriaL" as the current directory type the command:
cp ~/tools/* ./
in a UNIX/Linux system, or however you like to copy files on your platform. This will add the tool scripts to the working directory. You have to do this, rather than execute them out of the "tools" directory, because they make assumptions about where they are executing from. From now on, we assume that TutoriaL is the current directory. The tutorial uses two components, here called "C1" and "C2" (the first is an imperative component and the second is a conditional). But in the running version they have several names, as we'll see later. You should first look at these components with the tools that would be used by a component developer to approximate the components, "COMP" and "Xcute". If you want to see the Perl code for C1 and C2 it is at "C1bin" and "C2bin". The subdomain definitions for these components are in "C1.ccf" and "C2.ccf". Look at them to see how often each subdomain is sampled.
For the tutorial the step-function approximation will be used. Type the command:
COMP -V
which will create an approximate component-measurement files in "C1.ccft" and "C2.ccft".
Xcute C1
gives you a graph of the actual and approximate behaviors and an error analysis. You can guess what you type to do the same thing for C2.
Now we are ready to synthesize a system. Look at the file "system.pscf".
It has a reverse Polish description of a system structure, which is shown
in the flowchart:
It uses six components in this system, but really each one of them is
either C1 or C2, depending on whether an imperative or conditional is
needed. If you look at the various code and .ccf files (e.g.,
C6.ccf), you'll see that it is just a copy of the C1 files.
It isn't necessary to replicate same code/subdomain files in this way,
unless you want to use the trace tools.
To synthesize a system, all the components have to have been approximated first (the tools will tell you to do it if you forget). Now to synthesize the system properties, type
SYN -V -G
and you'll see the trace of the synthesizer running, doing the reverse Polish operators in the proper order, synthesizing equivalent components (which it names "theory1.ccf" ... "theory4.ccf" for this example) for the subsystems. (If you are interested in seeing what these look like, you can use XcuteF on them later, for example
Xcute theory1
to see how the loop equivalent component behaves.
But when you look at these computed approximations there is no
comparison with actual code. If you want a comparison, it can be
had by redefining the "system" being synthesized. For example,
you could validate "theory1" by making the system consist of
just the loop, in which case the synthesis would stop after
calculating theory1.)
But right now you will see the behavior of the synthesized system
compared to the actual executed system code, with an error analysis.
There is something cool you can do here to check if the tools are working properly. If you synthesize with
SYN -V -X -G
(adding the "-X" option),
the "actual" system that is compared to the theory calculation is built
from the approximation files (C1.ccft, etc.), and since those are supposed
to have the approximate behavior that the theory calculates, the "theory"
and "actual" results should agree perfectly, so the error analysis should
show zero differences. (If it doesn't, you've uncovered a bug in
the tools -- not, please God in the theory!; send an e-mail to report it.)
If you run
SYN -V -T -G
the execution will be traced. After it is complete, running
profile C6
will produce a histogram of the operational profile that appears at the input of component C6 in the system, both measured and calculated.
You might want to study the system results in more detail, and the Xcomp script lets you do that. (It was run for you when you used the -G option on SYN.) Following an execution of SYN,
Xcomp 5 9 200
(for example) displays the same error analysis and comparison graph, but only on the interval [5,9) and using 200 equispaced sampling points for the actual execution.
You could repeat the entire tutorial using the piecewise-linear approximation by starting above with
COMP -V -L
to measure the components using a piecewise-linear approximation. The rest of the tutorial will then proceed but with better results. You might want to replicate everything into a new directory for such a run, especially if you want to compare the approximations and have them both available at the same time.
To experiment with refining the subdomains, the script "splitsub 1" can be run. It will create in the parent of the current directory a complete new directory TutoriaL2 which is a copy of TutoriaL but with all the subdomains of all components split in two. Changing directory to TutoriaL2 and running the scripts will produce results that show how smaller subdomains improve the accuracy of measurements and predictions. The "splitsub" script takes an argument that is 5 by default, whence it creates directories TutoriaL2, TutoriaL22, ..., TutoriaL22222 successive refined down to five halvings.
You can now try other examples with more interesting components. You could start by changing either the system structure or the component behaviors in the tutorial. It is suggested that you do so in a new directory that you first copy from TutoriaL. If you are using an example provided by someone else, the way to understand it is to change to its directory, look first at "system.pscf" to see the system structure and the component names, then look at the .ccf file(s) for one or more components (which will identify the executable code file), and to run "COMP" and "Xcute" on these to see how they behave alone. Then run "SYN" to see the system synthesis.
The example system of the state tutorial is the same as in the stateless case, except for the component C1. C1 keeps persistent state, and therefore so does the system.
The script "COMP" can handle any mixture of stateless and with-state components:
COMP -V
The graphs and error reports for components can be obtained using "Xcute" as before. To see graphs for the component C1 with state, the command is:
Xcute C1
These graphs are 2-D projections of the 3-D results as a function of (input X state). GNUPlot is used in its interactive mode, so the projection surfaces for components with state can be rotated for a better view. (Sometimes only the X-windows version of GNUPlot has this feature, so it may be absent on your platform.) Now you have all the components approximated.
The synthesis command is as before
SYN -V -G
which creates the files `theory1', etc. (but now with extension `.ccfc') and an executable file named "SystemCode". (Look at it; it just "executes" the component code files.) The -G option causes a graphical comparison for output between calculation and execution with an error analysis. After this has been done for the functional system results, "Xcomp" can produce just the comparisons:
Xcomp
repeats the functional comparison, while
Xcomp -T
is for run time, and -S for state.
Using the -X option:
SYN -V -X -G
will compare not the actual system, but the table-lookup system described above. For the tutorial, as in the stateless case, there is exact agreement, but this is not always the case for conditionals that have state in their controlled code.
The tidy system behavior graphs of the example are not the rule. If more than one component has state, the graph becomes 4- or more dimensional and can't be directly displayed. The tools do graph something, but the `state' values are the vector sum of several states, and may appear misleading.
Last updated: April, 2009