1square(1) Scalasca Trace Tools square(1)
2
6 square - Scalasca analysis report explorer
7
9 square [OPTIONS] (EXPERIMENT_DIR | CUBE_FILE)
10
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 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 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 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 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 • summary.cubex: post-processed runtime summary result
41 • trace.cubex: post-processed trace analysis result
43 In scoring mode (-s option), square generates:
45 • scorep.score: detailed measurement score report, optionally suffixed
47 with the name of a provided filter file (-f option)
48 In multi-run mode, aggregated reports are created if the corresponding
50 input files are available:
51 • profile_aggr.cubex: aggregated runtime summary result
53 • scout_aggr.cubex: aggregated trace analysis result
55 • scout+profile.cubex: merged runtime summary and trace analysis result
57 • summary_aggr.cubex: post-processed aggregated runtime summary result
59 • trace_aggr.cubex: post-processed aggregated trace analysis result
61 • trace+summary.cubex: post-processed merged runtime summary and trace
63 result
64
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 -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 -F Force post-processing of analysis reports, even if a post-processed
82 report already exists.
83 -f filter_file
85 Apply the specified filter file when generating a score report
86 (option -s).
87 -s Output a textual score report. Skips launching the Cube GUI.
89 -v Enable verbose mode.
91 -n Suppress the calculation of 'Idle Threads' metric.
93 -x <scorep-score opt>
95 Pass option(s) directly to scorep-score. Any composite options have
96 to be quoted as needed.
97 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 -T MODE
105 Set aggregation mode for trace analysis results of each
106 configuration. Currently supported modes are 'mean' and 'merge'
107 (default).
108 -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 -I Ignore structural sanity checks and force aggregation of
116 measurements in a multi-run experiment.
117
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 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 The aggregation of multi-run measurement results happens in the
138 following order:
139 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 2. Aggregate averaged runtime summarization results from all
145 configurations in ascending order using the selected mode (-S
146 option).
147 3. Aggregate averaged trace analysis analysis results from all
149 configurations in ascending order using the selected mode (-T
150 option).
151 4. Merge the aggregated runtime summarization and trace analysis
153 results into a combined report.
154 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 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
171 square exits with status 0 on success, and greater than 0 if errors
172 occur.
173
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
185 Please report bugs to scalasca@fz-juelich.de. Make sure to include at
186 least the following information in your bug report:
187 • The Scalasca Trace Tools version reported by 'scalasca -V'.
189 • The Scalasca Trace Tools configuration reported by 'scalasca -c'.
191 • The Score-P version reported by 'scorep --version'.
193 • The Score-P configuration reported by 'scorep-info config-summary'.
195 • The exact command line of the failing command.
197 • The exact failure/error message.
199
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 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 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
217 scalasca(1), scan(1)
218 The full Scalasca Trace Tools documentation is available online at
220 https://www.scalasca.org.
221Version 2.6 Mon Apr 19 2021 square(1)