Initial commit

.JuliaFormatter.toml

@@ -0,0 +1,57 @@
+# Configuration file for code formatting
+# see here for default options : https://github.com/domluna/JuliaFormatter.jl#formatting-options
+
+always_for_in = true
+whitespace_typedefs = true
+whitespace_ops_in_indices = true
+remove_extra_newlines = true
+short_to_long_function_def = true
+long_to_short_function_def = false
+# always_use_return = true
+whitespace_in_kwargs = true
+format_docstrings = false
+conditional_to_if = true
+trailing_comma = true
+normalize_line_endings = "unix"
+join_lines_based_on_source = false
+separate_kwargs_with_semicolon = true
+align_assignment = true
+align_struct_field = true
+align_conditional = true
+# align_pair_arrow = true
+# align_matrix = true
+# format_markdown = true
+
+
+# possible style : sciml, blue, yas
+
+# ### SciML options
+# whitespace_ops_in_indices = true
+# remove_extra_newlines = true
+# always_for_in = true
+# whitespace_typedefs = true
+# normalize_line_endings = "unix"
+
+# ### YAS options
+# always_for_in = true
+# whitespace_ops_in_indices = true
+# remove_extra_newlines = true
+# import_to_using = true
+# pipe_to_function_call = true
+# short_to_long_function_def = true
+# always_use_return = true
+# whitespace_in_kwargs = false
+# join_lines_based_on_source = true
+# separate_kwargs_with_semicolon = true
+
+# ### Blue option
+# always_use_return = true
+# short_to_long_function_def = true
+# whitespace_ops_in_indices = true
+# remove_extra_newlines = true
+# always_for_in = true
+# import_to_using = true
+# pipe_to_function_call = true
+# whitespace_in_kwargs = false
+# annotate_untyped_fields_with_any = false
+# separate_kwargs_with_semicolon = true

.github/workflows/Documentation.yml

@@ -0,0 +1,27 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+    tags: "*"
+  pull_request:
+    types: [unlabeled, opened, synchronize, reopened]
+
+# Only trigger the job when `draft` label is not assigned to the PR
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    if: contains(github.event.pull_request.labels.*.name, 'draft') == false
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: "1.9"
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); 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
+        run: julia --project=docs/ docs/make.jl

.github/workflows/TagBot.yml

@@ -0,0 +1,13 @@
+name: TagBot
+on:
+  schedule:
+    - cron: 0 0 * * *
+  workflow_dispatch:
+jobs:
+  TagBot:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: JuliaRegistries/TagBot@v1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          ssh: ${{ secrets.DOCUMENTER_KEY }}

.github/workflows/format_check.yml

@@ -0,0 +1,48 @@
+## from :
+## https://github.com/julia-actions/julia-format/blob/a8502d9a6b40ef5da6e88721e253e79981aa26d1/workflows/format_check.yml
+
+name: format-check
+
+on:
+  push:
+    branches:
+      - "main"
+      - "release-"
+    tags: "*"
+  pull_request:
+    types: [unlabeled, opened, synchronize, reopened]
+
+# Only trigger the job when `draft` label is not assigned to the PR
+jobs:
+  format:
+    runs-on: ${{ matrix.os }}
+    if: contains(github.event.pull_request.labels.*.name, 'draft') == false
+    strategy:
+      matrix:
+        julia-version: [1.9]
+        julia-arch: [x86]
+        os: [ubuntu-latest]
+    steps:
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: ${{ matrix.julia-version }}
+
+      - uses: actions/checkout@v1
+      - name: Install JuliaFormatter and format
+        # This will use the latest version by default but you can set the version like so:
+        #
+        # julia  -e 'using Pkg; Pkg.add(PackageSpec(name="JuliaFormatter", version="0.13.0"))'
+        run: |
+          julia  -e 'using Pkg; Pkg.add(PackageSpec(name="JuliaFormatter"))'
+          julia  -e 'using JuliaFormatter; format(".", verbose=true)'
+      - name: Format check
+        run: |
+          julia -e '
+          out = Cmd(`git diff --name-only`) |> read |> String
+          if out == ""
+              exit(0)
+          else
+              @error "Some files have not been formatted !!!"
+              write(stdout, out)
+              exit(1)
+          end'

.gitignore

@@ -0,0 +1,6 @@
+/docs/build/
+/docs/site/
+/docs/Manifest.toml
+/docs/src/example/
+/docs/src/tutorial/
+.vscode

Project.toml

@@ -0,0 +1,4 @@
+name = "BcubeTutorials"
+uuid = "96b9ee7b-4a19-4ce3-a39f-9fbf54b5b072"
+authors = ["Ghislain Blanchard, Lokman Bennani and Maxime Bouyges"]
+version = "0.1.0"

README.md

@@ -1,2 +1,9 @@
 # BcubeTutorials.jl
-Tutorials and examples for the Bcube project
+
+[![](https://img.shields.io/badge/docs-release-blue.svg)](https://bcube-project.github.io/BcubeTutorials.jl)
+
+Documented tutorials and various examples for the [Bcube.jl](https://bcube-project.github.io/Bcube.jl) project. Browse the [online documentation](https://bcube-project.github.io/BcubeTutorials.jl).
+
+## Authors
+
+Ghislain Blanchard, Lokman Bennani and Maxime Bouyges.

docs/Project.toml

@@ -0,0 +1,4 @@
+[deps]
+BcubeTutorials = "96b9ee7b-4a19-4ce3-a39f-9fbf54b5b072"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"

docs/make.jl

@@ -0,0 +1,94 @@
+push!(LOAD_PATH, "../src/")
+
+using BcubeTutorials
+using Documenter
+using Literate
+
+# Alias for `Literate.markdown`
+function gen_markdown(src, name, dir)
+    Literate.markdown(joinpath(src, name), dir; documenter = false, execute = false)
+end
+
+"""
+Build a markdown file with just the content of the julia file in it.
+"""
+function julia_to_markdown(src_dir, target_dir, filename, title)
+    open(joinpath(target_dir, split(filename, ".")[1] * ".md"), "w") do io
+        println(io, "# " * title)
+        println(io, "```julia")
+        f = open(joinpath(src_dir, filename), "r")
+        lines = readlines(f)
+        close(f)
+        map(line -> println(io, line), lines)
+        println(io, "```")
+    end
+end
+
+# Generate tutorials
+# `documenter = false` to avoid Documenter to execute cells
+tutorial_names =
+    ["helmholtz", "heat_equation", "linear_transport", "phase_field_supercooled"]
+tutorial_src = joinpath(@__DIR__, "..", "src", "tutorial")
+tutorial_dir = joinpath(@__DIR__, "src", "tutorial")
+Sys.rm(tutorial_dir; recursive = true, force = true)
+map(filename -> gen_markdown(tutorial_src, "$(filename).jl", tutorial_dir), tutorial_names)
+
+# Generate "commented" examples
+# `documenter = false` to avoid Documenter to execute cells
+example_src = joinpath(@__DIR__, "..", "src", "example")
+example_dir = joinpath(@__DIR__, "src", "example")
+Sys.rm(example_dir; recursive = true, force = true)
+mkdir(example_dir)
+# gen_markdown(example_src, "euler_naca_steady.jl", example_dir)
+# gen_markdown(example_src, "covo.jl", example_dir)
+# gen_markdown(example_src, "linear_elasticity.jl", example_dir)
+
+# Generate "uncommented" examples
+julia_to_markdown(
+    example_src,
+    example_dir,
+    "euler_naca_steady.jl",
+    "Euler equations on a NACA0012",
+)
+julia_to_markdown(example_src, example_dir, "covo.jl", "Euler equations - covo")
+julia_to_markdown(example_src, example_dir, "linear_elasticity.jl", "Linear elasticity")
+julia_to_markdown(
+    example_src,
+    example_dir,
+    "linear_thermoelasticity.jl",
+    "Linear thermo-elasticity",
+)
+
+makedocs(;
+    modules = [BcubeTutorials],
+    authors = "Ghislain Blanchard, Lokman Bennani and Maxime Bouyges",
+    sitename = "BcubeTutorials",
+    clean = true,
+    doctest = false,
+    format = Documenter.HTML(;
+        prettyurls = get(ENV, "CI", "false") == "true",
+        canonical = "https://bcube-project.github.io/BcubeTutorials.jl",
+        assets = String[],
+    ),
+    checkdocs = :none,
+    pages = [
+        "Home" => "index.md",
+        "Tutorials" => ["tutorial/$(filename).md" for filename in tutorial_names],
+        "Advanced examples" => Any[
+            "example/covo.md",
+            "example/euler_naca_steady.md",
+            "example/linear_elasticity.md",
+            "example/linear_thermoelasticity.md",
+        ],
+        "Manual" => Any[
+            "manual/geometry.md",
+            "manual/integration.md",
+            "manual/cellfunction.md",
+            "manual/function_space.md",
+            "manual/operator.md",
+        ],
+        "How to..." => "howto/howto.md",
+    ],
+)
+
+deploydocs(; repo = "github.com/bcube-project/BcubeTutorials.jl.git", push_preview = true)

docs/src/howto/howto.md

@@ -0,0 +1,84 @@
+# How to
+
+To be completed to answer common user questions.
+
+## Comparing manually the benchmarks with `main`
+
+Let's say you want to compare the performance of your current branch (named "target" hereafter) with the `main` branch (named "baseline" hereafter).
+
+Open from `Bcube.jl/` a REPL and type:
+
+```julia
+pkg> activate --temp
+pkg> add PkgBenchmark BenchmarkTools
+pkg> dev .
+using PkgBenchmark
+import Bcube
+benchmarkpkg(Bcube, BenchmarkConfig(; env = Dict("JULIA_NUM_THREADS" => "1")); resultfile = joinpath(@__DIR__, "result-target.json"))
+```
+
+This will create a `result-target.json` in the current directory.
+
+Then checkout the `main` branch. Start a fresh REPL and type (almost the same):
+
+```julia
+pkg> activate --temp
+pkg> add PkgBenchmark BenchmarkTools
+pkg> dev .
+using PkgBenchmark
+import Bcube
+benchmarkpkg(Bcube, BenchmarkConfig(; env = Dict("JULIA_NUM_THREADS" => "1")); resultfile = joinpath(@__DIR__, "result-baseline.json"))
+```
+
+This will create a `result-baseline.json` in the current directory.
+
+You can now "compare" the two files by running (watch-out for the order):
+
+```julia
+target = PkgBenchmark.readresults("result-target.json")
+baseline = PkgBenchmark.readresults("result-baseline.json")
+judgement = judge(target, baseline)
+export_markdown("judgement.md", judgement)
+```
+
+This will create the markdown file `judgement.md` with the results.
+
+For more details, once you've built the `judgement` object, you can also type the following code from `https://github.com/tkf/BenchmarkCI.jl`:
+
+```julia
+open("detailed-judgement.md", "w") do io
+    println(io, "# Judge result")
+    export_markdown(io, judgement)
+    println(io)
+    println(io)
+    println(io, "---")
+    println(io, "# Target result")
+    export_markdown(io, PkgBenchmark.target_result(judgement))
+    println(io)
+    println(io)
+    println(io, "---")
+    println(io, "# Baseline result")
+    export_markdown(io, PkgBenchmark.baseline_result(judgement))
+    println(io)
+    println(io)
+    println(io, "---")
+end
+```
+
+## Run the benchmark manually
+
+Let's say you want to run the benchmarks locally (without comparing with `main`)
+
+Open from `Bcube.jl/` a REPL and type:
+
+```julia
+pkg> activate --temp
+pkg> add PkgBenchmark
+pkg> dev .
+using PkgBenchmark
+import Bcube
+results = benchmarkpkg(Bcube, BenchmarkConfig(; env = Dict("JULIA_NUM_THREADS" => "1")); resultfile = joinpath(@__DIR__, "result.json"))
+export_markdown("results.md", results)
+```
+
+This will create the markdown file `results.md` with the results.

docs/src/index.md

@@ -0,0 +1,26 @@
+```@meta
+CurrentModule = BcubeTutorials
+```
+
+# Bcube
+
+## Purpose of Bcube
+
+Bcube is a Julia library providing tools for the spatial discretization of partial differential equation(s) (PDE). The main objectives are:
+
+- to provide a set of tools to quickly assemble an algorithm solving partial differential equation(s) (so the main objective is to help building prototypes without thinking about the numerical core)
+- to be completed : efficient/performant PDE resolution?
+
+This documentation is organised as follow. Checkout the tutorials to see what Bcube is capable of and/or quickly learn how to use it. Then, some more elaborated examples are provided to demonstrate the library capabilities. The "Manual" part explains how the core is organized. Finally, the "API" section is the low level code documentation.
+
+## Writing documentation
+
+To write documentation for Bcube, Julia's guidelines should be followed : [https://docs.julialang.org/en/v1/manual/documentation/](https://docs.julialang.org/en/v1/manual/documentation/). Moreover, this project tries to apply the [SciML Style Guide](https://github.com/SciML/SciMLStyle).
+
+## Conventions
+
+This documentation follows the following notation or naming conventions:
+
+- coordinates inside a reference frame are noted $$\hat{x}, \hat{y}$$ or $$\xi, \eta$$ while coordinates in the physical frame are noted $$x,y$$
+- when talking about a mapping, $$F$$ or sometimes $$F_{rp}$$ designates the mapping from the reference element to the physical element. On the other side, $$F^{-1}$$ or sometimes $$F_{pr}$$ designates the physical element to the reference element mapping.
+- "dof" means "degree of freedom"

docs/src/manual/cellfunction.md

@@ -0,0 +1,3 @@
+# Cell function
+
+As explained earlier, at least two coordinates systems exist in Bcube : the "reference" coordinates (`ReferenceDomain`) and the "physical" coordinates (`PhysicalDomain`). The evaluation of a function on a point in a cell depends on the way this point has been defined. Hence the definition of `CellPoint`s that embed the coordinate system. Given a `CellPoint` (or eventually a `FacePoint`), an `AbstractCellFunction` will be evaluated and the mapping between the `ReferenceDomain` to the `PhysicalDomain` (or reciprocally) will be performed internally if necessary : if an `AbstractCellFunction` defined in terms of reference coordinates is applied on a `CellPoint` expressed in the reference coordinates system, no mapping is needed.