trixi-framework / trixi-framework/Trixi.jl

More consistent documentation of available grid types

Open
#1,907 1 comment 0 reactions 0 assignees View on GitHub
discussion documentation possible student project
Dominant language
Julia
Stars
731
Forks
166
Avg merge
2d 18h
Merged PRs (30d)
25

Description

After some time working with Trixi and reading the docs, the descriptions of the available grids, their capabilities and restrictions seem somewhat scattered throughout the documentation, so I wanted to create this issue to systematise my observations and help out on unifying the documentation in that regard.

The issues I see:

1. The overview of the grid capabilities (AMR support, connectivity, etc.) is only present in the "Getting Started/Overview" section. It is not present in the "Basic building blocks/Meshes" section (even as a link), which is where one might be expected to actually look for info on grids.
2. This overview however does not mention which type of fluxes (i.e. dispatching on normals or integer directions) are needed for which grid
3. The descriptions of the Tree and Structured Mesh types are quite sparse (and could possibly be replaced by the table listing the different grid capabilities?)
4. The P4est Mesh documentation in "Basic building blocks/Meshes/P4est" has quite a bit of info on constructing grids from Abaqus files, but no mention of possibility of gmsh import (which is instead a tutorial). I personally think it would easier to read if the Abaqus file read-in was also moved to the tutorial, and the P4est mesh documentation just linked to the gmsh and Abaqus tutorials.
5. Similarly, links for the TreeMesh documentation part to the "Non-periodic boundaries" section and for the Structured Mesh to the "Structured mesh with curvilinear mapping" would also be helpful
6. Finally, I haven't seen it explicitly mentioned that TreeMesh makes the domain square? I know I got confused by the implicit conversion happening (see https://github.com/trixi-framework/Trixi.jl/issues/1889)

Contributor guide

Open the contributing guide

Research direction

Start with the "Getting Started/Overview" and "Basic building blocks/Meshes" sections, then review the TreeMesh, Structured Mesh, and P4est Mesh documentation alongside the linked tutorials and boundary sections. Compare the existing descriptions, grid capabilities, flux requirements, imports, links, and domain-shape note. Done means the grid guidance is unified, cross-linked, and covers the observations listed in the issue.

Written by the indexing model from the issue text.

Assessment

Tech stack
julia
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.