API Documentation

Dawn Toolchain Components

In many aspects, the Dawn toolchain code organization is designed to follow the component structure in LLVM. Dawn accepts a stencil intermediate representation (SIR) that frontends output, an optimizer that lowers this to a internal parallel intermediate representation (IIR) and runs optimization pass groups, then code generation backends that take this internal intermediate representation and generate code that can be understood by system compilers.

As far as possible, Dawn provides multiple ways of accessing its features: a C++ library with documented public interface, python bindings, and command line tools to access each toolchain component.

Frontend

The GT4Py frontend (not part of this repository), can write out the SIR that the Dawn toolchain consumes. However, the Dawn toolchain comes with one built-in embedded C++ frontend called GTClang. While originally a research project, it remains here mostly a proof of concept for ease of debugging. There are two methods to use this frontend:

1. C++ library

std::shared_ptr<dawn::SIR>
gtclang::run(const std::string& fileName, const gtclang::ParseOptions& options = {})

This takes a C++ file (fileName) and parsing options, and emits SIR.

2. Command line interface

Parsing utility

$ gtclang/bin/gtc-parse

This takes a C++ DSL file and writes SIR to file, if -o outfile.sir, or stdout.

There is also an end-to-end executable aptly named gtclang

$ gtclang/bin/gtclang

This is the end-to-end embedded C++ compiler using the GTClang DSL language that runs the frontend, optimizer, and when not given the -fnocodegen flag, the backend code generator. The backend may be selected by -backend=<backend> where <backend> is one of the code generation backends.

Optimizer

This is the core of the Dawn toolchain, and contains passes that lower from SIR to IIR, and optimize the IIR, e.g. reordering statements and fusing loops. Methods to access this are:

1. C++ library

Lower from SIR to IIR, and optimize IIR

/// @brief Lower to IIR and run groups
std::map<std::string, std::shared_ptr<dawn::iir::StencilInstantiation>>
dawn::run(const std::shared_ptr<dawn::SIR>& stencilIR,
          const std::list<dawn::PassGroup>& groups,
          const dawn::Options& options = {});

/// @brief Use strings in place of C++ structures
std::map<std::string, std::string>
dawn::run(const std::string& sir,
          dawn::SIRSerializer::Format format,
          const std::list<dawn::PassGroup>& groups = {},
          const dawn::Options& options = {});

Optimize IIR

/// @brief Run groups
std::map<std::string, std::shared_ptr<dawn::iir::StencilInstantiation>>
dawn::run(const std::map<std::string, std::shared_ptr<dawn::iir::StencilInstantiation>>&
              stencilInstantiationMap,
          const std::list<dawn::PassGroup>& groups,
          const dawn::Options& options = {});

/// @brief Use strings in place of C++ structures
std::map<std::string, std::string>
dawn::run(const std::map<std::string, std::string>& stencilInstantiationMap,
          dawn::IIRSerializer::Format format,
          const std::list<dawn::PassGroup>& groups = {},
          const dawn::Options& options = {});

2. Command line interface

The dawn/bin/dawn-opt executable accepts from stdin or file an SIR or IIR to lower and/or optimize, and writes IIR to stdout or a file.

3. Python

The pybind11 bindings wrap the string-based methods described above, but because Python does not allow overloading they are named slightly differently. Therefore, the prototypes for the calls are

def run_optimizer_sir(sir : str,
                      format = SIRSerializerFormat.Byte : str,
                      groups = [] : [PassGroup],
                      options = OptimizerOptions() : OptimizerOptions) -> {str:str}
    """Lower the sir (protobuf string) to a stencil instantiation map and run optimizer groups."""

def run_optimizer_iir(stencil_instantiation_map : {str,str},
                      format = IIRSerializerFormat.Byte : str,
                      groups = [] : [PassGroup],
                      options = OptimizerOptions() : OptimizerOptions) -> {str:str}
    """Run optimizer groups on the stencil instantiation map."""

Code Generation

The backends consume stencil instantiation maps and generate code with parallel abstractions that can be understood by other compilers.

1. C++ library The run methods take either stencil instantiation maps and convert these to translation units, or take a string IIR and convert it to a string of code.

/// @brief Run the code generation
std::unique_ptr<TranslationUnit>
dawn::codegen::run(const std::map<std::string, std::shared_ptr<iir::StencilInstantiation>>& context,
                   dawn::codegen::Backend backend,
                   const dawn::codegen::Options& options = {});

/// @brief Use strings in place of C++ structures
std::string
dawn::codegen::run(const std::map<std::string, std::string>& stencilInstantiationMap,
                   dawn::IIRSerializer::Format format,
                   const std::string& backend,
                   const dawn::codegen::Options& options = {});

Additionally, there are end-to-end methods that take SIR and write out a translation unit or code string:

/// @brief Compile SIR to a translation unit
std::unique_ptr<dawn::codegen::TranslationUnit>
dawn::compile(const std::shared_ptr<dawn::SIR>& stencilIR,
              const std::list<dawn::PassGroup>& passGroups = defaultPassGroups(),
              const dawn::Options& optimizerOptions = {},
              dawn::codegen::Backend backend = dawn::codegen::Backend::GridTools,
              const dawn::codegen::Options& codegenOptions = {});

/// @brief Use strings in place of C++ structures
std::string
dawn::compile(const std::string& sir,
              dawn::SIRSerializer::Format format,
              const std::list<dawn::PassGroup>& passGroups = dawn::defaultPassGroups(),
              const dawn::Options& optimizerOptions = {},
              dawn::codegen::Backend backend = dawn::codegen::Backend::GridTools,
              const dawn::codegen::Options& codegenOptions = {});

2. Command line interface

The dawn/bin/dawn-codegen utility accepts IIR and writes a code string to stdout or a file (if -o is passed).

3. Python

def run_codegen(stencil_instantiation_map : {str,str},
                format = IIRSerialzer.Byte : IIRSerializer,
                backend = CodeGenBackend.GridTools : CodeGenBackend,
                options OptimizerOptions() : OptimizerOptions) -> str

def compile_sir(sir : str,
                format = SIRSerializer.Byte : SIRSerializer,
                optimizer_groups = default_pass_groups() : [PassGroup],
                optimizer_options = OptimizerOptions() : OptimizerOptions,
                codegen_backend = CodeGenBackend.GridTools : CodeGenBackend,
                codegen_options OptimizerOptions() : OptimizerOptions) -> str