agentleFS
trixi-frameworktrixi-framework/Trixi.jl/AGENTS.md

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.

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
  1. Distinctive:

    When editing this file, only add instructions and commands that have actually been tested in this repository.

    line 13
  2. Distinctive:

    Before editing, inspect git status and preserve all existing work.

    line 24
  3. Very specific:

    Instead, run only the individual test items related to the code you changed.

    line 100
  4. Very specific:

    Use the local Julia project run_agents/ at the root of this repository for running tests, elixirs, and scratch scripts.

    line 121
  5. Very specific:

    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 …

    line 132
  6. Distinctive:

    If a persistent Julia session via MCP is available, run the Julia code of the following command there (see below).

    line 148
  7. Very specific:

    Always call @run_package_tests inside cd(".../test") do ...

    line 179
  8. Very specific:

    Do not use julia --project=.

    line 185
  9. Very specific:

    Only variables that are assigned in the elixir can be overridden (e.g., not every elixir defines tspan).

    line 202
  10. Very specific:

    When developing new kernels, run Julia with --check-bounds=yes so that out-of-bounds accesses are caught despite @inbounds.

    line 205
  11. Very specific:

    Test items with the tag :mpi exercise the MPI code only with more than one MPI rank.

    line 207
  12. Very specific:

    Add tests as @testitems to the matching test/test_xxx.jl file (e.g., 3D linear advection on the TreeMesh goes into …

    line 244
  13. Distinctive:

    Test item names must be unique within a file.

    line 250
  14. Very specific:

    Never loosen tolerances (atol, rtol) just to make a failing test pass.

    line 265
  15. Very specific:

    Before adding or changing a numerical flux, a wave speed estimate, an equation, or pointwise functions of an equation, read …

    line 269
  16. Very specific:

    Use a suffix _ (name_) for local variables that would otherwise shadow existing names and a prefix _ (_name) for fragile internal functions …

    line 301
  17. Very specific:

    Prefer for i in ... over for i = ....

    line 304
  18. Very specific:

    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 …

    line 307
  19. Distinctive:

    Document new public functions and types with docstrings.

    line 314
  20. Very specific:

    Use wrap_array_native only where needed for external interfaces, and document exceptions such as AMR.

    line 344
  21. Very specific:

    Keep changes focused on a single goal.

    line 355
  22. Very specific:

    Document significant user-visible changes, including bug fixes that change results, in NEWS.md (section of the current lifecycle, e.g., …

    line 357
  23. Very specific:

    If a PR is created based on major contributions from an LLM/AI tool, disclose the LLM/AI assistance in the PR description (see …

    line 360
  24. Very specific:

    Do not commit generated files (e.g., out*/ directories, .vtu/.h5 output, Manifest.toml files) or temporary notes.

    line 362
  25. Distinctive:

    Do not commit or push unless asked to do so by the user.

    line 364

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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 point test/runtests.jl, test items in test/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 in README.md. Do not modify it; agents use run_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 in src/basic_types.jl. The include order in src/Trixi.jl is 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, and DGMultiMesh.
  • Solvers (src/solvers/) form a mesh × solver matrix: DGSEM in dgsem_tree, dgsem_structured, dgsem_unstructured, dgsem_p4est, dgsem_t8code (plus common parts in dgsem), and other families in dgmulti, fdsbp_*, and blockfv. Shared functionality lives in the directory of the most basic mesh/solver type (mostly dgsem_tree/); the other directories only add what differs. A DGSEM solver is composed of interchangeable VolumeIntegral*, SurfaceIntegral*, Indicator*, and mortar components. The right-hand side rhs_hyperbolic! (and rhs_parabolic!) sequences steps such as prolong2interfaces!, interface, boundary, and mortar fluxes, and volume and surface integrals.
  • Semidiscretizations (src/semidiscretization/) couple mesh, equations, and solver. SemidiscretizationHyperbolic is the workhorse; variants cover hyperbolic-parabolic, coupled, split, Euler-gravity, and Euler-acoustics systems. semidiscretize(semi, tspan) returns an ODEProblem.
  • Time integration and callbacks: OrdinaryDiffEq.jl/SciMLBase (solve(ode, alg; ...)) plus custom integrators in src/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 via trixi_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") or julia test/runtests.jl without a restrictive setup (without TRIXI_TEST, they run the threaded suite by default),
  • TRIXI_TEST=all, or entire CI partitions such as TRIXI_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, or AMDGPU.

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.jl

It 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_tests inside cd(".../test") do ... end as above. The macro searches for test items in the parent directory of the file it is called from; outside of a file (e.g., in julia -e or an MCP session), this is the parent of the current working directory. The do block restores the previous working directory afterward. Output files of test items are written to test/out/, as in Pkg.test.
  • Do not use julia --project=. (the package environment lacks the test dependencies) or julia --project=test (the test environment lacks Trixi.jl), and do not stack environments via JULIA_LOAD_PATH; the latter can mix incompatible package versions and fail during precompilation.
  • The first run after setting up or updating run_agents may 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/ (or grep -rn). Remember that elixirs can be included by other elixirs and tests via trixi_include.
  • To quickly try an elixir without the test harness, use trixi_include in the run_agents project, which can override assignments in the elixir, e.g.,
    using Trixi
    trixi_include(joinpath(examples_dir(), "tree_2d_dgsem", "elixir_advection_extended.jl"),
                  tspan = (0.0, 0.1))
    Only variables that are assigned in the elixir can be overridden (e.g., not every elixir defines tspan). Output files are written to out/, which must not be committed.
  • When developing new kernels, run Julia with --check-bounds=yes so that out-of-bounds accesses are caught despite @inbounds.
  • Test items with the tag :mpi exercise the MPI code only with more than one MPI rank. Before running them, read docs/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:

  1. a Kaimon.jl session started by the developer that loads Trixi.jl from this checkout (tools such as ping and ex; read docs/agents/kaimon.md before the first call), otherwise
  2. a session of julia-mcp (tools julia_eval, julia_restart, and julia_list_sessions; read docs/agents/julia_mcp.md before the first call), otherwise
  3. 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 matching test/test_xxx.jl file (e.g., 3D linear advection on the TreeMesh goes into test/test_tree_3d_advection.jl, unit tests into test/test_unit.jl). Copy the setup = [...] and tags = [...] 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_include compare l2/linf errors 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 the Evaluated: 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.md for 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 in run_agents/formatter/ (created by the setup command), e.g., from the root of the repository,
    julia --project=run_agents/formatter -e 'using JuliaFormatter; format(["src/file.jl", "test/test_file.jl"])'
    or via julia-mcp if available (see docs/agents/julia_mcp.md). format returns true if all files were already formatted; otherwise, it formats them in place and returns false. Pass only the files you changed. (Human developers often use utils/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_case for functions and variables, CamelCase for 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, or cache if only the cache is modified), otherwise mesh, 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 (not central_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 ... over for 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 (Float32 and Float64 are supported, as well as AD types): use 0.5f0 for exactly representable constants and convert(RealT, pi) with RealT = eltype(u) (or eltype(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, and initial_refinement_level or cells_per_dimension for the resolution, so that trixi_include and convergence_test can modify them. With a StepsizeCallback, pass an integer dummy time step dt = 1 (not 1.0) to solve.

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_direction argument 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 as FluxRotated explicitly forms a unit normal_vector and restores the magnitude afterward. Numerical fluxes and wave speed estimates must be homogeneous of degree one in normal_direction, i.e., f(u_ll, u_rr, α * n) == α * f(u_ll, u_rr, n) for α > 0 (e.g., multiply sound speeds by norm(normal_direction)). Check agreement with the corresponding orientation method 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 with semi, normally wrap them with wrap_array(u_ode, semi) before internal use. Wrapped arrays have no suffix. Use wrap_array_native only 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). See docs/src/github-git.md for the general workflow.
  • Keep changes focused on a single goal; PRs should usually change at most about 500 lines. See .github/review-checklist.md for 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/.h5 output, Manifest.toml files) or temporary notes.
  • Do not commit or push unless asked to do so by the user.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.