Improve documentation and gradient limiter calculation

.github/workflows/TagBot.yml

@@ -0,0 +1,31 @@
+name: TagBot
+on:
+ issue_comment:
+ types:
+ - created
+ workflow_dispatch:
+ inputs:
+ lookback:
+ default: "3"
+permissions:
+ actions: read
+ checks: read
+ contents: write
+ deployments: read
+ issues: read
+ discussions: read
+ packages: read
+ pages: read
+ pull-requests: read
+ repository-projects: read
+ security-events: read
+ statuses: read
+jobs:
+ TagBot:
+ if: github.event_name == 'workflow_dispatch' || github.actor == 'JuliaTagBot'
+ runs-on: ubuntu-latest
+ steps:
+ - uses: JuliaRegistries/TagBot@v1
+ with:
+ token: ${{ secrets.GITHUB_TOKEN }}
+ ssh: ${{ secrets.DOCUMENTER_KEY }}

.github/workflows/documentation.yml

@@ -3,7 +3,7 @@ name: Documentation
 on:
  push:
  branches:
- - dev-0.3-main # update to match your development branch (master, main, dev, trunk, ...)
+ - dev-0.3-main # update to match your development branch (master, main, etc.)
  tags: '*'
  pull_request:
 
@@ -25,5 +25,5 @@ jobs:
  run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
  - name: Build and deploy
  env:
- GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # If authenticating with GitHub Actions token
+ DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
  run: julia --project=docs/ docs/make.jl

CHANGELOG.md

@@ -0,0 +1,59 @@
+# Release notes
+
+The format used for this `changelog` is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Notice that until the package reaches version `v1.0.0` minor releases are likely to be `breaking`. Starting from version `v3.0.1` breaking changes will be recorded here. 
+
+## Version [v0.3.1] - 2024-10-18
+
+### Added
+* Vastly improved documentation with new examples provided
+* Changelog added to record changes more clearly. Record kept in [Release notes](@ref)
+
+### Fixed
+* The calculation of gradients can be limited for stability. This functionality can be activated by passing the key work argument `limit_gradient` to the `run!` function. The implementation has been improved for robustness.
+
+### Changed
+* Master branch protected and requires PRs to push changes
+
+### Breaking
+* No breaking changes
+
+### Deprecated
+* No functions deprecated
+
+### Removed
+* No functionality has been removed
+
+## Version [v0.3.0] - 2024-09-21
+
+* New name - XCALibre.jl - which is now registered in the General Julia registry
+* Can do 3D and GPU accelerated simulations
+* Can read .unv and OpenFOAM mesh files (3D)
+* Can do incompressible and compressible simulations
+* RANS and LES models available
+* User-provided functions or neural networks for boundary conditions
+* Reasonably complete "user" documentation now provided
+* Made repository public (in v0.2 the work was kept in a private repository and could only do 2D simulations)
+* Tidy up mesh type definitions by @mberto79 in #5
+* Adapt code base to work with new mesh format by @mberto79 in [#6]
+* Mesh boundary struct changes PR by @TomMazin in [#7]
+* Mesh boundary struct changes PR fix by @TomMazin in [#8]
+
+
+## Version [v0.2.0] - 2023-01-23
+
+* New mesh format and type implemented that are GPU friendly.
+* No functionality changes
+
+## Version [v0.1.0] - 2023-01-23
+
+### Initial release
+
+2D implementation of classic incompressible solvers for laminar and turbulent flows:
+
+* Framework for equation definition
+* SIMPLE nad PISO algorithms
+* Read UNV meshes in 2D
+* Capability for RANS models
+* Various discretisation schemes available
+* Planned extension to 3D and GPU acceleration!

Project.toml

@@ -43,9 +43,9 @@ KernelAbstractions = "0.9.25"
 Krylov = "0.9"
 LDLFactorizations = "0.10"
 LinearOperators = "2.8"
+PrecompileTools = "1.2"
 ProgressMeter = "1.10"
 Reexport = "1.2"
 Setfield = "1.1"
 StaticArrays = "1.9"
 julia = "1.8"
-PrecompileTools = "1.2"

README.md

@@ -14,30 +14,31 @@
 ## What is XCALibre.jl?
 
 
-XCALibre.jl (pronounced as the mythical sword *Excalibur*) is a general purpose Computational Fluid Dynamics (CFD) library for 2D and 3D simulations on structured/unstructured grids using the finite volume method. XCALibre.jl has been designed to act as a platform for developing, testing and using *XPU CFD Algorithms and Libraries* to give researchers in both academia and industry alike a tool that can be used to test out ideas easily within a framework that offers acceptable performance. To this end, XCALibre.jl has been implemented to offer both CPU multi-threaded capabilities or GPU acceleration using the same codebase (thanks to the unified programming framework provided by [KernelAbstractions.jl](https://juliagpu.github.io/KernelAbstractions.jl/stable/)). Additionally, XCALibre.jl also offers a friendly API for those users who are interested in running CFD simulations with the existing solvers and models built into XCALibre.jl. 
+XCALibre.jl (pronounced as the mythical sword *Excalibur*) is a general purpose Computational Fluid Dynamics (CFD) library for 2D and 3D simulations on structured/unstructured grids using the finite volume method. XCALibre.jl has been designed to act as a platform for developing, testing and using *XPU CFD Algorithms and Libraries* to give researchers in both academia and industry alike a tool that can be used to test out ideas easily within a framework that offers acceptable performance. To this end, XCALibre.jl has been implemented to offer both CPU multi-threaded capabilities or GPU acceleration using the same codebase (thanks to the unified programming framework provided by [KernelAbstractions.jl](https://juliagpu.github.io/KernelAbstractions.jl/stable/)). XCALibre.jl also offers a friendly API for those users who are interested in running CFD simulations with the existing solvers and models built into XCALibre.jl. 
 
+![](docs/src/figures/animated_cylinder_re1000-2x.gif)
 
 ## Installation
 
 
-First, you need to [download and install Julia in your system](https://julialang.org/downloads/). Once you have a working installation of Julia, XCALibre.jl can be installed using the built in package manager. 
+First, you need to [download and install Julia on your system](https://julialang.org/downloads/). Once you have a working installation of Julia, XCALibre.jl can be installed using the built-in package manager. 
 
-To install XCALibre.jl directly from Github, open a Julia REPL, press `]` to enter the package manager. The REPL prompt icon will change from **julia>** (green) to **pkg>** (and change colour to blue) or **(myenvironment) pkg>** where `myenvironment` is the name of the currently active Juila environment. Once in package manager mode enter
+XCALibre.jl is available directly from the the General Julia Registry. Thus, to install XCALibre.jl open a Julia REPL, press `]` to enter the package manager. The REPL prompt icon will change from **julia>** (green) to **pkg>** (and change colour to blue) or **(myenvironment) pkg>** where `myenvironment` is the name of the currently active Julia environment. Once you have activated the package manager mode enter
 
 ```julia
-pkg> add XCALibre https://github.com/mberto79/XCALibre.jl.git
+pkg> add XCALibre
 ```
 
-A specific branch can be installed by providing the branch name precided by a `#`, for example, to install the `dev-0.3-main` branch
+To install XCALibre.jl directly from Github enter the following command (for the latest release)
 
 ```julia
-pkg> add XCALibre https://github.com/mberto79/XCALibre.jl.git#dev-0.3-main
+pkg> add XCALibre https://github.com/mberto79/XCALibre.jl.git
 ```
 
-We plan to register XCALibre.jl so that is added to the General Julia Registry. Once this has been completed, to install XCALibre.jl use the following command (in package mode as detailed above)
+A specific branch can be installed by providing the branch name precided by a `#`, for example, to install the `dev-0.3-main` branch enter
 
 ```julia
-pkg> add XCALibre
+pkg> add XCALibre https://github.com/mberto79/XCALibre.jl.git#dev-0.3-main
 ```
 
 ## Main features
@@ -70,13 +71,14 @@ U_eqn = (
 ## Main dependencies
 
 
-XCALibre.jl is possible (and relies) on the functionality provided by other packages in the Julia ecosystem. For a full list of direct dependencies please refer to the Project.toml file included with this repository. We are thankful to the teams that have helped develop and maintain every single of our dependencies. Major functionally is provided by the following:
+XCALibre.jl relies on the functionality provided by other packages from the Julia ecosystem. For a full list of direct dependencies please refer to the Project.toml file included with this repository. We are thankful to the teams that have helped develop and maintain every single of our dependencies. Major functionally is provided by the following:
 
 * KernelAbstractions.jl - provides a unified parallel programming framework for CPUs and GPUs
-* Krylov.jl - provide solvers for linear systems at the heart of XCALibre.jl
+* Krylov.jl - provides solvers for linear systems at the heart of XCALibre.jl
 * LinearOperators.jl - wrappers for matrices and linear operators
-* Atomix.jl - enable atomix operations to ensure race conditions are avoided in parallel kernels
-* CUDA.jl, AMD.jl, Metal.jl and OneAPI.jl - not direct dependencies but packages enable GPU usage in Julia
+* Atomix.jl - enables atomix operations to ensure race conditions are avoided in parallel kernels
+* CUDA.jl, AMD.jl, Metal.jl and OneAPI.jl - not direct dependencies but packages enabling GPU usage in Julia
+* StaticArrays.jl - provides definitions and performant primitives for working with vectors and matrices
 
 ## Related projects
 

dev_notes.md

@@ -11,8 +11,13 @@
 - [x] Check Divergence BCs for Upwind scheme
 - [ ] Implement Upwind as deferred correction
 - [x] Do mesh conversion to new format within UNV read/writer (2D and 3D meshes)
-- [x ] Add tests
+- [x] Add tests
 - [x] Add documentation (becoming urgent)
+- [ ] Explore new ways to store output files from simulations
+ - [ ] Should this be a folder?
+ - [ ] Should we overwrite by default or warn?
+ - [ ] Should be create a new folder?
+ - [ ] Should the folder name be "results" or "iterations"/"time_steps"
 
 ### Mesh module
 

docs/Project.toml

@@ -1,6 +1,15 @@
 [deps]
 AbstractTrees = "1520ce14-60c1-5f80-bbc7-55ef81b5835c"
+Changelog = "5217a498-cd5d-4ec6-b8c2-9b85a09b6e3e"
+Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterTools = "35a29f4d-8980-5a13-9543-d66fff28ecb8"
+GaussianProcesses = "891a1506-143c-57d2-908e-e1f8e92e6de9"
+KernelAbstractions = "63c18a36-062a-441e-b654-da1e3ab1ce7c"
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
+StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
+Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 
 [compat]
 Documenter = "1.6"

docs/make.jl

@@ -7,5 +7,7 @@ include("makeLocal.jl")
 # for more information.
 deploydocs(
  repo = "github.com/mberto79/XCALibre.jl.git",
+ devurl = "dev",
+ versions = ["stable" => "v^", "dev" => "dev"],
  devbranch = "dev-0.3-main"
 )

docs/makeLocal.jl

@@ -1,9 +1,18 @@
 using Documenter
 using InteractiveUtils
 using AbstractTrees
+using Changelog
 using XCALibre
 
-# push!(LOAD_PATH,"../src/") # for local build only
+ENV["GKSwstype"] = "100"
+
+# Generate a Documenter-friendly changelog from CHANGELOG.md
+Changelog.generate(
+ Changelog.Documenter(),
+ joinpath(@__DIR__, "..", "CHANGELOG.md"),
+ joinpath(@__DIR__, "src", "release_notes.md");
+ repo = "github.com/mberto79/XCALibre.jl",
+)
 
 USER_GUIDE_PAGES = Any[
  "0_introduction_and_workflow.md",
@@ -14,10 +23,12 @@ USER_GUIDE_PAGES = Any[
  "5_postprocessing.md"
 ]
 
-VERIFICATION_VALIDATION_PAGES = Any[
+EXAMPLES_PAGES = Any[
  "01_2d-isothermal-backward-facing-step.md",
  "02_2d-incompressible-transient-cylinder.md",
- "03_2d-constant-temperature-flat-plate.md"
+ "03_2d-constant-temperature-flat-plate.md",
+ "04_2d-inflow-using-Flux.md",
+ "05_2d-aerofoil-inflow-optimisation.md"
 ]
 
 makedocs(
@@ -28,7 +39,7 @@ makedocs(
  pages = [
  "Home" => "index.md",
  "quick_start.md",
- "Verification & validation" => "VV/" .* VERIFICATION_VALIDATION_PAGES,
+ "Examples" => "examples/" .* EXAMPLES_PAGES,
  "User Guide" => "user_guide/" .* USER_GUIDE_PAGES,
  hide("Theory Guide" => "theory_guide/introduction.md"),
  "contributor_guide.md",
@@ -37,5 +48,5 @@ makedocs(
  ]
 )
 
-foreach(rm, filter(endswith(".vtk"), readdir("docs", join=true)))
-foreach(rm, filter(endswith(".vtu"), readdir("docs", join=true)))
+# foreach(rm, filter(endswith(".vtk"), readdir("docs", join=true)))
+# foreach(rm, filter(endswith(".vtu"), readdir("docs", join=true)))

docs/src/contributor_guide.md

@@ -11,7 +11,7 @@ From its humble beginning as a 1D diffusion example code to explore the features
 ## Some guidelines
 ---
 
-To help use keep the codebase consistent and allow us to merge future Pull Requests (PRs) more easily, we kindly request that contributors adhere to some basic guidelines. We are are trying to struck a balance between consistency and ease of contribution by aiming not to be overly demanding on contributors. A minimum set of guidelines is provided below (subject to review as the codebase evolves), in no particular order:
+To help use keep the codebase consistent and allow us to merge future Pull Requests (PRs) more easily, we kindly request that contributors adhere to some basic guidelines. We are trying to strike a balance between consistency and ease of contribution by aiming not to be overly demanding on contributors. A minimum set of guidelines is provided below (subject to review as the codebase evolves), in no particular order:
 
 ### Code style
 
@@ -35,12 +35,12 @@ To help use keep the codebase consistent and allow us to merge future Pull Reque
 | Module | Description |
 |:-------|:------------|
 XCALibre.Mesh | This module defines all types required to construct the mesh object used by the flow solvers. Two main mesh types are used `Mesh2` and `Mesh3` used for 2D and 3D simulations, respectively. Some access functions are also included in this module. |
-XCALibre.Fields | This module define the fields used to hold and represent the flow variable. Scalar, vector and tensor fields are defined e.g. `ScalarField`, etc. Information is stored at cell centres. These fields also have face variant where information is stored at face centres e.g. `FaceVectorField`. These fields are generally used to store fluxes. A limited set of field operations are also defined e.g. `getfield` to allow indexing field object directly. |
-XCALibre.ModelFramework | This module provides the framework used to define `scalar and vector model equations whilst storing information about the operators used. The data structure also defines sparse matrices used to storage discretisation information. |
+XCALibre.Fields | This module defines the fields used to hold and represent the flow variable. Scalar, vector and tensor fields are defined e.g. `ScalarField`, etc. Information is stored at cell centres. These fields also have face variant where information is stored at face centres e.g. `FaceVectorField`. These fields are generally used to store fluxes. A limited set of field operations are also defined e.g. `getfield` to allow indexing field object directly. |
+XCALibre.ModelFramework | This module provides the framework used to define scalar and vector model equations whilst storing information about the operators used. The data structure also defines sparse matrices used to store discretisation information. |
 XCALibre.Discretise | This module defines the various operators needed to represent each terms in a model equation and the main discretisation loop that linearises each term according to the schemes available. Boundary conditions are also implemented in this module. |
 XCALibre.Solve | This module includes all functions and logic needed to solve the linear system of equations that follows the equation discretisation. The internal API to solve these systems of equations is included in this module. |
 XCALibre.Calculate | Implementation of functions use to carry out calculations essential to the implementation of flow solvers is included in this module. This includes interpolation of variables from cell centroid to cell faces, gradient calculation, surface normals, etc. |
-XCALibre.ModelPhysics | This module includes the implemetations of all the physical models i.e. fluid, turbulence and energy models. |
+XCALibre.ModelPhysics | This module includes the implementations of all the physical models i.e. fluid, turbulence and energy models. |
 XCALibre.Simulate | This model contains information needed to set up a simulation, including the [`Configuration`](@ref) type used by all flow solvers. |
 XCALibre.Solvers | Implementations of the SIMPLE and PISO flow solvers from steady and unsteady solutions, including their compressible variant. |
 XCALibre.Postprocess | A limited set of functions for postprocessing are implemented in this module. |
@@ -71,7 +71,7 @@ To fully characterise how mesh information is represented in XCALibre.jl, it is
 * Face normals for internal faces is always pointing in the direction from the ownerCell with the smallest ID to the largest. Since the discretisation loop is cell based, for the cell with the highest ID the direction must be reversed. This information is tracked in `Mesh3.nsign` which stores 1 if the face normal is correctly aligned or -1 if the normal needs to be reversed.
 * Boundary faces (e.g. patches) are stored consecutively in `Mesh3.Faces` starting at the beginning of the array followed by all the internal faces.
 * Boundary faces are those connected only to 1 `Cell`, thus, for these faces the entry `Face3D.ownerCells` is a 2-element vector with a repeated index e.g. [3, 3]
-* Boundary cells only store information for internal faces. This improves performance for the main discretisation loop (cell based) since it can always been assumed that non of the faces will be a boundary face, which are dealt with in a separate loop.
+* Boundary cells only store information for internal faces. This improves performance for the main discretisation loop (cell based) since it can always been assumed that none of the faces will be a boundary face, which are dealt with in a separate loop.
 
 
 ### Field types