diff --git a/docs/make.jl b/docs/make.jl index cdbd3476..1db76bac 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -1,6 +1,18 @@ using Documenter using MeshIntegrals -makedocs(sitename="MeshIntegrals.jl Documentation") +makedocs( + sitename="MeshIntegrals.jl", + pages = [ + "Home" => [ + "About" => "index.md", + "Support Matrix" => "supportmatrix.md" + ], + "Derivations" => [ + "Integrating a Triangle" => "triangle.md" + ], + "Public API" => "api.md" + ] +) deploydocs(repo = "github.com/mikeingold/MeshIntegrals.jl.git") diff --git a/docs/src/api.md b/docs/src/api.md new file mode 100644 index 00000000..2a473bf0 --- /dev/null +++ b/docs/src/api.md @@ -0,0 +1,23 @@ +# Public API + +## Integrals + +```@docs +MeshIntegrals.integral +``` + +### Aliases + +```@docs +MeshIntegrals.lineintegral +MeshIntegrals.surfaceintegral +MeshIntegrals.volumeintegral +``` + +## Integration Algorithms + +```@docs +MeshIntegrals.GaussKronrod +MeshIntegrals.GaussLegendre +MeshIntegrals.HAdaptiveCubature +``` diff --git a/docs/src/supportmatrix.md b/docs/src/supportmatrix.md new file mode 100644 index 00000000..53e1d487 --- /dev/null +++ b/docs/src/supportmatrix.md @@ -0,0 +1,38 @@ +# Support Matrix + +| Symbol | Meaning | +|--------|---------| +| :white_check_mark: | Implemented, passes tests | +| :x: | Not yet supported | +| :stop_sign: | Not supported | + +### Integral +| Geometry | Gauss-Legendre | Gauss-Kronrod | H-Adaptive Cubature | +|----------|----------------|---------------|---------------------| +| `Ball` in `𝔼{2}` | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| `Ball` in `𝔼{3}` | :white_check_mark: | :stop_sign: | :white_check_mark: | +| `BezierCurve` | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| `Box` in `𝔼{1}` | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| `Box` in `𝔼{2}` | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| `Box` in `𝔼{3}` | :white_check_mark: | :stop_sign: | :white_check_mark: | +| `Circle` | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| `Cone` | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| `ConeSurface` | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| `Cylinder` | :white_check_mark: | :stop_sign: | :white_check_mark: | +| `CylinderSurface` | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| `Disk` | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| `Frustum` | :stop_sign: | :stop_sign: | :stop_sign: | +| `FrustumSurface` | :stop_sign: | :stop_sign: | :stop_sign: | +| `Line` | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| `ParaboloidSurface` | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| `Plane` | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| `Ray` | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| `Ring` | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| `Rope` | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| `Segment` | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| `SimpleMesh` | :x: | :x: | :x: | +| `Sphere` in `𝔼{2}` | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| `Sphere` in `𝔼{3}` | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| `Tetrahedron` in `𝔼{3}` | :x: | :white_check_mark: | :x: | +| `Triangle` | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| `Torus` | :white_check_mark: | :white_check_mark: | :white_check_mark: | diff --git a/docs/src/triangle.md b/docs/src/triangle.md new file mode 100644 index 00000000..34ce9e9c --- /dev/null +++ b/docs/src/triangle.md @@ -0,0 +1,17 @@ +# Integrating a Triangle + +For a specified `Meshes.Triangle` surface with area $A$, let $u$ and $v$ be Barycentric coordinates that span the surface. +```math +\int_\triangle f(\bar{r}) \, \text{d}A + = \iint_\triangle f\left( \bar{r}(u,v) \right) \, \left( \text{d}u \wedge \text{d}v \right) +``` + +Since the geometric transformation from the originally-arbitrary domain to a Barycentric domain is linear, the magnitude of the surface element $\text{d}u \wedge \text{d}v$ is constant throughout the integration domain. This constant will be equal to twice the magnitude of $A$. +```math +\int_\triangle f(\bar{r}) \, \text{d}A + = 2A \int_0^1 \int_0^{1-v} f\left( \bar{r}(u,v) \right) \, \text{d}u \, \text{d}v +``` + +This non-rectangular Barycentric domain prevents a direct application of most numerical integration methods. It can be directly integrated, albeit inefficiently, using nested Gauss-Kronrod quadrature rules. Alternatively, additional transformation could be applied to map this domain onto a rectangular domain. + +**WORK IN PROGRESS:** continued derivation to detail this barycentric-rectangular domain transformation diff --git a/docs/surfaceintegral_triangle.md b/docs/surfaceintegral_triangle.md deleted file mode 100644 index a95943ab..00000000 --- a/docs/surfaceintegral_triangle.md +++ /dev/null @@ -1,69 +0,0 @@ -# Surface Integral Over a Triangle - -**Note: This explanation reflects my original method but is no longer valid. -An updated derivation is planned. ** - -A linear transformation can be applied that maps any triangle onto a Barycentric -coordinate system. A linear correction factor is then applied to correct for the -domain transformation, where the area of the original triangle is $A$ and the area -of the Barycentric triangle is $1/2$. -```math -\int_\triangle f(\bar{r}) \text{d}A - = \frac{A}{1/2} \int_0^1 \int_0^{1-v} f(u,v) \text{d}v \text{d}u -``` - -This Barycentric integral can be directly estimated using a nested application of -the h-adaptive Gauss-Kronrod quadrature rules from QuadGK.jl (`quadgk_surface`). -Alternatively, with some additional modification it can be transformed onto a -fixed rectangular domain for integration via cubature rules or other nested -quadrature rules. - -Let $g$ be a wrapper function for $f$ that is only non-zero at valid Barycentric -coordinates. -```math -g(u,v,) = - \begin{cases} - f(u,v) & \text{if } 0 \le u+v \le 1 \\ - 0 & \text{otherwise} - \end{cases} -``` - -Then -```math -\int_0^1 \int_0^{1-v} f(u,v) \text{d}v \text{d}u - = \int_0^1 \int_0^1 g(u,v) \text{d}v \text{d}u -``` - -A domain transformation can be applied to map the Barycentric coordinate domains -from $u,v \in [0,1]$ to $s,t \in [-1,1]$, enabling the application of Gauss-Legendre -quadrature rules. -```math -s(u) = 2u - 1 \\ -u(s) = \frac{s+1}{2} -\text{d}u = \frac{1}{2}\text{d}s -``` -```math -t(v) = 2v - 1 \\ -v(t) = \frac{t+1}{2} -\text{d}v = \frac{1}{2}\text{d}t -``` - -Leading to -```math -\int_0^1 \int_0^1 g(u,v) \text{d}v \text{d}u - = \frac{1}{4} \int_{-1}^1 \int_{-1}^1 g(\frac{s+1}{2},\frac{t+1}{2}) \text{d}t \text{d}s -``` - -Gauss-Legendre nodes ($x \in [-1,1]$) and weights ($w$) for a rule of order $N$ -can be efficiently calculated using the FastGaussQuadrature.jl package. -```math -\int_{-1}^1 \int_{-1}^1 g(\frac{s+1}{2},\frac{t+1}{2}) \text{d}t \text{d}s - \approx \sum_{i=1}^N \sum_{j=1}_N w_i w_j f(x_i,x_j) -``` - -This approximation can be rolled back up the stack of equations, leading to an -expression that numerically approximates the original integral problem as -```math -\int_\triangle f(\bar{r}) \text{d}A - = \frac{A}{4(1/2)} \sum_{i=1}^N \sum_{j=1}_N w_i w_j f(\frac{x_i+1}{2}, \frac{x_j+1}{2}) -``` diff --git a/src/integral.jl b/src/integral.jl index 870f4ea7..c8d642d5 100644 --- a/src/integral.jl +++ b/src/integral.jl @@ -8,7 +8,7 @@ abstract type IntegrationAlgorithm end GaussKronrod(kwargs...) Numerically integrate using the h-adaptive Gauss-Kronrod quadrature rule implemented -by QuadGK.jl. All standard [`QuadGK.quadgk`](@ref) keyword arguments are supported. +by QuadGK.jl. All standard `QuadGK.quadgk` keyword arguments are supported. """ struct GaussKronrod <: IntegrationAlgorithm kwargs @@ -35,7 +35,7 @@ end GaussKronrod(kwargs...) Numerically integrate areas and surfaces using the h-adaptive cubature rule -implemented by HCubature.jl. All standard [`HCubature.hcubature`](@ref) keyword +implemented by HCubature.jl. All standard `HCubature.hcubature` keyword arguments are supported. """ struct HAdaptiveCubature <: IntegrationAlgorithm