From f5dd51e25b84065a9334a843989450a37677ef80 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=BCrgen=20Fuhrmann?= Date: Sat, 9 Mar 2024 16:46:35 +0100 Subject: [PATCH 1/4] Add test for undocumented names on Julia 1.11 Add docstrings for some of these --- src/ExtendableGrids.jl | 6 ++++++ src/simplexgrid.jl | 15 +++++++++++++++ test/gmsh.jl | 2 -- test/runtests.jl | 30 ++++++++++++++++++++++-------- 4 files changed, 43 insertions(+), 10 deletions(-) diff --git a/src/ExtendableGrids.jl b/src/ExtendableGrids.jl index 1cb082d1..6f5ca6a8 100644 --- a/src/ExtendableGrids.jl +++ b/src/ExtendableGrids.jl @@ -1,3 +1,9 @@ +""" + ExtendableGrids + +Package providing container structure `ExtendableGrid` with type stable content access and lazy content creation holding data for discretization +grids for finite element and finite volume methods. +""" module ExtendableGrids using DocStringExtensions diff --git a/src/simplexgrid.jl b/src/simplexgrid.jl index 5092923e..ce65aa3b 100644 --- a/src/simplexgrid.jl +++ b/src/simplexgrid.jl @@ -91,8 +91,23 @@ end ########################################################## + +""" + $(TYPEDEF) +X coordinates of simplex grid derived from tensor product +""" abstract type XCoordinates <: AbstractGridFloatArray1D end + +""" + $(TYPEDEF) +Y coordinates of simplex grid derived from tensor product +""" abstract type YCoordinates <: AbstractGridFloatArray1D end + +""" + $(TYPEDEF) +Z coordinates of simplex grid derived from tensor product +""" abstract type ZCoordinates <: AbstractGridFloatArray1D end diff --git a/test/gmsh.jl b/test/gmsh.jl index e10825d5..959c1fca 100644 --- a/test/gmsh.jl +++ b/test/gmsh.jl @@ -1,5 +1,3 @@ -using Gmsh: gmsh - # Add this later as an verbosity option # gmsh.option.setNumber("General.Terminal", 0) # gmsh.option.setNumber("General.Verbosity", 0) diff --git a/test/runtests.jl b/test/runtests.jl index 11786b49..2f3f7569 100644 --- a/test/runtests.jl +++ b/test/runtests.jl @@ -1,19 +1,33 @@ using Test, Aqua using ExampleJuggler +using Gmsh: gmsh using ExtendableGrids, SHA using AbstractTrees, StatsBase +@show pkgdir(ExtendableGrids) +@show :grid_unitcube ∈ Docs.undocumented_names(ExtendableGrids) + +@testset "undocumented names" begin + undocnames=Docs.undocumented_names(ExtendableGrids) + @test isempty(undocnames) +end + +end + @testset "Aqua" begin -Aqua.test_ambiguities([ExtendableGrids, Base, Core], exclude=[view, ==, StatsBase.TestStat, copyto!]) -Aqua.test_unbound_args(ExtendableGrids) -Aqua.test_undefined_exports(ExtendableGrids) -Aqua.test_project_extras(ExtendableGrids) -Aqua.test_stale_deps(ExtendableGrids,ignore=[:Requires,:Bijections]) -Aqua.test_deps_compat(ExtendableGrids) -Aqua.test_piracies(ExtendableGrids,treat_as_own=[AbstractTrees.children]) -Aqua.test_persistent_tasks(ExtendableGrids) + # not sure why copyto! and StatsBase are popping up here + Aqua.test_ambiguities([ExtendableGrids, Base, Core], exclude=[view, ==, StatsBase.TestStat, copyto!]) + Aqua.test_unbound_args(ExtendableGrids) + Aqua.test_undefined_exports(ExtendableGrids) + Aqua.test_project_extras(ExtendableGrids) + Aqua.test_stale_deps(ExtendableGrids,ignore=[:Requires,:Bijections]) + Aqua.test_deps_compat(ExtendableGrids) + + # Guilty of pirating: AbstracTrees.children(::Type)... + Aqua.test_piracies(ExtendableGrids,treat_as_own=[AbstractTrees.children]) + Aqua.test_persistent_tasks(ExtendableGrids) end From 2b2ab6b21cb966adf3ccb81ff1b3d55b301a5c6c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=BCrgen=20Fuhrmann?= Date: Sat, 9 Mar 2024 17:18:52 +0100 Subject: [PATCH 2/4] fix syntax bug in runteste --- test/runtests.jl | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/test/runtests.jl b/test/runtests.jl index 2f3f7569..6d1f4d9b 100644 --- a/test/runtests.jl +++ b/test/runtests.jl @@ -5,14 +5,12 @@ using Gmsh: gmsh using ExtendableGrids, SHA using AbstractTrees, StatsBase -@show pkgdir(ExtendableGrids) -@show :grid_unitcube ∈ Docs.undocumented_names(ExtendableGrids) +if isdefined(Docs,:undocumented_names) # 1.11 @testset "undocumented names" begin undocnames=Docs.undocumented_names(ExtendableGrids) @test isempty(undocnames) end - end From 51e3d0f975094dc1c5cbda6882f4b3bcd3bfad86 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=BCrgen=20Fuhrmann?= Date: Sat, 9 Mar 2024 19:32:26 +0100 Subject: [PATCH 3/4] add some missing docstrings --- docs/src/gridconstructors.md | 3 +++ docs/src/index.md | 13 +++++----- docs/src/tdict.md | 50 ------------------------------------ src/ExtendableGrids.jl | 3 +-- 4 files changed, 10 insertions(+), 59 deletions(-) delete mode 100644 docs/src/tdict.md diff --git a/docs/src/gridconstructors.md b/docs/src/gridconstructors.md index 7f194aa6..ca5fdd56 100644 --- a/docs/src/gridconstructors.md +++ b/docs/src/gridconstructors.md @@ -4,6 +4,9 @@ ```@docs simplexgrid +XCoordinates +YCoordinates +ZCoordinates glue ``` diff --git a/docs/src/index.md b/docs/src/index.md index 01b25c85..e4a53b67 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -1,7 +1,6 @@ -````@eval -using Markdown -Markdown.parse(""" -$(read("../../README.md",String)) -""") -```` - +```@docs +ExtendableGrids +``` +```@contents +Depth=5 +``` diff --git a/docs/src/tdict.md b/docs/src/tdict.md deleted file mode 100644 index 61c615d0..00000000 --- a/docs/src/tdict.md +++ /dev/null @@ -1,50 +0,0 @@ -# The TDict interface pattern - -Here we describe the idea behind the data structure used in this package. -TDict means: extendable containers with type stable content access and lazy content creation via the Julia type system. - -### Problem to be addressed - -In certain contexts it is desirable to use containers with core components -which are user extendable and allow for type stable component acces. Moreover, -some components are necessary on demand only, so they should be created lazily. -Furthermore, there should be a kind of safety protocol which prevents errors -from typos in component names etc. - -Julia default data structures do not provide these properties. - -#### `struct` - - Julia structs with proper field type annotations guarantee type stability - - Julia structs are not extendable, fields and their types are fixed upon definition - - If we don't fix types of struct fields they become Any and a source - for type instability - - The situation could be fixed if `getfield` could be overloaded but it cant't - -#### `Dict` - - Plain Dicts with flexible value types are a source of type instability - - Dicts with strings as keys needs a meta protocol to handle - semantics of keys which at the end probably hinges on string comparison which - will make things slow - - Dicts with symbols as keys still need this meta protocol - - Same for the implementation of a lazy evaluation protocol - - If a dict contains components of different types, component access will not be typestable - -### Proposed solution: - -Harness the power of the Julia type system: -- Use a struct containing a Dict with DataType as keys. Every key is a type. -- Use type hierarchies to manage different value classes -- Use the type system to dispatch between `getindex`/`setindex!` methods for keys -- Extension requires declaring new types, keys can be only existing types almost removing - typos as sources for errors -- Lazy extension is managed bye an `instantiate` method called by `getindex` if necessary -- Component access is made type stable by type dispatched`getindex` methods -- Component insertion is made safe by having `setindex!` calling a `veryform` method - -#### Pros -See above ... - -#### Cons -- Implemented using a Dict, so access is inherently slower than access to a component - of a struct. Therefore it is not well suited for inner loops. - diff --git a/src/ExtendableGrids.jl b/src/ExtendableGrids.jl index 6f5ca6a8..2e4d4c6a 100644 --- a/src/ExtendableGrids.jl +++ b/src/ExtendableGrids.jl @@ -1,8 +1,7 @@ """ ExtendableGrids -Package providing container structure `ExtendableGrid` with type stable content access and lazy content creation holding data for discretization -grids for finite element and finite volume methods. +$(read(joinpath(@__DIR__,"..","README.md"),String)) """ module ExtendableGrids From d0966dcaf5cb4f7230b2a6d37a3e89c0f210a9b0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=BCrgen=20Fuhrmann?= Date: Sat, 9 Mar 2024 19:32:47 +0100 Subject: [PATCH 4/4] some experiments with docs structure: - @contents block in large pages - slight reordering --- docs/Project.toml | 2 +- docs/make.jl | 2 +- docs/src/adjacency.md | 19 ++++++----- docs/src/extendablegrid.md | 64 ++++++++++++++++++++++++++++++++++++-- docs/src/gmsh.md | 5 ++- 5 files changed, 78 insertions(+), 14 deletions(-) diff --git a/docs/Project.toml b/docs/Project.toml index d9c84172..62eafab5 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -10,6 +10,6 @@ SimplexGridFactory = "57bfcd06-606e-45d6-baf4-4ba06da0efd5" Triangulate = "f7e6ffb2-c36d-4f8f-a77e-16e897189344" [compat] -Documenter = "1" +Documenter = "1.3" julia = "1.9" ExampleJuggler = "2" diff --git a/docs/make.jl b/docs/make.jl index 64246621..2ae773a9 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -16,13 +16,13 @@ function mkdocs() repo = "https://github.com/j-fu/ExtendableGrids.jl", pages = [ "Home" => "index.md", + "extendablegrid.md", "adjacency.md", "vectorofconstants.md", "typehierarchy.md", "elementgeometry.md", "shape_specs.md", "coordinatesystem.md", - "extendablegrid.md", "subgrid.md", "more.md", "voronoi.md", diff --git a/docs/src/adjacency.md b/docs/src/adjacency.md index 7f99a6c2..2b2880e7 100644 --- a/docs/src/adjacency.md +++ b/docs/src/adjacency.md @@ -1,3 +1,6 @@ +```@meta +CollapsedDocStrings = true +``` # Adjacency This handles adjacency matrices between entities of polyhedral complexes, e.g. @@ -22,19 +25,19 @@ From these ideas we develop the following interface for an adjacency a. In order to avoid name confusion, we introduce the following notation which should be consistent with the use in assembly loops. -source: source of adjacency link -target: target of adjacency link + source: source of adjacency link + target: target of adjacency link E.g. the cell-node adjacency for FEM assembly links a number of cells with a collection of nodes. The cells are the sources, and the targets are the nodes. - getindex(a,i,isource) aka a[i,isource]: return i-th target of source j - num_sources(a): overall number of sources, e.g. number of cells - num_targets(a): overall number of targets - num_targets(a,isource): number of targets for source given by isource - num_links(a): number of links aka nonzero entries of adjacency matrix - show(a): print stuff + getindex(a,i,isource) aka a[i,isource]: return i-th target of source j + num_sources(a): overall number of sources, e.g. number of cells + num_targets(a): overall number of targets + num_targets(a,isource): number of targets for source given by isource + num_links(a): number of links aka nonzero entries of adjacency matrix + show(a): print stuff Further API ideas: - Convert between Matrix and Variable target stuff using 0 entries as "padding" diff --git a/docs/src/extendablegrid.md b/docs/src/extendablegrid.md index 474b7dd4..5ccb17be 100644 --- a/docs/src/extendablegrid.md +++ b/docs/src/extendablegrid.md @@ -1,10 +1,16 @@ # Extendable grid + An ExtendableGrid in form of a dictionary with types as keys and type stable value access. -This means that grid components are accessed as dict entries, e.g. `grid[Coordinates]` . -The rationale of this approach is explained [here](tdict.md). +This means that grid components are accessed as dict entries, e.g. `grid[Coordinates]`. +The rationale behind this decision is described [below](@ref TDict). + +```@contents +Pages = ["extendablegrid.md"] +Depth = 2:6 +``` -## Notations +## Extendable grid notations A grid is assumed to be a subset of components of a polyhedral complex in d-dimensional space. We distinguish the following element classes characterized by their dimension: @@ -78,3 +84,55 @@ Modules = [ExtendableGrids] Pages = ["extendablegrid.jl"] ``` + + +## [The TDict interface pattern](@id TDict) + +Here we describe the idea behind the data structure used in this package. +TDict means: extendable containers with type stable content access and lazy content creation via the Julia type system. + +### Problem to be addressed + +In certain contexts it is desirable to use containers with core components +which are user extendable and allow for type stable component acces. Moreover, +some components are necessary on demand only, so they should be created lazily. +Furthermore, there should be a kind of safety protocol which prevents errors +from typos in component names etc. + +Julia default data structures do not provide these properties. + +#### `struct` + - Julia structs with proper field type annotations guarantee type stability + - Julia structs are not extendable, fields and their types are fixed upon definition + - If we don't fix types of struct fields they become Any and a source + for type instability + - The situation could be fixed if `getfield` could be overloaded but it cant't + +#### `Dict` + - Plain Dicts with flexible value types are a source of type instability + - Dicts with strings as keys needs a meta protocol to handle + semantics of keys which at the end probably hinges on string comparison which + will make things slow + - Dicts with symbols as keys still need this meta protocol + - Same for the implementation of a lazy evaluation protocol + - If a dict contains components of different types, component access will not be typestable + +### Proposed solution: + +Harness the power of the Julia type system: +- Use a struct containing a Dict with DataType as keys. Every key is a type. +- Use type hierarchies to manage different value classes +- Use the type system to dispatch between `getindex`/`setindex!` methods for keys +- Extension requires declaring new types, keys can be only existing types almost removing + typos as sources for errors +- Lazy extension is managed bye an `instantiate` method called by `getindex` if necessary +- Component access is made type stable by type dispatched`getindex` methods +- Component insertion is made safe by having `setindex!` calling a `veryform` method + +#### Pros +See above ... + +#### Cons +- Implemented using a Dict, so access is inherently slower than access to a component + of a struct. Therefore it is not well suited for inner loops. + diff --git a/docs/src/gmsh.md b/docs/src/gmsh.md index 90d03b34..596e0a54 100644 --- a/docs/src/gmsh.md +++ b/docs/src/gmsh.md @@ -3,7 +3,10 @@ This functionality is in beta stage. Breaking changes for this API are considered non-breaking for the package. Therefore, these functions are not exported yet. - +```@contents +Pages = ["gmsh.md"] +Depth = 2:4 +``` ## API These methods become available via a package extension which is loaded together with