{'fraction_non_alphanumeric': 0.030742249961314284, 'fraction_numerical': 0.0061897147573116, 'mean_word_length': 5.060643951234761, 'pattern_counts': {'":': 0, '<': 1, '<?xml version=': 0, '>': 1, 'https://': 3, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 8, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
SCOPE: C3SR Systems Characterization and Benchmarking Framework

This report presents the design of the Scope infrastructure for extensible and portable benchmarking. Improvements in high- performance computing systems rely on coordination across different levels of system abstraction. Developing and defining accurate performance measurements is necessary at all levels of the system hierarchy, and should be as accessible as possible to developers with different backgrounds. The Scope project aims to lower the barrier to entry for developing performance benchmarks by providing a software architecture that allows benchmarks to be developed independently, by providing useful C/C++ abstractions and utilities, and by providing a Python package for generating publication-quality plots of resulting measurements.


I. MOTIVATION
The IBM-ILLINOIS Center for Cognitive Computing Systems Research (C 3 SR) is a long-term collaboration between IBM Research and the University of Illinois at Urbana-Champaign focused on developing advanced Cognitive Computing and Artificial Intelligence (AI) systems that are optimized across the vertical stacks of AI solutions, software, and hardware systems. In particular, C3SR aims to develop technologies to improve cognitive application developers' productivity on heterogeneous infrastructure [1].
This effort demands us to perform various system characterization and performance measurements work at all levels of computer system abstraction, including processors (such as X86, POWER, and ARM cores), system communication links (such as PCIe, NVLinks, CAPI/OpenCAPI), special system accelerators (both discrete ones such as FPGAs and integrated ones such as Tensor Cores), libraries (such as CUDA and CuDNN), and frameworks (such as TensorFlow, Caffee, and PyTorch).
Instead of developing ad-hoc performance measurement solutions for each task, we decide to develop a common system characterization and benchmarking infrastructure and tooling for all of our tasks, providing some uniformity across the various tasks.
As time passes by, we find that this infrastructure is proven not only useful, but also greatly boosted our productivity. A number of interesting systems projects at C 3 SR have already benefited from having such an infrastructure and tooling. Therefore, we decide to open source this infrastructure so that other research teams interested in systems work can also benefit from our work. Hence the genesis of this C 3 SR project: SCOPE.

II. DESIGN PHILOSOPHY
This whitepaper describes the motivation and design of the initial release (v1.0) of the Scope benchmarking infrastructure. Scope is designed around three primary goals: • extensibility: It should be easy for external groups to develop independent benchmarks without requiring centralized coordination with the Scope project. This allows different teams to develop their own measurement tools to fit their own needs. • portability: The Scope infrastructure should support as many different systems as possible. Though individual benchmarks may have specific requirements, Scope itself should not be a barrier to running benchmarks on a particular system. Scope has been tested on POWER8/POWER9-and x86 64-based systems, but should support any system that has a C++11 compiler and the CUDA [2] toolkit. • development silos: New groups of benchmarks should be able to be open-or closed-source. Each group of benchmarks may have its own software dependencies, compiler feature requirements, or other necessities, and those requirements should not be globally propagated to all benchmark code. This allows Scope to remain system-agnostic and useful to the widest possible audience. The Scope infrastructure consists of three kinds of software components. First, the SCOPE repository (Section III) manages configuration and compilation and provides shared utility functions for the benchmarks. Second, scopes (Section IV) define groups of benchmarks, with their own optional dependencies and utilities. Third, the ScopePlot project (Section V) provides a Python package for plotting and manipulating Scope results. Figure 1 shows the relationship between Scope infrastructure components.  [5], matplotlib [6], bokeh [7], and pandas [8].

A. Licensing, Hosting, and Contributing
The Scope infrastructure is free and open source, licensed under the Apache 2.0 license [9]. Scope welcomes contributions. See CONTRIBUTING.md in the Scope source tree for up-to-date information about contributing. Table I

B. Configuring the SCOPE Binary Compilation and Fetching Dependencies
Since the SCOPE repository does not contain any benchmark code, a user will typically provide benchmark code by including additional scopes (Section IV) during the build process. Scopes are semi-independent packages that contain benchmark code. For development isolation, scopes are maintained as separate projects and are included in SCOPE as CMake-aware projects in the scopes directory of the SCOPE source tree. SCOPE includes several completed scopes (Table IV) as Git submodules. When scopes are added as submodules, it is easy to assicated each SCOPE release with a specific revision of benchmark code, and the correct version of the scopes can be automatically downloaded when downloading the whole scope project. Other scopes can be manually added to this directory.
Scope uses CMake [4] to configure the Scope binary compilation during the configuration stage, shown in Figure 2(b). CMake simplifies the process of supporting a variety of compilers and systems as well as fetching dependencies. Through CMake, the Git submodules in SCOPE are downloaded and the fixed revisions are checked out. SCOPE then invokes CMake's add_subdirectory command on all directories in the scopes directory to add those scopes to the SCOPE binary build. Each scope exports a CMake Object Library [10] -a CMake target that represents a set of object files containing the implementation of that scope, as well as associated information about required dependencies for those object files.
Since benchmarks may only be compatible with particular systems, Scope allows conditional compilation of benchmarks. By selectively including or excluding object libraries during configuration, Scope may selectively include benchmark code and associated dependencies. Each scope's CMakeLists.txt may define options for disabling the scope. For example, cmake -DENABLE_EXAMPLE=ON scope-source-directory directs CMake to include object files and dependencies from Example|Scope (Section IV-C) when building the Scope binary.
Scope relies on Hunter [11] for CMake to fetch dependencies. Some dependencies, such as spdlog, are present in Scope so all benchmarks may used them. Table II shows the libraries included in Scope v1.0.0. Other dependencies are only required for certain benchmarks. For example, Comm|Scope requires libnuma [12] for pinning allocations or processes to memory regions on Linux systems, even though Scope itself does not.
Hunter downloads, configures, and builds the C++ library dependencies that SCOPE relies on. Individual scopes may also use Hunter to retrieve their dependencies, or they may require the user to provide them in some other way (for example, as libraries present on the system). If a scope uses Hunter, the scope's dependencies will only be retrieved if that scope was enabled in the configuration step. All downloads through Hunter occur at the end of the configuration step, so that the required library and header files are present for the build.

C. Compiling SCOPE
During the build stage (c), object files for all enabled scopes are produced and linked into a single binary. In this step, every source file that was included in a scope submodule object library is compiled into an object file. The source files that implement the Scope infrastructure helpers are also compiled into object files, and then all of the objects are linked together in a single step to form the scope binary. D. Running SCOPE Finally, running the produced SCOPE binary allows the user to select any subset of the included benchmarks and produce a data file at any location.

E. Providing Common Utilities
Scope provides a set of utilities that scopes may use. The interfaces for these utilities are available to the scopes through C++ header files. When scopes include those headers, the implementations will be available when all objects are linked together.
• The entire Google Benchmark library is provided to configure and register the benchmark code.
• CUDA error checking is provided, as most extant benchmarks are CUDA benchmarks. • Logging is provided so that scopes may have a consistent output mechanism. • C++ functions for declaring new command line options. • C++ function for executing pre-benchmark initialization code. • Convenience CMake functions for integrating with SCOPE. Scope also provides a tools/generate_sugar_files.py python script for generating Sugar-compatible [16] CMake files in each scope source tree. Scope uses Sugar to read the sugar.cmake files, which tell CMake where the CUDA and C++ source files for Scope and the benchmarks are. This script is provided so that the sugar.cmake files can be quickly regenerated during development of each scope. The script will create sugar.cmake files that export the CMake variables described in Table III. <VAR> is replaced by the string passed to the "-var" flag.

F. Providing CMake Functions
SCOPE provides three functions to help scopes integrate with the SCOPE CMake build. Scope_add_library is a wrapper around add_library, which also sets the SCOPE_NEW_TARGET variable so that SCOPE can link against the CMake Object Library defined in the scope. Target_include_scope_directories causes SCOPE's utility include directories to be added to the compilation of the scope so that the SCOPE utilities can be used. SCOPE also provides scope_status, scope_warning, and scope_fatal, which scopes may use in their CMakeLists.txt files to print messages that will be visible during configure time.

G. Initialization Hooks and Command-line Options
SCOPE provides the ability for benchmarks to run arbitrary initialization when the binary is executed. Scopes may register clara::Opts to create new command line arguments accepted by the SCOPE binary. Scopes may also register arbitrary code to be executed before command line arguments are parsed, or after arguments are parsed, but before any benchmarks are executed. Though these routines, benchmarks may do any unguided or user-directed initialization desired before benchmark execution.

IV. DESIGN OF SCOPE SUBMODULES
SCOPE does not include any benchmark code -all benchmarks are provided through individual scopes. Scopes are structured directories in the Scope source tree, included in Scope through the CMake include_directory command. As of this writing, eight scopes are either completed or in development, to measure various aspects of system compute and communication performance at different levels of abstraction.

A. Defining a CMake Object Library
Each scope needs to include a CMakeLists.txt at the top level of its directory. This allows it to be included in the Scope configuration through the include_directory command in the Scope CMakeLists.txt. Fundamentally, each scope only needs to define a CMake object library target though the object form of the add_library command [10]. Example|Scope defines the example_scope target. Scope suggests using Sugar and the provided tooling (Section III-E) to automate the process of providing source files to the scope_add_library command. The scope target may have its own dependencies or other constraints. Example|Scope marks itself as requiring C++11 through the target_compile_features CMake command. This tells CMake that objects in Example|Scope should be built with C++11 support in the compiler. Example|Scope also adds include directories, a CUDA language standard, and a requirement to link against the Google Benchmark library to the example_scope target. These requirements will be propagated to the entire Scope build as required.

B. Integration with Scope through Git Submodules
For development isolation, scopes are maintained as independent directories. If the scope is maintained as a Git repository, the scope can have its own versioning and revision history. Additionally, this allows the scope to be included in the SCOPE repository as a Git submodule. Git submodules can be automatically downloaded alongside Scope when Scope is downloaded, and pinned to the appropriate version.

C. Example Scope
The Scope project provides a template scope Example|Scope [18] that demonstrates how a new scope can be structured. Example|Scope is available at https://github.com/c3sr/example_scope. Example|Scope demonstrates the following required or suggested structures: 1) CMakeLists.txt (required) and Sugar (optional): This file defines a CMake object library and uses Sugar to parse the sugar.cmake files in the Example|Scope source tree.
2) Code Structure (optional): Example|Scope places all of its source files in the src directory.
3) Benchmark Library (required): All benchmarks are registered through the Benchmark library. This enables the Scope binary to filter, run, and report results in a consistent way. 4) Documentation (optional): Example|Scope contains Markdown files describes each benchmark, the algorithm, and implementation in docs in its source tree. 5) Initialization and Command Line Flags (optional) : Example|Scope uses clara::Opts to declare two new commandline arguments, and uses the SCOPE initialization hooks to cause SCOPE to exit during initialization if those options are used. Initialization code is placed in src/init.

V. SCOPE UTILITIES A. ScopePlot Python Package
ScopePlot is a python package available to help plot and manipulate results in the JSON files produced by SCOPE. The Google Benchmark-formatted JSON files (hereafter referred to as JSON files) produced by Scope are unmodified from the format produced by the Google Benchmark library, so ScopePlot is compatible with other tools that use that library. ScopePlot is freely available on the Python Package Index (PyPI) at https://pypi.org/project/scope-plot/. ScopePlot is also open-source, hosted at https://github.com/rai-project/scope_plot. ScopePlot uses Python's distutils to manage installation. When ScopePlot is installed, it provides the scope_plot binary. The rest of this section describes notable scope_plot subcommands.
1) spec Subcommand: scope_plot spec generates an arbitrary plot from a YAML [19] specification file (hereafter referred to as a spec file). Examples of valid specification files can be found in the ScopePlot source tree. The specification file controls the plot type (line with error bars, bar plot, linear regression plot with error bars), the source JSON file for each data series, filters to extract the desired data from the JSON file, per-series data transformations, and plot styling and formatting.  2) deps Subcommand: scope_plot deps can be used to help integrate the scope_plot command with GNU Makefiles. Similar to how make can be used to partially recompile code when certain files have changed, make can be used to regenerate plots when the underlying Benchmark JSON files have been updated. deps scans a spec file and emits the paths of the benchmark JSON files it depends on in make format, so that make target dependencies can be automatically generated as part of a build process.
3) bar Subcommand: scope_plot bar generates a bar plot from a Benchmark JSON file. It has a subset of the functionality of the spec subcommand, without requiring a full spec file. Command line options allow the user to specify the fields used for the x-and y-axis data, and the plot title. 4) cat Subcommand: scope_plot cat is inspired by the Linux/Unix "cat" command, but specialized to Google Benchmark JSON files. When passed one or more Benchmark JSON files, it concatenates the benchmarks field of those files and dumps the content to the standard output stream. In this way, it preserves the structure of the JSON files when they are concatenated, where the standard "cat" would simply append the JSON contents together, yielding a malformed result. 5) filter_name Subcommand: scope_plot filter_name filters the benchmark outputs in the Benchmark JSON file to only keep benchmarks with a name that matches a provided regular expression. 6) Using ScopePlot as a Library: ScopePlot may also be used as a python library to develop other JSON file manipulation and analysis tools. ScopePlot has an object model for JSON files and various methods for filtering them and converting them to pandas DataFrames.

B. Scope Docker Images
Scope includes several Docker [20] images, which can be used to run benchmarks. This allows users on supported platforms to run pre-packaged versions of the benchmark code without having to compile or configure it. Table V lists the Docker files and corresponding Docker images publicly available on the Docker Hub.

VI. SCOPE DEVELOPMENT AND MAINTENANCE
Scope and ScopePlot rely on continuous integration for testing and building Docker images. The continuous integration system is centered around Travis-CI [21]. Whenever modifications to Scope or ScopePlot are pushed to GitHub, Travis-CI starts a series of parallel jobs. Figure 4 summarizes the continuous integration flow for Scope and ScopePlot.

A. Scope
Whenever a push is made to the Scope repository, Travis-CI is configured to start a series of parallel builds: • An x86-64 CUDA 9.2 build. • An x86-64 Docker CUDA 7.5 build.
• An x86-64 Docker CUDA 8.0 build. • An x86-64 Docker CUDA 9.0 build. Each of these builds incorporate Comm|Scope and Example|Scope, the two completed scopes at the time of writing.
All of Travis' build hardware is x86-64, so Travis is directly used to create x86-64-compatible docker images. To generate POWER-compatible Docker images, Scope uses rai [22], a separate job submission system. Two additional Travis jobs are started, each of which simply submit the POWER builds to rai on Oregon State University's PowerCI [23] infrastructure.
• POWER Docker CUDA 8.0 build. • POWER Docker CUDA 9.2 build. If these Docker builds individually succeed, they are pushed to Docker hub to be immediately available to the public. An image corresponding to each tag is retained indefinitely. Furthermore, the most recent commit on each branch is available.

B. ScopePlot
Whenever a push is made to the ScopePlot repository, Travis-CI is configured to test the ScopePlot package against Python 2.7, 3.4, 3.5, 3.6, and 3.7. If all of those tests pass, and the commit has a corresponding tag, a new version of ScopePlot is made available on the Python Package Index (PyPI) for installation with pip install scope_plot.

VII. CONCLUSION
The Scope project arose out of a desire to lower the barrier to entry for system benchmarking in the IBM / University of Illinois Urbana-Champaign Center for Cognitive Computing Systems Research (C 3 SR). Scope does this by incorporating common libraries and providing convenience functions for writing new system benchmarks, easily supporting compilation on x86 and POWER platforms, and by providing a command-line tool for managing and plotting results. Scope is free and open-source, and welcomes contributors and collaborators.