{"id":13808607,"url":"https://github.com/beaver-lodge/beaver","last_synced_at":"2025-12-12T00:14:09.779Z","repository":{"id":65425707,"uuid":"483460745","full_name":"beaver-lodge/beaver","owner":"beaver-lodge","description":"MLIR Toolkit in Elixir and Zig.","archived":false,"fork":false,"pushed_at":"2025-05-06T03:10:06.000Z","size":1524,"stargazers_count":193,"open_issues_count":7,"forks_count":9,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-05-06T03:34:04.206Z","etag":null,"topics":["compiler","elixir","gpu","mlir","zig"],"latest_commit_sha":null,"homepage":"","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/beaver-lodge.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-04-20T01:06:16.000Z","updated_at":"2025-04-29T05:56:56.000Z","dependencies_parsed_at":"2023-10-24T10:45:16.598Z","dependency_job_id":"9a82b8d4-68e6-4fb7-9b79-67a16e1b52b4","html_url":"https://github.com/beaver-lodge/beaver","commit_stats":{"total_commits":320,"total_committers":2,"mean_commits":160.0,"dds":"0.0031250000000000444","last_synced_commit":"a25dcc54f852b2e3379bd8a5764eda04eb873f9a"},"previous_names":["beaver-project/beaver"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beaver-lodge%2Fbeaver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beaver-lodge%2Fbeaver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beaver-lodge%2Fbeaver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beaver-lodge%2Fbeaver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/beaver-lodge","download_url":"https://codeload.github.com/beaver-lodge/beaver/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254459088,"owners_count":22074605,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["compiler","elixir","gpu","mlir","zig"],"created_at":"2024-08-04T01:01:47.320Z","updated_at":"2025-12-12T00:14:09.737Z","avatar_url":"https://github.com/beaver-lodge.png","language":"Elixir","funding_links":[],"categories":["Artificial Intelligence","Elixir"],"sub_categories":[],"readme":"[![Run in Livebook](https://livebook.dev/badge/v1/black.svg)](https://livebook.dev/run?url=https%3A%2F%2Fhexdocs.pm%2Fbeaver%2Fyour-first-beaver-compiler.livemd)\n\n# Beaver 🦫\n\n[![Package](https://img.shields.io/badge/-Package-important)](https://hex.pm/packages/beaver) [![Documentation](https://img.shields.io/badge/-Documentation-blueviolet)](https://hexdocs.pm/beaver)\n[![Check Upstream](https://github.com/beaver-lodge/beaver/actions/workflows/upstream.yml/badge.svg)](https://github.com/beaver-lodge/beaver/actions/workflows/upstream.yml)\n\n**Boost the almighty blue-silver dragon with some magical elixir!** 🧙🧙‍♀️🧙‍♂️\n\n## Motivation\n\nIn the de-facto way of using MLIR, we need to work with C/C++, TableGen, CMake and Python (in most of cases). Each language or tool here has some functionalities and convenience we want to leverage. There is nothing wrong choosing the most popular and upstream-supported solution, but having alternative ways to build MLIR-based projects is still valuable or at least worth trying.\n\nElixir could actually be a good fit as a MLIR front end. Elixir has SSA, pattern-matching, pipe-operator. We can use these language features to define MLIR patterns and pass pipeline in a natural and uniformed way. Elixir is strong-typed but not static-typed which makes it a great choice for quickly building prototypes to validate and explore new ideas.\n\nTo build a piece of IR in Beaver:\n\n```elixir\nFunc.func some_func(function_type: Type.function([], [Type.i(32)])) do\n  region do\n    block _() do\n      v0 = Arith.constant(value: Attribute.integer(Type.i(32), 0)) \u003e\u003e\u003e Type.i(32)\n      cond0 = Arith.constant(true) \u003e\u003e\u003e Type.i(1)\n      CF.cond_br(cond0, Beaver.Env.block(bb1), {Beaver.Env.block(bb2), [v0]}) \u003e\u003e\u003e []\n    end\n\n    block bb1() do\n      v1 = Arith.constant(value: Attribute.integer(Type.i(32), 0)) \u003e\u003e\u003e Type.i(32)\n      _add = Arith.addi(v0, v0) \u003e\u003e\u003e Type.i(32)\n      CF.br({Beaver.Env.block(bb2), [v1]}) \u003e\u003e\u003e []\n    end\n\n    block bb2(arg \u003e\u003e\u003e Type.i(32)) do\n      v2 = Arith.constant(value: Attribute.integer(Type.i(32), 0)) \u003e\u003e\u003e Type.i(32)\n      add = Arith.addi(arg, v2) \u003e\u003e\u003e Type.i(32)\n      Func.return(add) \u003e\u003e\u003e []\n    end\n  end\nend\n```\n\nAnd a small example to showcase what it is like to define and run a pass in Beaver (with some monad magic):\n\n```elixir\ndefmodule ToyPass do\n  @moduledoc false\n  use Beaver\n  alias MLIR.Dialect.{Func, TOSA}\n  require Func\n  import Beaver.Pattern\n  use MLIR.Pass, on: \"builtin.module\"\n\n  defpat replace_add_op() do\n    a = value()\n    b = value()\n    res = type()\n    {op, _t} = TOSA.add(a, b) \u003e\u003e\u003e {:op, [res]}\n\n    rewrite op do\n      {r, _} = TOSA.sub(a, b) \u003e\u003e\u003e {:op, [res]}\n      replace(op, with: r)\n    end\n  end\n\n  def run(%MLIR.Operation{} = operation, _state) do\n    with 1 \u003c- Beaver.Walker.regions(operation) |\u003e Enum.count(),\n         {:ok, _} \u003c-\n           MLIR.apply_(MLIR.Module.from_operation(operation), [replace_add_op(benefit: 2)]) do\n      :ok\n    else\n      _ -\u003e raise \"unreachable\"\n    end\n  end\nend\n\nuse Beaver\nimport MLIR.Transform\nctx = MLIR.Context.create()\n~m\"\"\"\nmodule {\n  func.func @tosa_add(%arg0: tensor\u003c1x3xf32\u003e, %arg1: tensor\u003c2x1xf32\u003e) -\u003e tensor\u003c2x3xf32\u003e {\n    %0 = \"tosa.add\"(%arg0, %arg1) : (tensor\u003c1x3xf32\u003e, tensor\u003c2x1xf32\u003e) -\u003e tensor\u003c2x3xf32\u003e\n    return %0 : tensor\u003c2x3xf32\u003e\n  }\n}\n\"\"\".(ctx)\n|\u003e Beaver.Composer.append(ToyPass)\n|\u003e canonicalize\n|\u003e Beaver.Composer.run!()\n```\n\n## Goals\n\n- Powered by Elixir's composable modularity and meta-programming features, provide a simple, intuitive, and extensible interface for MLIR.\n- Edit-Build-Test-Debug Loop at seconds. Everything in Elixir and Zig are compiled in parallel.\n- Compile Elixir to native/WASM/GPU with the help from MLIR.\n- Revisit and reincarnate symbolic AI in the HW-accelerated world. Erlang/Elixir has [a Prolog root](https://www.erlang.org/blog/beam-compiler-history/#the-prolog-interpreter)!\n- Introduce a new stack to machine learning.\n  - Higher-level: Elixir\n  - Representation: MLIR\n  - Lower-level: Zig\n\n## Why is it called Beaver?\n\nBeaver is an umbrella species increase biodiversity. We hope this project could enable other compilers and applications in the way a beaver pond becomes the habitat of many other creatures. Many Elixir projects also use animal names as their package names and it is often about raising awareness of endangered species. To read more about why beavers are important to our planet, check out [this National Geographic article](https://www.nationalgeographic.com/animals/article/beavers-climate-change-conservation-news).\n\n## Quick introduction\n\nBeaver is essentially LLVM/MLIR on Erlang/Elixir. It is kind of interesting to see a crossover of two well established communities and four sub-communities. Here are some brief information about each of them.\n\n### For Erlang/Elixir forks\n\n- Explain this MLIR thing to me in one sentence\n\n  MLIR could be regarded as the XML for compilers and an MLIR dialect acts like HTTP standard which gives the generic format real-world semantics and functionalities.\n\n- Check out [the home page](https://mlir.llvm.org/) of MLIR.\n\n### For LLVM/MLIR forks\n\n- What's so good about this programming language Elixir?\n\n  - It gets compiled to Erlang and runs on BEAM (Erlang's VM). So it has all the fault-tolerance and concurrency features of Erlang.\n  - As a Lisp, Elixir has all the good stuff of a Lisp-y language including hygienic macro, protocol-based polymorphism.\n  - Elixir has a powerful [module system](https://elixir-lang.org/getting-started/module-attributes.html) to persist compile-time data and this allows library users to easily adjust runtime behavior.\n  - Minimum, very few keywords. Most of the language is built with itself.\n\n\u003c!-- TODO: some rephrase --\u003e\n\n- Check out [the official guide](https://elixir-lang.org/getting-started/introduction.html) of Elixir.\n\n## Getting started\n\n- Tutorial: [Your first compiler with Beaver!](https://hexdocs.pm/beaver/your-first-beaver-compiler.html)\n\n\u003c!-- TODO: single .exs example --\u003e\n\n### Installation\n\nThe package can be installed\nby adding `beaver` to your list of dependencies in `mix.exs`:\n\n```elixir\ndef deps do\n  [\n    {:beaver, \"~\u003e 0.4.0\"}\n  ]\nend\n```\n\nAdd this to your `.formatter.exs` will have the formatter properly transform the macros introduced by `beaver`\n```elixir\nimport_deps: [:beaver],\n```\n\n### Projects built on top of Beaver\n\n- [Charm](https://github.com/beaver-lodge/charms): Compile a subset of Elixir to native targets.\n- [MLIR Accelerated Nx](https://github.com/beaver-lodge/manx): A backend for [Nx](https://github.com/elixir-nx/nx/).\n\n## How it works?\n\nTo implement a MLIR toolkit, we at least need these group of APIs:\n\n- IR API, to create and update Ops and blocks in the IR\n- Pass API, to create and run passes\n- Pattern API, in which you declare the transformation of a specific structure of Ops\n\nWe implement the IR API and Pass API with the help of the [MLIR C API](https://mlir.llvm.org/docs/CAPI/). There are both lower level APIs generated from the C headers and higher level APIs that are more idiomatic in Elixir.\nThe Pattern API is implemented with the help from the [PDL dialect](https://mlir.llvm.org/docs/Dialects/PDLOps/). We are using the lower level IR APIs to compile your Elixir code to PDL. Another way to look at this is that Elixir/Erlang pattern matching is serving as a frontend alternative to [PDLL](https://mlir.llvm.org/docs/PDLL/).\n\n## Design principles\n\n### Transformation over builder\n\nIt is very common to use builder pattern to construct IR, especially in an OO programming language like C++/Python.\nOne problem this approach has is that the compiler code looks very different from the code it is generating.\nBecause Erlang/Elixir is SSA by its nature, in Beaver a MLIR Op's creation is very declarative and its container will transform it with the correct contextual information. By doing this, we could:\n\n- Keep compiler code's structure as close as possible to the generated code, with less noise and more readability.\n- Allow dialects of different targets and semantic to introduce different DSL. For instance, CPU, SIMD, GPU could all have their specialized transformation tailored for their own unique concepts.\n\nOne example:\n\n```elixir\nmodule do\n  v2 = Arith.constant(1) \u003e\u003e\u003e ~t\u003ci32\u003e\nend\n# module/1 is a macro, it will transformed the SSA `v2= Arith.constant..` to:\nv2 =\n %Beaver.SSA{}\n  |\u003e Beaver.SSA.put_arguments(value: ~a{1})\n  |\u003e Beaver.SSA.put_block(Beaver.Env.block())\n  |\u003e Beaver.SSA.put_ctx(Beaver.Env.context())\n  |\u003e Beaver.SSA.put_results(~t\u003ci32\u003e)\n  |\u003e Arith.constant()\n```\n\nAlso, using the declarative way to construct IR, proper dominance and operand reference is formed naturally.\n\n\u003c!-- TODO: use real code here --\u003e\n\n```elixir\nSomeDialect.some_op do\n  region do\n    block entry() do\n      x = Arith.constant(1) \u003e\u003e\u003e ~t\u003ci32\u003e\n      y = Arith.constant(1) \u003e\u003e\u003e ~t\u003ci32\u003e\n    end\n  end\n  region do\n    block entry() do\n      z = Arith.addi(x, y) \u003e\u003e\u003e ~t\u003ci32\u003e\n    end\n  end\nend\n\n# will be transformed to:\n\nSomeDialect.some_op(\n  regions: fn -\u003e do\n    region = Beaver.Env.region() # first region created\n    block = Beaver.Env.block()\n    x = Arith.constant(...)\n    y = Arith.constant(...)\n\n    region = Beaver.Env.region() # second region created\n    block = Beaver.Env.block()\n    z = Arith.addi([x, y, ...]) # x and y dominate z\n  end\n)\n```\n\n### Beaver DSL as higher level AST for MLIR\n\nThere should be a 1:1 mapping between Beaver SSA DSL to MLIR SSA. It is possible to do a roundtrip parsing MLIR text format and dump it to Beaver DSL which is Elixir AST essentially. This makes it possible to easily debug a piece of IR in a more programmable and readable way.\n\nIn Beaver, working with MLIR should be in one format, no matter it is generating, transforming, debugging.\n\n### High level API in Erlang/Elixir idiom\n\nWhen possible, lower level C APIs should be wrapped as Elixir struct with support to common Elixir protocols.\nFor instance the iteration over one MLIR operation's operands, results, successors, attributes, regions should be implemented in Elixir's Enumerable protocol.\nThis enable the possibility to use the rich collection of functions in Elixir standard libraries and Hex packages.\n\n## Is Beaver a compiler or binding to LLVM/MLIR?\n\nElixir is a programming language built for all purposes. There are multiple sub-ecosystems in the general Erlang/Elixir ecosystem.\nEach sub-ecosystem appears distinct/unrelated to each other, but they actually complement each other in the real world production.\nTo name a few:\n\n- [Phoenix Framework](https://phoenixframework.org/) for web application and realtime message\n- [Nerves Project](https://www.nerves-project.org/) for embedded device and IoT\n- [Nx](https://github.com/elixir-nx/nx) for tensor and numerical\n\nEach of these sub-ecosystems starts with a seed project/library. Beaver should evolve to become a sub-ecosystem for compilers built with Elixir and MLIR.\n\n## MLIR context management\n\nWhen calling higher-level APIs, it is ideal not to have MLIR context passing around everywhere.\nIf no MLIR context provided, an attribute and type getter should return an anonymous function with MLIR context as argument.\nIn Erlang, all values are copied, so it is very safe to pass around these anonymous functions.\nWhen creating an operation, these functions will be called with the MLIR context in an operation state.\nWith this approach we achieve both succinctness and modularity, not having a global MLIR context.\nUsually a function accepting a MLIR context to create an operation or type is called a \"creator\" in Beaver.\n\n## Development\n\nPlease refer to [Beaver's contributing guide](/CONTRIBUTING.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeaver-lodge%2Fbeaver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbeaver-lodge%2Fbeaver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeaver-lodge%2Fbeaver/lists"}