Add support for additional preconditioners

• Chebyshev (probably will involve Jacobi refactor)
• H-multigrid (will require macro elements)
• BDDC (will use macro elements from above)

Hi there,

I am trying to build an advection diffusion operator and I want to apply Jacobi PC as a starter.
I try to follow the code GalleryOperator("advection",..., GalleryOperator("diffusion",... and the example demo301: linear elasticity

The weak form requires three input argument

    function advdiffusionweakform(u::Array{Float64}, du::Array{Float64}, w::Array{Float64})
        dv = parameters.wind * u * w[1] + du * w[1]
        return [dv]
    end

    inputs = [
        OperatorField(basis, [EvaluationMode.interpolation], "adv"), 
        OperatorField(basis, [EvaluationMode.gradient], "gradent of deformation"),
        OperatorField(basis, [EvaluationMode.quadratureweights], "quadrature weights"),
    ]

which will build the elementmatrix of size (p+1) x 2(p+1) since getelementmatrix goes through all inputs but not allowing using two evaluation modes at the same time.

Since it's a linear operations, is there any way to combine two operator so advection + diffusion = advdiffusion?
Or do I have to go through Base.getproperty and modify the interface to fit my weakform function?

Thanks,
Yu-Hsiang

I need to decide how to compose smoothers. Do I want to assemble an element matrix, modify the element matrix for the smoothers, and then build the symbols from a given combo? It'd be nice to provide an impl of * that composes operators and smoothers.

Clean up multicomponent shape for QFunction inputs

Add P/H specific input validation for multigrid constructors

Notional roadmap for p-multigrid LFA paper

I think math is correct, but I need to do some more investigation. That makes this timeline super unknown, but I want to get something together by the end of the semester.

Code ToDo:

• numerically verify two grid analysis with known defects, will need to cannibalize libCEED + PETSc p-multigrid to add 1/2D (just 3D now) and add initial guess with known defect
• investigate theta -> 0 in 2D
• demonstrate optimization of smoothing parameter (I'd like to add Chebychev in addition to Jacobi as a smoother... we'll see if I get there)

Paper ToDo:

• continue to refine docs as draft of background information
• derive symbols by hand for some cases for comparison

Timeline unknown because I'm not comfortable with the current behaviour near the singularity at theta -> 0

Venue currently unknown for the paper.

This paper is being submitted to the 2021 Copper Mountain student paper competition. Submission on 22 Jan 2021.

For your info @jedbrown, but feel free to comment

Polynomials = "f27b6e38-b328-58d1-80ce-0feddd5e7a45"
CalculusWithJulia = "a2e0e22d-7d4c-5312-9169-8b992201a882"

@AdelekeBankole

The current naming is misleading. To be precise in terminology, these are Gauss-Legendre and Gauss-Legendre-Lobatto quadratures because both are constructed with Legendre polynomials (versus a different family of orthogonal polynomials, such as Chebyshev, Hermite, etc.). The Legendre is sometimes elided to give Gauss and Gauss-Lobatto.

Meanwhile, "Lagrange quadrature" isn't a thing as far as I know. Lagrange (interpolating) polynomials can be constructed on any set of points. A common choice of basis is to use Lagrange interpolating polynomials on Gauss-Legendre-Lobatto points. So many names.

┌ Warning: 6 docstrings not included in the manual:
│ 
│     LFAToolkit.computesymbols :: Tuple{Jacobi, Array{<:Real}, Array{<:Real}}
│     LFAToolkit.computesymbols :: Tuple{Chebyshev, Array{<:Real}, Array{<:Real}}
│     LFAToolkit.computesymbols :: Tuple{BDDC, Array{<:Real}, Array{<:Real}}
│     LFAToolkit.computesymbols :: Tuple{Multigrid, Array{<:Real}, Array{Int64}, Array{<:Real}}
│     LFAToolkit.computesymbols :: Tuple{Operator, Array{<:Real}}
│     LFAToolkit.computesymbolsoverrange :: Tuple{Multigrid, Array{<:Real}, Array{Int64}, Int64}
│ 
│ These are docstrings in the checked modules (configured with the modules keyword)
│ that are not included in @docs or @autodocs blocks.

There is some trick to fixing this false report, but I don't recall it at the moment

Add @lfa_weakform macro similar to libCEED @interior_qf macro.

Will add loop over multiple qpts

Will not need some of the arguments however

It would be great if we could find a way to run the tests in parallel. Right now the doctests are the slow part of test/runtests.jl

Computing with hundreds of quadrature points is rather slow and I suspect our quadrature nodes are not quite accurate to machine precision. Using lots of points is convenient for plotting and sometimes may be useful for the harmonic transform. I think we should discard the basic Newton algorithm and just use FastGaussQuadrature, which can compute millions of points in a fraction of a second. This may come at small precompilation overhead to new runs, but it's minor and fast, accurate quadrature is worth it.

The documentation should be expanded with more narrative explaining the various library features

The roadmap for this collection of PRs is unclear to me. Many of the commits seem to be intermingled across multiple PRs. This issue is my effort to try to come up with a plan to get all this work merged.

Here is my understanding of the features we want to add:

• Transplanted quadtrature (Mostly in #48, but that has some extra content)
  • Sausage transformation
  • Kosloff and Tal-Ezer transformation
  • Hale and Trefethen Strip transformation
• Advection example (#51)
  • New convenience constructor
  • New example ex010_advection.jl and demo010_advection.ipynb
  • Documentation update in docs/src/examples/advection.md
• Advection example with SUPG (#52)
  • New convenience constructor
  • New example ex011_advection_supg.jl and demo011_advection_supg.ipynb
  • Documentation update in docs/src/examples/advection.md

I think that once we get these three PRs fixed up and merged, then we can move to the other two.

The commit history on these branches is messy - I'm fine with squash-merge if we can get the contents of those branches rebased for the updates in main and the have the formatting and documentation issues all tidied up, though the best case scenario would be 'clean' branches with one or two relevant commits to add each new feature.

This is a general checklist for every PR:

• Formatting
  • run julia .Style.jl to automatically fix all formatting
• Documentation
  • Docstrings - every function added should have a docstring with the fields Arguments, Returns and Example
  • Doctest - every function added should have at least one doctest covering all relevant use cases
  • Markdown - new functions need to be added to docs/src in the relevant *.md file

"""
```julia
gausslobattoquadrature(q, weights)
```

Construct a Gauss-Legendre-Lobatto quadrature

# Arguments:
- `q`:        number of Gauss-Legendre-Lobatto points
- `weights`:  boolean flag indicating if quadrature weights are desired

# Returns:
- Gauss-Legendre-Lobatto quadrature points or points and weights

# Example:
```jldoctest
# generate Gauss-Legendre-Lobatto points
quadraturepoints = LFAToolkit.gausslobattoquadrature(5, false);

# verify
truepoints = [-1.0, -√(3/7), 0.0, √(3/7), 1.0];
@assert truepoints ≈ quadraturepoints

# generate Gauss-Legendre-Lobatto points and weights
quadraturepoints, quadratureweights = LFAToolkit.gausslobattoquadrature(5, true);

# verify
trueweights = [1/10, 49/90, 32/45, 49/90, 1/10];
@assert trueweights ≈ quadratureweights

# output

```
"""

Did I capture the main plan? Am I missing anything?

Add h multigrid level operators to gallery

It would be nice to have a StaticLint.jl CI job.

https://github.com/julia-vscode/StaticLint.jl

Hey @MalachiTimothyPhillips, your work on analyzing Schwarz looks really interesting. Would you be interested in adding those PCs back to main?

We should revert disabling the strict checks when running makedocs when JuliaDocs/Documenter.jl#1883 is fixed. Until then we should manually double check in PRs that docstrings are added and included in the manual when new methods are created.