summaryrefslogtreecommitdiffstats
path: root/_intro_par_cont_hyperslab.html
blob: ebf02336ae22eb8db7530788579f9b4c0d9f1563 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.9.1"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>HDF5: Writing by Contiguous Hyperslab</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
  $(document).ready(function() { init_search(); });
/* @license-end */
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="hdf5doxy.css" rel="stylesheet" type="text/css">
<!-- <link href="hdf5doxy.css" rel="stylesheet" type="text/css"/>
 -->
<script type="text/javascript" src="hdf5_navtree_hacks.js"></script>
</head>
<body>
<div style="background:#FFDDDD;font-size:120%;text-align:center;margin:0;padding:5px">Please, help us to better serve our user community by answering the following short survey:  <a href="https://www.hdfgroup.org/website-survey/">https://www.hdfgroup.org/website-survey/</a></div>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="HDFG-logo.png"/></td>
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname"><a href="https://www.hdfgroup.org">HDF5</a>
   &#160;<span id="projectnumber">1.15.0.f39b228</span>
   </div>
   <div id="projectbrief">API Reference</div>
  </td>
   <td>        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.svg"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a>
          </span>
        </div>
</td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.1 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search','.html');
/* @license-end */
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(document).ready(function(){initNavTree('_intro_par_cont_hyperslab.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="PageDoc"><div class="header">
  <div class="headertitle">
<div class="title">Writing by Contiguous Hyperslab </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>Navigate back: <a class="el" href="index.html">Main</a> / <a class="el" href="_getting_started.html">Getting Started with HDF5</a> / <a class="el" href="_intro_par_h_d_f5.html">A Brief Introduction to Parallel HDF5</a> </p><hr  />
<p>This example shows how to write a contiguous buffer in memory to a contiguous hyperslab in a file. In this case, each parallel process writes a contiguous hyperslab to the file.</p>
<p>In the C example (figure a), each hyperslab in memory consists of an equal number of consecutive rows. In the FORTRAN 90 example (figure b), each hyperslab in memory consists of an equal number of consecutive columns. This reflects the difference in the storage order for C and FORTRAN 90. </p><table class="doxtable">
<tr>
<th><b>Figure a</b> C Example </th><th><b>Figure b</b> Fortran Example </th></tr>
<tr>
<td><div class="image">
<img src="pcont_hy_figa.gif" alt=""/>
</div>
  </td><td><div class="image">
<img src="pcont_hy_figb.gif" alt=""/>
</div>
   </td></tr>
</table>
<h1><a class="anchor" id="secIntroParContHyperslabC"></a>
Writing a Contiguous Hyperslab in C</h1>
<p>In this example, you have a dataset of 8 (rows) x 5 (columns) and each process writes an equal number of rows to the dataset. The dataset hyperslab is defined as follows: </p><div class="fragment"><div class="line">count [0] = dimsf [0] / number_processes</div>
<div class="line">count [1] = dimsf [1]</div>
</div><!-- fragment --><p> where, </p><div class="fragment"><div class="line">dimsf [0] is the number of rows in the dataset</div>
<div class="line">dimsf [1] is the number of columns in the dataset</div>
</div><!-- fragment --><p> The offset for the hyperslab is different for each process: </p><div class="fragment"><div class="line">offset [0] = k * count[0]</div>
<div class="line">offset [1] = 0</div>
</div><!-- fragment --><p> where, </p><div class="fragment"><div class="line"><span class="stringliteral">&quot;k&quot;</span> is the process <span class="keywordtype">id</span> number</div>
<div class="line">count [0] is the number of rows written in each hyperslab</div>
<div class="line">offset [1] = 0 indicates to start at the beginning of the row</div>
</div><!-- fragment --><p>The number of processes that you could use would be 1, 2, 4, or 8. The number of rows that would be written by each slab is as follows: </p><table class="doxtable">
<tr>
<th><b>Processes</b> </th><th><b>Size of count<a href="\# of rows">0</a> </b> </th></tr>
<tr>
<td>1</td><td>8 </td></tr>
<tr>
<td>2</td><td>4 </td></tr>
<tr>
<td>4</td><td>2 </td></tr>
<tr>
<td>8</td><td>1  </td></tr>
</table>
<p>If using 4 processes, then process 1 would look like: </p><table class="doxtable">
<tr>
<td><div class="image">
<img src="pcont_hy_figc.gif" alt=""/>
</div>
   </td></tr>
</table>
<p>The code would look like the following: </p><div class="fragment"><div class="line">71      <span class="comment">/*</span></div>
<div class="line"><span class="comment">72       * Each process defines dataset in memory and writes it to the hyperslab</span></div>
<div class="line"><span class="comment">73       * in the file.</span></div>
<div class="line"><span class="comment">74       */</span></div>
<div class="line">75      count[0] = dimsf[0]/mpi_size;</div>
<div class="line">76      count[1] = dimsf[1];</div>
<div class="line">77      offset[0] = mpi_rank * count[0];</div>
<div class="line">78      offset[1] = 0;</div>
<div class="line">79      memspace = <a class="code" href="group___h5_s.html#ga8e35eea5738b4805856eac7d595254ae">H5Screate_simple</a>(RANK, count, NULL);</div>
<div class="line">80</div>
<div class="line">81      <span class="comment">/*</span></div>
<div class="line"><span class="comment">82       * Select hyperslab in the file.</span></div>
<div class="line"><span class="comment">83       */</span></div>
<div class="line">84      filespace = <a class="code" href="group___h5_d.html#gad42a46be153d895d8c28a11ebf5a0d0a">H5Dget_space</a>(dset_id);</div>
<div class="line">85      <a class="code" href="group___h5_s.html#ga6adfdf1b95dc108a65bf66e97d38536d">H5Sselect_hyperslab</a>(filespace, <a class="code" href="_h5_spublic_8h.html#a10093bab27cc5720efdab3186993da0fab90faf3dc59ecf6f28197ef471141550">H5S_SELECT_SET</a>, offset, NULL, count, NULL);</div>
<div class="ttc" id="a_h5_spublic_8h_html_a10093bab27cc5720efdab3186993da0fab90faf3dc59ecf6f28197ef471141550"><div class="ttname"><a href="_h5_spublic_8h.html#a10093bab27cc5720efdab3186993da0fab90faf3dc59ecf6f28197ef471141550">H5S_SELECT_SET</a></div><div class="ttdeci">@ H5S_SELECT_SET</div><div class="ttdef"><b>Definition:</b> H5Spublic.h:87</div></div>
<div class="ttc" id="agroup___h5_d_html_gad42a46be153d895d8c28a11ebf5a0d0a"><div class="ttname"><a href="group___h5_d.html#gad42a46be153d895d8c28a11ebf5a0d0a">H5Dget_space</a></div><div class="ttdeci">hid_t H5Dget_space(hid_t dset_id)</div><div class="ttdoc">Returns an identifier for a copy of the dataspace for a dataset.</div></div>
<div class="ttc" id="agroup___h5_s_html_ga6adfdf1b95dc108a65bf66e97d38536d"><div class="ttname"><a href="group___h5_s.html#ga6adfdf1b95dc108a65bf66e97d38536d">H5Sselect_hyperslab</a></div><div class="ttdeci">herr_t H5Sselect_hyperslab(hid_t space_id, H5S_seloper_t op, const hsize_t start[], const hsize_t stride[], const hsize_t count[], const hsize_t block[])</div><div class="ttdoc">Selects a hyperslab region to add to the current selected region.</div></div>
<div class="ttc" id="agroup___h5_s_html_ga8e35eea5738b4805856eac7d595254ae"><div class="ttname"><a href="group___h5_s.html#ga8e35eea5738b4805856eac7d595254ae">H5Screate_simple</a></div><div class="ttdeci">hid_t H5Screate_simple(int rank, const hsize_t dims[], const hsize_t maxdims[])</div><div class="ttdoc">Creates a new simple dataspace and opens it for access.</div></div>
</div><!-- fragment --><p>Below is the example program: </p><table class="doxtable">
<tr>
<td><a href="https://github.com/HDFGroup/hdf5-examples/blob/master/C/H5Parallel/ph5_hyperslab_by_row.c">hyperslab_by_row.c</a>   </td></tr>
</table>
<p>If using this example with 4 processes, then, </p><ul>
<li>Process 0 writes "10"s to the file. </li>
<li>Process 1 writes "11"s. </li>
<li>Process 2 writes "12"s. </li>
<li>Process 3 writes "13"s.</li>
</ul>
<p>The following is the output from h5dump for the HDF5 file created by this example using 4 processes: </p><div class="fragment"><div class="line">HDF5 <span class="stringliteral">&quot;SDS_row.h5&quot;</span> {</div>
<div class="line">GROUP <span class="stringliteral">&quot;/&quot;</span> {</div>
<div class="line">   DATASET <span class="stringliteral">&quot;IntArray&quot;</span> {</div>
<div class="line">      DATATYPE  <a class="code" href="group___p_d_t_s_t_d.html#ga37e8a6be7ee64587c2a282b965019bb8">H5T_STD_I32BE</a>  </div>
<div class="line">      DATASPACE  SIMPLE { ( 8, 5 ) / ( 8, 5 ) } </div>
<div class="line">      DATA {</div>
<div class="line">         10, 10, 10, 10, 10,</div>
<div class="line">         10, 10, 10, 10, 10,</div>
<div class="line">         11, 11, 11, 11, 11,</div>
<div class="line">         11, 11, 11, 11, 11,</div>
<div class="line">         12, 12, 12, 12, 12,</div>
<div class="line">         12, 12, 12, 12, 12,</div>
<div class="line">         13, 13, 13, 13, 13,</div>
<div class="line">         13, 13, 13, 13, 13</div>
<div class="line">      } </div>
<div class="line">   } </div>
<div class="line">} </div>
<div class="line">} </div>
<div class="ttc" id="agroup___p_d_t_s_t_d_html_ga37e8a6be7ee64587c2a282b965019bb8"><div class="ttname"><a href="group___p_d_t_s_t_d.html#ga37e8a6be7ee64587c2a282b965019bb8">H5T_STD_I32BE</a></div><div class="ttdeci">#define H5T_STD_I32BE</div><div class="ttdef"><b>Definition:</b> H5Tpublic.h:305</div></div>
</div><!-- fragment --><h1><a class="anchor" id="secIntroParContHyperslabFort"></a>
Writing a Contiguous Hyperslab in Fortran</h1>
<p>In this example you have a dataset of 5 (rows) x 8 (columns). Since a contiguous hyperslab in Fortran 90 consists of consecutive columns, each process will be writing an equal number of columns to the dataset.</p>
<p>You would define the size of the hyperslab to write to the dataset as follows: </p><div class="fragment"><div class="line">count(1) = dimsf(1)</div>
<div class="line">count(2) = dimsf(2) / number_of_processes</div>
</div><!-- fragment --><p>where, </p><div class="fragment"><div class="line">dimsf(1) is the number of rows in the dataset</div>
<div class="line">dimsf(2) is the number of columns</div>
</div><!-- fragment --><p>The offset for the hyperslab dimension would be different for each process: </p><div class="fragment"><div class="line">offset (1) = 0</div>
<div class="line">offset (2) = k * count (2)</div>
</div><!-- fragment --><p>where, </p><div class="fragment"><div class="line">offset (1) = 0 indicates to start at the beginning of the column</div>
<div class="line"><span class="stringliteral">&quot;k&quot;</span> is the process <span class="keywordtype">id</span> number</div>
<div class="line"><span class="stringliteral">&quot;count(2) is the number of columns to be written by each hyperslab</span></div>
</div><!-- fragment --><p>The number of processes that could be used in this example are 1, 2, 4, or 8. The number of columns that could be written by each slab is as follows: </p><table class="doxtable">
<tr>
<th><b>Processes</b> </th><th><b>Size of count (2)(# of columns) </b> </th></tr>
<tr>
<td>1</td><td>8 </td></tr>
<tr>
<td>2</td><td>4 </td></tr>
<tr>
<td>4</td><td>2 </td></tr>
<tr>
<td>8</td><td>1  </td></tr>
</table>
<p>If using 4 processes, the offset and count parameters for Process 1 would look like: </p><table class="doxtable">
<tr>
<td><div class="image">
<img src="pcont_hy_figd.gif" alt=""/>
</div>
   </td></tr>
</table>
<p>The code would look like the following: </p><div class="fragment"><div class="line">69       ! Each process defines dataset in memory and writes it to the hyperslab</div>
<div class="line">70       ! in the file.</div>
<div class="line">71       !</div>
<div class="line">72       count(1) = dimsf(1)</div>
<div class="line">73       count(2) = dimsf(2)/mpi_size</div>
<div class="line">74       offset(1) = 0</div>
<div class="line">75       offset(2) = mpi_rank * count(2)</div>
<div class="line">76       CALL <a class="code" href="group___f_h5_s.html#ga54083c84fd4be392ac770cf223cd6cf4">h5screate_simple_f</a>(rank, count, memspace, error)</div>
<div class="line">77       !</div>
<div class="line">78       ! Select hyperslab in the file.</div>
<div class="line">79       !</div>
<div class="line">80       CALL <a class="code" href="group___f_h5_d.html#gafb8a6067c9e7ef80ee48c0054e584ad7">h5dget_space_f</a>(dset_id, filespace, error)</div>
<div class="line">81       CALL <a class="code" href="group___f_h5_s.html#ga82aeb8a0da64f827e8a852eaab701ff9">h5sselect_hyperslab_f</a> (filespace, H5S_SELECT_SET_F, offset, count, error)</div>
<div class="ttc" id="agroup___f_h5_d_html_gafb8a6067c9e7ef80ee48c0054e584ad7"><div class="ttname"><a href="group___f_h5_d.html#gafb8a6067c9e7ef80ee48c0054e584ad7">h5d::h5dget_space_f</a></div><div class="ttdeci">subroutine h5dget_space_f(dataset_id, dataspace_id, hdferr)</div><div class="ttdoc">Returns an identifier for a copy of the dataspace for a dataset.</div><div class="ttdef"><b>Definition:</b> H5Dff.F90:1340</div></div>
<div class="ttc" id="agroup___f_h5_s_html_ga54083c84fd4be392ac770cf223cd6cf4"><div class="ttname"><a href="group___f_h5_s.html#ga54083c84fd4be392ac770cf223cd6cf4">h5s::h5screate_simple_f</a></div><div class="ttdeci">subroutine h5screate_simple_f(rank, dims, space_id, hdferr, maxdims)</div><div class="ttdoc">Creates a new simple data space and opens it for access.</div><div class="ttdef"><b>Definition:</b> H5Sff.F90:59</div></div>
<div class="ttc" id="agroup___f_h5_s_html_ga82aeb8a0da64f827e8a852eaab701ff9"><div class="ttname"><a href="group___f_h5_s.html#ga82aeb8a0da64f827e8a852eaab701ff9">h5s::h5sselect_hyperslab_f</a></div><div class="ttdeci">subroutine h5sselect_hyperslab_f(space_id, OPERATOR, start, count, hdferr, stride, BLOCK)</div><div class="ttdoc">Selects a hyperslab region to add to the current selected region.</div><div class="ttdef"><b>Definition:</b> H5Sff.F90:906</div></div>
</div><!-- fragment --><p>Below is the F90 example program which illustrates how to write contiguous hyperslabs by column in Parallel HDF5: </p><table class="doxtable">
<tr>
<td><a href="https://github.com/HDFGroup/hdf5-examples/blob/master/Fortran/H5Parallel/ph5_f90_hyperslab_by_col.F90">hyperslab_by_col.F90</a>   </td></tr>
</table>
<p>If you run this program with 4 processes and look at the output with h5dump you will notice that the output is much like the output shown above for the C example. This is because h5dump is written in C. The data would be displayed in columns if it was printed using Fortran 90 code.</p>
<hr  />
<p> Navigate back: <a class="el" href="index.html">Main</a> / <a class="el" href="_getting_started.html">Getting Started with HDF5</a> / <a class="el" href="_intro_par_h_d_f5.html">A Brief Introduction to Parallel HDF5</a> </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.9.1 </li>
  </ul>
</div>
</body>
</html>