From 978a8a57ffdc3374f4022baea0f1d725da438941 Mon Sep 17 00:00:00 2001 From: Simeon David Schaub Date: Mon, 23 Sep 2024 20:29:01 +0200 Subject: [PATCH] add some docs closes #2 --- docs/Manifest.toml | 8 +++--- docs/make.jl | 3 ++- docs/src/index.md | 9 +++++++ src/AztecDiamonds.jl | 59 ++++++++++++++++++++++++++++++++++++++++++-- src/ka.jl | 10 +++++++- src/show.jl | 2 +- test/show.jl | 15 +++++------ 7 files changed, 90 insertions(+), 16 deletions(-) diff --git a/docs/Manifest.toml b/docs/Manifest.toml index 39b21f1..a9a6807 100644 --- a/docs/Manifest.toml +++ b/docs/Manifest.toml @@ -74,10 +74,10 @@ uuid = "39de3d68-74b9-583c-8d2d-e117c070f3a9" version = "0.4.7" [[deps.AztecDiamonds]] -deps = ["Adapt", "Colors", "ImageIO", "ImageShow", "KernelAbstractions", "OffsetArrays", "Transducers"] +deps = ["Adapt", "Base64", "Colors", "ImageIO", "ImageShow", "KernelAbstractions", "OffsetArrays", "Transducers"] path = ".." uuid = "8762d9c5-fcab-4007-8fd1-c6de73397726" -version = "0.2.3" +version = "0.2.4" [deps.AztecDiamonds.extensions] MakieExtension = ["Makie", "GeometryBasics"] @@ -358,9 +358,9 @@ version = "0.7.10" Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2" [[deps.InverseFunctions]] -git-tree-sha1 = "2787db24f4e03daf859c6509ff87764e4182f7d1" +git-tree-sha1 = "a779299d77cd080bf77b97535acecd73e1c5e5cb" uuid = "3587e190-3f89-42d0-90ee-14403ec27112" -version = "0.1.16" +version = "0.1.17" weakdeps = ["Dates", "Test"] [deps.InverseFunctions.extensions] diff --git a/docs/make.jl b/docs/make.jl index 4ecad62..dc11839 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -6,7 +6,7 @@ DocMeta.setdocmeta!(AztecDiamonds, :DocTestSetup, :(using AztecDiamonds); recurs makedocs(; modules = [AztecDiamonds], authors = "Simeon David Schaub and contributors", - repo = "https://github.com/JuliaLabs/AztecDiamonds.jl/blob/{commit}{path}#{line}", + repo = Remotes.GitHub("JuliaLabs", "AztecDiamonds.jl"), sitename = "AztecDiamonds.jl", format = Documenter.HTML(; prettyurls = get(ENV, "CI", "false") == "true", @@ -25,4 +25,5 @@ makedocs(; deploydocs(; repo = "github.com/JuliaLabs/AztecDiamonds.jl", devbranch = "main", + push_preview = true, ) diff --git a/docs/src/index.md b/docs/src/index.md index 7e16015..3dd46bd 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -6,6 +6,15 @@ CurrentModule = AztecDiamonds Documentation for [AztecDiamonds](https://github.com/JuliaLabs/AztecDiamonds.jl). +For an example notebook using this package, see [here](https://julia.mit.edu/AztecDiamonds.jl/examples/stable/notebook.html). + +Here's a random diamond: + +```@example +using AztecDiamonds +show(stdout, MIME("text/plain"), diamond(10)) +``` + ```@index ``` diff --git a/src/AztecDiamonds.jl b/src/AztecDiamonds.jl index a55ae36..0a7c027 100644 --- a/src/AztecDiamonds.jl +++ b/src/AztecDiamonds.jl @@ -9,11 +9,41 @@ export Tiling, diamond, ka_diamond, dr_path inds(N) = ((1 - N):N, (1 - N):N) +""" + Tiling(N::Int[, x::OffsetMatrix{AztecDiamonds.Edge}]; sizehint::Int = N) + +Represents an order N diamond-shaped tiling. If `x` is not provided, it is initialized with `NONE` +representing an empty tiling. The `sizehint` keyword argument may be used to preallocate a larger +matrix for `x` fitting a tiling of order `sizehint` to avoid reallocations when the tiling grows. + +The indices of `x` represent the coordinates of the diamond-shaped tiling and run from 1-N to N +(though `x` is allowed to be larger as long as it contains these indices). +The edges it contains can either be `UP`, `RIGHT`, or `NONE`, where `UP` represents a vertical tile +covering one more tile to the top, `RIGHT` represents a horizontal tile covering one more tile to +the right. `NONE` means the edge is either already covered by another tile to the bottom or left or +the tiling is not fully filled yet. + +```jldoctest +julia> t = Tiling(1) +1-order Tiling{Matrix{AztecDiamonds.Edge}} + + + +julia> t[0, 0] = t[1, 0] = AztecDiamonds.RIGHT; + +julia> t +1-order Tiling{Matrix{AztecDiamonds.Edge}} +🬇🬋🬋🬃 +🬇🬋🬋🬃 +``` + +See [`diamond`](@ref) and [`ka_diamond`](@ref) for constructing a filled tiling. +""" struct Tiling{M <: AbstractMatrix{Edge}} N::Int x::OffsetMatrix{Edge, M} end -Tiling(N::Int; sizehint = N) = Tiling(N, fill(NONE, inds(sizehint))) +Tiling(N::Int; sizehint::Int = N) = Tiling(N, fill(NONE, inds(sizehint))) in_diamond(N, i, j) = abs(2i - 1) + abs(2j - 1) ≤ 2N Base.checkbounds(::Type{Bool}, (; N)::Tiling, i, j) = in_diamond(N, i, j) @@ -145,7 +175,32 @@ function diamond!(t, t′, N) return t end -function diamond(N) +""" + diamond(N::Int) -> Tiling{Matrix{AztecDiamonds.Edge}} + +Generates a uniformally random order N diamond tiling. + +```jldoctest +julia> using Random; Random.seed!(1); + +julia> diamond(4) +4-order Tiling{Matrix{AztecDiamonds.Edge}} + 🬇🬋🬋🬃 + 🬇🬋🬋🬃🬇🬋🬋🬃 + 🬦🬓🬦🬓🬦🬓🬦🬓🬇🬋🬋🬃 +🬦🬓🬉🬄🬉🬄🬉🬄🬉🬄🬇🬋🬋🬃🬦🬓 +🬉🬄🬦🬓🬦🬓🬇🬋🬋🬃🬦🬓🬦🬓🬉🬄 + 🬉🬄🬉🬄🬇🬋🬋🬃🬉🬄🬉🬄 + 🬇🬋🬋🬃🬇🬋🬋🬃 + 🬇🬋🬋🬃 +``` + +See [`ka_diamond`](@ref) for a version that can take advantage of GPU acceleration. +`ka_diamond(N, Array)` may also be faster for large N. + +Ref [`Tiling`](@ref) +""" +function diamond(N::Int) t, t′ = Tiling(0; sizehint = N), Tiling(0; sizehint = N) return diamond!(t, t′, N) end diff --git a/src/ka.jl b/src/ka.jl index 1d0c2fa..e1a0da8 100644 --- a/src/ka.jl +++ b/src/ka.jl @@ -113,7 +113,15 @@ function ka_diamond!(t, t′, N; backend) return t end -function ka_diamond(N, ArrayT) +""" + ka_diamond(N::Int, ArrayT::Type{<:AbstractArray}) -> Tiling{ArrayT{Edge}} + +Generate a uniformly random diamond tiling just like [`diamond`](@ref), but using `KernelAbstractions.jl` +to be able to take advantage of (GPU) parallelism. `ArrayT` can either be `Array` or any GPU array type. + +Ref [`Tiling`](@ref) +""" +function ka_diamond(N::Int, ArrayT::Type{<:AbstractArray}) mem = ntuple(_ -> fill!(ArrayT{Edge}(undef, 2N, 2N), NONE), 2) t, t′ = map(x -> Tiling(0, OffsetMatrix(x, inds(N))), mem) return ka_diamond!(t, t′, N; backend = KernelAbstractions.get_backend(mem[1])) diff --git a/src/show.jl b/src/show.jl index 8f28add..c11932f 100644 --- a/src/show.jl +++ b/src/show.jl @@ -70,7 +70,7 @@ function Base.show(io::IO, ::MIME"text/plain", t::Tiling) elseif get(t, (i, j - 1), NONE) == RIGHT color = !isdotted ? :yellow : :blue printstyled(io, "🬋🬃"; color) - else + elseif j < 0 || in_diamond(N, i, j) # don't produce trailing spaces print(io, " ") end end diff --git a/test/show.jl b/test/show.jl index b47b5b9..67e7cd2 100644 --- a/test/show.jl +++ b/test/show.jl @@ -19,7 +19,7 @@ end N = 20 D = diamond(N) r = repr(MIME("text/plain"), D) - @test length(r) > 2(2N)^2 + @test length(r) == 2537 r_color = repr(MIME("text/plain"), D; context = :color => true) @test length(r_color) == length(r) + 10length(AztecDiamonds.faces(D)) @@ -46,17 +46,18 @@ end t[2, -1] = RIGHT t[2, 0] = RIGHT + # TODO: should expected = replace( """ 4-order $Tiling{Matrix{AztecDiamonds.Edge}} - 🬦🬓 \\ - UU \\ - 🬉🬄 \\ + 🬦🬓 \\ + UU \\ + 🬉🬄 \\ 🬇🬋UR 🬦🬓🬦🬓 \\ 🬉🬄🬇🬋NRRU🬋🬃 \\ - 🬇🬋RR🬋🬃 \\ - \\ - """, + 🬇🬋RR🬋🬃 \\ + \\ + """, "\\" => "" ) @test repr(MIME("text/plain"), t) == expected