diff --git a/.github/workflows/DocPreviewCleanup.yml b/.github/workflows/DocPreviewCleanup.yml new file mode 100644 index 00000000..66d0b342 --- /dev/null +++ b/.github/workflows/DocPreviewCleanup.yml @@ -0,0 +1,32 @@ +name: Doc Preview Cleanup + +on: + pull_request: + types: [closed] + +jobs: + doc-preview-cleanup: + # Do not run on forks to avoid authorization errors + # Source: https://github.community/t/have-github-action-only-run-on-master-repo-and-not-on-forks/140840/18 + if: github.repository_owner == 'trixi-framework' + runs-on: ubuntu-latest + steps: + - name: Checkout gh-pages branch + uses: actions/checkout@v3 + with: + ref: gh-pages + + - name: Delete preview and history + shell: bash + run: | + git config user.name "Documenter.jl" + git config user.email "documenter@juliadocs.github.io" + git rm -rf --ignore-unmatch "previews/PR$PRNUM" + git commit -m "delete preview" --allow-empty + git branch gh-pages-new $(echo "delete history" | git commit-tree HEAD^{tree}) + env: + PRNUM: ${{ github.event.number }} + + - name: Push changes + run: | + git push --force origin gh-pages-new:gh-pages diff --git a/.github/workflows/Documenter.yml b/.github/workflows/Documenter.yml new file mode 100644 index 00000000..359cd247 --- /dev/null +++ b/.github/workflows/Documenter.yml @@ -0,0 +1,47 @@ +name: Documentation + +on: + push: + branches: + - 'main' + tags: '*' + paths-ignore: + - '.zenodo.json' + - '.github/workflows/ci.yml' + - '.github/workflows/CompatHelper.yml' + - '.github/workflows/TagBot.yml' + pull_request: + paths-ignore: + - '.zenodo.json' + - '.github/workflows/ci.yml' + - '.github/workflows/CompatHelper.yml' + - '.github/workflows/TagBot.yml' + workflow_dispatch: + +# Cancel redundant CI tests automatically +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: julia-actions/setup-julia@v1 + with: + version: '1.9' + show-versioninfo: true + - uses: julia-actions/julia-buildpkg@v1 + with: + project: 'LibTrixi.jl' + env: + PYTHON: "" + - name: Install dependencies + run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=joinpath(pwd(), "LibTrixi.jl"))); Pkg.instantiate()' + - name: Build and deploy + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token + DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key + GKSwstype: 100 # To make GitHub Action work, disable showing a plot window with the GR backend of the Plots package + run: julia --project=docs --color=yes docs/make.jl diff --git a/.gitignore b/.gitignore index d6a91acc..afcedbde 100644 --- a/.gitignore +++ b/.gitignore @@ -10,3 +10,6 @@ cmake_install.cmake libtrixi.mod libtrixi.so* fortran_hello_world + +# Documenter +docs/build diff --git a/LibTrixi.jl/.gitignore b/LibTrixi.jl/.gitignore index f5bdd214..d384dde0 100644 --- a/LibTrixi.jl/.gitignore +++ b/LibTrixi.jl/.gitignore @@ -1 +1,2 @@ +Manifest.toml run diff --git a/LibTrixi.jl/src/api_c.jl b/LibTrixi.jl/src/api_c.jl index f05fba32..2f4c083b 100644 --- a/LibTrixi.jl/src/api_c.jl +++ b/LibTrixi.jl/src/api_c.jl @@ -3,7 +3,7 @@ trixi_initialize(libelixir::AbstractString)::Cint Initialize a new simulation based on the file `libelixir`and return a handle to the -corresponding [`simulationstate`](@ref) as a `Cint` (i.e, a plain C `int`). +corresponding [`SimulationState`](@ref) as a `Cint` (i.e, a plain C `int`). The libelixir has a similar purpose as a regular "elixir" in Trixi.jl, as it completely defines a simulation setup in Julia code. A key difference (and thus the name libelixir) is diff --git a/LibTrixi.jl/src/simulationstate.jl b/LibTrixi.jl/src/simulationstate.jl index 0f3ab795..4ca4796c 100644 --- a/LibTrixi.jl/src/simulationstate.jl +++ b/LibTrixi.jl/src/simulationstate.jl @@ -1,5 +1,9 @@ -# Struct to store a simulation state that consists of a semidiscretization plus the time -# integrator +""" + SimulationState + +Data structure to store a simulation state that consists of a semidiscretization +plus the time integrator. +""" mutable struct SimulationState{SemiType, IntegratorType} semi::SemiType integrator::IntegratorType diff --git a/README.md b/README.md index 9a4bebc3..68b22547 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,9 @@ # libtrixi -Interface library for using Trixi.jl from C/C++/Fortran. +[![Docs-dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://trixi-framework.github.io/libtrixi/dev) +[![License: MIT](https://img.shields.io/badge/License-MIT-success.svg)](https://opensource.org/licenses/MIT) + +**Libtrixi** is an interface library for using Trixi.jl from C/C++/Fortran. **Note: This project is in a very early stage and subject to changes without warning at any time.** @@ -73,3 +76,20 @@ are also its principal maintainers. ## License Libtrixi is licensed under the MIT license (see [LICENSE.md](LICENSE.md)). + +## Acknowledgments +

+ + + + +

+ +This project has benefited from funding by the Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) +through the research unit FOR 5409 "Structure-Preserving Numerical Methods for Bulk- and +Interface Coupling of Heterogeneous Models (SNuBIC)" (project number 463312734). + +This project has benefited from funding from the German Federal Ministry of +Education and Research through the project grant "Adaptive earth system modeling +with significantly reduced computation time for exascale supercomputers +(ADAPTEX)" (funding id: 16ME0668K). diff --git a/docs/Project.toml b/docs/Project.toml new file mode 100644 index 00000000..3a52a5db --- /dev/null +++ b/docs/Project.toml @@ -0,0 +1,5 @@ +[deps] +Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" + +[compat] +Documenter = "0.27" diff --git a/docs/make.jl b/docs/make.jl new file mode 100644 index 00000000..653f5bb1 --- /dev/null +++ b/docs/make.jl @@ -0,0 +1,45 @@ +using Documenter +import Pkg + +# Get LibTrixi.jl root directory +libtrixi_root_dir = dirname(@__DIR__) + +# Fix for https://github.com/trixi-framework/Trixi.jl/issues/668 +if (get(ENV, "CI", nothing) != "true") && (get(ENV, "TRIXI_DOC_DEFAULT_ENVIRONMENT", nothing) != "true") + push!(LOAD_PATH, libtrixi_root_dir) +end + +using LibTrixi + +# Define module-wide setups such that the respective modules are available in doctests +DocMeta.setdocmeta!(LibTrixi, :DocTestSetup, :(using LibTrixi); recursive=true) + +# Make documentation +makedocs( + # Specify modules for which docstrings should be shown + modules = [LibTrixi], + # Set sitename to Trixi.jl + sitename="Libtrixi", + # Provide additional formatting options + format = Documenter.HTML( + # Disable pretty URLs during manual testing + prettyurls = get(ENV, "CI", nothing) == "true", + # Set canonical URL to GitHub pages URL + canonical = "https://trixi-framework.github.io/libtrixi/stable" + ), + # Explicitly specify documentation structure + pages = [ + "Home" => "index.md", + "Reference" => [ + "LibTrixi.jl" => "reference-libtrixi-jl.md", + ], + "License" => "license.md" + ], + strict = true # to make the GitHub action fail when doctests fail, see https://github.com/neuropsychology/Psycho.jl/issues/34 +) + +deploydocs( + repo = "github.com/trixi-framework/libtrixi", + devbranch = "main", + push_preview = true +) diff --git a/docs/src/index.md b/docs/src/index.md new file mode 100644 index 00000000..8e41d709 --- /dev/null +++ b/docs/src/index.md @@ -0,0 +1,88 @@ +# libtrixi + +[![Docs-dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://trixi-framework.github.io/libtrixi/dev) +[![License: MIT](https://img.shields.io/badge/License-MIT-success.svg)](https://opensource.org/licenses/MIT) + +**Libtrixi** is an interface library for using Trixi.jl from C/C++/Fortran. + +**Note: This project is in a very early stage and subject to changes without warning at any time.** + +## Getting started + +### Prerequisites + +A local installation of `MPI` and `Julia` is required. + +### Get the sources + +```bash +git clone git@github.com:trixi-framework/libtrixi.git +``` + +### Building + +For building, `cmake` and its typical workflow is used. + +1. It is recommended to created an out-of-source build directory, e.g. + + ```bash + mkdir build + cd build + ``` + +2. Call cmake + + ```bash + cmake -DCMAKE_INSTALL_PREFIX= .. + ``` + + `cmake` should find `MPI` and `Julia` automatically. If not, the directories + can be specified manually. + The `cmake` clients `ccmake` or `cmake-gui` could be useful. + + Specifying the directory `install_directory` for later installation is optional. + +3. Call make + + ```bash + make + ``` + + This will build and place `libtrixi.so` in the current directory along with its + header and a Fortran `mod` file. Your application will have to include and link + against these. + + Examples can be found in the `examples` subdirectory. + +4. Install (optional) + + ```bash + make install + ``` + + This will install all provided file to the specified location. + +### Testing + +Check out the `fortran_hello_world` example. + +## Authors +Libtrixi was initiated by +[Benedict Geihe](https://www.mi.uni-koeln.de/NumSim/) +(University of Cologne, Germany) and +[Michael Schlottke-Lakemper](https://lakemper.eu) +(RWTH Aachen University/High-Performance Computing Center Stuttgart (HLRS), Germany), who +are also its principal maintainers. + +## [License](@id readme-license) +Libtrixi is licensed under the MIT license (see [License](@ref)). + +## Acknowledgments +This project has benefited from funding by the Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) +through the research unit FOR 5409 "Structure-Preserving Numerical Methods for Bulk- and +Interface Coupling of Heterogeneous Models (SNuBIC)" (project number 463312734). + +This project has benefited from funding from the German Federal Ministry of +Education and Research through the project grant "Adaptive earth system modeling +with significantly reduced computation time for exascale supercomputers +(ADAPTEX)" (funding id: 16ME0668K). diff --git a/docs/src/license.md b/docs/src/license.md new file mode 100644 index 00000000..35a17f5c --- /dev/null +++ b/docs/src/license.md @@ -0,0 +1,23 @@ +# License + +> MIT License +> +> Copyright (c) 2023 Benedict Geihe and Michael Schlottke-Lakemper +> +> Permission is hereby granted, free of charge, to any person obtaining a copy +> of this software and associated documentation files (the "Software"), to deal +> in the Software without restriction, including without limitation the rights +> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +> copies of the Software, and to permit persons to whom the Software is +> furnished to do so, subject to the following conditions: +> +> The above copyright notice and this permission notice shall be included in all +> copies or substantial portions of the Software. +> +> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +> SOFTWARE. diff --git a/docs/src/reference-libtrixi-jl.md b/docs/src/reference-libtrixi-jl.md new file mode 100644 index 00000000..476baaf6 --- /dev/null +++ b/docs/src/reference-libtrixi-jl.md @@ -0,0 +1,9 @@ +# LibTrixi.jl API + +```@meta +CurrentModule = LibTrixi +``` + +```@autodocs +Modules = [LibTrixi] +```