Skip to content

Commit

Permalink
Fix datatype documentation (#1108)
Browse files Browse the repository at this point in the history
* Fix datatype documentations

* Add additional resources page

* Actually add resources.md
  • Loading branch information
mkitti authored Sep 6, 2023
1 parent 1f65f4d commit 6afbafb
Show file tree
Hide file tree
Showing 5 changed files with 77 additions and 27 deletions.
64 changes: 38 additions & 26 deletions docs/Manifest.toml
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# This file is machine-generated - editing it directly is not advised

julia_version = "1.9.0"
julia_version = "1.9.3"
manifest_format = "2.0"
project_hash = "b82c9c318ab556c33f5a67f1e314caaa8d7804ae"
project_hash = "2d4ae38483c05e04907e6c281e51323f031e5f7e"

[[deps.ANSIColoredPrinters]]
git-tree-sha1 = "574baf8110975760d391c710b6341da1afa48d8c"
Expand Down Expand Up @@ -62,9 +62,9 @@ version = "0.7.2"

[[deps.Compat]]
deps = ["UUIDs"]
git-tree-sha1 = "4e88377ae7ebeaf29a047aa1ee40826e0b708a5d"
git-tree-sha1 = "e460f044ca8b99be31d35fe54fc33a5c33dd8ed7"
uuid = "34da2185-b29b-5c13-b0c7-acf172513d20"
version = "4.7.0"
version = "4.9.0"

[deps.Compat.extensions]
CompatLinearAlgebraExt = "LinearAlgebra"
Expand All @@ -76,7 +76,7 @@ version = "4.7.0"
[[deps.CompilerSupportLibraries_jll]]
deps = ["Artifacts", "Libdl"]
uuid = "e66e0078-7015-5450-92f7-15fbd957f2ae"
version = "1.0.2+0"
version = "1.0.5+0"

[[deps.Dates]]
deps = ["Printf"]
Expand Down Expand Up @@ -112,6 +112,12 @@ version = "1.6.0"
[[deps.FileWatching]]
uuid = "7b1f6079-737a-58dc-b8bc-7a2ca5c1b5ee"

[[deps.H5Zbitshuffle]]
deps = ["HDF5", "bitshuffle_jll"]
path = "../filters/H5Zbitshuffle"
uuid = "51b4e782-877f-4ccf-958a-27bf628210da"
version = "0.1.1"

[[deps.H5Zblosc]]
deps = ["Blosc", "HDF5"]
path = "../filters/H5Zblosc"
Expand Down Expand Up @@ -148,9 +154,9 @@ weakdeps = ["MPI"]

[[deps.HDF5_jll]]
deps = ["Artifacts", "CompilerSupportLibraries_jll", "JLLWrappers", "LLVMOpenMP_jll", "LazyArtifacts", "LibCURL_jll", "Libdl", "MPICH_jll", "MPIPreferences", "MPItrampoline_jll", "MicrosoftMPI_jll", "OpenMPI_jll", "OpenSSL_jll", "TOML", "Zlib_jll", "libaec_jll"]
git-tree-sha1 = "3b20c3ce9c14aedd0adca2bc8c882927844bd53d"
git-tree-sha1 = "10c72358aaaa5cd6bc7cc39b95e6eadf92f5a336"
uuid = "0234f1f7-429e-5d53-9886-15a909be8d59"
version = "1.14.0+0"
version = "1.14.2+0"

[[deps.IOCapture]]
deps = ["Logging", "Random"]
Expand All @@ -163,10 +169,10 @@ deps = ["Markdown"]
uuid = "b77e0a4c-d291-57a0-90e8-8db25a27a240"

[[deps.JLLWrappers]]
deps = ["Preferences"]
git-tree-sha1 = "abc9885a7ca2052a736a600f7fa66209f96506e1"
deps = ["Artifacts", "Preferences"]
git-tree-sha1 = "7e5d6779a1e09a36db2a7b6cff50942a0a7d0fca"
uuid = "692b3bcd-3c85-4b1f-b108-f13ce0eb3210"
version = "1.4.1"
version = "1.5.0"

[[deps.JSON]]
deps = ["Dates", "Mmap", "Parsers", "Unicode"]
Expand Down Expand Up @@ -210,16 +216,16 @@ uuid = "8f399da3-3557-5675-b5ff-fb832c97cbdb"
uuid = "56ddb016-857b-54e1-b83d-db4d58db5568"

[[deps.Lz4_jll]]
deps = ["Artifacts", "JLLWrappers", "Libdl", "Pkg"]
git-tree-sha1 = "5d494bc6e85c4c9b626ee0cab05daa4085486ab1"
deps = ["Artifacts", "JLLWrappers", "Libdl"]
git-tree-sha1 = "6c26c5e8a4203d43b5497be3ec5d4e0c3cde240a"
uuid = "5ced341a-0733-55b8-9ab6-a4889d929147"
version = "1.9.3+0"
version = "1.9.4+0"

[[deps.MPI]]
deps = ["Distributed", "DocStringExtensions", "Libdl", "MPICH_jll", "MPIPreferences", "MPItrampoline_jll", "MicrosoftMPI_jll", "OpenMPI_jll", "PkgVersion", "PrecompileTools", "Requires", "Serialization", "Sockets"]
git-tree-sha1 = "98fc280a56d3b5cc218435f82df60e05771fefa6"
git-tree-sha1 = "32cafbe56c7f0b7160a1a6c492773af66c0b722f"
uuid = "da04e1cc-30fd-572f-bb4f-1f8673147195"
version = "0.20.12"
version = "0.20.14"

[deps.MPI.extensions]
AMDGPUExt = "AMDGPU"
Expand All @@ -237,9 +243,9 @@ version = "4.1.2+0"

[[deps.MPIPreferences]]
deps = ["Libdl", "Preferences"]
git-tree-sha1 = "d86a788b336e8ae96429c0c42740ccd60ac0dfcc"
git-tree-sha1 = "781916a2ebf2841467cda03b6f1af43e23839d85"
uuid = "3da0fdf6-3ccc-4f1b-acd9-58baa6c99267"
version = "0.1.8"
version = "0.1.9"

[[deps.MPItrampoline_jll]]
deps = ["Artifacts", "CompilerSupportLibraries_jll", "JLLWrappers", "LazyArtifacts", "Libdl", "MPIPreferences", "TOML"]
Expand Down Expand Up @@ -281,32 +287,32 @@ version = "4.1.5+0"

[[deps.OpenSSL_jll]]
deps = ["Artifacts", "JLLWrappers", "Libdl"]
git-tree-sha1 = "cae3153c7f6cf3f069a853883fd1919a6e5bab5b"
git-tree-sha1 = "e78db7bd5c26fc5a6911b50a47ee302219157ea8"
uuid = "458c3c95-2e84-50aa-8efc-19380b2a3a95"
version = "3.0.9+0"
version = "3.0.10+0"

[[deps.Parsers]]
deps = ["Dates", "PrecompileTools", "UUIDs"]
git-tree-sha1 = "4b2e829ee66d4218e0cef22c0a64ee37cf258c29"
git-tree-sha1 = "716e24b21538abc91f6205fd1d8363f39b442851"
uuid = "69de0a69-1ddd-5017-9359-2bf0b02dc9f0"
version = "2.7.1"
version = "2.7.2"

[[deps.Pkg]]
deps = ["Artifacts", "Dates", "Downloads", "FileWatching", "LibGit2", "Libdl", "Logging", "Markdown", "Printf", "REPL", "Random", "SHA", "Serialization", "TOML", "Tar", "UUIDs", "p7zip_jll"]
uuid = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
version = "1.9.0"
version = "1.9.2"

[[deps.PkgVersion]]
deps = ["Pkg"]
git-tree-sha1 = "f6cf8e7944e50901594838951729a1861e668cb8"
git-tree-sha1 = "f9501cc0430a26bc3d156ae1b5b0c1b47af4d6da"
uuid = "eebad327-c553-4316-9ea0-9fa01ccd7688"
version = "0.3.2"
version = "0.3.3"

[[deps.PrecompileTools]]
deps = ["Preferences"]
git-tree-sha1 = "9673d39decc5feece56ef3940e5dafba15ba0f81"
git-tree-sha1 = "03b4c25b43cb84cee5c90aa9b5ea0a78fd848d2f"
uuid = "aea7be01-6a6a-4083-8856-8a6e6704d82a"
version = "1.1.2"
version = "1.2.0"

[[deps.Preferences]]
deps = ["TOML"]
Expand Down Expand Up @@ -380,6 +386,12 @@ git-tree-sha1 = "49ce682769cd5de6c72dcf1b94ed7790cd08974c"
uuid = "3161d3a3-bdf6-5164-811a-617609db77b4"
version = "1.5.5+0"

[[deps.bitshuffle_jll]]
deps = ["Artifacts", "JLLWrappers", "Libdl", "Lz4_jll", "Pkg", "Zstd_jll"]
git-tree-sha1 = "fc80beaec46263a31471fe2f14f5a0d9bea05c4c"
uuid = "228fe19c-1b83-5282-a626-13744502a320"
version = "0.4.2+0"

[[deps.libaec_jll]]
deps = ["Artifacts", "JLLWrappers", "Libdl"]
git-tree-sha1 = "eddd19a8dea6b139ea97bdc8a0e2667d4b661720"
Expand Down
1 change: 1 addition & 0 deletions docs/Project.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
[deps]
DelimitedFiles = "8bb1440f-4735-579b-a4ab-409b98df4dab"
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
H5Zbitshuffle = "51b4e782-877f-4ccf-958a-27bf628210da"
H5Zblosc = "c8ec2601-a99c-407f-b158-e79c03c2f5f7"
H5Zbzip2 = "094576f2-1e46-4c84-8e32-c46c042eaaa2"
H5Zlz4 = "eb20ec05-5464-47b5-ba41-098e3c1068a3"
Expand Down
1 change: 1 addition & 0 deletions docs/make.jl
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@ makedocs(;
],
"mpi.md",
"Low-level library bindings" => "api_bindings.md",
"Additional Resources" => "resources.md",
]
)

Expand Down
22 changes: 21 additions & 1 deletion docs/src/index.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
```@meta
CurrentModule = HDF5
DocTestSetup = quote
using HDF5
end
```

# HDF5.jl
Expand Down Expand Up @@ -334,12 +337,29 @@ mtx = HDF5.readmmap(mtx_dset) # succeeds immediately

## Supported data types

`HDF5.jl` knows how to store values of the following types: signed and unsigned integers of 8, 16, 32, and 64 bits, `Float32`, `Float64`; `Complex` versions of these numeric types; `Array`s of these numeric types (including complex versions); `ASCIIString` and `UTF8String`; and `Array`s of these two string types.
`HDF5.jl` knows how to store values of the following types: signed and unsigned integers of 8, 16, 32, and 64 bits, `Float32`, `Float64`; `Complex` versions of these numeric types; `Array`s of these numeric types (including complex versions); `String`; and `Array`s of `String`.
`Array`s of strings are supported using HDF5's variable-length-strings facility.
By default `Complex` numbers are stored as compound types with `r` and `i` fields following the `h5py` convention.
When reading data, compound types with matching field names will be loaded as the corresponding `Complex` Julia type.
These field names are configurable with the `HDF5.set_complex_field_names(real::AbstractString, imag::AbstractString)` function and complex support can be completely enabled/disabled with `HDF5.enable/disable_complex_support()`.

As of HDF5.jl version 0.16.13, support was added to map Julia structs to compound HDF5 datatypes.

```jldoctest
julia> struct Point3{T}
x::T
y::T
z::T
end
julia> datatype(Point3{Float64})
HDF5.Datatype: H5T_COMPOUND {
H5T_IEEE_F64LE "x" : 0;
H5T_IEEE_F64LE "y" : 8;
H5T_IEEE_F64LE "z" : 16;
}
```

For `Array`s, note that the array dimensionality is preserved, including 0-length
dimensions:

Expand Down
16 changes: 16 additions & 0 deletions docs/src/resources.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# Additional Resources

## JuliaCon 2023 Presentation

During JuliaCon 2023, Mark Kittisopikul and Simon Byrne presented "HDF5.jl: Hierarchial Data Storage for Julia" with assistance from Mustafa Mohamad. A recording of the talk is available on YouTube below.

```@raw html
<iframe width="560" height="315" src="https://www.youtube.com/embed/YNDDB8uR26Q?si=V5ArUwOkG6s7VesL" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
```

The slides for the JuliaCon 2023 presentation are also available [download](https://github.com/JuliaIO/HDF5.jl/blob/master/docs/juliacon_2023/juliacon_2023_presentation.pdf).

## Community Help Channels

* The Julia Discourse forum has a [hdf5 tag](https://discourse.julialang.org/tag/hdf5)
* The [Julia Community](https://julialang.org/community/) also has a number of chat options. See the [#data](https://julialang.slack.com/archives/C674VR0HH) or [#helpdesk](https://julialang.slack.com/archives/C6A044SQH) chat channels.

4 comments on commit 6afbafb

@mkitti
Copy link
Member Author

@mkitti mkitti commented on 6afbafb Sep 6, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@JuliaRegistrator
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Registration pull request created: JuliaRegistries/General/90906

After the above pull request is merged, it is recommended that a tag is created on this repository for the registered package version.

This will be done automatically if the Julia TagBot GitHub Action is installed, or can be done manually through the github interface, or via:

git tag -a v0.17.0 -m "<description of version>" 6afbafb22c4d9b462a89c23ae4d524f50889a39e
git push origin v0.17.0

@mkitti
Copy link
Member Author

@mkitti mkitti commented on 6afbafb Sep 7, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@JuliaRegistrator register subdir=filters/H5Zbitshuffle
@JuliaRegistrator register subdir=filters/H5Zblosc
@JuliaRegistrator register subdir=filters/H5Zbzip2
@JuliaRegistrator register subdir=filters/H5Zlz4
@JuliaRegistrator register subdir=filters/H5Zzstd

@JuliaRegistrator
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Error while trying to register: "Tag with name H5Zbitshuffle-v0.1.1 already exists and points to a different commit"

Please sign in to comment.