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

Institutional Support #1880

Closed
wants to merge 10 commits into from
Closed

Institutional Support #1880

Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
bbb5379
added SNuBIC link
torrilhon Mar 4, 2024
261ff60
Merge branch 'trixi-framework:main' into main
torrilhon Mar 17, 2024
2f4a08d
Institutional Support in README.md
torrilhon Mar 17, 2024
936daeb
Update README.md
torrilhon Mar 30, 2024
fec6c38
Apply suggestions from code review
torrilhon Mar 30, 2024
5a83bb2
added institutional logos
torrilhon Mar 30, 2024
6673e78
Merge branch 'main' into main
torrilhon Mar 30, 2024
22d177d
Merge branch 'trixi-framework:main' into main
torrilhon Jul 11, 2024
d0f749c
matching recent developments
torrilhon Jul 11, 2024
4ef6222
Merge branch 'main' into main
sloede Dec 2, 2024
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
201 changes: 163 additions & 38 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,8 @@
<img width="300px" src="https://trixi-framework.github.io/assets/logo.png">
</p>

**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
Expand Down Expand Up @@ -100,32 +101,60 @@ 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
git clone [email protected]: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
<script id="asciicast-373869"
src="https://asciinema.org/a/373869.js"
async
data-cols=100
data-rows=20
data-speed=3></script>
```
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
Expand All @@ -147,28 +176,102 @@ 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:
<p align="center">
<img width="300px" src="https://user-images.githubusercontent.com/26361975/177492363-74cee347-7abe-4522-8b2d-0dfadc317f7e.png">
</p>

![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
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
<script id="asciicast-372987"
src="https://asciinema.org/a/372987.js"
async
data-cols=100
data-rows=48></script>
```
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
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
Expand All @@ -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:
Expand Down Expand Up @@ -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
Expand All @@ -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
<p align="center" style="font-size:0;"><!--
BMBF --><img align="middle" src="https://github.com/trixi-framework/Trixi.jl/assets/3637659/f59af636-3098-4be6-bf80-c6be3f17cbc6" height="120"><!--
DFG --><img align="middle" src="https://github.com/trixi-framework/Trixi.jl/assets/3637659/e67b9ed3-7699-466a-bdaf-2ba070a29a8e" height="120"><!--
SRC --><img align="middle" src="https://github.com/trixi-framework/Trixi.jl/assets/3637659/48f9da06-6f7a-4586-b23e-739bee3901c0" height="120"><!--
ERC --><img align="middle" src="https://github.com/trixi-framework/Trixi.jl/assets/3637659/9371e7e4-3491-4433-ac5f-b3bfb215f5ca" height="120"><!--
NSF --><img align="middle" src="https://github.com/trixi-framework/Trixi.jl/assets/3637659/5325103c-ae81-4747-b87c-c6e4a1b1d7a8" height="120"><!--
DUBS --><img align="middle" src="https://github.com/trixi-framework/Trixi.jl/assets/3637659/bb021e6e-42e6-4fe1-a414-c847402e1937" height="120"><!--
NumFOCUS --><img align="middle" src="https://github.com/trixi-framework/Trixi.jl/assets/3637659/8496ac9e-b586-475f-adb7-69bcfc415185" height="120"><!--
-->
</p>

```@raw html
<div style="width: 100%; text-align: center; font-size: 0;">
<div><!--
BMBF --><img src="https://github.com/trixi-framework/Trixi.jl/assets/3637659/f59af636-3098-4be6-bf80-c6be3f17cbc6" style="height: 120px; width: auto"><!--
DFG --><img src="https://github.com/trixi-framework/Trixi.jl/assets/3637659/e67b9ed3-7699-466a-bdaf-2ba070a29a8e" style="height: 120px; width: auto"><!--
SRC --><img src="https://github.com/trixi-framework/Trixi.jl/assets/3637659/48f9da06-6f7a-4586-b23e-739bee3901c0" style="height: 120px; width: auto"><!--
-->
</div>
<div><!--
ERC --><img src="https://github.com/trixi-framework/Trixi.jl/assets/3637659/9371e7e4-3491-4433-ac5f-b3bfb215f5ca" style="height: 120px; width: auto"><!--
NSF --><img src="https://github.com/trixi-framework/Trixi.jl/assets/3637659/5325103c-ae81-4747-b87c-c6e4a1b1d7a8" style="height: 120px; width: auto"><!--
DUBS --><img src="https://github.com/trixi-framework/Trixi.jl/assets/3637659/bb021e6e-42e6-4fe1-a414-c847402e1937" style="height: 120px; width: auto"><!--
-->
</div>
<div><!--
NumFOCUS --><img src="https://github.com/trixi-framework/Trixi.jl/assets/3637659/8496ac9e-b586-475f-adb7-69bcfc415185" style="height: 120px; width: auto"><!--
-->
</div>
</div>
```

This project has benefited from funding by the [Deutsche
Forschungsgemeinschaft](https://www.dfg.de/) (DFG, German Research Foundation)
Expand Down
Loading