Trixi.jl

<p align="center"> <img width="300px" src="https://trixi-framework.github.io/assets/logo.png"> </p>

Trixi.jl is a numerical simulation framework for conservation laws written in Julia. A key objective for the framework is to be useful to both scientists and students. Therefore, next to having an extensible design with a fast implementation, Trixi.jl is focused on being easy to use for new or inexperienced users, including the installation and postprocessing procedures. Its features include:

1D, 2D, and 3D simulations on line/quad/hex/simplex meshes
- Cartesian and curvilinear meshes
- Conforming and non-conforming meshes
- Structured and unstructured meshes
- Hierarchical quadtree/octree grid with adaptive mesh refinement
- Forests of quadtrees/octrees with p4est via P4est.jl
High-order accuracy in space and time
- Arbitrary floating-point precision
Discontinuous Galerkin methods
- Kinetic energy-preserving and entropy-stable methods based on flux differencing
- Entropy-stable shock capturing
- Finite difference summation by parts (SBP) methods
Advanced limiting strategies
- Positivity-preserving limiting
- Subcell invariant domain-preserving (IDP) limiting
- Entropy-bounded limiting
Compatible with the SciML ecosystem for ordinary differential equations
- Explicit low-storage Runge-Kutta time integration
- Strong stability preserving methods
- CFL-based and error-based time step control
Custom explicit time integration schemes
- Maximized linear stability via paired explicit Runge-Kutta methods
- Relaxation Runge-Kutta methods for entropy-conservative time integration
Native support for differentiable programming
- Forward mode automatic differentiation via ForwardDiff.jl
- Automatic Jacobian sparsity detection via SparseConnectivityTracer.jl
Periodic and weakly-enforced boundary conditions
Multiple governing equations:
- Compressible Euler equations
- Compressible Navier-Stokes equations
- Magnetohydrodynamics (MHD) equations
- Multi-component compressible Euler and MHD equations
- Multi-ion compressible MHD equations
- Linearized Euler and acoustic perturbation equations
- Hyperbolic diffusion equations for elliptic problems
- Lattice-Boltzmann equations (D2Q9 and D3Q27 schemes)
- Shallow water equations via TrixiShallowWater.jl
- Several scalar conservation laws (e.g., linear advection, Burgers' equation, LWR traffic flow)
Multi-physics simulations
- Self-gravitating gas dynamics
Shared-memory parallelization via multithreading
Multi-node parallelization via MPI
Visualization and postprocessing of the results
- In-situ and a posteriori visualization with Plots.jl
- Interactive visualization with Makie.jl
- Postprocessing with ParaView/VisIt via Trixi2Vtk

Installation

If you have not yet installed Julia, please follow the instructions for your operating system. Trixi.jl works with Julia v1.10 and newer. We recommend using the latest stable release of Julia.

For users

Trixi.jl and its related tools are registered Julia packages. Hence, you can install Trixi.jl, the visualization tools Trixi2Vtk, and Plots.jl as well as the time integration sub-packages of OrdinaryDiffEq.jl, by executing the following commands in the Julia REPL:

julia> using Pkg

julia> Pkg.add(["Trixi", "Trixi2Vtk", "OrdinaryDiffEqLowStorageRK",
                "OrdinaryDiffEqSSPRK", "Plots"])

You can copy and paste all commands to the REPL including the leading julia> prompts - they will automatically be stripped away by Julia. The package OrdinaryDiffEq.jl and its sub-packages provide time integration schemes used by Trixi.jl, while Plots.jl can be used to directly visualize Trixi.jl's results from the REPL.

Note on package versions: If some of the examples for how to use Trixi.jl do not work, verify that you are using a recent Trixi.jl release by comparing the installed Trixi.jl version from

julia> using Pkg; Pkg.update("Trixi"); Pkg.status("Trixi")

to the latest release. If the installed version does not match the current release, please check the Troubleshooting section in the documentation.

The commands above can also be used to update Trixi.jl. A brief list of notable changes to Trixi.jl is available in NEWS.md.

For developers

If you plan on editing Trixi.jl itself, you can download Trixi.jl locally and use the code from the cloned directory:

git clone git@github.com:trixi-framework/Trixi.jl.git
cd Trixi.jl
mkdir run
cd run
julia --project=. -e 'using Pkg; Pkg.develop(PackageSpec(path=".."))' # Install local Trixi.jl clone
julia --project=. -e 'using Pkg; Pkg.add(["OrdinaryDiffEqLowStorageRK", "OrdinaryDiffEqSSPRK",
                                          "Trixi2Vtk", "Plots"])' # Install additional packages

Note that the postprocessing tools Trixi2Vtk.jl and Plots.jl are optional and can be omitted.

If you installed Trixi.jl this way, you always have to start Julia with the --project flag set to your run directory, e.g.,

julia --project=.

if already inside the run directory. Further details can be found in the documentation.

Usage

In the Julia REPL, first load the package Trixi.jl

julia> using Trixi

Then start a simulation by executing

julia> trixi_include(default_example())

Please be patient since Julia will compile the code just before running it. To visualize the results, load the package Plots

julia> using Plots

and generate a heatmap plot of the results with

julia> plot(sol) # No trailing semicolon, otherwise no plot is shown

This will open a new window with a 2D visualization of the final solution:

The method trixi_include(...) expects a single string argument with the path to a Trixi.jl elixir, i.e., a text file containing Julia code necessary to set up and run a simulation. To quickly see Trixi.jl in action, default_example() returns the path to an example elixir with a short, two-dimensional problem setup. A list of all example elixirs packaged with Trixi.jl can be obtained by running get_examples(). Alternatively, you can also browse the examples/ subdirectory. If you want to modify one of the elixirs to set up your own simulation, download it to your machine, edit the configuration, and pass the file path to trixi_include(...).

Note on performance: Julia uses just-in-time compilation to transform its source code to native, optimized machine code at the time of execution and caches the co

Trixi.jl

Install / Use

README

Trixi.jl

Installation

For users

For developers

Usage