Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add preprocessing step to automate numbering in tutorial introduction #1901

Merged
merged 4 commits into from
Apr 9, 2024
Merged

Add preprocessing step to automate numbering in tutorial introduction #1901

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a7d4280
Add preprocessing of tutorial introduction file
bennibolm Apr 8, 2024
eda7a83
Rename variables
bennibolm Apr 9, 2024
b88f128
implement suggestions
bennibolm Apr 9, 2024
2e93da2
Merge branch 'main' into preprocessing-introduction
bennibolm Apr 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion docs/literate/make.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,17 @@ function create_tutorials(files)
end

# Generate markdown file for introduction page
Literate.markdown(joinpath(repo_src, "index.jl"), pages_dir; name="introduction")
# Preprocessing introduction file: Generate consecutive tutorial numbers by replacing
# each occurrence of `{index}` with an integer incremented by 1, starting at 1.
function preprocess_introduction(content)
counter = 1
while occursin("{index}", content)
content = replace(content, "{index}" => "$counter", count = 1)
counter += 1
end
return content
end
Literate.markdown(joinpath(repo_src, "index.jl"), pages_dir; name="introduction", preprocess=preprocess_introduction)
# Navigation system for makedocs
pages = Any["Introduction" => "tutorials/introduction.md",]

Expand Down
60 changes: 40 additions & 20 deletions docs/literate/src/files/index.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,14 +14,16 @@

# There are tutorials for the following topics:

# ### [1 First steps in Trixi.jl](@ref getting_started)
#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
# ### [{index} First steps in Trixi.jl](@ref getting_started)
#-
# This tutorial provides guidance for getting started with Trixi.jl, and Julia as well. It outlines
# the installation procedures for both Julia and Trixi.jl, the execution of Trixi.jl elixirs, the
# fundamental structure of a Trixi.jl setup, the visualization of results, and the development
# process for Trixi.jl.

# ### [2 Behind the scenes of a simulation setup](@ref behind_the_scenes_simulation_setup)
#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
# ### [{index} Behind the scenes of a simulation setup](@ref behind_the_scenes_simulation_setup)
#-
# This tutorial will guide you through a simple Trixi.jl setup ("elixir"), giving an overview of
# what happens in the background during the initialization of a simulation. While the setup
Expand All @@ -30,92 +32,106 @@
# the more fundamental, *technical* concepts that are applicable to a variety of
# (also more complex) configurations.s

# ### [3 Introduction to DG methods](@ref scalar_linear_advection_1d)
#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
# ### [{index} Introduction to DG methods](@ref scalar_linear_advection_1d)
#-
# This tutorial gives an introduction to discontinuous Galerkin (DG) methods with the example of the
# scalar linear advection equation in 1D. Starting with some theoretical explanations, we first implement
# a raw version of a discontinuous Galerkin spectral element method (DGSEM). Then, we will show how
# to use features of Trixi.jl to achieve the same result.

# ### [4 DGSEM with flux differencing](@ref DGSEM_FluxDiff)
#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
# ### [{index} DGSEM with flux differencing](@ref DGSEM_FluxDiff)
#-
# To improve stability often the flux differencing formulation of the DGSEM (split form) is used.
# We want to present the idea and formulation on a basic 1D level. Then, we show how this formulation
# can be implemented in Trixi.jl and analyse entropy conservation for two different flux combinations.

# ### [5 Shock capturing with flux differencing and stage limiter](@ref shock_capturing)
#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
# ### [{index} Shock capturing with flux differencing and stage limiter](@ref shock_capturing)
#-
# Using the flux differencing formulation, a simple procedure to capture shocks is a hybrid blending
# of a high-order DG method and a low-order subcell finite volume (FV) method. We present the idea on a
# very basic level and show the implementation in Trixi.jl. Then, a positivity preserving limiter is
# explained and added to an exemplary simulation of the Sedov blast wave with the 2D compressible Euler
# equations.

# ### [6 Non-periodic boundary conditions](@ref non_periodic_boundaries)
#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
# ### [{index} Non-periodic boundary conditions](@ref non_periodic_boundaries)
#-
# Thus far, all examples used periodic boundaries. In Trixi.jl, you can also set up a simulation with
# non-periodic boundaries. This tutorial presents the implementation of the classical Dirichlet
# boundary condition with a following example. Then, other non-periodic boundaries are mentioned.

# ### [7 DG schemes via `DGMulti` solver](@ref DGMulti_1)
#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
# ### [{index} DG schemes via `DGMulti` solver](@ref DGMulti_1)
#-
# This tutorial is about the more general DG solver [`DGMulti`](@ref), introduced [here](@ref DGMulti).
# We are showing some examples for this solver, for instance with discretization nodes by Gauss or
# triangular elements. Moreover, we present a simple way to include pre-defined triangulate meshes for
# non-Cartesian domains using the package [StartUpDG.jl](https://github.com/jlchan/StartUpDG.jl).

# ### [8 Other SBP schemes (FD, CGSEM) via `DGMulti` solver](@ref DGMulti_2)
#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
# ### [{index} Other SBP schemes (FD, CGSEM) via `DGMulti` solver](@ref DGMulti_2)
#-
# Supplementary to the previous tutorial about DG schemes via the `DGMulti` solver we now present
# the possibility for `DGMulti` to use other SBP schemes via the package
# [SummationByPartsOperators.jl](https://github.com/ranocha/SummationByPartsOperators.jl).
# For instance, we show how to set up a finite differences (FD) scheme and a continuous Galerkin
# (CGSEM) method.

# ### [9 Upwind FD SBP schemes](@ref upwind_fdsbp)
#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
# ### [{index} Upwind FD SBP schemes](@ref upwind_fdsbp)
#-
# General SBP schemes can not only be used via the [`DGMulti`](@ref) solver but
# also with a general `DG` solver. In particular, upwind finite difference SBP
# methods can be used together with the `TreeMesh`. Similar to general SBP
# schemes in the `DGMulti` framework, the interface is based on the package
# [SummationByPartsOperators.jl](https://github.com/ranocha/SummationByPartsOperators.jl).

# ### [10 Adding a new scalar conservation law](@ref adding_new_scalar_equations)
#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
# ### [{index} Adding a new scalar conservation law](@ref adding_new_scalar_equations)
#-
# This tutorial explains how to add a new physics model using the example of the cubic conservation
# law. First, we define the equation using a `struct` `CubicEquation` and the physical flux. Then,
# the corresponding standard setup in Trixi.jl (`mesh`, `solver`, `semi` and `ode`) is implemented
# and the ODE problem is solved by OrdinaryDiffEq's `solve` method.

# ### [11 Adding a non-conservative equation](@ref adding_nonconservative_equation)
#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
# ### [{index} Adding a non-conservative equation](@ref adding_nonconservative_equation)
#-
# In this part, another physics model is implemented, the nonconservative linear advection equation.
# We run two different simulations with different levels of refinement and compare the resulting errors.

# ### [12 Parabolic terms](@ref parabolic_terms)
#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
# ### [{index} Parabolic terms](@ref parabolic_terms)
#-
# This tutorial describes how parabolic terms are implemented in Trixi.jl, e.g.,
# to solve the advection-diffusion equation.

# ### [13 Adding new parabolic terms](@ref adding_new_parabolic_terms)
#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
# ### [{index} Adding new parabolic terms](@ref adding_new_parabolic_terms)
#-
# This tutorial describes how new parabolic terms can be implemented using Trixi.jl.

# ### [14 Adaptive mesh refinement](@ref adaptive_mesh_refinement)
#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
# ### [{index} Adaptive mesh refinement](@ref adaptive_mesh_refinement)
#-
# Adaptive mesh refinement (AMR) helps to increase the accuracy in sensitive or turbolent regions while
# not wasting resources for less interesting parts of the domain. This leads to much more efficient
# simulations. This tutorial presents the implementation strategy of AMR in Trixi.jl, including the use of
# different indicators and controllers.

# ### [15 Structured mesh with curvilinear mapping](@ref structured_mesh_mapping)
#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
# ### [{index} Structured mesh with curvilinear mapping](@ref structured_mesh_mapping)
#-
# In this tutorial, the use of Trixi.jl's structured curved mesh type [`StructuredMesh`](@ref) is explained.
# We present the two basic option to initialize such a mesh. First, the curved domain boundaries
# of a circular cylinder are set by explicit boundary functions. Then, a fully curved mesh is
# defined by passing the transformation mapping.

# ### [16 Unstructured meshes with HOHQMesh.jl](@ref hohqmesh_tutorial)
#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
# ### [{index} Unstructured meshes with HOHQMesh.jl](@ref hohqmesh_tutorial)
#-
# The purpose of this tutorial is to demonstrate how to use the [`UnstructuredMesh2D`](@ref)
# functionality of Trixi.jl. This begins by running and visualizing an available unstructured
Expand All @@ -124,26 +140,30 @@
# software in the Trixi.jl ecosystem, and then run a simulation using Trixi.jl on said mesh.
# In the end, the tutorial briefly explains how to simulate an example using AMR via `P4estMesh`.

# ### [17 P4est mesh from gmsh](@ref p4est_from_gmsh)
#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
# ### [{index} P4est mesh from gmsh](@ref p4est_from_gmsh)
#-
# This tutorial describes how to obtain a [`P4estMesh`](@ref) from an existing mesh generated
# by [`gmsh`](https://gmsh.info/) or any other meshing software that can export to the Abaqus
# input `.inp` format. The tutorial demonstrates how edges/faces can be associated with boundary conditions based on the physical nodesets.

# ### [18 Explicit time stepping](@ref time_stepping)
#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
# ### [{index} Explicit time stepping](@ref time_stepping)
#-
# This tutorial is about time integration using [OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl).
# It explains how to use their algorithms and presents two types of time step choices - with error-based
# and CFL-based adaptive step size control.

# ### [19 Differentiable programming](@ref differentiable_programming)
#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
# ### [{index} Differentiable programming](@ref differentiable_programming)
#-
# This part deals with some basic differentiable programming topics. For example, a Jacobian, its
# eigenvalues and a curve of total energy (through the simulation) are calculated and plotted for
# a few semidiscretizations. Moreover, we calculate an example for propagating errors with Measurement.jl
# at the end.

# ### [20 Custom semidiscretization](@ref custom_semidiscretization)
#src Note to developers: Use "{ index }" (but without spaces, see next line) to enable automatic indexing
# ### [{index} Custom semidiscretization](@ref custom_semidiscretization)
#-
# This tutorial describes the [semidiscretiations](@ref overview-semidiscretizations) of Trixi.jl
# and explains how to extend them for custom tasks.
Expand Down
Loading