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

Jump to bottom

update docs to Taal and fix typos #298

Merged
merged 2 commits into from
Nov 6, 2020
Merged

update docs to Taal and fix typos #298

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a5952c6
update docs to Taal and fix typos
ranocha Nov 5, 2020
b9d7056
update notes on visualization tools
ranocha Nov 5, 2020
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
29 changes: 16 additions & 13 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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=@.
sloede marked this conversation as resolved.
Show resolved Hide resolved
```
Further details can be found in the [documentation](#documentation).

Expand All @@ -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
Expand All @@ -103,21 +104,23 @@ that can be opened with any image viewer:
<img width="300px" src="docs/src/assets/solution_000040_scalar_resized.png">
</p>

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.
sloede marked this conversation as resolved.
Show resolved Hide resolved


## Documentation
Expand Down
11 changes: 5 additions & 6 deletions docs/src/development.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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]`
Expand Down
19 changes: 11 additions & 8 deletions docs/src/github-git.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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)

Expand All @@ -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
Expand Down Expand Up @@ -156,15 +159,15 @@ 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.

#### Remove large file from repository
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!

Expand Down
58 changes: 32 additions & 26 deletions docs/src/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -65,20 +69,19 @@ 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.

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

Expand Down Expand Up @@ -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
Expand All @@ -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
<!-- TODO: Taal docs, create new version of this asciicast -->
sloede marked this conversation as resolved.
Show resolved Hide resolved
```@raw html
<script id="asciicast-356942"
src="https://asciinema.org/a/356942.js"
Expand All @@ -145,25 +151,25 @@ your machine, edit the configuration, and pass the file path to `Trixi.run(...)`
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.


### Performing a convergence analysis
To automatically determine the experimental order of convergence (EOC) for a
given setup, execute
```julia
Trixi.convtest("examples/2d/parameters_advection_basic.toml", 4)
julia> convergence_test(default_example(), 4)
```
This will run a convergence test with the parameters file `examples/2d/parameters_advection_basic.toml`,
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 parameters file 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
Finally, the measured ``l^2`` and ``l^\infty`` errors and the determined EOCs
will be displayed like this:
```
[...]
L2
l2
scalar
error EOC
9.14e-06 -
Expand All @@ -173,7 +179,7 @@ error EOC

mean 4.00
--------------------------------------------------------------------------------
Linf
linf
scalar
error EOC
6.44e-05 -
Expand All @@ -187,11 +193,11 @@ mean 3.99

An example with multiple variables looks like this:
```julia
julia> Trixi.convtest("examples/2d/parameters_euler_source_terms.toml", 3)
julia> convergence_test(joinpath(examples_dir(), "2d", "elixir_euler_source_terms.jl"), 3)
```
```
[...]
L2
l2
rho rho_v1 rho_v2 rho_e
error EOC error EOC error EOC error EOC
8.52e-07 - 1.24e-06 - 1.24e-06 - 4.28e-06 -
Expand All @@ -200,7 +206,7 @@ error EOC error EOC error EOC error EOC

mean 3.81 mean 3.92 mean 3.92 mean 3.90
--------------------------------------------------------------------------------
Linf
linf
rho rho_v1 rho_v2 rho_e
error EOC error EOC error EOC error EOC
8.36e-06 - 1.03e-05 - 1.03e-05 - 4.50e-05 -
Expand Down
Loading