Skip to content

add the Compilation Handbook and video plugin#399

Merged
chbricout merged 4 commits into
mainfrom
compilation-handbook
May 28, 2026
Merged

add the Compilation Handbook and video plugin#399
chbricout merged 4 commits into
mainfrom
compilation-handbook

Conversation

@chbricout

Copy link
Copy Markdown
Contributor

This PR add my attempt to explain the compilation process of cirkit. I had to add a dependency to "mkdocs-video" a plugin to, you guessed it, add video on the documentation pages.

@codecov

codecov Bot commented Mar 9, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 68.71%. Comparing base (b9ed179) to head (a5e9763).
⚠️ Report is 5 commits behind head on main.

Additional details and impacted files
@@           Coverage Diff           @@
##             main     #399   +/-   ##
=======================================
  Coverage   68.71%   68.71%           
=======================================
  Files          58       58           
  Lines        6007     6007           
  Branches      773      773           
=======================================
  Hits         4128     4128           
  Misses       1590     1590           
  Partials      289      289           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@loreloc loreloc self-requested a review March 16, 2026 19:26

@loreloc loreloc left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I really like this PR! I have some feedback about the videos and the text though.

  • Layer Topological Order. I think the topological ordering in the video is not correct. E.g., in the first frame, the topological ordering should consider ALL input layers. Instead, all input layers except a single one are added to the set. In other words, the topological ordering does not care about the depth, but only cares about the connectivity. Layers at different depth can be folded together at the moment. We can also link to Kahn's algorithm, which is the one being implemented https://en.wikipedia.org/wiki/Topological_sorting.

  • Torch Compiler Components. Double check the indentation of the bullet points. All bullet points are at the same level, which I think is not intended.

  • Layer Compilation Process. I really like the diagram showing the compilation process. However, it is difficult to follow on a 16:9 screen, since it is a very tall diagram. I believe it can be simplified and and rotated to be horizontal.

  • Optimization Patterns. I struggled a lot trying to understand the diagram explaining the optimization patterns (and I wrote that part! :)). I feel you can remove this diagram.

  • About the optimization and implemented optimizations. I would keep a single simplified md file explaining both the optimization and implemented optimizations. That is, instead of having the examples in a separate md file, you could use the examples to motivate and explain how an optimization is being written. E.g., you can use the Log + Softmax = LogSoftmax as an example of the "fuse" optimization. I believe this would make the md file easy to follow, without having to resort to the very abstract example being shown now (the LayerPatternOne).

  • Other suggestions. I think it would be very useful if you could put hyperlinks from the handbook README files to the documentation urls. E.g., TorchParameter can point to the API page.

  • Minor. there are some wrong "math dollars symbols" below the "Sum Collapse Optimization" sections.

@chbricout

Copy link
Copy Markdown
Contributor Author

The only thing that I have not done is merging optimization and implemented patterns, I feel like it is quite useful to be able to see every implemented patterns in a single place with explanation. I guess the API reference is also supposed to do that but this leave more space for explanation.

@loreloc loreloc self-requested a review May 28, 2026 09:43

@loreloc loreloc left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@chbricout
Looks good to me! The graphics are nice and the documentation looks much more solid overall. It's good to also be having a pointer to a paper for the "Sum-Kronecker" optimization.
One can indeed improve the APIs for the optimization patterns in another PR.

@chbricout chbricout merged commit 7f69b64 into main May 28, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants