diff --git a/README.md b/README.md index 4b163c7414..0b93f82501 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,8 @@ installation and postprocessing procedures. Its features include: * Multi-physics simulations * [Self-gravitating gas dynamics](https://github.com/trixi-framework/paper-self-gravitating-gas-dynamics) * Shared-memory parallelization via multithreading -* Visualization of results with Julia-only tools (2D) or ParaView/VisIt (2D/3D) +* Visualization of results with Julia-only tools ([Trixi2Img](https://github.com/trixi-framework/Trixi2Img.jl)) + or ParaView/VisIt ([Trixi2Vtk](https://github.com/trixi-framework/Trixi2Vtk.jl)) ## Installation @@ -69,13 +70,13 @@ within the cloned directory: ```bash git clone git@github.com:trixi-framework/Trixi.jl.git cd Trixi.jl -julia --project=. -e 'import Pkg; Pkg.instantiate()' # Install Trixi's dependencies +julia --project=@. -e 'import Pkg; Pkg.instantiate()' # Install Trixi's dependencies julia -e 'import Pkg; Pkg.add("Trixi2Vtk"); Pkg.add("Trixi2Img")' # Install postprocessing tools ``` If you installed Trixi this way, you always have to start Julia with the `--project` flag set to your local Trixi clone, e.g., ```bash -julia --project=. +julia --project=@. ``` Further details can be found in the [documentation](#documentation). @@ -87,7 +88,7 @@ julia> using Trixi ``` Then start a simulation by executing ```julia -julia> Trixi.run(default_example()) +julia> trixi_include(default_example()) ``` To visualize the results, load the package Trixi2Img ```julia @@ -103,21 +104,23 @@ that can be opened with any image viewer:

-The method `Trixi.run(...)` expects a single string argument with the path to a -Trixi parameter file. To quickly see Trixi in action, `default_example()` -returns the path to an example parameter file with a short, two-dimensional -problem setup. A list of all example parameter files packaged with Trixi can be +The method `trixi_include(...)` expects a single string argument with the path to a +Trixi elixir, i.e.. a text file containing Julia code necessary to set up and run a +simulation. To quickly see Trixi 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 can be obtained by running `get_examples()`. Alternatively, you can also browse the -[`examples/`](examples/) subdirectory. If you want to -modify one of the parameter files to set up your own simulation, download it to -your machine, edit the configuration, and pass the file path to `Trixi.run(...)`. +[`examples/`](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 compiled methods for further use. That means that the first execution of a Julia method is typically slow, with subsequent runs being much faster. For -instance, in the example above the first execution of `Trixi.run` takes about 15 -seconds, while subsequent runs require less than 50 *milli*seconds. +instance, in the example above the first execution of `trixi_include` takes about +20 seconds, while subsequent runs require less than 50 *milli*seconds. ## Documentation diff --git a/docs/src/development.md b/docs/src/development.md index e78f15046e..8c9f2e1d93 100644 --- a/docs/src/development.md +++ b/docs/src/development.md @@ -16,7 +16,7 @@ which destroys any potential benefits from caching. However, restarting Julia can be avoided by using the [Revise.jl](https://github.com/timholy/Revise.jl) package, which tracks changed files and re-loads them automatically. Therefore, it is *highly recommended* to first install Revise with the following command in Julia: -To enter the packe REPL mode, press `]` in the standard Julia REPL mode. Then, execute +To enter the package REPL mode, press `]` in the standard Julia REPL mode. Then, execute ```julia (@v1.5) pkg> add Revise ``` @@ -47,7 +47,7 @@ julia> using Revise; using Trixi ``` You can run a simulation by executing ```julia -julia> Trixi.run("examples/2d/parameters_advection_basic.toml") +julia> trixi_include(default_example()) ``` Together, all of these commands can take some time, roughly half a minute on a modern workstation. Most of the time is spent on compilation of Julia code etc. @@ -77,7 +77,7 @@ if Trixi is not installed in the global environment. The same procedure also applies should you opt to install the postprocessing tools [Trixi2Vtk](https://github.com/trixi-framework/Trixi2Vtk.jl) and [Trixi2Img](https://github.com/trixi-framework/Trixi2Img.jl) manually such that -you can modify their implemenations. +you can modify their implementations. ### Pitfalls when using Revise @@ -153,7 +153,7 @@ which will set the project path, load Revise (if installed), and import Trixi: ```bash julia> include("utils/juno.jl") ``` -Afterwards, you can start Trixi in the usual way by calling the `Trixi.run` method. +Afterwards, you can start Trixi in the usual way by calling the `trixi_include` method. ### Vim or Emacs Vim and Emacs are both very popular editors that work great with Julia. One @@ -246,8 +246,7 @@ You can also make it more detailed by benchmarking only, e.g., the calculation o 6. Set the correct version number in the badge "GitHub commits since tagged version" in README.md. The badge will only show up correctly if TagBot has released a new version. This will - be done automatically over night. If you don't want to wait, trigger the GitHub Action - TagBot manually. + be done automatically. 7. When a new version of Trixi was released, check whether the `[compat]` entries in `test/Project.toml` in Trixi2Vtk/Trixi2Img should be updated. When a new version of Trixi2Vtk/Trixi2Img was released, check whether the `[compat]` diff --git a/docs/src/github-git.md b/docs/src/github-git.md index bfa5d3cd91..70ee3acef1 100644 --- a/docs/src/github-git.md +++ b/docs/src/github-git.md @@ -4,7 +4,7 @@ This page contains information on how to use GitHub and Git when developing Trix ## Development workflow -For adding modifcations to Trixi, we generally follow these steps: +For adding modifications to Trixi, we generally follow these steps: ### Create an issue (optional) In many cases it makes sense to start by creating an issue on GitHub. For @@ -42,7 +42,8 @@ git push -u myfork Immediately creating a PR for your branch has the benefit that all code discussions can now be held directly next to the corresponding code. Also, the PR allows to easily compare your branch to the upstream branch - (usually `master`) to see what you have changed. + (usually `master`) to see what you have changed. Moreover, tests will run + automatically. ### Make changes With a branch and PR in place, you can now write your code and commit @@ -86,13 +87,13 @@ review. That is, you should * merge the current `master` to your branch * run tests if available, but at least ensure that you did not accidentally - change the results for one of the existing parameter files + change the results for one of the existing example elixirs * properly comment your code * delete old/unused code, especially commented lines (unless they contain helpful code, in which case you should add a comment on why you keep this around) * remove debug statements - * add a `parameters_xxx.toml` that uses your feature (only relevant for new + * add a `elixir_xxx.jl` that uses your feature (only relevant for new features) * make sure your code formatting adheres to the [Style guide](@ref) @@ -116,10 +117,12 @@ we just try to keep Trixi as accessible and easy to use for everyone. ### Merge branch Once your branch is reviewed and declared ready for merging by the reviewer, -make sure that all the latest changes have been pushed. Then, go +make sure that all the latest changes have been pushed. Then, one of the +developers will merge your PR. If you are one of the developers, you can also go to the pull request page on GitHub and and click on **Merge pull request**. Voilá, you are done! Your branch will have been merged to -`master` and the source branch will have been deleted in the GitHub repository (if you are not working in your own fork). +`master` and the source branch will have been deleted in the GitHub repository +(if you are not working in your own fork). ### Update your working copy Once you have merged your branch by accepting the PR on GitHub, you @@ -156,7 +159,7 @@ git reset HEAD~ ``` This only works if you have not yet pushed your branch to the GitHub repository. In this case, please talk to one of the core developers on how to proceed. -Especially when you accidentally commited a large file (image, or video), please +Especially when you accidentally committed a large file (image, or video), please let us know as fast as possible, since the effort to fix the repository grows considerably over time. @@ -164,7 +167,7 @@ considerably over time. If a large file was accidentally committed **and pushed** to the Trixi repository, please talk to one of the core developers as soon as possible so that they can fix it. -!!! danger +!!! danger "Large files" You should never try to fix this yourself, as it potentially disrupts/destroys the work of others! diff --git a/docs/src/index.md b/docs/src/index.md index a142c225ad..c4cce01030 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -8,13 +8,16 @@ focused on being easy to use for new or inexperienced users, including the installation and postprocessing procedures. Its features include: * Hierarchical quadtree/octree grid with adaptive mesh refinement -* Native support for 2D and 3D simulations +* Native support for 1D, 2D, and 3D simulations * High-order accuracy in space in time * Nodal discontinuous Galerkin spectral element methods * Kinetic energy-preserving and entropy-stable split forms * Entropy-stable shock capturing * Positivity-preserving limiting -* Explicit low-storage Runge-Kutta time integration +* Compatible with the [SciML ecosystem for ordinary differential equations](https://diffeq.sciml.ai/latest/) + * [Explicit low-storage Runge-Kutta time integration](https://diffeq.sciml.ai/latest/solvers/ode_solve/#Low-Storage-Methods) + * [Strong stability preserving methods](https://diffeq.sciml.ai/latest/solvers/ode_solve/#Explicit-Strong-Stability-Preserving-Runge-Kutta-Methods-for-Hyperbolic-PDEs-(Conservation-Laws)) + * CFL-based and error-based time step control * Square/cubic domains with periodic and weakly-enforced boundary conditions * Multiple governing equations: * Compressible Euler equations @@ -24,7 +27,8 @@ installation and postprocessing procedures. Its features include: * Multi-physics simulations * [Self-gravitating gas dynamics](https://github.com/trixi-framework/paper-self-gravitating-gas-dynamics) * Shared-memory parallelization via multithreading -* Visualization of results with Julia-only tools ([Trixi2Img](https://github.com/trixi-framework/Trixi2Img.jl)) or ParaView/VisIt ([Trixi2Vtk](https://github.com/trixi-framework/Trixi2Vtk.jl)) +* Visualization of results with Julia-only tools ([Trixi2Img](https://github.com/trixi-framework/Trixi2Img.jl)) + or ParaView/VisIt ([Trixi2Vtk](https://github.com/trixi-framework/Trixi2Vtk.jl)) ## Installation @@ -65,7 +69,7 @@ If you plan on editing Trixi itself, you have two options: installing it as a ```bash git clone git@github.com:trixi-framework/Trixi.jl.git cd Trixi.jl - julia --project=. -e 'import Pkg; Pkg.instantiate()' # Install Trixi's dependencies + julia --project=@. -e 'import Pkg; Pkg.instantiate()' # Install Trixi's dependencies ``` The last line can also be used to *update* the dependencies if they have changed since you first installed Trixi. @@ -73,12 +77,11 @@ If you plan on editing Trixi itself, you have two options: installing it as a If you installed Trixi this way, you always have to start Julia with the `--project` flag set to your local Trixi clone, e.g., ```bash - julia --project=. + julia --project=@. ``` -Either way, since the -postprocessing tools typically do not need to be modified, it is recommended to -install them as normal packages by executing +Either way, since the postprocessing tools typically do not need to be modified, +it is recommended to install them as normal packages by executing ```julia julia> import Pkg @@ -109,7 +112,7 @@ julia> using Trixi ``` Then start a simulation by executing ```julia -julia> Trixi.run(default_example()) +julia> trixi_include(default_example()) ``` To visualize the results, load the package Trixi2Img ```julia @@ -124,16 +127,19 @@ that can be opened with any image viewer: !["solution_000040_scalar_resized"](assets/solution_000040_scalar_resized.png) -The method `Trixi.run(...)` expects a single string argument with the path to a -Trixi parameter file. To quickly see Trixi in action, `default_example()` -returns the path to an example parameter file with a short, two-dimensional -problem setup. A list of all example parameter files packaged with Trixi can be +The method `trixi_include(...)` expects a single string argument with the path to a +Trixi elixir, i.e.. a text file containing Julia code necessary to set up and run a +simulation. To quickly see Trixi 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 can be obtained by running `get_examples()`. Alternatively, you can also browse the -[`examples/`](https://github.com/trixi-framework/Trixi.jl/examples/) subdirectory. If you want to -modify one of the parameter files to set up your own simulation, download it to -your machine, edit the configuration, and pass the file path to `Trixi.run(...)`. +[`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 + ```@raw html