| # CodeRabbit configuration for Eigen. | |
| # Schema: https://docs.coderabbit.ai/reference/configuration | |
| # | |
| # Eigen is a header-only C++14 template library, GitLab-hosted, with a strict | |
| # ABI policy and several major downstream consumers (notably TensorFlow). The | |
| # settings below favor signal over volume: chill profile, minimal noise on | |
| # auto-generated docs and vendored Fortran, and explicit guidance for the | |
| # template-heavy core. | |
| language: en-US | |
| # CodeRabbit caps tone_instructions at 250 chars. Keep the essential | |
| # focus areas here; the full reviewer guidance (provenance discipline, | |
| # numerical-tolerance policy, GPU caveats, etc.) lives in AGENTS.md | |
| # and is loaded via knowledge_base.code_guidelines.filePatterns below. | |
| tone_instructions: >- | |
| Eigen, header-only C++14. Focus: correctness, numerical accuracy | |
| (LAPACK-level; flag regressions), ABI, performance, template pitfalls, | |
| missing tests, uncited published algorithms (LAPACK, LAWN, Higham, | |
| Golub & van Loan). Skip style nits and C++17+. | |
| early_access: false | |
| enable_free_tier: true | |
| # Pull repo-level reviewer guidance from AGENTS.md (the agent-facing | |
| # condensation of CONTRIBUTING + wiki). Set explicitly because the | |
| # default filePatterns list may be inactive when no patterns are | |
| # specified by the user. | |
| knowledge_base: | |
| code_guidelines: | |
| enabled: true | |
| filePatterns: | |
| - "AGENTS.md" | |
| reviews: | |
| profile: chill | |
| request_changes_workflow: false | |
| # Trim down the noise in the auto-posted comment: drop sections that don't | |
| # carry weight on a numerics-heavy template library. Keep the walkthrough | |
| # (file-by-file summary) but skip the high-level summary, the changed-files | |
| # overview, and don't collapse the walkthrough so reviewers see it expanded. | |
| high_level_summary: false | |
| high_level_summary_in_walkthrough: false | |
| poem: false | |
| review_status: true | |
| collapse_walkthrough: false | |
| changed_files_summary: false | |
| enable_prompt_for_ai_agents: true | |
| sequence_diagrams: false | |
| estimate_code_review_effort: false | |
| assess_linked_issues: false | |
| related_issues: false | |
| related_prs: false | |
| suggested_labels: false | |
| suggested_reviewers: false | |
| in_progress_fortune: false | |
| pre_merge_checks: | |
| # Eigen is a header-only template library where docstring coverage | |
| # has limited value; the docstrings precheck adds noise without signal. | |
| docstrings: | |
| mode: off | |
| auto_review: | |
| enabled: true | |
| drafts: false | |
| # Eigen MRs often see many WIP pushes; reviewing every push burns the | |
| # per-developer hourly rate limit on the free/OSS tier. Review the first | |
| # diff only; further reviews can be requested with `@coderabbitai review`. | |
| auto_incremental_review: false | |
| base_branches: | |
| - master | |
| path_filters: | |
| - "!doc/snippets/**" | |
| - "!doc/examples/**" | |
| - "!lapack/*.f" | |
| - "!blas/testing/**" | |
| - "!**/*.png" | |
| - "!**/*.bin" | |
| - "!**/*.svg" | |
| - "!**/*.pdf" | |
| path_instructions: | |
| - path: "**" | |
| instructions: | | |
| Repo-wide conventions (apply across all paths): | |
| - **SPDX / REUSE.** Every new source file (`.h`, `.cpp`, `.cu`, | |
| `.inc`, `.cmake`, `CMakeLists.txt`, etc.) must carry the | |
| standard Eigen MPL-2.0 SPDX + copyright header inline. The | |
| `reuse lint` check in the `checkformat:lint` CI job blocks otherwise. | |
| Files that can't carry inline headers (top-level docs, | |
| generated/templated files, binary assets) are covered by | |
| path-based annotations in `REUSE.toml` — add the path there | |
| if creating one. | |
| - **GitLab is upstream**; the GitHub mirror is read-only. Do | |
| not suggest opening PRs / pushing to GitHub. | |
| - **Commit messages** follow `Category: Short description` | |
| (e.g. `GPU: Fix special-function test coverage`). | |
| - path: "Eigen/src/**" | |
| instructions: | | |
| Eigen is a header-only C++14 template library with a strict ABI policy. | |
| - **Numerical accuracy is a top priority.** Eigen targets accuracy | |
| comparable to established numerical libraries such as LAPACK. Flag | |
| any change that may degrade accuracy, condition handling, stability | |
| under near-singular / ill-conditioned inputs, or behavior near | |
| subnormals, infinities, NaNs, or extreme exponents. In general, | |
| do not trade accuracy for speed. | |
| - **Acceptable accuracy tradeoff on regular inputs only.** A faster | |
| algorithm whose worst-case error on regular inputs is bounded to | |
| a few ULPs by a principled analysis may be acceptable. Surface | |
| the tradeoff and the bound clearly so a human reviewer can judge; | |
| do not auto-approve or auto-reject these. **Special-value handling | |
| is not subject to the few-ULP tradeoff** — IEEE-754 entities (NaN, | |
| ±0, ±∞, subnormals) and standard-library edge cases (e.g. `log(0)`, | |
| `pow(0, 0)`) must match the cppreference / IEEE 754 spec exactly. | |
| - **Numerical changes require numerical tests.** Any new numerical | |
| algorithm, kernel, or accuracy-sensitive change MUST come with | |
| tests that exercise its accuracy claims: random ill-conditioned | |
| inputs across a range of condition numbers, edge values, and | |
| matrices structured for the algorithm (Hilbert, Vandermonde, | |
| Pascal, Wilkinson's W, Frank, Lehmer, KMS / Toeplitz, banded, | |
| rank-deficient, defective / near-defective Jordan blocks, | |
| positive-definite-but-barely — MATLAB's `gallery()` is the | |
| standard catalog; Higham's *Accuracy and Stability of Numerical | |
| Algorithms* / *Functions of Matrices* and Golub & van Loan are | |
| the references). For routines with a | |
| LAPACK counterpart, match LAPACK's TESTING/ category coverage as | |
| the bar. Quantify accuracy in ULPs against a scalar reference, | |
| not just relative error. Sollya / MPFR are the standard tools | |
| for ground-truth and polynomial generation; prefer in-C++ MPFR | |
| verification over a Python reference. If such tests are missing, | |
| request them. | |
| - **Performance-sensitive changes ship with a benchmark** under | |
| `benchmarks/` or `contrib/benchmarks/`. Don't defer to a | |
| follow-up MR. | |
| - **Preserve `EIGEN_DEVICE_FUNC`.** It is pervasive on coefficient- | |
| level methods so the same code compiles for host and CUDA / HIP / | |
| SYCL device. Dropping it silently breaks GPU builds and is rarely | |
| caught locally — flag any removal or omission on new methods. | |
| - **Header-only contract.** Never include from `Eigen/src/...` (or | |
| `contrib/Eigen/src/...`) directly; reach implementation via | |
| the umbrella module headers (`Eigen/Core`, `Eigen/Dense`, …). | |
| `InternalHeaderCheck.h` makes direct internal includes a hard | |
| error. Old internal headers do not get backward-compatibility | |
| forwarding shims when moved/renamed; only the public umbrella | |
| headers do. | |
| - **Aliasing in fast paths.** Aliasing safety is not a uniform | |
| invariant. The standard product path inserts an auto-temporary | |
| so `mat = mat * mat` is safe, but optimized fast paths that | |
| bypass the general assignment machinery have historically | |
| introduced aliasing bugs. When a change modifies or adds such a | |
| fast path, check whether LHS/RHS aliasing is handled and prefer | |
| falling back to the general path when in doubt. | |
| - Treat the public API surface as frozen: do not propose renames or | |
| signature changes for non-internal types. | |
| - Performance and inlining matter; flag possible regressions in hot | |
| paths (products, packet kernels, evaluators, decompositions). | |
| - Watch for accidental allocations in templates that should be | |
| allocation-free. | |
| - C++14 is the minimum; do not suggest C++17+ features. (A migration | |
| to C++17 is planned on a separate branch; until it lands on master, | |
| new code must compile under C++14.) | |
| - **Skip "modernize" advice.** Do not propose `modernize-*` or | |
| `cppcoreguidelines-*` clang-tidy fixes; do not suggest replacing | |
| `EIGEN_STRONG_INLINE` with `inline`; do not propose reordering | |
| internal includes (`SortIncludes: false` is intentional); and do | |
| not "fix" Eigen's macro indentation (`.clang-format` registers | |
| Eigen macros as `StatementMacros` / `AttributeMacros`). | |
| Style is `clang-format-17` exactly — the CI diff is authoritative. | |
| - **Assertions.** Prefer `eigen_assert` (and | |
| `eigen_internal_assert` for internal-only invariants) over raw | |
| `assert` for runtime preconditions; prefer `EIGEN_STATIC_ASSERT` | |
| over plain `static_assert` for compile-time conditions. | |
| - path: "Eigen/src/Core/arch/**" | |
| instructions: | | |
| Per-architecture packet math (SIMD vectorization) backends. In | |
| addition to the general `Eigen/src/**` rules: | |
| - **Guard intrinsics by ISA macro.** Each intrinsic must be wrapped | |
| in its own `EIGEN_VECTORIZE_*` `#ifdef` — being inside `arch/AVX/` | |
| does not imply AVX2 / FMA / AVX-512 are available. Wrap AVX2 in | |
| `EIGEN_VECTORIZE_AVX2`, FMA in `EIGEN_VECTORIZE_FMA`, AVX-512DQ | |
| in `EIGEN_VECTORIZE_AVX512DQ`, etc., and provide a fallback for | |
| the un-guarded path. Same discipline applies on NEON | |
| (`EIGEN_VECTORIZE_NEON_FP16`), VSX (`EIGEN_VECTORIZE_VSX`), etc. | |
| Missing guards typically compile fine on the developer's machine | |
| and break CI on narrower ISA targets — flag any unguarded | |
| intrinsic. | |
| - **Backend symmetry.** New packet operations should be specialized | |
| across **every** backend that supports the type, with | |
| `arch/Default/` providing scalar fallbacks. A missing or divergent | |
| backend specialization usually shows up first in | |
| `test/packetmath.cpp` or `contrib/test/special_packetmath.cpp` | |
| — flag PRs that add a packet op in one backend without the others. | |
| - path: "{Eigen/ThreadPool,Eigen/src/ThreadPool/**}" | |
| instructions: | | |
| Eigen's work-stealing thread pool — umbrella header `Eigen/ThreadPool` | |
| with sources under `Eigen/src/ThreadPool/` (`NonBlockingThreadPool`, | |
| `RunQueue`, `EventCount`, `ForkJoin`, `CoreThreadPoolDevice`). Backs | |
| `EIGEN_GEMM_THREADPOOL` and the Tensor module's `ThreadPoolDevice`. | |
| Originally developed for TensorFlow and still depended on there — | |
| signatures, semantics, and performance are load-bearing. Apply the | |
| same caution as the Tensor module: prefer additive changes, keep | |
| header layout stable, and call out behavior changes prominently. | |
| - path: "test/**" | |
| instructions: | | |
| Tests use Eigen's custom framework defined in `test/main.h`: | |
| `VERIFY_*` assertions, `CALL_SUBTEST_N` / `EIGEN_TEST_PART_N` to | |
| split one `.cpp` into N per-shard executables, and | |
| `EIGEN_DECLARE_TEST(<name>) { ... }` as the entry point. | |
| `EIGEN_REPEAT` / `EIGEN_SEED` are runtime env vars, not the shard | |
| mechanism. Do not suggest restructuring the harness, switching to | |
| gtest assertions, or deduplicating shards. Numerical-tolerance | |
| comparisons (`VERIFY_IS_APPROX`) are deliberate; do not push for | |
| exact equality. Tests may be long and procedural. | |
| **In-flight migration to Google Test:** | |
| [MR 2159](https://gitlab.com/libeigen/eigen/-/merge_requests/2159) | |
| replaces `EIGEN_DECLARE_TEST` / `CALL_SUBTEST_N` with gtest | |
| `TEST` / `TYPED_TEST` while bridging `VERIFY_*` to gtest | |
| expectations; once it lands, the "do not switch to gtest" rule | |
| flips for new tests. | |
| - path: "contrib/Eigen/**" | |
| instructions: | | |
| The `contrib/` tree means looser API-stability guarantees, **not** | |
| low-traffic or low-stakes. The Tensor module | |
| (`contrib/Eigen/Tensor`, sources under | |
| `contrib/Eigen/src/Tensor/`) is TensorFlow's core compute | |
| backend; treat its signatures, header layout, semantics, and | |
| performance on contraction / reduction / morphing kernels as | |
| load-bearing. Prefer additive changes, keep header paths stable, | |
| and call out behavior changes prominently. Other modules | |
| (`TensorSymmetry`, `AutoDiff`, `Polynomials`, `MatrixFunctions`, | |
| `NNLS`, `FFT`, `GPU`, `Splines`, `NumericalDiff`, | |
| `IterativeSolvers`) are genuinely more permissive but should still | |
| preserve their public API. `unsupported/Eigen/CXX11/` is backward- | |
| compatibility forwarding shims only — do not place new headers | |
| there. | |
| - path: "contrib/Eigen/src/GPU/**" | |
| instructions: | | |
| Host-side dispatch to NVIDIA libraries (cuBLAS / cuSOLVER / cuFFT / | |
| cuSPARSE / cuDSS) on device-resident operands (`gpu::DeviceMatrix`). | |
| This is **not** an expression-template layer — every supported | |
| expression maps to a single library call, and `DeviceMatrix` does | |
| not inherit from `MatrixBase`. Do not suggest reshaping it into an | |
| expression-template system. Tests are deliberately compiled as | |
| `.cpp` (not `.cu`) so NVCC does not instantiate Eigen CPU packet | |
| ops for CUDA vector types — do not propose moving them to `.cu`. | |
| - path: "blas/**" | |
| instructions: | | |
| These are Reference BLAS API wrappers around Eigen. Match the BLAS | |
| standard exactly; do not suggest deviating from netlib semantics. | |
| - path: "lapack/**" | |
| instructions: | | |
| The .f sources are vendored netlib LAPACK reference; do not review | |
| them. The C++ wrappers should faithfully implement the LAPACK | |
| contract. | |
| - path: "ci/**" | |
| instructions: | | |
| GitLab CI configuration. Be conservative -- do not suggest | |
| restructuring the existing job graph or changing runner tags without | |
| strong reason. | |
| - path: "benchmarks/**" | |
| instructions: | | |
| Microbenchmarks built against Google Benchmark. Clarity matters less | |
| than realistic measurement; flag only correctness or measurement | |
| methodology issues, not style. | |
| chat: | |
| auto_reply: true |