diff --git a/README.md b/README.md index 70c28799f31..f857db9aaaf 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,8 @@

-**Trixi.jl** is a numerical simulation framework for conservation +[**Trixi.jl**](https://github.com/trixi-framework/Trixi.jl) +is a numerical simulation framework for conservation laws written in [Julia](https://julialang.org). 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 @@ -100,12 +101,12 @@ julia> using Pkg; Pkg.update("Trixi"); Pkg.status("Trixi") ``` to the [latest release](https://github.com/trixi-framework/Trixi.jl/releases/latest). If the installed version does not match the current release, please check the -*Troubleshooting* section in the [documentation](#documentation). +[Troubleshooting](@ref old-release) section. 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`](NEWS.md). +changes to Trixi.jl is available in the [`Changelog`](@ref). -### For developers +### [For developers](@id for-developers) If you plan on editing Trixi.jl itself, you can download Trixi.jl locally and use the code from the cloned directory: ```bash @@ -113,19 +114,47 @@ 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(["OrdinaryDiffEq", "Trixi2Vtk", "Plots"])' # Install additional packages +julia --project=. -e 'using Pkg; Pkg.develop(PackageSpec(path=".."))' ``` -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., ```bash julia --project=. ``` if already inside the `run` directory. -Further details can be found in the [documentation](#documentation). + +The advantage of using a separate `run` directory is that you can also add other +related packages (see below, e.g., for time integration or visualization) to the +project in the `run` folder and always have a reproducible environment at hand +to share with others. + +Since the postprocessing tool Trixi2Vtk.jl typically does not need to be modified, +it is recommended to install it as a normal package. Likewise, you can install +[OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl) and +[Plots.jl](https://github.com/JuliaPlots/Plots.jl) +as ordinary packages. To achieve this, use the following REPL commands: +```julia +julia> using Pkg + +julia> Pkg.add(["OrdinaryDiffEq", "Trixi2Vtk", "Plots"]) +``` +Note that the postprocessing tools Trixi2Vtk.jl and Plots.jl are optional and +can be omitted. + + + +### Example: Installing Trixi.jl as a package +```@raw html + +``` +Please note that the playback speed is set to 3x, thus the entire installation +procedure lasts around 45 seconds in real time (depending on the performance of +your computer and on how many dependencies had already been installed before). ## Usage @@ -147,9 +176,8 @@ 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: -

- -

+ +![image](https://user-images.githubusercontent.com/26361975/177492363-74cee347-7abe-4522-8b2d-0dfadc317f7e.png) 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 @@ -157,11 +185,23 @@ 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/`](examples/) subdirectory. +[`examples/`](https://github.com/trixi-framework/Trixi.jl/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(...)`. +### Example: Running a simulation with Trixi.jl +```@raw html + +``` +If this produces weird symbols or question marks in the terminal on your system, +you are probably using Mac OS with problematic fonts. In that case, please check +the [Troubleshooting](@ref font-issues) section. + *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 compiled methods for further use. That means that the first execution @@ -169,6 +209,69 @@ of a Julia method is typically slow, with subsequent runs being much faster. For instance, in the example above the first execution of `trixi_include` takes about 20 seconds, while subsequent runs require less than 60 *milli*seconds. + +### Performing a convergence analysis +To automatically determine the experimental order of convergence (EOC) for a +given setup, execute +```julia +julia> convergence_test(default_example(), 4) +``` +This will run a convergence test with the elixir `default_example()`, +using four iterations with different initial refinement levels. The initial +iteration will use the elixir unchanged, while for each subsequent +iteration the `initial_refinement_level` parameter is incremented by one. +Finally, the measured ``l^2`` and ``l^\infty`` errors and the determined EOCs +will be displayed like this: +``` +[...] +l2 +scalar +error EOC +9.14e-06 - +5.69e-07 4.01 +3.55e-08 4.00 +2.22e-09 4.00 + +mean 4.00 +-------------------------------------------------------------------------------- +linf +scalar +error EOC +6.44e-05 - +4.11e-06 3.97 +2.58e-07 3.99 +1.62e-08 4.00 + +mean 3.99 +-------------------------------------------------------------------------------- +``` + +An example with multiple variables looks like this: +```julia +julia> convergence_test(joinpath(examples_dir(), "tree_2d_dgsem", "elixir_euler_source_terms.jl"), 3) +``` +``` +[...] +l2 +rho rho_v1 rho_v2 rho_e +error EOC error EOC error EOC error EOC +9.32e-07 - 1.42e-06 - 1.42e-06 - 4.82e-06 - +7.03e-08 3.73 9.53e-08 3.90 9.53e-08 3.90 3.30e-07 3.87 +4.65e-09 3.92 6.09e-09 3.97 6.09e-09 3.97 2.12e-08 3.96 + +mean 3.82 mean 3.93 mean 3.93 mean 3.91 +-------------------------------------------------------------------------------- +linf +rho rho_v1 rho_v2 rho_e +error EOC error EOC error EOC error EOC +9.58e-06 - 1.17e-05 - 1.17e-05 - 4.89e-05 - +6.23e-07 3.94 7.48e-07 3.97 7.48e-07 3.97 3.22e-06 3.92 +4.05e-08 3.94 4.97e-08 3.91 4.97e-08 3.91 2.10e-07 3.94 + +mean 3.94 mean 3.94 mean 3.94 mean 3.93 +-------------------------------------------------------------------------------- +``` + ### Showcase of advanced features The presentation [From Mesh Generation to Adaptive Simulation: A Journey in Julia](https://youtu.be/_N4ozHr-t9E), originally given as part of JuliaCon 2022, outlines how to use Trixi.jl for an adaptive simulation @@ -177,14 +280,6 @@ as well as code to run the simulation presented can be found at the [reproducibility repository](https://github.com/trixi-framework/talk-2022-juliacon_toolchain) for the presentation. -## Documentation -Additional documentation is available that contains more information on how to -modify/extend Trixi.jl's implementation, how to visualize output files etc. It -also includes a section on our preferred development workflow and some tips for -using Git. The latest documentation can be accessed either -[online](https://trixi-framework.github.io/Trixi.jl/stable) or under [`docs/src`](docs/src). - - ## Referencing If you use Trixi.jl in your own research or write a paper using results obtained with the help of Trixi.jl, please cite the following articles: @@ -237,8 +332,7 @@ In addition, you can also refer to Trixi.jl directly as } ``` - -## Authors +## [Authors](@id authors-index-md) Trixi.jl was initiated by [Michael Schlottke-Lakemper](https://www.uni-augsburg.de/fakultaet/mntf/math/prof/hpsc) (University of Augsburg, Germany) and @@ -247,31 +341,62 @@ Schlottke-Lakemper](https://www.uni-augsburg.de/fakultaet/mntf/math/prof/hpsc) (Johannes Gutenberg University Mainz, Germany), [Andrew Winters](https://liu.se/en/employee/andwi94) (Linköping University, Sweden), and [Jesse Chan](https://jlchan.github.io) (Rice University, US), they are the principal developers of Trixi.jl. -The full list of contributors can be found in [AUTHORS.md](AUTHORS.md). +The full list of contributors can be found under [Authors](@ref). ## License and contributing -Trixi.jl is licensed under the MIT license (see [LICENSE.md](LICENSE.md)). Since Trixi.jl is +Trixi.jl is licensed under the MIT license (see [License](@ref)). Since Trixi.jl is an open-source project, we are very happy to accept contributions from the -community. Please refer to [CONTRIBUTING.md](CONTRIBUTING.md) for more details. +community. Please refer to [Contributing](@ref) for more details. Note that we strive to be a friendly, inclusive open-source community and ask all members -of our community to adhere to our [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md). +of our community to adhere to our [Code of Conduct](@ref code-of-conduct). To get in touch with the developers, [join us on Slack](https://join.slack.com/t/trixi-framework/shared_invite/zt-sgkc6ppw-6OXJqZAD5SPjBYqLd8MU~g) or [create an issue](https://github.com/trixi-framework/Trixi.jl/issues/new). +## Participating research groups +Participating research groups in alphabetical order: + +[Applied and Computational Mathematics, RWTH Aachen University 🇩🇪](https://www.acom.rwth-aachen.de) + +[Applied Mathematics, Department of Mathematics, University of Hamburg 🇩🇪](https://www.math.uni-hamburg.de/en/forschung/bereiche/am.html) + +[Applied Mathematics, Linköping University 🇸🇪](https://liu.se/en/employee/andwi94) + +[Computational and Applied Mathematics, Rice University 🇺🇸](https://jlchan.github.io/) + +[High-Performance Computing, Institute of Software Technology, German Aerospace Center (DLR) 🇩🇪](https://www.dlr.de/en/sc/about-us/departments/high-performance-computing) + +[High-Performance Scientific Computing, University of Augsburg 🇩🇪](https://www.uni-augsburg.de/fakultaet/mntf/math/prof/hpsc) + +[Numerical Mathematics, Institute of Mathematics, Johannes Gutenberg University Mainz 🇩🇪](https://ranocha.de) + +[Numerical Simulation, Department of Mathematics and Computer Science, University of Cologne 🇩🇪](https://www.mi.uni-koeln.de/NumSim/) + + ## Acknowledgments -

-

+ +```@raw html +
+
+
+
+
+
+
+
+``` This project has benefited from funding by the [Deutsche Forschungsgemeinschaft](https://www.dfg.de/) (DFG, German Research Foundation)