From c6e57b4602b495ba74772313d5fa0d036478ade0 Mon Sep 17 00:00:00 2001 From: Qin Yu Date: Mon, 18 Jan 2021 15:19:23 +0100 Subject: [PATCH] Add row/column-major order documentation (#805) * Improve doc on row- and column-major order * Apply suggestions from code review Co-authored-by: Mustafa M * Update link to new page * Apply suggestions from code review Co-authored-by: Mustafa M Co-authored-by: Mustafa M --- docs/src/index.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/src/index.md b/docs/src/index.md index f976dbab2..d772042c1 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -584,14 +584,16 @@ See also the [HDF5 docs](https://portal.hdfgroup.org/display/HDF5/H5P_SET_DXPL_M A few more examples are available in [`test/mpio.jl`](https://github.com/JuliaIO/HDF5.jl/blob/master/test/mpio.jl). -## Details - -Julia, like Fortran and MATLAB, stores arrays in column-major order. -HDF5 uses C's row-major order, and consequently every array's -dimensions are inverted compared to what you see with tools like -h5dump. This is the same convention as in Fortran and MATLAB's HDF5 -interfaces. The advantage is that no data rearrangement takes place -when reading or writing. +## Language interoperability with row- and column-major order arrays + +There are two main methods for storing multidimensional arrays in linear storage [row-major order and column-major order](https://en.wikipedia.org/wiki/Row-_and_column-major_order). Julia, like Fortran and MATLAB, stores multidimensional arrays in column-major order, while other languages, including C and Python (NumPy), use row-major order. Therefore when reading an array in Julia from row-major order language the dimensions may be inverted. + +To read a multidimensional array into the original shape from an HDF5 file written by Python (`numpy` and `h5py`) or C/C++/Objective-C, simply reverse the dimensions. For example, one may add the following line after reading the dataset `dset`: +```julia +dset = permutedims(dset, reverse(1:ndims(dset))) +``` + +Note that some languages or libraries use both methods, so please check the datset's description for details. For example, NumPy arrays are row-major by default, but NumPy can use either row-major or column-major ordered arrays. ## Credits