CompilerGym v0.2.5

Release 0.2.5 (2022-11-01)

CompilerGym v0.2.5 adds a new LLVM dataset, two new observation spaces, and includes numerous updates and bug fixes.

Summary of Changes

• [llvm] Added two new observation spaces, LexedIr and LexedIrTuple, providing access to a sequence of IR tokens (#742, thanks @fivosts!).
• [llvm] Added the "Jotaibench" benchmark suite, providing 18,761 new executable C programs extracted from handwritten code on GitHub (#705, thanks @canesche!).
• Added support for Python 3.10.
• [llvm] Fixed a bug with non-terminating subprocesses (#741, thanks @thecoblack!).
• [llvm] Fixed a bug where the incorrect number of runtimes were reported by reset() (#761), and an incorrect number of warm up runs were being performed (#717, thanks @lqwk!).
• [llvm] New leaderboard submission using GATv2 and DD-PPO (#728, thanks @anthony0727!).
• Added the ability to set timeout on each of the individual environment operations (#716, thanks @ricardoprins!).

• Added support for loading URLs in CompilerEnvStateReader.read_paths() (#692, thanks @thecoblack!).

• Simplified Makefile rules: renamed install-test to test and deprecated bazel test rules.
• Fixed a bug where the TimeLimit wrapper would interfere with benchmark iterator wrappers (#739, thanks @nluu175!).
• [ci] Added CI test coverage of example services (#695, #642, #699, thanks @mostafaelhoushi!).
• [ci] Updated Github actions to use Node v16.
• Reduced verbosity and wall time of CMake builds.
• Updates and fixes dependent package conflicts (fixes #771, #768).

Credits

A huge thank you to all code contributors!

• @anthony0727
• @canesche made their first contribution in #705
• @fivosts made their first contribution in #742
• @jaopaulolc made their first contribution in #738
• @lqwk made their first contribution in #717
• @mostafaelhoushi
• @nluu175 made their first contribution in #739
• @ricardoprins made their first contribution in #716
• @ryanrussell made their first contribution in #755
• @sahirgomez1
• @thecoblack
• @youweiliang made their first contribution in #751

Full Changelog: v0.2.4...v0.2.5

CompilerGym v0.2.4

This release adds a new compiler environment, new APIs, and a suite of backend improvements to improve the flexibility of CompilerGym environments. Many thanks to code contributors: @sogartar, @KyleHerndon, @SoumyajitKarmakar, @uduse, and @anthony0727!

Highlights of this release include:

• [mlir] Began work on a new environment for matrix multiplication using MLIR (#652, thanks @KyleHerndon and @sogartar!). Note this environment is not yet included in the pypi package and must be compiled from source.
• [llvm] Added a new env.benchmark_from_clang_invocation() method (#577) that can be used for constructing LLVM environment automatically from C/C++ compiler invocations. This makes it much easier to integrate CompilerGym with your existing build scripts.
• Added three new wrapper classes: Counter, that provides op counts for analysis (#683); SynchronousSqliteLogger, that provides logging of environment interactions to a relational database (#679), and ForkOnStep that provides an undo() operation (#682).
• Added reward_space and observation_space parameters to env.reset() (#659, thanks @SoumyajitKarmakar!)

This release includes a number of improvements to the backend APIs that make it easier to write new CompilerGym environments:

• Refactored the backend to make CompilerEnv an abstract interface, and ClientServiceCompilerEnv the concrete implementation of this interface. This enables new environments to be implemented without using gRPC (#633, thanks @sogartar!).
• Extended the support for different types of action and observation spaces (#641, #643, thanks @sogartar!), including new Permutation and SpaceSequence spaces (#645, thanks @sogartar!)..
• Added a new disk/ subdirectory to compiler service's working directories, which is symlinked to an on-disk location for devices which support in-memory working directories. This fixes a bug with leftover temporary directories from LLVM (#672).

This release also includes numerous bug fixes and improvements, many of which were reported or fixed by the community. For example, fixing a bug in cache file locations (#656, thanks @uduse!), and a missing flag definition in example code (#684, thanks @anthony0727!).

CompilerGym v0.2.3

This release brings in deprecating changes to the core env.step() routine, and lays the groundwork for enabling new types of compiler optimizations to be exposed through CompilerGym. Many thanks to code contributors: @mostafaelhoushi, @sogartar, @KyleHerndon, @uduse, @parthchadha, and @xtremey!

Highlights of this release include:

• Added a new TextSizeInBytes observation space for LLVM (#575).

• Added a new PPO leaderboard entry (#580). Thanks @xtremey!

• Fixed a bug in which temporary directories created by the LLVM environment were not cleaned up (#592).
• [Backend] The function createAndRunCompilerGymService now returns an int, which is the exit return code (#592).
• Improvements to the examples documentation (#548) and FAQ (#586)

Deprecations and breaking changes:

• CompilerEnv.step no longer accepts a list of actions (#627). A new method, CompilerEnv.multistep provides this functionality. This is to provide compatibility with environments whose action spaces are lists. To update your code, replace any calls to env.step() which take a list of actions to use env.multistep(). Thanks @sogartar!
• The arguments observations and rewards to step() have been renamed observation_spaces and reward_spaces, respectively (#627).
• Reward.id has been renamed Reward.name (#565, #612). Thanks @parthchadha!

• The backend protocol buffer schema has been updated to natively support more types of observation and action, and to support nested spaces (#531). Thanks @sogartar!

Full Changelog: v0.2.2...v0.2.3

CompilerGym v0.2.2

Amongst the highlights of this release are support for building with CMake and a new compiler environment based on loop unrolling. Many thanks to @sogartar, @mostafaelhoushi, @KyleHerndon, and @yqtianust for code contributions!

• Added support for building CompilerGym from source on Linux using CMake (#498, #478). The new build system coexists with the bazel build and enables customization over the CMake configuration used to build the LLVM environment. See INSTALL.md for details. Credit: @sogartar, @KyleHerndon.
• Added an environment for loop optimizations in LLVM (#530, #529, #517). This new example environment provides control over loop unrolling factors and demonstrates how to build a standalone LLVM binary using the new CMake build system. Credit: @mostafaelhoushi.
• Added a new BenchmarkUri class and API for parsing URIs (#525). This enables benchmarks to have optional parameters that can be used by the backend services to modify their behavior.
• [llvm] Enabled runtime reward to be calculated on systems where /dev/shm does not permit executables (#510).
• [llvm] Added a new benchmark://mibench-v1 dataset and deprecated benchmark://mibench-v0 (#511). If you are using mibench-v0, please update to the new version.
• [llvm] Enabled all 20 of the cBench runtime datasets to be used by the benchmark://cbench-v1 dataset (#525).
• Made the site_data_base argument of the Dataset class constructor optional (#518).
• Added support for building CompilerGym from source on macOS Monterey (#494).
• Removed the legacy dataset scripts and APIs that were deprecated in v0.1.8. Please use the new dataset API. The following has been removed:
  • The compiler_gym.bin.datasets script.
  • The properties: CompilerEnv.available_datasets, and CompilerEnv.benchmarks.
  • The CompilerEnv.require_dataset(), CompilerEnv.require_datasets(), CompilerEnv.register_dataset(), and CompilerEnv.get_benchmark_validation_callback() methods.
• Numerous other bug fixes and improvements.

Full Change Log: v0.2.1...v0.2.2

CompilerGym v0.2.1

Highlights of this release include:

• [Complex and composite action spaces] Added a new schema for describing action spaces (#369). This complete overhaul enables a much richer set of actions to be exposed, such as composite actions spaces, dictionaries, and continuous actions.
• [State Transition Dataset] We have released the first iteration of the state transition dataset, a large collection of (state,action,reward) tuples for the LLVM environments, suitable for large-scale supervised learning. We have added an example learned cost model using a graph neural network in examples/gnn_cost_model (#484, thanks @bcui19!).
• [New examples] We have added several new examples to the examples/ directory, including a new loop unrolling demo based on LLVM (#477, thanks @mostafaelhoushi!), a loop tool demo (#457, thanks @bwasti!), micro-benchmarks for operations, and example reinforcement learning scripts (#484). See examples/README.md for details. We also overhauled the example compiler gym service (#467).
• [New logo] Thanks Christy for designing a great new logo for CompilerGym! (#471)
• [llvm] Added a new Bitcode observation space (#442).
• Numerous bug fixes and improvements.

Deprecations and breaking changes:

• [Breaking change] Out-of-tree compiler services will require updating to the new action space API (#369).
• The env.observation.add_derived_space() method has been deprecated and will be removed in a future release. Please use the new derived_observation_spaces argument to the CompilerEnv constructor (#463).
• The compiler_gym.utils.logs module has been deprecated. Use compiler_gym.utils.runfiles_path instead (#453).
• The compiler_gym.replay_search module has been deprecated and merged into the compiler_gym.random_search (#453).

Full Changelog: v0.2.0...v0.2.1

CompilerGym v0.2.0

This release adds two new compiler optimization problems to CompilerGym: GCC command line flag optimization and CUDA loop nest optimization.

• [GCC] A new gcc-v0 environment, authored by @hughleat, exposes the command line flags of GCC as a reinforcement learning environment. GCC is a production-grade compiler for C and C++ used throughout industry. The environment provides several datasets and a large, high dimensional action space that works on several GCC versions. For further details check out the reference documentation.
• [loop_tool] A new loop_tool-v0 environment, authored by @bwasti, provides an experimental intermediate representation of n-dimensional data computation that can be lowered to both CPU and GPU backends. This provides a reinforcement learning environment for manipulating nests of loop computations to maximize throughput. For further details check out the reference documentation.

Other highlights of this release include:

• [Docker] Published a chriscummins/compiler_gym docker image that can be used to run CompilerGym services in standalone isolated containers (#424).
• [LLVM] Fixed a bug in the experimental Runtime observation space that caused observations to slow down over time (#398).
• [LLVM] Added a new utility module to compute observations from bitcodes (#405).
• Overhauled the continuous integration services to reduce computational requirements by 59.4% while increasing test coverage (#392).
• Improved error reporting if computing an observation fails (#380).
• Changed the return type of compiler_gym.random_search() to a CompilerEnv (#387).
• Numerous other bug fixes and improvements.

Many thanks to code contributors: @thecoblack, @bwasti, @hughleat, and @sahirgomez1!

CompilerGym v0.1.10

This release lays the foundation for several new exciting additions to CompilerGym:

• [LLVM] Added experimental support for optimizing for runtime and compile time (#307). This is still proof of concept and is not yet stable. For now, only the benchmark://cbench-v1 and generator://csmith-v0 datasets are supported.
• [CompilerGym Explorer] Started development of a web frontend for the LLVM environments. The work-in-progress Flask API and React website can be found in the www directory.
• [New Backend API] Added a mechanism for sending arbitrary data payloads to the compiler service backends (#313). This allows ad-hoc parameters that do not conform to the usual action space to be set for the duration of an episode. Add support for these parameters in the backend by implementing the optional handle_session_parameter() method, and then send parameters using the send_params() method.

Other highlights of this release include:

• [LLVM] The Csmith program generator is now shipped as part of the CompilerGym binary release, removing the need to compile it locally (#348).
• [LLVM] A new ProgramlJson observation space provides the JSON node-link data of a ProGraML graph without parsing to a nx.MultiDiGraph (#332).
• [LLVM] Added a leaderboard submission for a DQN agent (#292, thanks @phesse001!).
• [Backend API Update] The Reward.reset() method now receives an observation view that can be used to compute initial states (#341, thanks @bwasti!).
• [Datasets API] The size of infinite datasets has been changed from float("inf") to 0 (#347). This is a compatibility fix for __len__() which requires integers values.
• Prevent excessive growth of in-memory caches (#299).
• Multiple compatibility fixes for compiler_gym.wrappers.
• Numerous other bug fixes and improvements.

CompilerGym v0.1.9

This release of CompilerGym focuses on backend extensibility and adds a bunch of new features to make it easier to add support for new compilers:

• Adds a new CompilationSession class encapsulates a single incremental compilation session (#261).
• Adds a common runtime for CompilerGym services that takes a CompilationSession subclass and handles all the RPC wrangling for you (#270).
• Ports the LLVM service and example services to the new runtime (#277). This provides a net performance win with fewer lines of code.

Other highlights of this release include:

• [Core API] Adds a new compiler_gym.wrappers module that makes it easy to apply modular transformations to CompilerGym environments without modifying the environment code (#272).
• [Core API] Adds a new Datasets.random_benchmark() method for selecting a uniform random benchmark from one or more datasets (#247).
• [Core API] Adds a new compiler_gym.make() function, equivalent to gym.make() (#257).
• [LLVM] Adds a new IrSha1 observation space that uses a fast, service-side C++ implementation to compute a checksum of the environment state (#267).
• [LLVM] Adds 12 new C programs from the CHStone benchmark suite (#284).
• [LLVM] Adds the anghabench-v1 dataset and deprecated anghabench-v0 (#242).
• Numerous bug fixes and improvements.

CompilerGym v0.1.8

This release introduces some significant changes to the way that benchmarks are managed, introducing a new dataset API. This enabled us to add support for millions of new benchmarks and a more efficient implementation for the LLVM environment, but this will require some migrating of old code to the new interfaces (see "Migration Checklist" below).

Highlights

Some of the key changes of this release are:

• [Core API change] We have added a Python Benchmark class (#190). The env.benchmark attribute is now an instance of this class rather than a string (#222).
• [Core behavior change] Environments will no longer select benchmarks randomly. Now env.reset() will now always select the last-used benchmark, unless the benchmark argument is provided or env.benchmark has been set. If no benchmark is specified, a default is used.
• [API deprecations] We have added a new Dataset class hierarchy (#191, #192). All datasets are now available without needing to be downloaded first, and a new Datasets class can be used to iterate over them (#200). We have deprecated the old dataset management operations, the compiler_gym.bin.datasets script, and removed the --dataset and --ls_benchmark flags from the command line tools.
• [RPC interface change] The StartSession RPC endpoint now accepts a list of initial observations to compute. This removes the need for an immediate call to Step, reducing environment reset time by 15-21% (#189).
• [LLVM] We have added several new datasets of benchmarks, including the Csmith and llvm-stress program generators (#207), a dataset of OpenCL kernels (#208), and a dataset of compilable C functions (#210). See the docs for an overview.
• CompilerEnv now takes an optional Logger instance at construction time for fine-grained control over logging output (#187).
• [LLVM] The ModuleID and source_filename of LLVM-IR modules are now anonymized to prevent unintentional overfitting to benchmarks by name (#171).
• [docs] We have added a Feature Stability section to the documentation (#196).
• Numerous bug fixes and improvements.

Migration Checklist

Please use this checklist when updating code for the previous CompilerGym release:

• Review code that accesses the env.benchmark property and update to env.benchmark.uri if a string name is required. Setting this attribute by string (env.benchmark = "benchmark://a-v0/b") and comparison to string types (env.benchmark == "benchmark://a-v0/b") still work.
• Review code that calls env.reset() without first setting a benchmark. Previously, calling env.reset() would select a random benchmark. Now, env.reset() always selects the last used benchmark, or a predetermined default if none is specified.
• Review code that relies on env.benchmark being None to select benchmarks randomly. Now, env.benchmark is always set to the previously used benchmark, or a predetermined default benchmark if none has been specified. Setting env.benchmark = None will raise an error. Select a benchmark randomly by sampling from the env.datasets.benchmark_uris() iterator.
• Remove calls to env.require_dataset() and related operations. These are no longer required.
• Remove accesses to env.benchmarks. An iterator over available benchmark URIs is now available at env.datasets.benchmark_uris(), but the list of URIs cannot be relied on to be fully enumerable (the LLVM environments have over 2^32 URIs).
• Review code that accesses env.observation_space and update to env.observation_space_spec where necessary (#228).
• Update compiler service implementations to support the updated RPC interface by removing the deprecated GetBenchmarks RPC endpoint and replacing it with Dataset classes. See the example service for details.
• [LLVM] Update references to the poj104-v0 dataset to poj104-v1.
• [LLVM] Update references to the cBench-v1 dataset to cbench-v1.

CompilerGym v0.1.7

This release introduces public leaderboards to track the performance of
user-submitted algorithms on compiler optimization tasks.

• Added a new compiler_gym.leaderboard package which contains utilities for
  preparing leaderboard submissions (#161).
• Added a LLVM instruction count leaderboard and seeded it with a random search
  baseline (#117).
• Added support for Python 3.9, extending the set of supported python versions to
  3.6, 3.7, 3.8, and 3.9 (#160).
• [llvm] Added a new InstCount observation space that contains the counts of
  each type of instruction (#159).

Build dependencies update notice

This release updates the required versions for a handful of build dependencies.
If you are building from source and upgrading from an older version of CompilerGym,
your build environment will need to be updated. The easiest way to do that is to
remove your existing conda environment using conda remove --name compiler_gym --all
and to repeat the steps in building from source.