{"id":21044385,"url":"https://github.com/trixi-framework/libtrixi","last_synced_at":"2025-05-15T17:32:40.172Z","repository":{"id":173314694,"uuid":"650560005","full_name":"trixi-framework/libtrixi","owner":"trixi-framework","description":"Interface library for using Trixi.jl from C/C++/Fortran","archived":false,"fork":false,"pushed_at":"2024-09-02T06:28:24.000Z","size":1286,"stargazers_count":3,"open_issues_count":12,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-09-07T00:03:59.249Z","etag":null,"topics":["amr","c-fortran-interface","conservation-laws","julia","numerical-library","simulation"],"latest_commit_sha":null,"homepage":"https://trixi-framework.github.io/libtrixi/","language":"Julia","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/trixi-framework.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.bib","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-06-07T10:24:41.000Z","updated_at":"2024-09-02T06:19:51.000Z","dependencies_parsed_at":"2024-01-06T09:39:55.222Z","dependency_job_id":"3918cb9d-bccc-4dd9-9fbb-36c0e04fcb4c","html_url":"https://github.com/trixi-framework/libtrixi","commit_stats":{"total_commits":116,"total_committers":6,"mean_commits":"19.333333333333332","dds":0.5775862068965517,"last_synced_commit":"a3ecd798bc12f5a507bbb68cd5e2dfb8b4b24554"},"previous_names":["trixi-framework/libtrixi-messy","trixi-framework/libtrixi"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trixi-framework%2Flibtrixi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trixi-framework%2Flibtrixi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trixi-framework%2Flibtrixi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trixi-framework%2Flibtrixi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trixi-framework","download_url":"https://codeload.github.com/trixi-framework/libtrixi/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254388304,"owners_count":22063023,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["amr","c-fortran-interface","conservation-laws","julia","numerical-library","simulation"],"created_at":"2024-11-19T14:16:36.492Z","updated_at":"2025-05-15T17:32:40.163Z","avatar_url":"https://github.com/trixi-framework.png","language":"Julia","funding_links":[],"categories":[],"sub_categories":[],"readme":"# libtrixi\n\n[![Docs-stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://trixi-framework.github.io/libtrixi/stable)\n[![Docs-dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://trixi-framework.github.io/libtrixi/dev)\n[![Build Status](https://github.com/trixi-framework/libtrixi/actions/workflows/ci.yml/badge.svg)](https://github.com/trixi-framework/libtrixi/actions?query=workflow%3ACI)\n[![Coveralls](https://coveralls.io/repos/github/trixi-framework/libtrixi/badge.svg)](https://coveralls.io/github/trixi-framework/libtrixi)\n[![Codecov](https://codecov.io/gh/trixi-framework/libtrixi/branch/main/graph/badge.svg)](https://codecov.io/gh/trixi-framework/libtrixi)\n[![License: MIT](https://img.shields.io/badge/License-MIT-success.svg)](https://opensource.org/licenses/MIT)\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.8321803.svg)](https://doi.org/10.5281/zenodo.8321803)\n\n**Libtrixi** is an interface library for using\n[Trixi.jl](https://github.com/trixi-framework/Trixi.jl) from C/C++/Fortran.\n\n\n## Getting started\n\n### Prerequisites\n\nCurrently, libtrixi is only developed and tested for Linux. Furthermore, the following\nsoftware packages need to be made available locally before installing libtrixi:\n* [Julia](https://julialang.org/downloads/platform/) v1.8+\n* C compiler with support for C11 or later (e.g., [gcc](https://gcc.gnu.org/) or [clang](https://clang.llvm.org/))\n* Fortran compiler with support for Fortran 2018 or later (e.g., [gfortran](https://gcc.gnu.org/fortran/))\n* [CMake](https://cmake.org/)\n* MPI (e.g., [OpenMPI](https://www.open-mpi.org/) or [MPICH](https://www.mpich.org/))\n* [HDF5](https://www.hdfgroup.org/solutions/hdf5/)\n* [t8code](https://github.com/DLR-AMR/t8code) v3.0.1\n\n### Get the sources\n\n```bash\ngit clone git@github.com:trixi-framework/libtrixi.git\n```\n\n### Building\n\nFor building, `cmake` and its typical workflow is used.\n\n1. It is recommended to create an out-of-source build directory, e.g.\n\n    ```bash\n    mkdir build\n    cd build\n    ```\n\n2. Call cmake\n\n    ```bash\n    cmake -DCMAKE_BUILD_TYPE=(Debug|Release) -DCMAKE_INSTALL_PREFIX=\u003cinstall_directory\u003e ..\n    ```\n\n    `cmake` should find `MPI` and `Julia` automatically. If not, the directories\n    can be specified manually.\n    The `cmake` clients `ccmake` or `cmake-gui` could be useful.\n\n    - Specifying the directory `install_directory` for later installation is optional.\n    - Optional specification of build type sets some default compiler options for optimized\n      or debug code.\n    - Building with t8code support is optional. It requires to pass\n      `-DT8CODE_ROOT=\u003ct8code_install_directory\u003e`.\n\n3. Call make\n\n    ```bash\n    make\n    ```\n\n    This will build and place `libtrixi.so` in the current directory along with its\n    header and a Fortran `mod` file. Your application will have to include and link\n    against these.\n\n    Examples can be found in the `examples` subdirectory.\n\n4. Install (optional)\n\n    ```bash\n    make install\n    ```\n\n    This will install all provided files to the specified location.\n\n### Setting up Julia\nBesides the library being installed, you need to configure Julia for use with libtrixi. For\nthis, create a directory where all necessary files will be placed, e.g., `libtrixi-julia`.\nThen, you can use the [`utils/libtrixi-init-julia`](utils/libtrixi-init-julia) tool (also\navailable at `\u003cinstall_directory\u003e/bin`) to do the rest for you. A minimal example would be:\n\n```shell\nmkdir libtrixi-julia\ncd libtrixi-julia\n\u003cinstall_directory\u003e/bin/libtrixi-init-julia \\\n    --t8code-library \u003ct8code_install_directory\u003e/lib/libt8.so\n    \u003cinstall_directory\u003e\n```\nUse `libtrixi-init-julia -h` to get help.\n\nIn your code, pass the path to the `libtrixi-julia` directory to `trixi_initialize`,\nsee the code of the examples. If you did not modify the default value for the Julia depot\nwhen calling `libtrixi-init-julia`, libtrixi will find it automatically.\nOtherwise, when running a program that uses libtrixi, you need to make sure to set the\n`JULIA_DEPOT_PATH` environment variable to point to the `\u003cjulia-depot\u003e` folder reported.\n\nIf you intend to use additional Julia packages, besides `Trixi` and `OrdinaryDiffEq`, you\nwill have to add them to your Julia project (i.e. use\n`julia --project=\u003clibtrixi-julia_directory\u003e` and `import Pkg; Pkg.add(\u003cpackage\u003e)`).\n\n### Testing\n\nGo to some directory from where you want to run a Trixi simulation.\n\n```shell\nLIBTRIXI_DEBUG=all \\\n    \u003cinstall_directory\u003e/bin/trixi_controller_simple_c \\\n    \u003clibtrixi-julia_directory\u003e \\\n    \u003cinstall_directory\u003e/share/libtrixi/LibTrixi.jl/examples/libelixir_tree1d_advection_basic.jl\n```\nwhich should give you an output similar to this:\n```\n████████╗██████╗ ██╗██╗  ██╗██╗\n╚══██╔══╝██╔══██╗██║╚██╗██╔╝██║\n   ██║   ██████╔╝██║ ╚███╔╝ ██║\n   ██║   ██╔══██╗██║ ██╔██╗ ██║\n   ██║   ██║  ██║██║██╔╝ ██╗██║\n   ╚═╝   ╚═╝  ╚═╝╚═╝╚═╝  ╚═╝╚═╝\n\n┌──────────────────────────────────────────────────────────────────────────────────────────────────┐\n│ SemidiscretizationHyperbolic                                                                     │\n│ ════════════════════════════                                                                     │\n│ #spatial dimensions: ………………………… 1                                                                │\n│ mesh: ………………………………………………………………… TreeMesh{1, Trixi.SerialTree{1}} with length 31                  │\n│ equations: …………………………………………………… LinearScalarAdvectionEquation1D                                  │\n│ initial condition: ……………………………… initial_condition_convergence_test                               │\n│ boundary conditions: ………………………… Trixi.BoundaryConditionPeriodic                                  │\n│ source terms: …………………………………………… nothing                                                          │\n│ solver: …………………………………………………………… DG                                                               │\n│ total #DOFs: ……………………………………………… 64                                                               │\n└──────────────────────────────────────────────────────────────────────────────────────────────────┘\n\n\u003csnip\u003e\n\n┌──────────────────────────────────────────────────────────────────────────────────────────────────┐\n│ Environment information                                                                          │\n│ ═══════════════════════                                                                          │\n│ #threads: ……………………………………………………… 1                                                                │\n└──────────────────────────────────────────────────────────────────────────────────────────────────┘\n\n────────────────────────────────────────────────────────────────────────────────────────────────────\n Simulation running 'LinearScalarAdvectionEquation1D' with DGSEM(polydeg=3)\n────────────────────────────────────────────────────────────────────────────────────────────────────\n #timesteps:                  0                run time:       7.20000000e-07 s\n Δt:             1.00000000e+00                └── GC time:    0.00000000e+00 s (0.000%)\n sim. time:      0.00000000e+00                time/DOF/rhs!:         NaN s\n                                               PID:                   Inf s\n #DOF:                       64                alloc'd memory:        143.411 MiB\n #elements:                  16\n\n Variable:       scalar\n L2 error:       2.78684204e-06\n Linf error:     6.06474411e-06\n ∑∂S/∂U ⋅ Uₜ :  -3.46944695e-18\n────────────────────────────────────────────────────────────────────────────────────────────────────\n\nCurrent time step length: 0.050000\n\n────────────────────────────────────────────────────────────────────────────────────────────────────\n Simulation running 'LinearScalarAdvectionEquation1D' with DGSEM(polydeg=3)\n────────────────────────────────────────────────────────────────────────────────────────────────────\n #timesteps:                 20                run time:       1.11329306e+00 s\n Δt:             5.00000000e-02                └── GC time:    5.11113150e-02 s (0.046%)\n sim. time:      1.00000000e+00                time/DOF/rhs!:  2.58861826e-08 s\n                                               PID:            1.57108461e-04 s\n #DOF:                       64                alloc'd memory:        116.126 MiB\n #elements:                  16\n\n Variable:       scalar\n L2 error:       6.03882964e-06\n Linf error:     3.21788773e-05\n ∑∂S/∂U ⋅ Uₜ :  -2.16706314e-09\n────────────────────────────────────────────────────────────────────────────────────────────────────\n\n ────────────────────────────────────────────────────────────────────────────────────\n              Trixi.jl                      Time                    Allocations\n                                   ───────────────────────   ────────────────────────\n         Tot / % measured:              1.13s /  52.4%           57.4MiB /  21.9%\n\n Section                   ncalls     time    %tot     avg     alloc    %tot      avg\n ────────────────────────────────────────────────────────────────────────────────────\n I/O                            3    495ms   83.5%   165ms   8.81MiB   70.0%  2.94MiB\n   ~I/O~                        3    230ms   38.8%  76.7ms   1.09MiB    8.7%   372KiB\n   get element variables        2    160ms   27.0%  80.2ms   1.90MiB   15.1%   975KiB\n   save solution                2    105ms   17.7%  52.5ms   5.81MiB   46.2%  2.91MiB\n   save mesh                    2    250ns    0.0%   125ns     0.00B    0.0%    0.00B\n analyze solution               2   98.1ms   16.5%  49.0ms   3.76MiB   29.9%  1.88MiB\n rhs!                         101    149μs    0.0%  1.47μs   6.61KiB    0.1%    67.0B\n   ~rhs!~                     101   88.1μs    0.0%   872ns   6.61KiB    0.1%    67.0B\n   volume integral            101   21.4μs    0.0%   212ns     0.00B    0.0%    0.00B\n   interface flux             101   10.2μs    0.0%   101ns     0.00B    0.0%    0.00B\n   prolong2interfaces         101   6.71μs    0.0%  66.4ns     0.00B    0.0%    0.00B\n   surface integral           101   5.52μs    0.0%  54.7ns     0.00B    0.0%    0.00B\n   Jacobian                   101   4.86μs    0.0%  48.1ns     0.00B    0.0%    0.00B\n   prolong2boundaries         101   3.79μs    0.0%  37.5ns     0.00B    0.0%    0.00B\n   reset ∂u/∂t                101   3.58μs    0.0%  35.5ns     0.00B    0.0%    0.00B\n   boundary flux              101   2.37μs    0.0%  23.5ns     0.00B    0.0%    0.00B\n   source terms               101   2.25μs    0.0%  22.3ns     0.00B    0.0%    0.00B\n calculate dt                  21   2.18μs    0.0%   104ns     0.00B    0.0%    0.00B\n ────────────────────────────────────────────────────────────────────────────────────\n```\n\nIf you change the executable name from `trixi_controller_simple_c` to\n`trixi_controller_simple_f`, you will get a near identical output. The corresponding source\nfiles can be found in the [`examples/`](examples/) folder. The examples demonstrate different\naspects on how to use the C and Fortran APIs of libtrixi:\n\n- `trixi_controller_simple.(c|f90)`: basic usage\n- `trixi_controller_mpi.(c|f90)`: usage in the presence of MPI\n- `trixi_controller_data.(c|f90)`: simulation data access\n- `trixi_controller_t8code.(c|f90)`: interacting with t8code\n\nIf you just want to test the Julia part of libtrixi, i.e., LibTrixi.jl, you can also run\n`trixi_controller_simple.jl` from Julia.\n\n```shell\nJULIA_DEPOT_PATH=\u003cjulia-depot_directory\u003e \\\nLIBTRIXI_DEBUG=all \\\n    julia --project=\u003clibtrixi-julia_directory\u003e\n    \u003cinstall_directory\u003e/share/libtrixi/examples/trixi_controller_simple.jl\n    \u003cinstall_directory\u003e/share/libtrixi/LibTrixi.jl/examples/libelixir_tree1d_advection_basic.jl\n```\n\nNote: Most auxiliary output is hidden unless the environment variable `LIBTRIXI_DEBUG` is\nset to `all`. Alternative values for the variable are `c` or `julia` to only show debug\nstatements from the C or Julia part of the library, respectively. All values are\ncase-sensitive and must be provided all lowercase.\n\n### Linking against libtrixi\n\n#### Make\n\nTo use libtrixi in your program, you need to specify `-I$LIBTRIXI_PREFIX/include` for the\ninclude directory with header and module files, `-L$LIBTRIXI_PREFIX/lib` for the library\ndirectory, and `-ltrixi` for the library itself during your build process. Optionally, you\ncan additionally specify `-Wl,-rpath,$LIBTRIXI_PREFIX/lib` such that the runtime loader\nknows where to find `libtrixi.so`. Here, `$LIBTRIXI_PREFIX` is the install prefix you\nspecified during the CMake configure stage with `-DCMAKE_INSTALL_PREFIX`\n(see [above](#building)).\n\nAn example `Makefile` is provided with\n[`examples/MakefileExternal`](examples/MakefileExternal), which can be invoked from inside\nthe `examples/` directory as\n```shell\nmake -f MakefileExternal LIBTRIXI_PREFIX=path/to/libtrixi/prefix\n```\nto build `trixi_controller_simple_f`.\n\n#### CMake\n\nA CMake module for the discovery of an installed libtrixi library is provided with\n[`cmake/FindLibTrixi.cmake`](cmake/FindLibTrixi.cmake). Before calling\n`find_package(LibTrixi)`, the CMake variable `LIBTRIXI_PREFIX` must be set to\n`\u003cinstall_directory\u003e`. An example `CMakeLists.txt` can be found in\n[`examples/external/CMakeLists.txt`](examples/external/CMakeLists.txt).\nTo see the commands required to build an example program with this CMake project,\nplease refer to [`examples/external/build.sh`](examples/external/build.sh).\n\n#### Note on thread-local storage (TLS)\n\nOn Linux and FreeBSD systems (i.e., *not* on macOS or Windows), Julia may internally\nuse a faster implementation for thread-local storage (TLS), which is used whenever Julia\nfunctions such task management, garbage collection etc. are used in a multithreaded\ncontext, or when they are themselves multithreaded. To activate the fast TLS in your\nprogram, you need to add the file `$LIBTRIXI_PREFIX/lib/libtrixi_tls.o` to the list of files\nthat are linked with your main program. See `MakefileExternal` for an example of how to do\nthis. If you skip this step, everything will work as usual, but some things might run\nslightly slower.\n\n### Experimental support for direct compilation of the Julia sources\nThere is _experimental_ support for compiling the Julia sources in LibTrixi.jl to a shared\nlibrary with a C interface. This is possible with the use of the Julia package\n[PackageCompiler.jl](https://github.com/JuliaLang/PackageCompiler.jl).\n\nTo try this out, perform the following steps:\n1.  Initialize the project directory `libtrixi-julia` using `libtrixi-init-julia` as\n    described above.\n2.  Build\n\n    *using make*\n    - Go to the `LibTrixi.jl/lib` directory in the repository root,\n      make sure that `PROJECT_DIR` (defined in `Makefile`) points to your `libtrixi-julia` directory,\n      and call `make`:\n      ```shell\n      cd LibTrixi.jl/lib\n      make\n      ```\n    - Go to the `examples` folder in the repository root and compile\n      `trixi_controller_simple_c`:\n      ```shell\n      cd examples\n      make -f MakefileCompiled LIBTRIXI_PREFIX=$PWD/../LibTrixi.jl/lib/build\n      ```\n      This will create a `trixi_controller_simple_c` file.\n\n    *using cmake*\n    - Add\n      ```\n      -DUSE_PACKAGE_COMPILER=ON -DJULIA_PROJECT_PATH=\u003clibtrixi-julia_directory\u003e\n      ```\n      to your cmake call (see above)\n3. From inside the `examples` folder you should be able to run the example (in parallel)\n   with the following command:\n   ```shell\n   mpirun -n 2 trixi_controller_simple_c \\\n       ../libtrixi-julia \\\n       ../LibTrixi.jl/examples/libelixir_p4est2d_euler_sedov.jl\n   ```\n   Optionally, you can set `LIBTRIXI_DEBUG=all` to get some debug output along the way.\n\n\n## Documentation\nDocumentation for the current release can be found at https://trixi-framework.github.io/libtrixi,\nand for the current development version at https://trixi-framework.github.io/libtrixi/dev.\n\n\n## Referencing\nIf you use libtrixi in your own research or write a paper using results obtained\nwith the help of libtrixi, you can refer to libtrixi directly as\n```bibtex\n@misc{schlottkelakemper2023libtrixi,\n  title={{L}ibtrixi: {I}nterface library for using {T}rixi.jl from {C}/{C}++/{F}ortran},\n  author={Schlottke-Lakemper, Michael and Geihe, Benedict and Gassner, Gregor J},\n  year={2023},\n  month={09},\n  howpublished={\\url{https://github.com/trixi-framework/libtrixi}},\n  doi={10.5281/zenodo.8321803}\n}\n```\nSince libtrixi is based on Trixi.jl, you should also\n[cite Trixi.jl](https://github.com/trixi-framework/Trixi.jl#referencing) in this case.\n\n\n## Authors\nLibtrixi was initiated by\n[Benedict Geihe](https://www.mi.uni-koeln.de/NumSim/)\n(University of Cologne, Germany) and\n[Michael Schlottke-Lakemper](https://lakemper.eu)\n(RWTH Aachen University/High-Performance Computing Center Stuttgart (HLRS), Germany), who\nare also its principal maintainers.\n\n\n## License\nLibtrixi is licensed under the MIT license (see [LICENSE.md](LICENSE.md)).\n\n\n## Acknowledgments\n\u003cp align=\"center\"\u003e\n  \u003c!-- DFG --\u003e\n  \u003cimg align=\"middle\" src=\"https://user-images.githubusercontent.com/3637659/231429826-31fd7e78-19b4-4bac-8d4c-d292c6570d93.jpg\" height=\"100\" /\u003e\n  \u003c!-- BMBF --\u003e\n  \u003cimg align=\"middle\" src=\"https://user-images.githubusercontent.com/3637659/231436391-b28a76a4-f027-40f9-bd28-14e3a2f3e16a.png\" height=\"100\" /\u003e\n\u003c/p\u003e\n\nThis project has benefited from funding by the Deutsche Forschungsgemeinschaft (DFG, German Research Foundation)\nthrough the research unit FOR 5409 \"Structure-Preserving Numerical Methods for Bulk- and\nInterface Coupling of Heterogeneous Models (SNuBIC)\" (project number 463312734).\n\nThis project has benefited from funding from the German Federal Ministry of\nEducation and Research through the project grant \"Adaptive earth system modeling\nwith significantly reduced computation time for exascale supercomputers\n(ADAPTEX)\" (funding id: 16ME0668K).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrixi-framework%2Flibtrixi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrixi-framework%2Flibtrixi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrixi-framework%2Flibtrixi/lists"}