search

trixi-framework / Trixi.jl

Trixi.jl: Adaptive high-order numerical simulations of conservation laws in Julia
https://trixi-framework.github.io/Trixi.jl
MIT License
505 stars 98 forks source link

More consistent documentation of available grid types #1907

Open knstmrd opened 2 months ago

knstmrd commented 2 months ago

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)
DanielDoehring commented 2 months ago

Thanks for your feedback!

I prepared a PR (#1911) addressing some of your points where I agree with you.

Regarding your feedback:

  1. I agree, it would be nice if Meshes would actually be a page on which you can link to the overview. I am not sure, however, if this is possible.
  2. Yes, the description is sparse but on that pages you actually find the info on the numerical fluxes you request in point 2. So removing them does not sound like a good idea to me.
  3. Well, this is opinion-based - I am not sure if it is worth moving stuff around if it is clearly visible from the main landing page.
  4. As the section on non-periodic boundaries is not restricted to TreeMesh, I do not see really the need to link there - again, the section on non-periodic boundaries is not to overlook from the main menu.