Trixi.jl
AGENTS.md737 starsChanged 14 days agoMITView on GitHub
Canonical instructions for AI coding agents (Claude Code, Codex, Copilot, Cursor, Gemini CLI, ...) working on Trixi.jl. Most tools read this file natively; Claude Code reads it via the @AGENTS.md import in CLAUDE.md. Keep this file the single source of truth; put only tool-specific notes into tool-specific files. The authoritative developer documentation lives in docs/src/ (in particular conventions.md, styleguide.md, testing.md, and development.md); this file summarizes what agents need most. Task-specific details live in docs/agents/; read a linked file there when…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,439 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repositoryOne other file it gives its agents.
- CLAUDE.mdCLAUDE.md
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
25 rules. About 0 are common, 6 are distinctive, and 19 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
19
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 13
When editing this file, only add instructions and commands that have actually been tested in this repository.
- Distinctive: line 24
Before editing, inspect git status and preserve all existing work.
- Very specific: line 100
Instead, run only the individual test items related to the code you changed.
- Very specific: line 121
Use the local Julia project run_agents/ at the root of this repository for running tests, elixirs, and scratch scripts.
- Very specific: line 132
Create or update all three projects by running the script utils/setup_run_agents.jl before running tests or the formatter, e.g., from the …
- Distinctive: line 148
If a persistent Julia session via MCP is available, run the Julia code of the following command there (see below).
- Very specific: line 179
Always call @run_package_tests inside cd(".../test") do ...
- Very specific: line 185
Do not use julia --project=.
- Very specific: line 202
Only variables that are assigned in the elixir can be overridden (e.g., not every elixir defines tspan).
- Very specific: line 205
When developing new kernels, run Julia with --check-bounds=yes so that out-of-bounds accesses are caught despite @inbounds.
- Very specific: line 207
Test items with the tag :mpi exercise the MPI code only with more than one MPI rank.
- Very specific: line 244
Add tests as @testitems to the matching test/test_xxx.jl file (e.g., 3D linear advection on the TreeMesh goes into …
- Distinctive: line 250
Test item names must be unique within a file.
- Very specific: line 265
Never loosen tolerances (atol, rtol) just to make a failing test pass.
- Very specific: line 269
Before adding or changing a numerical flux, a wave speed estimate, an equation, or pointwise functions of an equation, read …
- Very specific: line 301
Use a suffix _ (name_) for local variables that would otherwise shadow existing names and a prefix _ (_name) for fragile internal functions …
- Very specific: line 304
Prefer for i in ... over for i = ....
- Very specific: line 307
Keep code type-stable and generic in the real type (Float32 and Float64 are supported, as well as AD types): use 0.5f0 for exactly …
- Distinctive: line 314
Document new public functions and types with docstrings.
- Very specific: line 344
Use wrap_array_native only where needed for external interfaces, and document exceptions such as AMR.
- Very specific: line 355
Keep changes focused on a single goal.
- Very specific: line 357
Document significant user-visible changes, including bug fixes that change results, in NEWS.md (section of the current lifecycle, e.g., …
- Very specific: line 360
If a PR is created based on major contributions from an LLM/AI tool, disclose the LLM/AI assistance in the PR description (see …
- Very specific: line 362
Do not commit generated files (e.g., out*/ directories, .vtu/.h5 output, Manifest.toml files) or temporary notes.
- Distinctive: line 364
Do not commit or push unless asked to do so by the user.
≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md
Canonical instructions for AI coding agents (Claude Code, Codex, Copilot,
Cursor, Gemini CLI, ...) working on Trixi.jl. Most tools read this file natively;
Claude Code reads it via the @AGENTS.md import in CLAUDE.md. Keep this file
the single source of truth; put only tool-specific notes into tool-specific
files. The authoritative developer documentation lives in docs/src/ (in
particular conventions.md, styleguide.md, testing.md, and
development.md); this file summarizes what agents need most. Task-specific
details live in docs/agents/; read a linked file there when this file tells
you to.
When editing this file, only add instructions and commands that have actually been tested in this repository. Instructions that do not work are worse than no instructions.
Trixi.jl is a Julia package for adaptive high-order numerical simulations of conservation laws (hyperbolic PDEs and related parabolic and multi-physics problems), mainly with discontinuous Galerkin spectral element methods (DGSEM). Correctness of the numerics matters more than anything else: many bugs are silent (e.g., a wrong index or sign that only reduces accuracy), so be careful and verify mathematical changes.
Before editing, inspect git status and preserve all existing work. Do not
discard, reset, or stash unrelated changes while testing a fix.
Repository layout
src/: package code (see Architecture).examples/: elixirs, i.e., scripts setting up and running a simulation, grouped by mesh, dimension, and solver (e.g.,tree_2d_dgsem,p4est_3d_dgsem).test/: test suite (entry pointtest/runtests.jl, test items intest/test_*.jl).ext/: package extensions for weak dependencies (e.g., Makie, Plots, CUDA, AMDGPU).docs/: documentation source (docs/src/) and task-specific instructions for agents (docs/agents/, linked from this file);utils/: developer scripts (e.g., formatting).run/(if present, ignored by git): the human developer's own Julia project as suggested inREADME.md. Do not modify it; agents userun_agents/instead (see below).
Architecture
Trixi.jl is built on multiple dispatch over an abstract type hierarchy. A simulation combines equations × mesh × solver into a semidiscretization, which is integrated in time.
- The abstract root types (
AbstractEquations,AbstractMesh,AbstractSemidiscretization, ...) are defined insrc/basic_types.jl. The include order insrc/Trixi.jlis deliberate (basic_types→equations→meshes→solvers→ parabolic equations →semidiscretization→time_integration→callbacks_step/callbacks_stage); respect it when adding cross-cutting types. - Equations (
src/equations/), e.g.,CompressibleEulerEquations2D, are concrete types defined mainly by pointwise functions dispatched on them:flux, numerical fluxes (flux_lax_friedrichs,flux_ranocha, ...), wave speed estimates,initial_condition_*,boundary_condition_*,source_terms_*, and variable conversions (cons2prim,cons2entropy, ...). - Meshes (
src/meshes/):TreeMesh(Cartesian, the most basic and most tested),StructuredMesh,UnstructuredMesh2D,P4estMesh,T8codeMesh, andDGMultiMesh. - Solvers (
src/solvers/) form a mesh × solver matrix: DGSEM indgsem_tree,dgsem_structured,dgsem_unstructured,dgsem_p4est,dgsem_t8code(plus common parts indgsem), and other families indgmulti,fdsbp_*, andblockfv. Shared functionality lives in the directory of the most basic mesh/solver type (mostlydgsem_tree/); the other directories only add what differs. A DGSEM solver is composed of interchangeableVolumeIntegral*,SurfaceIntegral*,Indicator*, and mortar components. The right-hand siderhs_hyperbolic!(andrhs_parabolic!) sequences steps such asprolong2interfaces!, interface, boundary, and mortar fluxes, and volume and surface integrals. - Semidiscretizations (
src/semidiscretization/) couple mesh, equations, and solver.SemidiscretizationHyperbolicis the workhorse; variants cover hyperbolic-parabolic, coupled, split, Euler-gravity, and Euler-acoustics systems.semidiscretize(semi, tspan)returns anODEProblem. - Time integration and callbacks: OrdinaryDiffEq.jl/SciMLBase
(
solve(ode, alg; ...)) plus custom integrators insrc/time_integration/(low-storage, SSP, paired explicit RK, relaxation methods).src/callbacks_step/contains callbacks between time steps (e.g.,AnalysisCallback,AMRCallback,SaveSolutionCallback,StepsizeCallback);src/callbacks_stage/contains stage limiters and bounds checks applied within Runge-Kutta stages. - Elixirs (
examples/) are the main user-facing entry point and are run viatrixi_include. Every elixir must be used in at least one test.
Testing: never run the full test suite
Never run the complete test suite of Trixi.jl. It takes many hours and is run in CI (GitHub Actions) for every pull request. In particular, do not run
Pkg.test("Trixi")orjulia test/runtests.jlwithout a restrictive setup (withoutTRIXI_TEST, they run thethreadedsuite by default),TRIXI_TEST=all, or entire CI partitions such asTRIXI_TEST=tree_part1,- whole test files such as
include("test/test_tree_2d_euler.jl"), - the special suites
mpi,threaded,threaded_legacy,downgrade,kernelabstractions,CUDA, orAMDGPU.
Instead, run only the individual test items related to the code you changed.
Tests are isolated @testitems (TestItems.jl) run with TestItemRunner.jl. Test
files are named like test_<mesh>_<dim>_<equation>.jl (e.g.,
test_tree_2d_euler.jl) plus files such as test_unit.jl. Each test item
lists its setup snippets via setup = [...] (e.g., Setup, defined in
test/runtests.jl, and file-specific snippets such as TreeMesh2DMHD, defined
at the top of the corresponding test file) and its CI job via tags = [...];
CI runs one job per value of the TRIXI_TEST variable, which selects the test
items with the corresponding tag (see test/runtests.jl and
.github/workflows/ci.yml).
Run Julia code (tests, elixirs, scratch scripts) in a persistent session via
MCP if one is available, in the order of preference given in
Persistent Julia sessions via MCP. Check
for such tools before running the first Julia command; some agents list MCP
tools only by name until they are loaded (see CLAUDE.md for Claude Code). Use
the shell commands in this file only if no such session is available.
Task-specific instructions that show shell commands do not override this rule.
The run_agents Julia projects
Use the local Julia project run_agents/ at the root of this repository for
running tests, elixirs, and scratch scripts. It develops the local version of
Trixi.jl and contains all dependencies of the tests (copied from
test/Project.toml). Use run_agents/kernelabstractions/, which has the same
packages but selects the KernelAbstractions.jl threading backend, for code and
test items of this backend (e.g., tagged :kernelabstractions). The formatter
lives in run_agents/formatter/ (see Code style). Recycle these
projects from one run (and session) to the next instead of creating new
environments. They are ignored by git (run*/ in .gitignore) and must never
be committed.
Create or update all three projects by running the script
utils/setup_run_agents.jl before running tests or the formatter, e.g.,
from the root of the repository,
julia utils/setup_run_agents.jlIt is idempotent and takes only a few seconds if nothing changed. Read
docs/agents/run_agents.md if the setup or
loading Trixi.jl fails (e.g., ArgumentError: Package Trixi does not have X in
its dependencies), if you need additional packages, or if you compare results
or package versions with CI.
Running selected test items
If a persistent Julia session via MCP is available, run the Julia code of the following command there (see below). Otherwise, run, e.g., from the root of the repository,
julia --project=run_agents -e '
using TestItemRunner
cd("test") do
@run_package_tests filter = ti -> ti.name in (
"TreeMesh2D Advection: elixir_advection_basic.jl",
"Unit: Spectral analysis",
)
end'Useful filters (ti has the fields name, filename, and tags):
- exact names:
ti -> ti.name in ("name 1", "name 2") - substring:
ti -> occursin("elixir_mhd_alfven_wave", ti.name) - one file (use sparingly, some files are large):
ti -> endswith(ti.filename, "test_tree_2d_mhdmulti.jl")
Notes:
- Check the test summary. A filter that matches no test item does not fail;
TestItemRunner just prints a summary without any tests (
None). Make sure that the number of passed tests is plausible, and copy test item names exactly from the@testitem "..."lines. - Without a persistent Julia session, batch related test items into one call to avoid repeated startup costs.
- Always call
@run_package_testsinsidecd(".../test") do ... endas above. The macro searches for test items in the parent directory of the file it is called from; outside of a file (e.g., injulia -eor an MCP session), this is the parent of the current working directory. Thedoblock restores the previous working directory afterward. Output files of test items are written totest/out/, as inPkg.test. - Do not use
julia --project=.(the package environment lacks the test dependencies) orjulia --project=test(the test environment lacks Trixi.jl), and do not stack environments viaJULIA_LOAD_PATH; the latter can mix incompatible package versions and fail during precompilation. - The first run after setting up or updating
run_agentsmay take several minutes because of precompilation. Later runs are much faster. - Find the relevant test items by searching
test/for the elixir name, function name, or equation type you changed, e.g.,rg -n "elixir_mhd_rotor" test/(orgrep -rn). Remember that elixirs can be included by other elixirs and tests viatrixi_include. - To quickly try an elixir without the test harness, use
trixi_includein therun_agentsproject, which can override assignments in the elixir, e.g.,
Only variables that are assigned in the elixir can be overridden (e.g., not every elixir definesusing Trixi trixi_include(joinpath(examples_dir(), "tree_2d_dgsem", "elixir_advection_extended.jl"), tspan = (0.0, 0.1))tspan). Output files are written toout/, which must not be committed. - When developing new kernels, run Julia with
--check-bounds=yesso that out-of-bounds accesses are caught despite@inbounds. - Test items with the tag
:mpiexercise the MPI code only with more than one MPI rank. Before running them, readdocs/agents/mpi_tests.md.
Persistent Julia sessions via MCP
Some developers configure MCP servers providing persistent Julia sessions, in
which packages are loaded and compiled only once. If the corresponding tools
are available to you (possibly only listed by name until they are loaded, see
CLAUDE.md for Claude Code), use them to run Julia code such as tests and
elixirs, in the following order of preference:
- a Kaimon.jl session started by
the developer that loads Trixi.jl from this checkout (tools such as
pingandex; readdocs/agents/kaimon.mdbefore the first call), otherwise - a session of julia-mcp (tools
julia_eval,julia_restart, andjulia_list_sessions; readdocs/agents/julia_mcp.mdbefore the first call), otherwise - the shell commands described above.
Everything else in this file applies unchanged. Run the run_agents setup
script in the shell in any case (e.g., for the formatter), even if the
description of an MCP tool tells you to never run Julia via the command line.
Sessions may run with non-default Julia flags chosen by the developer (e.g.,
--threads=1 --check-bounds=yes). Check them with Threads.nthreads() and
Base.JLOptions().check_bounds (1 means bounds checking is enabled) if they
matter, e.g., for timings or allocation tests.
Adding and changing tests
- New or changed behavior must be covered by focused tests; the overall test coverage must not decrease (hard lower bound 97%). For a bug fix, verify that the regression test detects the original behavior when feasible, using a separate checkout or temporarily reverting only your own changes. Preserve unrelated work in the shared working tree.
- Add tests as
@testitems to the matchingtest/test_xxx.jlfile (e.g., 3D linear advection on theTreeMeshgoes intotest/test_tree_3d_advection.jl, unit tests intotest/test_unit.jl). Copy thesetup = [...]andtags = [...]of neighboring test items; the tags select the CI job. - Exercise every new elixir in at least one test item. For a new equation or numerical method, run a convergence study and report the observed order.
- Test item names must be unique within a file.
- Each test item should run in less than 10 seconds (single thread, after
compilation). Use short
tspans or coarse meshes where possible. - Regression tests via
@test_trixi_includecomparel2/linferrors with reference values. If a change intentionally modifies results, inspect the actual values and relevant numerical behavior first, and check that the change is plausible; for example, errors of smooth test cases with an analytical solution (e.g., convergence tests with manufactured solutions) should usually not increase after a bug fix. Otherwise, the errors are computed with respect to the initial condition evaluated at the final time, which is in general not the exact solution, so they may change in either direction. Then run the affected test items once, take the actual values from theEvaluated: isapprox(expected, actual; ...)lines of the failures, replace the reference values only within the affected test items, rerun them, and explain the change in the PR. - Never loosen tolerances (
atol,rtol) just to make a failing test pass. A local, commented tolerance is acceptable only for small differences whose cause is understood and outside Trixi.jl (e.g., adaptive time stepping in a new dependency version); mention it to the user. - Before adding or changing a numerical flux, a wave speed estimate, an
equation, or pointwise functions of an equation, read
docs/agents/tests_fluxes_equations.mdfor the required unit, consistency, and type stability tests.
Code style
- Format all changed Julia files with JuliaFormatter.jl v1.0.60 (configuration
in
.JuliaFormatter.toml, SciML style); CI checks the formatting. Other versions of JuliaFormatter.jl format differently, so use the pinned version inrun_agents/formatter/(created by the setup command), e.g., from the root of the repository,
or via julia-mcp if available (seejulia --project=run_agents/formatter -e 'using JuliaFormatter; format(["src/file.jl", "test/test_file.jl"])'docs/agents/julia_mcp.md).formatreturnstrueif all files were already formatted; otherwise, it formats them in place and returnsfalse. Pass only the files you changed. (Human developers often useutils/trixi-format-file.jl, which installs the formatter in a temporary environment on every call.) - Maximum line length 92, 4 spaces for indentation (never tabs),
snake_casefor functions and variables,CamelCasefor modules and types, trailing!for mutating functions. Executable code must be ASCII; comments and docstrings may use Unicode. - Argument order: the modified argument first (e.g.,
du, orcacheif only the cache is modified), otherwisemesh, equations, solver, cache; dispatch helpers before the general argument (e.g.,have_nonconservative_terms(equations), equations). - Name related functions with the general category first, e.g.,
flux_central(notcentral_flux),min_max_speed_davis. - Use a suffix
_(name_) for local variables that would otherwise shadow existing names and a prefix_(_name) for fragile internal functions that are not part of the documented API. - Prefer
for i in ...overfor i = .... Group multiline expressions with explicit parentheses instead of relying on implicit line continuation. - Most source files are wrapped in
@muladd begin ... end; keep this structure. - Keep code type-stable and generic in the real type (
Float32andFloat64are supported, as well as AD types): use0.5f0for exactly representable constants andconvert(RealT, pi)withRealT = eltype(u)(oreltype(x)) otherwise. Use StaticArrays.jl (SVector,MVector, ...) for small arrays of fixed size. - Performance-critical code must not allocate; many regression tests check this
with
@test_allocations. - Document new public functions and types with docstrings; for internal code, a top-level comment can suffice. Reference publications where appropriate. Comments should explain why, not only what.
- Match the style of the surrounding code, and look for existing helpers before adding new ones.
- In elixirs, use the standard variable names
polydeg,surface_flux,volume_flux, andinitial_refinement_levelorcells_per_dimensionfor the resolution, so thattrixi_includeandconvergence_testcan modify them. With aStepsizeCallback, pass an integer dummy time stepdt = 1(not1.0) tosolve.
Numerical conventions and common pitfalls
orientations:1 => x, 2 => y, 3 => z;directions:1 => -x, 2 => +x, 3 => -y, 4 => +y, 5 => -z, 6 => +z.- A
normal_directionargument may be non-unit and carry surface scaling, especially on curved meshes. Fluxes and wave speeds using it must account for its magnitude exactly once. Code such asFluxRotatedexplicitly forms a unitnormal_vectorand restores the magnitude afterward. Numerical fluxes and wave speed estimates must be homogeneous of degree one innormal_direction, i.e.,f(u_ll, u_rr, α * n) == α * f(u_ll, u_rr, n)forα > 0(e.g., multiply sound speeds bynorm(normal_direction)). Check agreement with the correspondingorientationmethod for axis-aligned unit normals. - Nonconservative surface terms depend on the argument order: the element
receiving the flux passes its own state first,
nonconservative_flux(u_own, u_neighbor, ...), including at mortars. - Arrays visible to the time integrator have the suffix
_ode(u_ode,du_ode); when passed withsemi, normally wrap them withwrap_array(u_ode, semi)before internal use. Wrapped arrays have no suffix. Usewrap_array_nativeonly where needed for external interfaces, and document exceptions such as AMR. - Compare 1D/2D/3D and x/y/z implementations of the same function when changing one of them; copy-paste errors between dimensions and directions are the most common source of bugs.
Pull requests and documentation
- Develop in a branch; branch names usually follow
<developer initials>/<short description>(e.g.,hr/fix_mortar_fluxes). Seedocs/src/github-git.mdfor the general workflow. - Keep changes focused on a single goal; PRs should usually change at most about
500 lines. See
.github/review-checklist.mdfor what reviewers look for. - Document significant user-visible changes, including bug fixes that change
results, in
NEWS.md(section of the current lifecycle, e.g., "Added" or "Changed", with the PR number once known). - If a PR is created based on major contributions from an LLM/AI tool, disclose
the LLM/AI assistance in the PR description (see
CONTRIBUTING.md). - Do not commit generated files (e.g.,
out*/directories,.vtu/.h5output,Manifest.tomlfiles) or temporary notes. - Do not commit or push unless asked to do so by the user.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

