Skip to content

Commit

Permalink
Add row/column-major order documentation (#805)
Browse files Browse the repository at this point in the history
* Improve doc on row- and column-major order

* Apply suggestions from code review

Co-authored-by: Mustafa M <[email protected]>

* Update link to new page

* Apply suggestions from code review

Co-authored-by: Mustafa M <[email protected]>

Co-authored-by: Mustafa M <[email protected]>
  • Loading branch information
qin-yu and musm authored Jan 18, 2021
1 parent cb1dcd8 commit c6e57b4
Showing 1 changed file with 10 additions and 8 deletions.
18 changes: 10 additions & 8 deletions docs/src/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down

0 comments on commit c6e57b4

Please sign in to comment.