How to create a page in the MANTIS docs.

To create a new page, create a filename.md-file somewhere in the docs folder (or any of its subfolders). You can type whatever you want here, which will be rendered into the content of your new page. These pages are written using MarkDown syntax, hence the .md extension. For the supported markdown syntax, see the Julia MarkDown Docs. Also check out the Documenter Showcase as well as the rest of the Documenter docs, to look up the syntax for the special boxes and whatnots.

You can make Admonitions boxes

These can highlight some of the important stuff. The colour of the boxes will change depending on the type of Admonition.

Requires at least Julia 1.10

Mantis was build assuming at least Julia 1.10.

This above may be wrong

I did not check that, but it may be useful to include such things.

You can also have a look at some of the pages I already created, which I also did to test things out. Note that the Documenter docs do not always explain every detail, so some googling may be required.

Some notes on MarkDown in VScode.

VScode does have MarkDown support, and even comes with the possibility to preview/render what you wrote. However, standard MarkDown and Julia MarkDown do occasionally differ, so you will not be able to preview everything. The VScode preview also only works on .md-files, so not on docstrings.

Adding the file to the docs.

While we have a file with MarkDown text, it does not yet show up in the build docs. To make this happen, go to the make.jl-file in the docs/-directory.

Do not change the name of the make.jl and index.jl files!

These files are needed by the Documenter package and need to have this filename. The build will fail if these are renamed (there are possibilities for doing this in more advanced setups, but we don't use these at the moment).

As you can see in the make.jl-file, the structure of the documentation is defined here. The titles in the left menu are defined here. The title of a specific page, however, is defined in the file for the page. Add the new file that you want to add in the right place, and (re-)build the docs to see the result (See the 'How to locally build the MANTIS docs.' page on how to build the docs).

Adding docstring to the docs.

The general MarkDown files create the pages of the documentation. Of course, the docs need to describe the code. To do this, it is possible to include the docstrings into the documentation. An example of what this looks like is the following:

Mantis.FunctionSpaces.Bernstein Type

julia

Bernstein <: AbstractCanonicalSpace

Concrete type for Bernstein polynomials; see [2].

Fields

p::Int: Degree of the Bernstein polynomial.

source

As you will see in the MarkDown file for this page, there are two blocks; one @meta-block, where the module is specified, and one @docs-block. In the @docs-block, you specify the module/type/method that you want to describe. In this specific case, the canonical=false option is specified. This allows this docstring to be included in the documentation multiple times. Without this option, the docstring can only be included once. If you try to include it multiple times anyway, the build will fail and the error message will show that you tried to include a function multiple times. The reason for only being allowed to include it once without the canonical=false option is simply; you can cross-reference to other docstrings and the only way to know which one is referenced is by only having it once without the canonical=false option.

You can put the @docs-block (as well as @meta-blocks) wherever you want. The blocks will be rendered at the place where you put them.

I have currently used @autodocs in the Developer Documentation page to list all the currently documented functions to see what this looks like.

Every docstring must be included at least once in the docs.

The documentation is set up in such a way that an error will occur if you do not include a docstring in the docs from one of the modules listed in the modules-option in the makedocs-function in the make.jl-file. This is to ensure that the documentation includes all documented functions.

Combining functions with the same name.

You can also combine the docstrings from functions with the same name but different input by using:

Mantis.FunctionSpaces.evaluate Function

julia

evaluate(polynomial::Bernstein, ξ::Vector{Float64}, nderivatives::Int=0)

Compute derivatives up to order nderivatives for all Bernstein polynomials of degree p at ξ for $ξ \in [0.0, 1.0]$ .

Arguments

polynomial::Bernstein: Bernstein polynomial.
ξ::Vector{Float64}: Vector of evaluation points $\in [0.0, 1.0]$ .
nderivatives::Int=0: Maximum order of derivatives to be computed (nderivatives $\leq p$ ). Defaults to 0, i.e., only the values of the polynomials are computed.

Returns

::Vector{Vector{Matrix{Float64}}}: Nested vector containing the values.

source

julia

evaluate(polynomials::AbstractLagrangePolynomials, ξ::Vector{Float64}, nderivatives::Int=0)

Evaluate the first nderivatives derivatives of the polynomials $B_{j} (ξ)$ , $j = 1, \dots, p + 1$ , in polynomials at ξ for $ξ \in [0.0, 1.0]$ .

Arguments

polynomials::AbstractLagrangePolynomials: $(p + 1)$ polynomials of degree $p$ , $B_{j}^{p} (ξ)$ with $j = 1, \dots, p + 1$ , to evaluate.
ξ::Vector{Float64}: vector of $n$ evaluation points $ξ \in [0.0, 1.0]$ .
nderivatives::Int: maximum order of derivatives to be computed (nderivatives $\leq p$ ). Will compute the polynomial, first derivative, second derivative, etc, up to nderivatives.

Returns

d_polynomials::Array{Float64, 3}(n, p+1, nderivatives) with the evaluation of polynomials and its derivatives up to degree nderivatives at every point ξ. d_polynomials[i, j, k] $= \frac{d^{k} B_{j}}{d ξ^{k}} (ξ_{i})$ .

source

julia

evaluate(polynomials::EdgeLobattoLegendre, ξ::Vector{Float64}, nderivatives::Int=0)

Evaluate the polynomials $B_{j} (ξ)$ , $j = 1, \dots, p + 1$ , in polynomials at ξ for $ξ \in [0.0, 1.0]$ .

Arguments

polynomials::EdgeLobattoLegendre: $(p + 1)$ polynomials of degree $p$ , $B_{j}^{p} (ξ)$ with $j = 1, \dots, p + 1$ , to evaluate.
ξ::Vector{Float64}: vector of $n$ evaluation points $ξ \in [0.0, 1.0]$ .
nderivatives::Int: maximum order of derivatives to be computed (nderivatives $\leq p$ ). Will compute the polynomial, first derivative, second derivative, etc, up to nderivatives.

Returns

source

julia

evaluate(ect_space::AbstractECTSpaces, ξ::Points.AbstractPoints{1}, nderivatives::Int=0)

Compute derivatives up to order nderivatives for all basis functions of degree p at ξ for $ξ \in [0.0, 1.0]$ .

Arguments

ect_space::AbstractECTSpaces: ECT section space.
ξ::Points.AbstractPoints{1}: vector of evaluation points $\in [0.0, 1.0]$ .
nderivatives::Int: maximum order of derivatives to be computed (nderivatives $\leq p$ ). Defaults to 0, i.e., only the values are computed.

source

julia

evaluate(ect_space::GeneralizedTrigonometric, ξ::Vector{Float64})

Compute all basis function values at ξ in $[0.0, 1.0]$ .

Arguments

ect_space::GeneralizedTrigonometric: Generalized Trigonometric section space.
xi::Vector{Float64}: vector of evaluation points in $[0.0, 1.0]$ .

source

julia

evaluate(ect_space::GeneralizedExponential, ξ::Vector{Float64})

Compute all basis function values at ξ in $[0.0, 1.0]$ .

Arguments

ect_space::GeneralizedExponential: Generalized Exponential section space.
xi::Vector{Float64}: vector of evaluation points $i n [0.0, 1.0]$ .

source

julia

evaluate(ect_space::Tchebycheff, ξ::Vector{Float64})

Compute all basis function values at ξ in $[0.0, 1.0]$ .

Arguments

ect_space::Tchebycheff: Tchebycheff section space.
xi::Vector{Float64}: vector of evaluation points $i n [0.0, 1.0]$ .

source

julia

evaluate(
    space::AbstractFESpace{manifold_dim, num_components, num_patches},
    element_id::Int,
    xi::NTuple{manifold_dim,Vector{Float64}},
    nderivatives::Int=0
) where {manifold_dim, num_components, num_patches}

Evaluate the basis functions of the finite element space space at the point xi on element element_id up to order nderivatives.

All of our function spaces are built in the parameteric domain. For example, in 1D, let the mapping from canonical coordinates to the i-th parametric element be Φᵢ: [0, 1] -> [aᵢ, bᵢ] then, for a function f defined on the parametric patch, the evaluate method actually returns the values/derivatives of f∘Φᵢ. Consider the function f₀ := f∘Φᵢ. Then, FunctionSpaces.evaluate(f) returns evaluations::Vector{Vector{Vector{Matrix{Float64}}} where evaluations[i][j][k][a,b] is the evaluation of:

the j-th mixed derivative ...
of order i-1 ...
for the b-th basis function ...
of the k-th component ...
at the a-th evaluation point ...
for f₀.

See get_derivative_idx for more details on the order in which all the mixed derivatives of order i-1 are stored.

Arguments

space::AbstractFESpace{manifold_dim, num_components, num_patches}: Finite element space.
element_id::Int: Index of the element.
xi::Points.AbstractPoints{manifold_dim}: Point on the element in canonical coordinates.
nderivatives::Int=0: Order of the derivatives. Default is 0 (i.e., function evaluation).

Returns

evaluation::Vector{Vector{Vector{Matrix{Float64}}}}: Values of the basis functions.
basis_indices::TI: Global indices of the basis functions. The type TI is an vector- like object with integer type elements. See the documentation of space or Indices for more details.

source

julia

evaluate(
    space::AbstractFESpace{manifold_dim, num_components, num_patches},
    element_id::Int,
    xi::NTuple{manifold_dim,Vector{Float64}},
    nderivatives::Int,
    coefficients::Vector{Float64}
) where {manifold_dim, num_components, num_patches}

Evaluate the basis functions with coefficients of the finite element space space at the point xi on element element_id up to order nderivatives. See evaluate for more details.

Arguments

space::AbstractFESpace{manifold_dim, num_components, num_patches}: Finite element space.
element_id::Int: Index of the element.
xi::Points.AbstractPoints{manifold_dim}: Point on the element in canonical coordinates.
nderivatives::Int=0: Order of the derivatives. Default is 0 (i.e., function evaluation).
coefficients::Vector{Float64}: Coefficients.

Returns

evaluation::Vector{Vector{Vector{Vector{Float64}}}}: Values at the points.

source

This may be clearer for these cases, though it can only be collapsed as one big block.

How to create a page in the MANTIS docs. ​

Some notes on MarkDown in VScode. ​

Adding the file to the docs. ​

Adding docstring to the docs. ​

Combining functions with the same name. ​

How to create a page in the MANTIS docs.

Some notes on MarkDown in VScode.

Adding the file to the docs.

Adding docstring to the docs.

Combining functions with the same name.