1square(1)                    Scalasca Trace Tools                    square(1)
2
3
4

NAME

6       square - Scalasca analysis report explorer
7

SYNOPSIS

9       square [OPTIONS] (EXPERIMENT_DIR | CUBE_FILE)
10

DESCRIPTION

12       square,  the  Scalasca  analysis  report  explorer,  facilitates  post-
13       processing, scoring, and interactive examination  of  analysis  reports
14       from both runtime summarization and tracing experiments.
15
16       When  provided  with  a  Score-P  experiment  directory EXPERIMENT_DIR,
17       square post-processes  intermediate  analysis  reports  produced  by  a
18       measurement  and/or  an  automatic  trace analysis to derive additional
19       metrics and construct a hierarchy of measured and derived metrics,  and
20       then  presents  this  final  report  using  the Cube GUI (unless the -s
21       option is used). If intermediate reports were  already  processed,  the
22       final  report  is shown immediately. If there is more than one analysis
23       report in a Score-P experiment directory, the most comprehensive report
24       is shown by default.
25
26       When  provided  with  the name of a specific analysis report CUBE_FILE,
27       post-processing is  skipped  and  the  corresponding  report  is  shown
28       immediately.
29
30       Analysis  report  examination  can  only  be done after measurement and
31       analysis are completed. Parallel resources are not required, and it  is
32       often  more  convenient  to  examine  analysis  reports  on a different
33       system, such as a desktop computer where interactivity is superior.
34
35       Depending on the measurement configuration and  the  provided  options,
36       square  places  additional files into the experiment archive directory.
37       For single-run experiments, the following  files  are  created  if  the
38       corresponding input files are available:
39
40       • summary.cubex: post-processed runtime summary result
41
42       • trace.cubex: post-processed trace analysis result
43
44       In scoring mode (-s option), square generates:
45
46       • scorep.score:  detailed measurement score report, optionally suffixed
47         with the name of a provided filter file (-f option)
48
49       In multi-run mode, aggregated reports are created if the  corresponding
50       input files are available:
51
52       • profile_aggr.cubex: aggregated runtime summary result
53
54       • scout_aggr.cubex: aggregated trace analysis result
55
56       • scout+profile.cubex: merged runtime summary and trace analysis result
57
58       • summary_aggr.cubex: post-processed aggregated runtime summary result
59
60       • trace_aggr.cubex: post-processed aggregated trace analysis result
61
62       • trace+summary.cubex:  post-processed merged runtime summary and trace
63         result
64

OPTIONS

66   Common options
67       -C LEVEL
68           Level of sanity checks for newly created reports (default: 'none').
69           'quick' performs various sanity checks on the experiment meta data,
70           while 'full' also executes a more time-consuming check for negative
71           metric values (which usually indicate a serious error).
72
73       -c num_counter
74           Specifies  the  number of hard- and software counters that shall be
75           considered when generating a score report (option -s). By  default,
76           this  value  is 0, which means that only a timestamp is measured on
77           each event. If you plan to record extra counters specify the number
78           of  counters.  Otherwise,  scoring  may  underestimate the required
79           space.
80
81       -F  Force post-processing of analysis reports, even if a post-processed
82           report already exists.
83
84       -f filter_file
85           Apply  the  specified  filter  file  when generating a score report
86           (option -s).
87
88       -s  Output a textual score report. Skips launching the Cube GUI.
89
90       -v  Enable verbose mode.
91
92       -n  Suppress the calculation of 'Idle Threads' metric.
93
94       -x <scorep-score opt>
95           Pass option(s) directly to scorep-score. Any composite options have
96           to be quoted as needed.
97
98   Options for multi-run experiments
99       -S MODE
100           Set  aggregation  mode  for  runtime  summarization results of each
101           configuration. Currently supported modes  are  'mean'  and  'merge'
102           (default).
103
104       -T MODE
105           Set   aggregation   mode   for   trace  analysis  results  of  each
106           configuration. Currently supported modes  are  'mean'  and  'merge'
107           (default).
108
109       -A  Force  post-processing  of every individual step report of a multi-
110           run experiment.
111           WARNING: Depending  on  the  number  and  size  of  the  individual
112           measurement  reports, the time required to post-process all reports
113           can be significant!
114
115       -I  Ignore  structural  sanity  checks   and   force   aggregation   of
116           measurements in a multi-run experiment.
117

MULTI-RUN EXPERIMENTS

119       For  multi-run  experiments,  square  provides  additional  options  to
120       aggregate the set of measurement results into a single Cube  file.  The
121       user  can choose between the two aggregation methods 'merge' and 'mean'
122       to combine results from different configurations, which underneath  use
123       the  corresponding  CubeLib command-line tools. The default aggregation
124       mode is to 'merge' results.
125
126       Note:
127           The 'merge' operation always  copies  metric  data  from  the  last
128           measurement  configuration  in  a  given  set  in  which data for a
129           particular metric is available. This should be taken  into  account
130           when  setting  up  a  multi-run  experiment  that is supposed to be
131           aggregated using the square command later on. In particular, it  is
132           recommended  to include a low-overhead measurement without hardware
133           performance counters at the end of a measurement configuration  set
134           including  hardware  counter  measurements in order to provide more
135           accurate time information.
136
137       The  aggregation  of  multi-run  measurement  results  happens  in  the
138       following order:
139
140       1.  Aggregate   results   from   multiple  runs  for  each  measurement
141           configuration. At this point, the  only  supported  mode  for  this
142           aggregation is 'mean', which is therefore hard-coded.
143
144       2.  Aggregate   averaged   runtime   summarization   results  from  all
145           configurations in ascending  order  using  the  selected  mode  (-S
146           option).
147
148       3.  Aggregate   averaged  trace  analysis  analysis  results  from  all
149           configurations in ascending  order  using  the  selected  mode  (-T
150           option).
151
152       4.  Merge  the  aggregated  runtime  summarization  and  trace analysis
153           results into a combined report.
154
155       5.  Post-process the combined report (step 4) if  available,  otherwise
156           post-process the aggregated report(s) generated in either step 2 or
157           step 3.
158
159       Depending on the measurement settings, those steps will be  applied  if
160       the   respective   intermediate   results  are  found.  Before  merging
161       intermediate results, square performs  sanity  checks  to  compare  the
162       call-tree structure to ensure merging will result in a valid Cube file.
163       In  rare  cases,  where  the  user  is  aware  of  potential  call-tree
164       differences,  it  may  be  necessary to skip these checks, which can be
165       accomplished by passing the -I option.  However,  note  that  this  may
166       produce  erroneous  or  at least misleading results. The reports of the
167       individual runs will only be post-processed when  explicitly  requested
168       (-A option).
169

EXIT STATUS

171       square  exits  with  status  0 on success, and greater than 0 if errors
172       occur.
173

NOTES

175       To examine an analysis report on a different  system,  for  example,  a
176       desktop or laptop computer, it is often best to post-process the report
177       using square's scoring functionality (-s option) on  the  system  where
178       the  measurement has been taken, and then copy over the resulting post-
179       processed Cube file. This is because square requires  various  command-
180       line  tools  and  support files from the Score-P, CubeLib, and Scalasca
181       Trace Tools  packages,  which  may  not  be  available  on  the  target
182       computer.
183

BUGS

185       Please  report  bugs to scalasca@fz-juelich.de. Make sure to include at
186       least the following information in your bug report:
187
188       • The Scalasca Trace Tools version reported by 'scalasca -V'.
189
190       • The Scalasca Trace Tools configuration reported by 'scalasca -c'.
191
192       • The Score-P version reported by 'scorep --version'.
193
194       • The Score-P configuration reported by 'scorep-info config-summary'.
195
196       • The exact command line of the failing command.
197
198       • The exact failure/error message.
199

EXAMPLES

201       square scorep_foo_4_trace
202       Post-process measurement reports in scorep_foo_4_trace and display  the
203       most comprehensive report using the Cube GUI.
204
205       square -s -f filter scorep_foo_4_sum
206       Post-process  measurement  reports  in  scorep_foo_4_sum and generate a
207       score report with the run-time measurement filter rules from  the  file
208       filter applied.
209
210       square -S mean scorep_foo_4_multi-run_c2_r4
211       Aggregate  and  post-process  the  measurement results of the multi-run
212       experiment with two configurations  and  four  runs  per  configuration
213       stored   in   scorep_foo_4_multi-run_c2_r4.   Then,   show   the   most
214       comprehensive report using the Cube GUI.
215

SEE ALSO

217       scalasca(1), scan(1)
218
219       The full Scalasca Trace Tools  documentation  is  available  online  at
220       https://www.scalasca.org.
221
222Version 2.6.1                   Wed Dec 14 2022                      square(1)
Impressum