forked from Parallel-NetCDF/PnetCDF
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathRELEASE_NOTES
2183 lines (1936 loc) · 116 KB
/
RELEASE_NOTES
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
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
=====================================
PnetCDF Release Notes
=====================================
-------------------------------------
Version _PNETCDF_VERSION_ (_PNETCDF_RELEASE_DATE_)
-------------------------------------
-------------------------------------
Version 1.11.2 (May 13, 2019)
-------------------------------------
* Bug fixes
+ When configure command-line option `--enable-netcdf4` is used, errors may
occur during the configure or make time. Thanks Bruno Pagani for reporting.
See bug fix in
[pull request #46](https://github.com/Parallel-NetCDF/PnetCDF/pull/46).
+ Fix configure date setting when environment variable `SOURCE_DATE_EPOCH`
is set.
* Clarifications
+ Limitation of supporting NetCDF-4 driver -- a list of APIs that are not
supported for NetCDF-4 files is given in `doc/README.NetCDF4.md`. Error
code `NC_ENOTSUPPORT` is returned when those APIs are called.
* Other updates:
+ Utility program `ncoffsets` is updated to skip printing the dimension names
if the number of dimensions of a variable is larger than 64.This predefined
constant can be changed a different number `N` by adding
`-DMAX_PRINT_NDIMS=N` to the compile command line.
+ Utility program `ncvalidator` is updated to be able to repair the file
header to fill in null-byte paddings in the space between the header size
and header extent.
+ Add a note to `doc/README.CRAY` about a compilation issue encountered on
Cori @ NERSC when module gcc/7.3.0 is loaded.
+ Change release date format from `Day Month, Year` to `Month Day, Year`.
* New test program
+ test/nc4/notsupport.c - Test if error code NC_ENOTSUPPORT is properly
returned when calling APIs for unsupported NetCDF-4 feature.
+ test/nc4/rtst_rec_vars.c - Test record variables for NetCDF-4 files.
+ test/nc4/tst_2_rec_dims.c - Test opening a NetCDF-4 file containing more
than one unlimited dimension on whether correct error can be returned.
+ test/nc4/tst_get_put_size.c - Test the amount of I/O so far for NetCDF-4
files.
+ test/testcases/tst_version.c - Check whether PnetCDF version string
returned from ncmpi_inq_libvers() matches the constant PNETCDF_VERSION
defined in header file pnetcdf.h.
-------------------------------------
Version 1.11.1 (April 12, 2019)
-------------------------------------
* New optimization
+ When inserting nonblocking requests into the PnetCDF internal pending
queues, the queues are now kept sorted (using an insert sort) into an
increasing order of variable starting file offsets. This can avoid the
quick sort when flushing the pending requests. See
[pull request #37](https://github.com/Parallel-NetCDF/PnetCDF/pull/37).
To avoid internal sorts completely, users are recommended to post
nonblocking requests in the increasing order of variable IDs and fixed-size
variables first followed by record variables.
* New Limitations
+ When building with NetCDF-4 feature enabled, using a NetCDF-4 library that
has already been built with PnetCDF enabled, i.e. `--enable-pnetcdf`, is not
supported. See [Issue #33](https://github.com/Parallel-NetCDF/PnetCDF/issues/33).
* Other updates:
+ Add a check whether the MPI library is built with shared-library support.
If not and `--enable-shared` is used, the configure process of PnetCDF will
fail.
+ In the NetCDF-4 driver, `nc4io_inq_var()` adds a NULL-argument check for
`no_fill` and `fill_value`. If both arguments are NULL, it skips the call
to `nc_inq_var_fill`.
+ File header extent area between end of header and first variable will be
padded with null bytes if PnetCDF is configured with option
`--enable-null-byte-header-padding`.
+ Add AC_PROG_CPP in configure.ac to check whether `-E` option is required by
the C preprocessor.
+ Add a check for whether `m4` utility is available, and abort the configure
if it is not.
* Bug fixes
+ Fix ncmpidiff when comparing dimension names of 2 variables between files
whose dimension define orders are different. See
[Issue #42](https://github.com/Parallel-NetCDF/PnetCDF/pull/42).
+ Fix error checking for programs in examples/C to ignore NC_ENOTENABLED
if PnetCDF was not built with `--enable-profiling`. Thanks to Bruno Pagani
and see [Issue #34](https://github.com/Parallel-NetCDF/PnetCDF/issues/34).
* New test program
+ test/burst_buffer/varn.c -- to test varn API when burst buffer driver is
used. The test includes cases when argument counts is NULL or some elements
in counts are NULL.
* Clarifications
+ Padding -- NetCDF classic file format specification states "Header padding
uses null (\x00) bytes. In data, padding uses variable's fill value."
PnetCDF implements the header padding specification but only enforces it
when the configure option `--enable-null-byte-header-padding` is set. Note
PnetCDF has not yet implemented the padding for data section.
-------------------------------------
Version 1.11.0 (December 19, 2018)
-------------------------------------
* New features
+ NetCDF-4 driver -- Accessing HDF5-based NetCDF-4 files is now supported.
PnetCDF can be built on top of NetCDF-4 library to let users to use PnetCDF
APIs to read and write a NetCDF-4 file. Users now can add NC_NETCDF4 flag
when calling ncmpi_create() to create NetCDF-4 files. For opening NetCDF-4
files, no additional flag is needed, as PnetCDF automatically detects the
file format and uses the HDF5 I/O driver underneath. This feature is
provided for convenience purpose. The parallel I/O performance to NetCDF-4
files is expected no difference from using NetCDF-4 library directly.
+ Per-file thread-safe capability is added. This feature can be enabled at
configure time by adding command-line option `--enable-thread-safe`. In
addition, option `--with-pthread` can be used to specify the install path
to the pthreads library. This feature currently only supports
one-thread-per-file I/O operations and the classic CDF-1, 2, and 5 files.
* New optimization
+ On some systems, e.g. Cori @NERSC, collective MPI-IO may perform poorly
when the I/O buffer is noncontiguous, compared to a contiguous one. To
avoid this, `ncmpi_wait()` and `ncmpi_wait_all()` now check whether the
buffer is noncontiguous and size is less than 16 MiB. If both are true, a
temporary contiguous buffer is allocated to copy the data over and used in
the MPI read or write calls. The size of the buffer can be adjusted through
a new hint `nc_ibuf_size`. See `New PnetCDF hint` below and
[PR #26](https://github.com/Parallel-NetCDF/PnetCDF/pull/26). Programs
developed to test this issue is available in
https://github.com/Parallel-NetCDF/E3SM-IO/tree/master/mpi_io_test
+ Burst buffer driver is updated to run varn APIs more efficiently. Previous
implementation breaks a single varn request into multiple vara requests,
which can be slow and require a large amount of meta data. It has changed
to consider each varn request a single entity. See
[PR #30](https://github.com/Parallel-NetCDF/PnetCDF/pull/30) and
[PR #31](https://github.com/Parallel-NetCDF/PnetCDF/pull/31).
* New Limitations
+ For creating new files, the NetCDF-4 driver in PnetCDF supports only the
classic model I/O operations. Advanced NetCDF-4 features, such as chunking,
compression, etc. are not supported in PnetCDF. This is due to the
unavailability of PnetCDF APIs for those operations.
+ The burst buffering driver does not support NetCDF-4 file formats.
+ Due to a bug in HDF5 1.10.2 that fails zero-length write requests to record
variables in the collective mode, PnetCDF is not able to support such
requests when NetCDF-4 feature is enabled. See discussion in
https://github.com/NCAR/ParallelIO/pull/1304
The bug fix has appeared in HDF5 1.10.4 release.
* Update configure options
+ Enable NetCDF-4 support.
- `--enable-netcdf4`: enables NetCDF4 format classic mode support
- `--with-netcdf4=/path/to/netcdf-4`: can be used to specify the path to
NetCDF-4 library installation
+ Enable multi-threading support.
- `--enable-thread-safe`: enable per-file thread-safe support
- `--with-pthread`: path to the pthread library installation
* New constants
+ none
* New APIs
+ C++ API `NcmpiFile::set_fill()` is added for setting and inquiring the
fill mode of an opened NetCDF file.
* API syntax changes
+ none
* API semantics updates
+ none
* New error code precedence
+ none
* Updated error strings
+ none
* New error code
+ none
* New PnetCDF hint
+ `nc_ibuf_size` -- to set the size of a temporal buffer to be allocated by
PnetCDF internally to pack noncontiguous user write buffers supplied to the
nonblocking requests into a contiguous space. Similarly for read case to
unpack the temporal buffer to user read buffers, if they are noncontiguous.
This affects both blocking and nonblocking APIs. On some systems, using
noncontiguous user buffers in MPI collective read/write functions performs
significantly worse than using contiguous buffers. Note if the size of
aggregated user buffers is larger than `nc_ibuf_size`, packing/unpacking
will be disabled to save memory footprint. The default value is 16 MiB.
* New run-time environment variables
+ none
* Build recipes
+ doc/README.NetCDF4.md is added to describe the usage of the new feature of
NetCDF-4 support.
* New/updated utility program
+ none
* Other updates:
+ The automatic file layout alignment for fixed-size variables is disabled.
This is because modern MPI-IO implementations have already aligned the file
access with the file lock boundaries and the automatic alignment can create
a file view with "holes" in between variables, which can adversely degrade
I/O performance. Users can still set hints `nc_header_align_size`,
`nc_var_align_size`, and `nc_record_align_size` to use customized alignment
sizes.
+ The internal data buffering mechanism used in the burst buffer driver is
removed. This mechanism caches the request data in memory until the
accumulated size is more than 8 MiB, so the write requests to burst buffers
can be aligned with 8 MiB boundaries. However, experiments on Cray DataWarp
show a negligible performance improvement unless the I/O request is small
and fragment. On the other hand, it can degrade performance for mid- and
large-sized requests. The burst buffer driver now writes directly to the
burst buffers for each user write request.
* Bug fixes
+ Fix bug of checking interleaved requests for scalar variables. See
[PR #27](https://github.com/Parallel-NetCDF/PnetCDF/pull/27).
+ When building PnetCDF using the IBM xlc compiler with -O optimization
option on Little Endian platforms, users may encounter errors related to
strict ANSI C aliasing rules. Thanks to Jim Edwards for reporting and Rafik
Zurob for providing the fix. See
[Issue #23](https://github.com/Parallel-NetCDF/PnetCDF/issues/23) and
[Pull Request #24](https://github.com/Parallel-NetCDF/PnetCDF/issues/24).
+ Shell ksh has a different way to redirect stdout and stderr from bash.
PnetCDF configure.ac and acinclude.m4 have been developed mainly on bash.
This bug can cause configure command to fail when using ksh. Thanks to
@poohRui for reporting the bug. See
[Issue #21](https://github.com/Parallel-NetCDF/PnetCDF/issues/21) and
[PR #22](https://github.com/Parallel-NetCDF/PnetCDF/pull/22).
However, running configure under ksh is still buggy. A GNU automake bug
report of hanging problem can be found in
https://lists.gnu.org/archive/html/bug-automake/2015-04/msg00000.html
PnetCDF users are recommended to run configure under other shells.
+ For put and get APIs when buftype is MPI_DATATYPE_NULL, bufcount is
ignored. This is not implemented correctly in blocking put and get APIs.
See bug fix committed on Aug. 25, 2018.
+ ncmpidiff -- when comparing two files that contain record variables but
no record has been written. See bug fix committed on Aug. 25, 2018.
+ ncmpidiff -- when comparing two scalar variables, error NC_EBADDIM may
mistakenly reported. See bug fix committed on Aug. 12, 2018.
+ When the MPI communicator used in ncmpi_create or ncmpi_open is freed by
the user after the call and before file is closed, programs would crash at
ncmpi_close with MPI error of "Invalid communicator". The fix moves the
duplication of MPI communicator to the place before calling driver create
and open subroutines. See bug fix committed on Jul 21, 2018.
* New example programs
+ examples/C/time_var.c and examples/F77/time_var.f - show how to define,
write, and read record variables.
+ examples/C/pthread.c - demonstrates the one-file-per-thread I/O example.
When running on some parallel machines, users may need to set certain
environment variable to enable MPI multi-threading support, for example on
Cori @NERSC with command
```
export MPICH_MAX_THREAD_SAFETY=multiple
```
+ examples/C/transpose2D.c - a 2D version of examples/C/transpose.c
* New programs for I/O benchmarks
+ none
* New test program
+ test/F90/test_fill.f90 - another test for bug fix r3730.
+ test/testcases/error_precedence.m4 - tests the error code reporting
precedence
+ test/nc4/tst_zero_req.c - tests a HDF5 1.10.2 bug that causes test program
to hang when writing to and reading back a 2D record variable in collective
mode with some of the processes making zero-length requests.
+ test/nc4/put_get_all_kinds.m4 - tests all supported variable read/write
API. Make sure they are properly wired up
+ test/nc4/interoperability_rd.m4 - tests whether NetCDF-4 file written using
NetCDF can be read by PnetCDF
+ test/nc4/interoperability_wr.m4 - tests whether NetCDF-4 file written using
PnetCDF can be read by NetCDF
+ test/nc4/simple_xy.c - tests reading NetCDF-4 files, borrowed the test
program simple_xy.c from NetCDF
+ test/testcases/tst_pthread.c - tests thread-safe capability for scenario of
each thread operating on a unique file.
+ test/testcases/tst_free_comm.c - free MPI communicator right after calling
ncmpi_create to see if PnetCDF duplicates the communicator correctly.
* Conformity with NetCDF library
+ none
* Discrepancy from NetCDF library
+ In contract to NetCDF-4 which allows to read/write variables in define mode
when the file format is in NetCDF-4 format, PnetCDF still requires reading
and writing variables in data mode.
+ In contrast to the semantics of nc_set_fill() defined in NetCDF-4,
ncmpi_set_fill() changes the fill mode of all variables newly defined in
the current scope of defined mode. Variables affected include the ones
defined before and after the call to ncmpi_set_fill(). Note this API has no
effect on the already existing variables created in the previous define
mode. This behavior follows the convention adopted by NetCDF-3. To change
fill mode for individual variables after the call to ncmpi_set_fill(), API
ncmpi_def_var_fill() can be used for this purpose. Refer NetCDF 4.1.3 user
guide for semantics of
[nc_set_fill()](https://www.unidata.ucar.edu/software/netcdf/documentation/historic/netcdf-c/nc_005fset_005ffill.html).
A discussion with NetCDF developers regarding this issue can be found in
[1114](https://github.com/Unidata/netcdf-c/pull/1114).
+ The error code return precedence can be different between NetCDF and
PnetCDF in some cases. A test program for error code return precedence is
available in test/testcases/error_precedence.m4. This program can be used
to test both PnetCDF and NetCDF libraries. Note when testing NetCDF
programs, because NetCDF does not follow the same precedence, failures are
expected. A discussion with NetCDF developers regarding this issue can be
found in [334](https://github.com/Unidata/netcdf-c/issues/334).
* Issues related to MPI library vendors:
+ none
* Issues related to Darshan library:
+ none
* Clarifications
+ PnetCDF currently does not support Fortran default integer type set to 8
bytes (for GNU Fortran compiler, this change of default setting is done by
using compile option -fdefault-integer-8). Checking this has been added
and configure command will fail, once default 8-byte integer is detected.
-------------------------------------
Version 1.10.0 (July 2, 2018)
-------------------------------------
o New features
* A new I/O layer that makes use of burst buffers is added. Burst buffer is
an I/O driver that implements a log-based I/O aggregation for write
requests with the present of burst buffer storage devices. The design is
to save first write requests in burst buffers and later flush the saved
requests to the destination file system. See doc/README.burst_buffering
for more detailed description.
o New optimization
* Internal memory management for nonblocking APIs has been improved further
to reduce memory footprint. See r3763.
* Both blocking and nonblocking varn APIs have been improved for better
performance and less memory footprint. See r3747-r3750.
* Prior to this release, when buftype in flexible APIs indicates a
noncontiguous layout in user buffer, PnetCDF packs the user buffer into
a contiguous buffer allocated internally, which will later be used in
MPI-IO calls. To reduce memory footprint, this release avoids the
additional memory allocation and directly uses the user buffer in MPI-IO
calls when neither byte-swap nor type-conversion is required. See r3722
and r3723.
o New Limitations
* none
o Update configure options
* The default setting for relax-coord-bound option is changed to "enable",
in accord with NetCDF 4.6.2. Users may use --disable-relax-coord-bound to
disable this setting at configure time or at run time by setting the
environment variable PNETCDF_RELAX_COORD_BOUND. See section "New run-time
environment variables" below for more information.
* Option in-place byte-swap is expanded into the following three settings.
--enable-in-place-swap : to perform byte swap on user I/O buffers
whenever possible. This option results in the least amount of internal
memory usage. However, if an immutable user buffer is used,
segmentation fault may occur when byte swap is performed on user
buffer in place.
--disable-in-place-swap : when byte swap is required, PnetCDF allocates
an internal memory to perform byte swap to avoid altering the contents
of user buffer. This option will increase internal memory footprint.
The default (neither the above option is used at the command line): an
internal buffer is allocated for byte swap only when the I/O request
size is less than 4 KiB. For larger requests, user buffers are used
for in-place byte swap.
The mode can also be changed at the run time by setting the PnetCDF hint
nc_in_place_swap in the run-time environment variable PNETCDF_HINTS. See
New hints below for more info. Note -in-place-swap option only affect
applications running on Little Endian machines, as no byte swap is
necessary on Big Endian machines.
o New constants
* none
o New APIs
* ncmpi_flush() flushes data buffered by PnetCDF to the destination file
system. When using the burst buffers, the data cached in the burst
buffers will be flushed.
o API syntax changes
* none
o API semantics updates
* The default setting for checking the coordinate bound is changed to the
more relaxed check. Users can still change this checking at run time by
setting the environment variable PNETCDF_RELAX_COORD_BOUND. See section
of "New run-time environment variables" below for more information.
* ncmpi_put_vard and ncmpi_get_vard APIs
1. Now allow to write and read two or more variables in a single call to
vard APIs. In this case, argument varid will be the ID of first
variable. Argument filetype should be constructed by using the
relative distance between any two successive variables. See example
program examples/C/vard_mvars.c.
2. When argument filetype is MPI_DATATYPE_NULL, the request is considered
a zero-length request.
3. Limitation of vard APIs: The element data type of filetype must
conform with the variable external NC data type. The element data
types of all variables accessed in filetype must be the same.
Otherwise, NC_EMULTITYPES will be returned.
4. buftype must contain only one same element data type if it is used to
read or write multiple variables from file. Otherwise NC_EMULTITYPES
will be returned.
o New error code precedence
* none
o Updated error strings
* none
o New error code
* NC_EFLUSHED when calling ncmpi_cancel() to cancel non-blocking requests
but the requests have already flushed.
* NC_EBADLOG when the log files stored in the burst buffers are found
corrupted.
o New PnetCDF hints
* nc_in_place_swap -- to enable or disable in-place byte swap on Little
Endian architectures. The default mode is auto. See in-place byte-swap
option above for descriptions of the three modes. Below is an example
that changes the mode to "enable" regardless the setting used at the
configure time, by setting the environment variable PNETCDF_HINTS with
command:
export PNETCDF_HINTS="nc_in_place_swap=enable"
* nc_burst_buf -- to use the burst buffering feature. The default setting
is disable. To enable at the run time, one can set the hint to
environment variable PNETCDF_HINTS, for example,
export PNETCDF_HINTS="nc_burst_buf=enable"
* nc_burst_buf_dirname -- Name of directory on the burst buffer where the
internal log files will be stored. This is usually set to the path where
burst buffer is mounted. The default path is the same directory of the
output file.
* nc_burst_buf_del_on_close -- Whether the burst buffer log files should
be deleted when closing the NetCDF file. The default is enable. To
disable at the run time, one can set the hint to environment variable
PNETCDF_HINTS, for example,
export PNETCDF_HINTS="nc_burst_buf_del_on_close=disable"
Note that on some systems, e.g. DataWarp, all files stored in burst
buffers may be purged when the user job is completed. In this case, users
who wish to keep the log files for other jobs must refer to the burst
buffer user guide for such setting. For DataWarp on Cori @NERSC, the
settings are described in
http://www.nersc.gov/users/computational-systems/cori/burst-buffer/example-batch-scripts/
* nc_burst_buf_flush_buffer_size -- Amount of memory allowed by users for
PnetCDF to allocate when flushing the burst buffer log files. The unit
is in bytes. Value 0 means unlimited. Users are suggested to use a
number that is at least the size of largest individual requests. The
default is unlimited.
o New run-time environment variables
* PNETCDF_RELAX_COORD_BOUND environment variable can be set to 0 to disable
or 1 to enable the more relaxed boundary check for argument start. Prior
to version 1.10.0, the default behavior is to use a strict boundary
check, i.e. error code NC_EINVALCOORDS will be thrown when the value of
start is larger than or equal to the defined dimension size.
o Build recipes
* doc/README.burst_buffering is added to describe the usage of the new
feature of burst buffering.
* doc/README.IBM is revised as the compiler behavior, particularly when
using GNU-based MPI compilers to build static-only libraries, has
changed on BGQ since the release of 1.9.0.
* doc/README.CRAY is revised as the compiler behavior, particularly when
using GNU-based MPI compilers to build static-only libraries, has
changed on CRAY since the release of 1.9.0.
* doc/README.Ubuntu is revised and the fix of adding LDFLAGS is no longer
necessary when building shared libraries.
o New/updated utility program
* ncvalidator adds a new option -t to turn on tracing mode which prints all
successfully validated metadata till the first error encountered.
* ncvalidator adds a check to detect whether there are two or more
unlimited dimensions defined in the file and, if yes, reports error code
NC_EUNLIMIT.
o Other updates:
* Inter-library dependencies among C, C++ and Fortran have been updated to
follow automake user guide: adding FLIBS and FCLIBS to _LIBADD. This
update resolves problems of building shared libraries for some systems.
* Move the memory allocation trace feature out of --enable-debug into the
new configure option --enable-profiling. By default, this is disabled.
* Add a check for NC_EUNLIMIT in API ncmpi_open to detect whether two or
more unlimited dimensions are defined to detect a corrupted file.
o Bug fixes
* Fix type_create_subarray64() for case when some dimensions of the global
array is larger than 4G and oldtype is not MPI_BYTE. See r3779. Without
this fix, test/largefile/large_var.c will fail. Note prior to 1.9.1,
type_create_subarray64() is always called with oldtype being MPI_BYTE.
* Fix configure-time bug that configure fails to recognize the compilers
with full-path names passed from the environment variable MPICC, MPICXX,
MPIF77, or MPIF90. See Ticket #35 for bug report and r3740 for fix.
* Fix the bug that writing scalar attributes of type NF_INT64 was
mistakenly casted to NF_INT. See r3730.
* Fix test/testcases/erange_fill.m4 for the case of NC_LONG data type.
NC_LONG is synonym of NC_INT. When setting fill value for variables of
type NC_LONG, the user buffer must be of type int (internal). See r3726.
* Fix the calculation of new record number in put_vard API. Thanks to
Jim Edwards. See r3675.
* Fix the calculation of growing size of nonblocking request queues to
include the number of records of a record variable, as such request is
split into multiple additional requests, one for each record. See r3651.
* Remove freeing name object because NC_ENULLPAD is not a fatal error. See
r3644. This bug only appears when "--enable-null-byte-header-padding" is
set at configure time and opening files whose headers are not padded with
null bytes.
* Member "value" of NC_dimarray, NC_attrarray, and NC_vararray can still be
NULL when a corrupted tag of NC_DIMENSION, NC_ATTRIBUTE, or NC_VARIABLE
is read from files. Add a check against NULL before freeing it. This bug
only appears when reading files with corrupted NC tags. See r3645.
o New example programs
* example/C/vard_mvars.c shows an example of using a single vard API call
to write or read two variables.
* example/burst_buffer/create_open.c shows an example of creating and
opening a NetCDF file with the burst buffering feature enabled.
* example/burst_buffer/nonblocking.c shows an example of using non-blocking
put APIs with the burst buffering feature enabled.
o New programs for I/O benchmarks
* none
o New test program
* test/burst_buffer/bb_bsize.c - test whether the burst buffer driver works
under limited flush buffer size.
* test/burst_buffer/bb_hints.c - test file hints related to the burst
buffer driver
* test/burst_buffer/bb_many_reqs.c - stress test the nonblocking request
pool in the burst buffer driver
* test/burst_buffer/bb_nonblocking.c - test the behavior of burst buffer
driver when using nonblocking I/O, particularly for case that tries to
cancel an already flushed request.
* test/burst_buffer/highdim.c - test whether the burst buffer driver can
handle very high dimension variables.
* test/testcases/test_fillvalue.c - tests PnetCDF allows to put attribute
_FillValue for global variable and for non-global variable, requires the
data type of attribute _FillValue be the same as the variable's.
* test/F90/test_attr_int64.f90 - tests the bug fixed in r3730 that
nf90mpi_put_att API writes a scalar attribute of type NF90_INT64 that
was mistakenly casted to NF90_INT.
* test/testcase/test_vard_rec.c - tests ncmpi_put_vard APIs for writing a
record variable with one record at a time. This is to test the fix to
bug reported by Jim Edwards in r3675.
* test/nonblocking/large_num_reqs.c - tests large number of nonblocking put
and get requests (larger than NC_REQUEST_CHUNK, the constant used to grow
the internal queues that store the nonblocking put and get requests. This
is to test bug fix in r3651.
* test/testcases/tst_def_var_fill.c - tests API ncmpi_def_var_fill and
verifies fill values when fill mode is turned on and off.
* src/utils/ncvalidator/tst_open.c - tests API ncmpi_open against corrupted
files and checks expected error codes.
o Conformity with NetCDF library
* NetCDF allows to put attribute _FillValue of any NC data type to the
global variable, NC_GLOBAL. Note this is allowed for classic files, but
not for the HDF5-based NetCDF-4 files. PnetCDF conforms with this
behavior from this release on. Reference of NetCDF 4.1.3 user guide for
nc_put_att_type() at https://www.unidata.ucar.edu/software/netcdf/documentation/historic/netcdf-c/nc_005fput_005fatt_005f-type.html
* For non-global variables, NetCDF treats the classic and HDF5 files
differently. For classic files, it allows to create attribute _FillValue
of a data type that is different from the variable's. For HDF5 files, the
data type of attribute _FillValue must be the same as the variable. Note
this behavior for classic files is against the convention specified in
the NetCDF user guide and NetCDF plans to revise the user guide to
describe the new convention. As for PnetCDF, we decided to enforce the
rule that requires the data type of attribute _FillValue be the same as
the variable's.
o New conflict with NetCDF library
* none
o New issues related to MPI library vendors:
* none
o New issues related to Darshan library:
* none
o New clarifications
* none
-------------------------------------
Version 1.9.0 (December 19, 2017)
-------------------------------------
o New features
* The configure environment has been migrated to use GNU automake and
libtool.
* Building shared libraries is now supported with configure option
--enable-shared. However, the default configuration is to build static
library only. Note linking shared libraries is not recommended due to
the likely performance degradation.
o New optimization
* Use hash function for faster attribute name lookup. See r3335.
o New Limitations
* PnetCDF now requires the underlying MPI library define data type
MPI_Offset an 8-byte integer. Configuration process will be aborted if
MPI_Offset is detected to be of size 4 bytes. See r2944.
* The maximum number of files that can be simultaneously opened by an MPI
process is now limited to 1024 (a new constant NC_MAX_NFILES defined in
pnetcdf.h). When this limit is reached, error code NC_ENFILE will be
thrown.
* NC_MAX_VAR_DIMS, the maximum number of dimensions per variable is raised
to 2147483647, i.e. NC_MAX_INT
* NC_MAX_DIMS, the maximum number of dimensions per file is raised to
2147483647, i.e. NC_MAX_INT
* NC_MAX_ATTRS, the maximum number of attributes per file is raised to
2147483647, i.e. NC_MAX_INT
* NC_MAX_VARS, the maximum number of variables per file is raised to
2147483647, i.e. NC_MAX_INT
* NC_EMAX_REQ error code will be thrown when a single request of a get/put
API call or the aggregated size of nonblocking requests in a wait API
call exceeds INT_MAX (max of 4-byte integer). Note the size limit is per
MPI process, not across all processes. This is due to MPI-IO may not
support a single MPI-IO request of size larger then INT_MAX. A new
configure command-line option "--enable-large-req" has been added
available to disable the checking. Use this option is recommended only
when the underneath MPI-IO library supports large single requests made by
each MPI process.
o New constants
* NC_FORMAT_UNKNOWN, NF_FORMAT_UNKNOWN, and NF90_FORMAT_UNKNOWN are new
constants that are one of the returned values of argument formatp in the
API ncmpi_inq_file_format when the file under inquiry is unrecognizable
by PnetCDF library.
* NC_MAX_NFILES, NF_MAX_NFILES, and NF90_MAX_NFILES define the maximum
number of files that can be kept opened by an MPI process.
o New APIs
* none
o API syntax changes
* Add C type qualifier "const" to argument fill_value of ncmpi_def_var_fill
to indicate the contents pointed by fill_value is immutable.
o Semantics updates
* Calling ncmpi_end_indep_data() in collective data mode is no longer
considered illegal, starting from this release 1.9.0. In this case, the
API simply returns NC_NOERR. Note calling ncmpi_begin_indep_data() in
independent data mode has been allowed since PnetCDF 1.2.0. Thanks to
Gregory Sjaardema for pointing out the asymmetry between the two APIs.
See r3517.
* For CDF-5 files, the maximum size of a variable or a variable's record
is NC_MAX_INT64-3 (i.e. 2^64-4).
* When the file create/open modes are not consistent among processes, the
modes on all processes will be replaced by rank 0's mode and PnetCDF
library will still try to create/open the file. Error code
NC_EMULTIDEFINE_CMODE or NC_EMULTIDEFINE_OMODE will be returned on
processes whose modes disagree with rank 0's. If safe mode is on, then
all processes will also get the same error code.
* API ncmpi_inq_nreqs() - allows argument nreqs to be NULL. In this case,
the API is equivalent to checking the validity of argument ncid. In
previous releases, NC_EINVAL is returned when argument nreqs is NULL.
* API ncmpi_inq_buffer_usage() - allows argument usage to be NULL. In this
case, the API is equivalent to checking the validity of argument ncid. In
previous releases, NC_EINVAL is returned when argument usage is NULL.
* API ncmpi_inq_buffer_size() - allows argument usage to be NULL. In this
case, the API is equivalent to checking the validity of argument ncid. In
previous releases, NC_EINVAL is returned when argument buf_size is NULL.
o New error code precedence
* none
o Updated error strings
* The error string corresponding to error code NC_EMAXDIMS is changed to
cover the case when NC_MAX_DIMS or NC_MAX_VAR_DIMS is exceeded.
o New error code
* NC_EMAX_REQ - indicates a single request of a get/put API call or the
aggregated size of nonblocking requests in a wait API call exceeds
INT_MAX (max of 4-byte integer). The corresponding F77 and F90 error
codes are NF_EMAX_REQ and NF90_EMAX_REQ, respectively.
* NC_ENULLPAD - indicates the file fails strict null-byte header check. The
corresponding F77 and F90 error codes are NF_ENULPAD and NF90_ENULPAD,
respectively. The same error code has also been defined in NetCDF since
4.5.1. Note this error is not considered fatal. PnetCDF will continue
the file open procedure if there is no other error found. Therefore, when
encountering this error code returned from the file open API, ncmpi_open,
user can safely ignore it. See section "Conflict with NetCDF library"
below for further discussion.
o New PnetCDF hint
* none
o New run-time environment variables
* none
o New build recipe
* doc/README.Ubuntu provides build instructions for Ubuntu Linux OS.
o New/updated utility program
* Utility program ncmpivalid is renamed to ncvalidator to reflect its
purpose. It is now running in serial and thus no longer requires an MPI
compiler to build it. In fact, its source codes are all in a single file,
ncvalidator.c, which can be compiled using gcc, i.e. command "gcc -o
ncvalidator ncvalidator.c". This utility program can be used to validate
a classic CDF file, and report the locations that fail to comply with CDF
formats. It can also repair a file whose header fails to use null bytes
for paddings, when the command-line option "-x" is used. See its man page
for further description of usage.
o Other updates:
* Update UTF8 encoding utility to use utf8proc library version 2.1.0 from
the Julia Language project, https://github.com/JuliaLang/utf8proc
License https://github.com/JuliaLang/utf8proc/blob/master/LICENSE.md
* Add quiet mode command-line option "-q" to utility program ncvalidator.
* Add an internal check for whether the file starting offsets of all
variables are in an increasing order as the variables defines. See r3369.
* All build recipes (README files) have been moved to folder doc. Most of
the recipes have been updated with instructions for building shared
libraries.
* Rename configure-time variables TEST_SEQRUN, TEST_MPIRUN, and TEST_OUTDIR
to TESTSEQRUN, TESTMPIRUN, and TESTOUTDIR, respectively. This change
avoids conflict to the name convention reserved by automake.
* Fix TESTMPIRUN default value to use full path specified in --with-mpi at
configure command line
o Bug fixes
* Fix a bug in nonblocking APIs when two separate nonblocking requests that
can be coalesced into a contiguous MPI fileview or buffer type but the
coalesced length becomes too big and overflows a 4-byte integer, data
type of argument blocklengths of MPI_Type_create_hindexed, coalescing
should be skipped. I.e. such two requests should be treated as two
separate blocks in MPI_Type_create_hindexed. Thanks Jim Edwards for
reporting. See r3565.
* Fix a bug in nonblocking APIs when one request's access region covers
more than one other non-interleaved requests. PnetCDF fails to identify
them as a single group of interleaved requests. Test program
test/nonblocking/interleaved.c has been revised to test the fix.
See r3389.
* Fix a bug in string parsing the environment variable PNETCDF_HINTS and
print warning messages when hint strings are ill-formed. See r3284.
* Fix a bug in F90 APIs for reading and writing scalar variables, i.e.
number of dimensions is zero. The bugs appear only when using Intel
Fortran compiler which does not allow checking presence of an argument
and its contents in the same if condition. See r3009, r3012, r3013.
* Conform with CDF-2 file format specification on using 2^32-1 for vsize
when the variable size is larger than 2^32-4 bytes. See r2957.
* Fix a bug in nc_test when running on an ARMv7 architecture, a raspberry
pi, where char is unsigned and which is little Endian, 32-bit machine.
See r2922.
* Fix a bug that fails to do byte-swap when retrieving user-defined fill
values. See r2864. This fix is critical when PnetCDF is configured with
option erange-fill enabled (default mode) and the target platform is a
Little Endian.
o New example programs
* none
o New programs for I/O benchmarks
* none
o New test program
* test/testcases/tst_vars_fill.m4 - tests strided put (vars) APIs with
fill mode on.
* test/largefile/large_coalesce.c - tests a bug fixed in r3565 when two
separate nonblocking requests that can be coalesced into a contiguous MPI
fileview or buffer type but the coalesced length becomes too big and
overflows a 4-byte integer.
* test/testcases/tst_info.c - tests an internal bug in heap memory
allocation trace mechanism. See r3514.
* test/cdf_format/tst_corrupt.c
1. tests whether NC_EMAXDIMS can be thrown when opening a corrupted file
header with number of dimensions being larger than NC_MAX_DIMS.
2. tests whether NC_EMAXATTS can be thrown when opening a corrupted file
header with number of attributes being larger than NC_MAX_ATTRS.
3. tests whether NC_EBADDIM can be thrown when opening a corrupted file
header with dimension ID of a variable is beyond the number of
dimensions defined in the file.
4. tests whether NC_EBADTYPE can be thrown when opening a corrupted file
header with nc_type of a variable is not within the legal NC atomic
data type allowed by the file format.
* test/testcases/tst_max_var_dims.c - tests the number of dimensions
against NC_MAX_VAR_DIMS when calling ncmpi_def_var API.
* test/largefile/tst_cdf5_begin.c - tests CDF-5 file header corruption for
the case when the starting file offsets of variables are not in an
increasing order as they defined.
* test/cdf_format/tst_open_cdf5.c - tests whether NC_ENOTNC can be
correctly thrown when opening a corrupted CDF-5 (bad_begin.nc5) which
contains two variables and the second variable's starting file offset is
less than the first variable's end offset.
* test/testcases/large_var_cdf5.c - tests whether NC_EVARSIZE can be
correctly thrown when a variable or a variable record is larger than
NC_MAX_INT64-3.
* test/testcases/mix_collectives.c - tests collective get/put APIs that
allow different processes to call different kinds of APIs (i.e. var1,
vara, vars, varm, etc.) and use different var IDs. In other words, the
API kinds can be different among processes in a collective call.
* test/largefile/high_dim_var.c - tests blocking vars APIs for high-
dimensional variables. See r3164.
* test/largefile/large_dims_vars_attrs.c - tests large number of
dimensions, large number of variables, and large number of attributes.
* test/testcases/put_all_kinds.m4 - tests various blocking put APIs.
* test/testcases/tst_dimsizes.c - borrowed from NetCDF library to test
define/inquire APIs for the maximum allowable dimension sizes. This test
program is similar to (or a subset of) test/cdf_format/dim_cdf12.c
* test/testcases/null_args.c - tests whether the correct error codes can
be returned when using NULL arguments for start, count, stride, or imap
o Conformity with NetCDF library
* API ncmpi_open now checks the number of large variables that is legal
for CDF-1 and CDF-2 files. See r2961. For the information about the
number of large variables allowed in the classic formats can be found in
http://www.unidata.ucar.edu/software/netcdf/docs/file_structure_and_performance.html#classic_format_limitations
* Add checking for error code NC_ELATEFILL. Setting a variable's attribute
_FillValue must be done in the variable's initial define mode.
* NetCDF-4 documents in 4.4.1 and prior state that setting attribute
_FillValue for global variable NC_GLOBAL is not allowed and error code
NC_EINVAL will be thrown. Revisions r2954, r2955, and r2956 enforce this
rule. However, because the rule has never been implemented in any NetCDF
official release, NetCDF developers have decided to abandon this rule
by revising the NetCDF document starting from v4.5. See discussion in
NetCDF GitHub pull request 458. To be consistent with NetCDF, PnetCDF
follows the same decision by wrapping the checking with preprocessor
conditional #ifdef NO_NC_GLOBAL_FILLVALUE (see r3403). Note NC_EGLOBAL
will be thrown when using NC_GLOBAL in ncmpi_def_var_fill(). This is
due to no data type information for the fill value can be passed.
* From the releases of 1.6.1 through 1.8.1, putting attribute _FillValue
automatically turns on the fill mode for the variable. Similarly,
deleting attribute _FillValue turns off the fill mode. However, this
behavior does not conform with NetCDF library. This release fixes this
inconsistency, so putting or deleting attribute _FillValue does not
affect a variable's fill mode. See r2951.
o Conflict with NetCDF library
* Null-byte padding for attribute values in file header -- The classic CDF
specifications require header padding uses null (\x00) bytes. However,
prior to version 4.5.0, NetCDF did not implement this specification
entirely. In particular, it has never enforced the null-byte padding for
attribute values (it has for others, such as names of dimension,
variables, and attributes.) It also appears that files created by SciPy
NetCDF module or NetCDF Java module, both developed independent from
NetCDF-C, also fail to respect this padding specification. This becomes
a problem for PnetCDF to read such netCDF files, because PnetCDF enforces
the header padding from its very first release. The files violating the
padding specification will not be readable by PnetCDF of all releases
prior to 1.9.0 and error code NC_EINVAL or NC_ENOTNC will be thrown when
opening such files. Note if the sizes of all attribute values of your
files are aligned with 4-byte boundaries, then the files are readable by
PnetCDF. In order to keep the files in question readable by PnetCDF,
checking for null-byte padding has been disabled in 1.9.0 by default. A
new configure command-line option "--enable-null-byte-header-padding" has
been made available to enable the checking and error code NC_ENULLPAD
will be thrown when opening files. Note NC_ENULLPAD is not considered a
fatal error. Users can safely ignore it. However, we keep this checking
in ncvalidator no matter the new configure option is set or not.
ncvalidator is a utility program reports whether a CDF file violates the
file format specification, including this null-byte padding. See r3528
for source codes changed and discussion in NetCDF Github issue
https://github.com/Unidata/netcdf-c/issues/657.
o Issues related to MPI library vendors:
* When using OpenMPI 2.0.0 through the latest 2.1.2 to build PnetCDF 1.8.1
and prior, the following message may appear when running make check:
"MPI error (MPI_File_open) : MPI_ERR_FILE: invalid file"
but the test programs report "pass". This message can be safely ignored.
It is due to OpenMPI failing to translate system error code ENOENT into
MPI_ERR_NO_SUCH_FILE, but returns MPI_ERR_FILE instead. Thanks to Edgar
Gabriel, a trick to silence the messages is to add the following to the
command line of make check:
TEST_SEQRUN="/path/to/OpenMPI/2.x.x/bin/mpirun --mca io romio314 -n 1"
See discussion thread in OpenMPI:
https://github.com/open-mpi/ompi/issues/4412
Note this error message does not appear in PnetCDF 1.9.0 and after.
* When using OpenMPI 2.1.1 and priors built with Intel compilers 17.0.0,
the test program nonblocking/mcoll_testf.f90 fails with segmentation
fault. This is due to a bug in OpenMPI. See discussion thread in OpenMPI:
https://github.com/open-mpi/ompi/issues/3695
* PnetCDF can no longer be built on 32-bit machines if using OpenMPI
versions 2.0.2 and 1.10.6 and earlier versions. This is because OpenMPI
configures type MPI_Offset as a 4-byte integer on all 32-bit machines,
even if the machines allow 64-bit file offsets, known as large-file
support. We suggest to use other MPI libraries to build PnetCDF on 32-bit
machines. See the discussion thread in OpenMPI:
https://github.com/open-mpi/ompi/issues/3195
* Fix test/nc_test/test_read.m4 and test/testcases/modes.c which test
whether the correct error codes can be returned when opening a
non-existing file. Thanks to Mark Dixon for testing various MPI
libraries, C compilers, and file systems, we found that when using
MVAPICH2 2.2, its Lustre driver always adds O_CREAT flag to the open()
calls. Because of this behavior, the non-existing file will be created
with zero length, which causes PnetCDF to spew NC_ENOTNC instead of
NC_ENOENT. A bug report has been filed to MVAPICH. The fix shall come in
the next release of MVAPICH. The bug report can be found in
http://mailman.cse.ohio-state.edu/pipermail/mvapich-discuss/2017-February/006300.html
o Issues related to Darshan library:
* When using Darshan in conjunction with PnetCDF, if you encounter
link-time or run-time errors with messages shown below, then we recommend
to use Darshan library version 3.1.5 and later.
During compile/link time:
/soft/perftools/darshan/lib/libdarshan-mpi-io.a(darshan-pnetcdf.o):
In function `__wrap_ncmpi_create': darshan-pnetcdf.c:62: undefined
reference to `ncmpi_create'
During run time:
WARNING: Darshan ncmpi_create() stub called; this is probably the result
of a link-time problem.
o Clarifications
* The NetCDF CDF formats define a set of external NC data types and
describe their intents of use, shown below.
External type No. Bits Intent of use
------------- -------- ---------------------------------
NC_CHAR 8 text data (the only non-numerical type in NetCDF)
NC_BYTE 8 1-byte integer
NC_SHORT 16 2-byte signed integer
NC_INT 32 4-byte signed integer
NC_FLOAT 32 4-byte floating point number
NC_DOUBLE 64 8-byte real number in double precision
NC_UBYTE 8 unsigned 1-byte integer
NC_USHORT 16 unsigned 2-byte integer
NC_UINT 32 unsigned 4-byte integer
NC_INT64 64 signed 8-byte integer
NC_UINT64 64 unsigned 8-byte integer
Note NC_CHAR is the only non-numerical data type available in NetCDF
realm. All other external types are considered numerical, which are
illegal to be converted (type-casted) to and from a NetCDF variable
defined in NC_CHAR type (error code NC_ECHAR will be thrown). The only
legal APIs to read/write a variable of type NC_CHAR are the "_text" APIs.
* Starting from 1.7.0, PnetCDF translates internal data types (i.e. data
types of the I/O buffer and also used in the API name such as text,
schar, uchar, short, int, etc.) to MPI data types based on the table
below. Note MPI_BYTE does no correspond to any internal data type used
in NetCDF/PnetCDF APIs. Thus, when MPI_BYTE is used to construct an MPI
derived data type which is later used as argument buftype in a flexible
API, the error code NC_EBADTYPE will be thrown (Not a valid data type).
Data type of Corresponding
internal I/O buffer Example API MPI datatype
------------- ---------------------- -----------------
text ncmpi_put_var_text MPI_CHAR
schar ncmpi_put_var_schar MPI_SIGNED_CHAR
uchar ncmpi_put_var_uchar MPI_UNSIGNED_CHAR
short ncmpi_put_var_short MPI_SHORT
ushort ncmpi_put_var_ushort MPI_UNSIGNED_SHORT
int ncmpi_put_var_int MPI_INT
uint ncmpi_put_var_uint MPI_UNSIGNED
long ncmpi_put_var_long MPI_LONG
float ncmpi_put_var_float MPI_FLOAT
double ncmpi_put_var_double MPI_DOUBLE
longlong ncmpi_put_var_longlong MPI_LONG_LONG_INT
ulonglong ncmpi_put_var_ulonglong MPI_UNSIGNED_LONG_LONG
-------------------------------------
Version 1.8.1 (January 28, 2017)
-------------------------------------
This release is mainly for fixing the following bug.
o Bug fixes:
* Fortran parameters NF_MAX_DIMS, NF_MAX_ATTRS, NF_MAX_VARS, and NF_MAX_NAME
defined in the Fortran header file, pnetcdf.inc, were set to obsolete
values and have been fixed in this release to conform with their
corresponding C constants. Because these four parameters were not used
by PnetCDF internally, the end users can safely skip this release and
1.8.1 should perform the same as 1.8.0. If your programs explicitly use
these four parameters, then updating to 1.8.1 is recommended.
o Other updates:
* To conform with GNU Coding Standards, the installation location for man
pages are changed to ${prefix}/share/man.
* Support of DESTDIR for Building Binary Packages has been added, as
suggested by [email protected]. Ticket #25
-------------------------------------
Version 1.8.0 (December 19, 2016)
-------------------------------------
o New features
* Copy fill values to data elements that cause out-of-bound error (i.e.
NC_ERANGE.) In netCDF v4.4.1 and priors, type conversion for out-of-
bound elements proceeds even if the out-of-bound error is detected, and
the contents (in both files and read buffers) are left up to the user
to handle. See the URL below for details.
http://www.unidata.ucar.edu/software/netcdf/docs/group__error.html
Instead of carrying out the type conversion, PnetCDF fills the out-of-
bound data elements with their "fill values", as specified by the
variable's attribute "_FillValue" or default CDF fill values if the
attribute is not defined. Specifically, for PnetCDF put APIs, the value
of attribute _FillValue, if defined, will be used when writing to files.
For get APIs, the default CDF _FillValue corresponding to the internal
data type will be used to fill the read buffer. This feature can be