Use trixi_include from TrixiBase.jl

Project.toml

@@ -45,6 +45,7 @@ TimerOutputs = "a759f4b9-e2f1-59dc-863e-4aeb61b1ea8f"
 Triangulate = "f7e6ffb2-c36d-4f8f-a77e-16e897189344"
 TriplotBase = "981d1d27-644d-49a2-9326-4793e63143c3"
 TriplotRecipes = "808ab39a-a642-4abf-81ff-4cb34ebbffa3"
+TrixiBase = "9a0f1c46-06d5-4909-a5a3-ce25d3fa3284"
 
 [weakdeps]
 Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"
@@ -95,6 +96,7 @@ TimerOutputs = "0.5.7"
 Triangulate = "2.0"
 TriplotBase = "0.1"
 TriplotRecipes = "0.1"
+TrixiBase = "0.1"
 julia = "1.8"
 
 [extras]

docs/Project.toml

@@ -10,6 +10,7 @@ OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 Trixi2Vtk = "bc1476a1-1ca6-4cc3-950b-c312b255ff95"
+TrixiBase = "9a0f1c46-06d5-4909-a5a3-ce25d3fa3284"
 
 [compat]
 CairoMakie = "0.6, 0.7, 0.8, 0.9, 0.10"
@@ -23,3 +24,4 @@ OrdinaryDiffEq = "6.49.1"
 Plots = "1.9"
 Test = "1"
 Trixi2Vtk = "0.3"
+TrixiBase = "0.1"

docs/make.jl

@@ -8,6 +8,7 @@ end
 
 using Trixi
 using Trixi2Vtk
+using TrixiBase
 
 # Get Trixi.jl root directory
 trixi_root_dir = dirname(@__DIR__)
@@ -122,6 +123,7 @@ makedocs(
         "Troubleshooting and FAQ" => "troubleshooting.md",
         "Reference" => [
                         "Trixi.jl" => "reference-trixi.md",
+                        "TrixiBase.jl" => "reference-trixibase.md",
                         "Trixi2Vtk.jl" => "reference-trixi2vtk.md"
                        ],
         "Authors" => "authors.md",

docs/src/conventions.md

@@ -47,10 +47,12 @@ Trixi.jl is distributed with several examples in the form of elixirs, small
 Julia scripts containing everything to set up and run a simulation. Working
 interactively from the Julia REPL with these scripts can be quite convenient
 while for exploratory research and development of Trixi.jl. For example, you
-can use the convenience function [`trixi_include`](@ref) to `include` an elixir
-with some modified arguments. To enable this, it is helpful to use a consistent
-naming scheme in elixirs, since [`trixi_include`](@ref) can only perform simple
-replacements. Some standard variables names are
+can use the convenience function
+[`trixi_include`](@ref)
+to `include` an elixir with some modified arguments. To enable this, it is
+helpful to use a consistent naming scheme in elixirs, since
+[`trixi_include`](@ref)
+can only perform simple replacements. Some standard variables names are
 
 - `polydeg` for the polynomial degree of a solver
 - `surface_flux` for the numerical flux at surfaces

docs/src/reference-trixibase.md

@@ -0,0 +1,9 @@
+# TrixiBase.jl API
+
+```@meta
+CurrentModule = TrixiBase
+```
+
+```@autodocs
+Modules = [TrixiBase]
+```

src/Trixi.jl

@@ -70,6 +70,7 @@ using Triangulate: Triangulate, TriangulateIO, triangulate
 export TriangulateIO # for type parameter in DGMultiMesh
 using TriplotBase: TriplotBase
 using TriplotRecipes: DGTriPseudocolor
+@reexport using TrixiBase: TrixiBase, trixi_include
 @reexport using SimpleUnPack: @unpack
 using SimpleUnPack: @pack!
 using DataStructures: BinaryHeap, FasterForward, extract_all!
@@ -129,7 +130,7 @@ include("callbacks_step/callbacks_step.jl")
 include("callbacks_stage/callbacks_stage.jl")
 include("semidiscretization/semidiscretization_euler_gravity.jl")
 
-# `trixi_include` and special elixirs such as `convergence_test`
+# Special elixirs such as `convergence_test`
 include("auxiliary/special_elixirs.jl")
 
 # Plot recipes and conversion functions to visualize results with Plots.jl

src/auxiliary/precompile.jl

@@ -577,9 +577,6 @@ function _precompile_manual_()
         @assert Base.precompile(Tuple{typeof(show), Base.TTY, lbm_collision_callback_type})
         @assert Base.precompile(Tuple{typeof(show), IOContext{Base.TTY}, MIME"text/plain",
                                       lbm_collision_callback_type})
-
-        # infrastructure, special elixirs
-        @assert Base.precompile(Tuple{typeof(trixi_include), String})
     end
 
     @assert Base.precompile(Tuple{typeof(init_mpi)})

src/auxiliary/special_elixirs.jl

@@ -5,58 +5,6 @@
 @muladd begin
 #! format: noindent
 
-# Note: We can't call the method below `Trixi.include` since that is created automatically
-# inside `module Trixi` to `include` source files and evaluate them within the global scope
-# of `Trixi`. However, users will want to evaluate in the global scope of `Main` or something
-# similar to manage dependencies on their own.
-"""
-    trixi_include([mod::Module=Main,] elixir::AbstractString; kwargs...)
-
-`include` the file `elixir` and evaluate its content in the global scope of module `mod`.
-You can override specific assignments in `elixir` by supplying keyword arguments.
-It's basic purpose is to make it easier to modify some parameters while running Trixi.jl from the
-REPL. Additionally, this is used in tests to reduce the computational burden for CI while still
-providing examples with sensible default values for users.
-
-Before replacing assignments in `elixir`, the keyword argument `maxiters` is inserted
-into calls to `solve` and `Trixi.solve` with it's default value used in the SciML ecosystem
-for ODEs, see the "Miscellaneous" section of the
-[documentation](https://docs.sciml.ai/DiffEqDocs/stable/basics/common_solver_opts/).
-
-# Examples
-
-```jldoctest
-julia> redirect_stdout(devnull) do
-         trixi_include(@__MODULE__, joinpath(examples_dir(), "tree_1d_dgsem", "elixir_advection_extended.jl"),
-                       tspan=(0.0, 0.1))
-         sol.t[end]
-       end
-[ Info: You just called `trixi_include`. Julia may now compile the code, please be patient.
-0.1
-```
-"""
-function trixi_include(mod::Module, elixir::AbstractString; kwargs...)
-    # Check that all kwargs exist as assignments
-    code = read(elixir, String)
-    expr = Meta.parse("begin \n$code \nend")
-    expr = insert_maxiters(expr)
-
-    for (key, val) in kwargs
-        # This will throw an error when `key` is not found
-        find_assignment(expr, key)
-    end
-
-    # Print information on potential wait time only in non-parallel case
-    if !mpi_isparallel()
-        @info "You just called `trixi_include`. Julia may now compile the code, please be patient."
-    end
-    Base.include(ex -> replace_assignments(insert_maxiters(ex); kwargs...), mod, elixir)
-end
-
-function trixi_include(elixir::AbstractString; kwargs...)
-    trixi_include(Main, elixir; kwargs...)
-end
-
 """
     convergence_test([mod::Module=Main,] elixir::AbstractString, iterations; kwargs...)
 
@@ -177,86 +125,15 @@ end
 
 # Helper methods used in the functions defined above
 
-# Apply the function `f` to `expr` and all sub-expressions recursively.
-walkexpr(f, expr::Expr) = f(Expr(expr.head, (walkexpr(f, arg) for arg in expr.args)...))
-walkexpr(f, x) = f(x)
-
-# Insert the keyword argument `maxiters` into calls to `solve` and `Trixi.solve`
-# with default value `10^5` if it is not already present.
-function insert_maxiters(expr)
-    maxiters_default = 10^5
-
-    expr = walkexpr(expr) do x
-        if x isa Expr
-            is_plain_solve = x.head === Symbol("call") && x.args[1] === Symbol("solve")
-            is_trixi_solve = (x.head === Symbol("call") && x.args[1] isa Expr &&
-                              x.args[1].head === Symbol(".") &&
-                              x.args[1].args[1] === Symbol("Trixi") &&
-                              x.args[1].args[2] isa QuoteNode &&
-                              x.args[1].args[2].value === Symbol("solve"))
-
-            if is_plain_solve || is_trixi_solve
-                # Do nothing if `maxiters` is already set as keyword argument...
-                for arg in x.args
-                    # This detects the case where `maxiters` is set as keyword argument
-                    # without or before a semicolon
-                    if (arg isa Expr && arg.head === Symbol("kw") &&
-                        arg.args[1] === Symbol("maxiters"))
-                        return x
-                    end
-
-                    # This detects the case where maxiters is set as keyword argument
-                    # after a semicolon
-                    if (arg isa Expr && arg.head === Symbol("parameters"))
-                        # We need to check each keyword argument listed here
-                        for nested_arg in arg.args
-                            if (nested_arg isa Expr &&
-                                nested_arg.head === Symbol("kw") &&
-                                nested_arg.args[1] === Symbol("maxiters"))
-                                return x
-                            end
-                        end
-                    end
-                end
-
-                # ...and insert it otherwise.
-                push!(x.args, Expr(Symbol("kw"), Symbol("maxiters"), maxiters_default))
-            end
-        end
-        return x
-    end
-
-    return expr
-end
-
-# Replace assignments to `key` in `expr` by `key = val` for all `(key,val)` in `kwargs`.
-function replace_assignments(expr; kwargs...)
-    # replace explicit and keyword assignments
-    expr = walkexpr(expr) do x
-        if x isa Expr
-            for (key, val) in kwargs
-                if (x.head === Symbol("=") || x.head === :kw) &&
-                   x.args[1] === Symbol(key)
-                    x.args[2] = :($val)
-                    # dump(x)
-                end
-            end
-        end
-        return x
-    end
-
-    return expr
-end
-
-# find a (keyword or common) assignment to `destination` in `expr`
-# and return the assigned value
+# Find a (keyword or common) assignment to `destination` in `expr`
+# and return the assigned value.
 function find_assignment(expr, destination)
     # declare result to be able to assign to it in the closure
     local result
     found = false
 
     # find explicit and keyword assignments
-    walkexpr(expr) do x
+    TrixiBase.walkexpr(expr) do x
         if x isa Expr
             if (x.head === Symbol("=") || x.head === :kw) &&
                x.args[1] === Symbol(destination)

src/callbacks_step/trivial.jl

@@ -8,8 +8,8 @@
 """
     TrivialCallback()
 
-A callback that does nothing. This can be useful to disable some callbacks
-easily via [`trixi_include`](@ref).
+A callback that does nothing. This can be useful to disable some callbacks easily via
+[`trixi_include`](@ref).
 """
 function TrivialCallback()
     DiscreteCallback(trivial_callback, trivial_callback,

test/test_unit.jl

@@ -1529,103 +1529,6 @@ end
 
     @test mesh.boundary_faces[:entire_boundary] == [1, 2]
 end
-
-@testset "trixi_include" begin
-    @trixi_testset "Basic" begin
-        example = """
-            x = 4
-            """
-
-        filename = tempname()
-        try
-            open(filename, "w") do file
-                write(file, example)
-            end
-
-            # Use `@trixi_testset`, which wraps code in a temporary module, and call
-            # `trixi_include` with `@__MODULE__` in order to isolate this test.
-            @test_warn "You just called" trixi_include(@__MODULE__, filename)
-            @test @isdefined x
-            @test x == 4
-
-            @test_warn "You just called" trixi_include(@__MODULE__, filename, x = 7)
-            @test x == 7
-
-            @test_throws "assignment `y` not found in expression" trixi_include(@__MODULE__,
-                                                                                filename,
-                                                                                y = 3)
-        finally
-            rm(filename, force = true)
-        end
-    end
-
-    @trixi_testset "With `solve` Without `maxiters`" begin
-        # `trixi_include` assumes this to be the `solve` function of OrdinaryDiffEq,
-        # and therefore tries to insert the kwarg `maxiters`, which will fail here.
-        example = """
-            solve() = 0
-            x = solve()
-            """
-
-        filename = tempname()
-        try
-            open(filename, "w") do file
-                write(file, example)
-            end
-
-            # Use `@trixi_testset`, which wraps code in a temporary module, and call
-            # `trixi_include` with `@__MODULE__` in order to isolate this test.
-            @test_throws "no method matching solve(; maxiters::Int64)" trixi_include(@__MODULE__,
-                                                                                     filename)
-
-            @test_throws "no method matching solve(; maxiters::Int64)" trixi_include(@__MODULE__,
-                                                                                     filename,
-                                                                                     maxiters = 3)
-        finally
-            rm(filename, force = true)
-        end
-    end
-
-    @trixi_testset "With `solve` with `maxiters`" begin
-        # We need another example file that we include with `Base.include` first, in order to
-        # define the `solve` method without `trixi_include` trying to insert `maxiters` kwargs.
-        # Then, we can test that `trixi_include` inserts the kwarg in the `solve()` call.
-        example1 = """
-            solve(; maxiters=0) = maxiters
-            """
-
-        example2 = """
-            x = solve()
-            """
-
-        filename1 = tempname()
-        filename2 = tempname()
-        try
-            open(filename1, "w") do file
-                write(file, example1)
-            end
-            open(filename2, "w") do file
-                write(file, example2)
-            end
-
-            # Use `@trixi_testset`, which wraps code in a temporary module, and call
-            # `Base.include` and `trixi_include` with `@__MODULE__` in order to isolate this test.
-            Base.include(@__MODULE__, filename1)
-            @test_warn "You just called" trixi_include(@__MODULE__, filename2)
-            @test @isdefined x
-            # This is the default `maxiters` inserted by `trixi_include`
-            @test x == 10^5
-
-            @test_warn "You just called" trixi_include(@__MODULE__, filename2,
-                                                       maxiters = 7)
-            # Test that `maxiters` got overwritten
-            @test x == 7
-        finally
-            rm(filename1, force = true)
-            rm(filename2, force = true)
-        end
-    end
-end
 end
 
 end #module