square(1)

💖 square(1) — the Scalasca Trace Tools era 💖

okay bestie, welcome to square, aka the Scalasca analysis report explorer, straight out of the Scalasca Trace Tools manual (section 1, if you're keeping track 📖✨). This is the page that tells you how to post-process, score, and literally stare at your analysis reports. Let's go 🦋

---

✨ NAME ✨

square — the Scalasca analysis report explorer. that's it, that's the name, she's iconic 💅

---

🌸 SYNOPSIS 🌸

square [OPTIONS] (EXPERIMENT_DIR | CUBE_FILE)

you give her options and either an experiment dir OR a cube file. pick one. she's not greedy, she just needs something 🫶

---

🎀 DESCRIPTION 🎀

so square, the Scalasca analysis report explorer (say it with me), is your girl for post-processing, scoring, and interactive examination of analysis reports — and she handles reports from both runtime summarization and tracing experiments. versatile queen 👑

When you hand her a Score-P experiment directory, like EXPERIMENT_DIR, she post-processes the intermediate analysis reports that a measurement and/or an automatic trace analysis produced. Then she derives extra metrics, builds you a whole hierarchy of measured and derived metrics, and presents the final report using the Cube GUI — unless you passed the -s option, in which case she skips the GUI entirely.

If those intermediate reports were already processed? She just shows you the final report immediately. no waiting, no drama. And if there's more than one analysis report hanging out in a Score-P experiment directory, she shows the most comprehensive one by default. queen behavior, honestly.

When you give her the name of one specific analysis report, aka CUBE_FILE, post-processing gets skipped and the corresponding report shows up right away. instant. ✨

important vibe check: analysis report examination can only happen after measurement and analysis are done. parallel resources are not required — and honestly it's often way more convenient to examine reports on a different system, like a desktop computer where the interactivity is just better. treat yourself 💻💖

Depending on the measurement configuration and the options you passed, square places additional files into the experiment archive directory. For single-run experiments, these files get created if the corresponding input files are available:

• summary.cubex: post-processed runtime summary result
• trace.cubex: post-processed trace analysis result

In scoring mode (that's the -s option), square generates:

• scorep.score: detailed measurement score report, optionally suffixed with the name of a provided filter file (that's the -f option)

In multi-run mode, aggregated reports get created if the corresponding input files are available:

• profile_aggr.cubex: aggregated runtime summary result
• scout_aggr.cubex: aggregated trace analysis result
• scout+profile.cubex: merged runtime summary and trace analysis result
• summary_aggr.cubex: post-processed aggregated runtime summary result
• trace_aggr.cubex: post-processed aggregated trace analysis result
• trace+summary.cubex: post-processed merged runtime summary and trace result

---

💅 OPTIONS 💅

🌈 Common options

• -C LEVEL — level of sanity checks for newly created reports (default: 'none'). 'quick' runs various sanity checks on the experiment meta data, while 'full' also runs a more time-consuming check for negative metric values (which usually mean something is seriously wrong 😭).
• -c num_counter — says how many hard- and software counters should be considered when generating a score report (that's the -s option). By default this value is 0, which means only a timestamp is measured on each event. If you plan to record extra counters, say the number. Otherwise scoring may underestimate the required space. fr fr.
• -F — force post-processing of analysis reports, even if a post-processed report already exists. no chill, just force 💪
• -f filter_file — apply the specified filter file when generating a score report (the -s option).
• -s — output a textual score report. skips launching the Cube GUI. (this is the "no GUI, just text" era ✨)
• -v — enable verbose mode. she will tell you things.
• -n — suppress the calculation of the 'Idle Threads' metric. bye girl 👋
• -x <scorep-score opt> — pass option(s) directly to scorep-score. Any composite options have to be quoted as needed.

🧚 Options for multi-run experiments

• -S MODE — set the aggregation mode for runtime summarization results of each configuration. Currently supported modes are 'mean' and 'merge' (default).
• -T MODE — set the aggregation mode for trace analysis results of each configuration. Currently supported modes are 'mean' and 'merge' (default).
• -A — force post-processing of every individual step report of a multi-run experiment.

⚠️ WARNING: depending on the number and size of the individual measurement reports, the time required to post-process all reports can be significant! like, go make a snack significant. 🍓

• -I — ignore structural sanity checks and force aggregation of measurements in a multi-run experiment.

---

👑 MULTI-RUN EXPERIMENTS 👑

For multi-run experiments, square has extra options to aggregate the whole set of measurement results into a single Cube file. You can choose between the two aggregation methods 'merge' and 'mean' to combine results from different configurations — and underneath, they use the corresponding CubeLib command-line tools. The default aggregation mode is to 'merge' results.

Note:

the 'merge' operation always copies metric data from the last measurement configuration in a given set in which data for a particular metric is available. Keep this in mind when you're setting up a multi-run experiment that's supposed to be aggregated using the square command later on. In particular, it's recommended to include a low-overhead measurement without hardware performance counters at the end of a measurement configuration set that includes hardware counter measurements, so you get more accurate time information. iykyk 💜

The aggregation of multi-run measurement results happens in this exact order:

1. Aggregate results from multiple runs for each measurement configuration. At this point, the only supported mode for this aggregation is 'mean', which is therefore hard-coded.
2. Aggregate averaged runtime summarization results from all configurations in ascending order using the selected mode (the -S option).
3. Aggregate averaged trace analysis results from all configurations in ascending order using the selected mode (the -T option).
4. Merge the aggregated runtime summarization and trace analysis results into a combined report.
5. Post-process the combined report (step 4) if available, otherwise post-process the aggregated report(s) generated in either step 2 or step 3.

Depending on the measurement settings, those steps will be applied if the respective intermediate results are found. Before merging intermediate results, square performs sanity checks comparing the call-tree structure to make sure merging will result in a valid Cube file. In rare cases, where you already know about potential call-tree differences, it may be necessary to skip these checks — which you can do by passing the -I option.

😭 but note: that may produce erroneous or at least misleading results. proceed with caution, bestie.

The reports of the individual runs will only be post-processed when explicitly requested (the -A option).

---

🦋 EXIT STATUS 🦋

square exits with status 0 on success, and greater than 0 if errors occur. clean and simple, as she should 💅

---

🌸 NOTES 🌸

To examine an analysis report on a different system — say, a desktop or laptop computer — it's often best to post-process the report using square's scoring functionality (the -s option) on the system where the measurement was taken, and then copy over the resulting post-processed Cube file.

why? because square requires various command-line tools and support files from the Score-P, CubeLib, and Scalasca Trace Tools packages, which may not be available on the target computer. plan ahead, glow up later ✨

---

💀 BUGS 💀

Please report bugs to scalasca@fz-juelich.de. And make sure to include at least the following info in your bug report, bestie:

• The Scalasca Trace Tools version reported by scalasca -V.
• The Scalasca Trace Tools configuration reported by scalasca -c.
• The Score-P version reported by scorep --version.
• The Score-P configuration reported by scorep-info config-summary.
• The exact command line of the failing command.
• The exact failure/error message.

give her the receipts, not just the vibe 🙈

---

🌟 EXAMPLES 🌟

square scorep_foo_4_trace

Post-process measurement reports in scorep_foo_4_trace and display the most comprehensive report using the Cube GUI. classic 💖

square -s -f filter scorep_foo_4_sum

Post-process measurement reports in scorep_foo_4_sum and generate a score report with the run-time measurement filter rules from the file filter applied.

square -S mean scorep_foo_4_multi-run_c2_r4

Aggregate and post-process the measurement results of the multi-run experiment with two configurations and four runs per configuration stored in scorep_foo_4_multi-run_c2_r4. Then show the most comprehensive report using the Cube GUI. multi-run main character energy 🔥

---

🫶 SEE ALSO 🫶

scalasca(1), scan(1)

The full Scalasca Trace Tools documentation is available online at https://www.scalasca.org. go read it, she's worth it 📚✨

---

and that's the page, babes 💜 this was Version 2.6.2, dated Wed Apr 2 2025, from your girl square(1) in the Scalasca Trace Tools lineup. now go post-process something and slay 👑💖🎀