@@ -6,6 +6,109 @@ PnetCDF Release Notes
66Version _PNETCDF_VERSION_ (_PNETCDF_RELEASE_DATE_)
77-------------------------------------
88
9+ * New optimization
10+ + When file header extent size grows, moving the data section to a higher
11+ file offset has changed to be done in chunks of 16 MB per process.
12+ See [PR #174](https://github.com/Parallel-NetCDF/PnetCDF/pull/174),
13+
14+ * Configure options
15+ + For PnetCDF developers, the requirement for libtool version has been
16+ changed to 2.5.4, due to an issue on Mac OS when using OpenMPI. See
17+ [Issue #155](https://github.com/Parallel-NetCDF/PnetCDF/issues/155),
18+ [Issue #163](https://github.com/Parallel-NetCDF/PnetCDF/issues/163),
19+ and [PR #164](https://github.com/Parallel-NetCDF/PnetCDF/pull/164).
20+
21+ * New APIs
22+ + A set of APIs that read the header of a CDL file header and allow users to
23+ query the metadata defined in the CDL file. These APIs can be useful for
24+ creating a program (such as an I/O benchmark) based on an output netCDF
25+ file from another application (a CDL file can be generated by running the
26+ utility `ncmpidump/ncdump`). See
27+ [PR #177](https://github.com/Parallel-NetCDF/PnetCDF/pull/177).
28+ * `cdl_hdr_open()` opens and parses the CDL file's header
29+ * `cdl_hdr_inq_format()` returns file format version
30+ * `cdl_hdr_inq_ndims()` returns number of dimensions defined in CDL file
31+ * `cdl_hdr_inq_dim()` returns metadata of a dimension
32+ * `cdl_hdr_inq_nvars()` returns number of variables
33+ * `cdl_hdr_inq_var()` returns metadata of a variable defined in CDL file
34+ * `cdl_hdr_inq_nattrs()` returns number of attributes of a given variable
35+ * `cdl_hdr_inq_attr()` returns metadata of an attribute
36+ * `cdl_hdr_close()` closes the CDL file
37+ + The CDL Header C Reference Manual is available in
38+ [cdl_api_guide.md](doc/cdl_api_guide.md). See
39+ [PR #184](https://github.com/Parallel-NetCDF/PnetCDF/pull/184).
40+
41+ * Bug fixes
42+ + Fix setting of user hint nc_ibuf_size.
43+ See [PR #161](https://github.com/Parallel-NetCDF/PnetCDF/pull/161).
44+
45+ * New example programs
46+ + examples/C/create_from_cdl.c shows how to call the new CDL header APIs to
47+ create a netCDF file with the same metadata.
48+
49+ * New programs for I/O benchmarks
50+ + WRF-IO contains an extraction of the I/O kernel of WRF (Wether Research
51+ and Forecast Model, a weather prediction computer simulation program
52+ developed at NCAR) that can be used to evaluate the file I/O performance
53+ of WRF. It's data partitioning pattern is a 2D block-block checkerboard
54+ pattern, along the longitude and latitude.
55+ See [PR #165](https://github.com/Parallel-NetCDF/PnetCDF/pull/165)
56+ and [PR #181](https://github.com/Parallel-NetCDF/PnetCDF/pull/181).
57+
58+ * New test program
59+ + test/cdf/tst_cdl_hdr_parser.c tests the new CDL header APIs.
60+ + test/testcases/tst_grow_header.c tests header extent growth by re-entering
61+ the define mode multiple times and add more fix-sized and record variables.
62+
63+ * Clarifications about of PnetCDF hints
64+ + There are three ways in PnetCDF for user to set hints to align the starting
65+ file offset for the data section (header extent) and record variable
66+ section.
67+ 1. through a call to API `nc_header_align_size` by setting arguments of
68+ `h_minfree`, `v_align`, `v_minfree`, and `r_align`.
69+ 2. through an MPI info object passed to calls of `ncmpi_create()` and
70+ `ncmpi_open()`. Hints are `nc_header_align_size`, `nc_var_align_size`,
71+ and `nc_record_align_size`.
72+ 3. through a run-time environment variable `PNETCDF_HINTS`. Hints are
73+ `nc_header_align_size`, `nc_var_align_size`, and `nc_record_align_size`.
74+ + As the same hints may be set by one or more of the above methods, PnetCDF
75+ implements the following hint precedence.
76+ * `PNETCDF_HINTS` > `ncmpi__enddef()` > `MPI info`.
77+ * 1st priority: hints set in the environment variable `PNETCDF_HINTS`, e.g.
78+ `PNETCDF_HINTS="nc_var_align_size=1048576"`. Making this the first
79+ priority is because it allows to run the same application executable
80+ without source code modification using different alignment settings
81+ through a run-time environment variable.
82+ * 2nd priority: hints set in the MPI info object passed to calls of
83+ `ncmpi_create()` and `ncmpi_open()`, e.g.
84+ `MPI_Info_set("nc_var_align_size", "1048576");`. The reasoning is when a
85+ 3rd-party library built on top of PnetCDF implements its codes using
86+ 'ncmpi__enddef'. An application that uses such 3rd-party library can pass
87+ an MPI info object to it, which further passes the info to PnetCDF. This
88+ precedence allows that application to exercise different hints without
89+ changing the 3rd-party library's source codes.
90+ * 3rd priority: hints used in the arguments of `ncmpi__enddef()`, e.g.
91+ `ncmpi__enddef(..., v_align=1048576,...)`.
92+ + PnetCDF I/O hint `nc_header_align_size` is essentially the same as hint
93+ `nc_var_align_size`, but its name appears to be closer to the hint's
94+ intent, i.e. to reserve some space for the header growth in the future when
95+ new data objects are added. Please note when both hints are set, only hint
96+ `nc_var_align_size` will take effect and `nc_header_align_size` ignored.
97+ + When there is no fix-sized variable (i.e. non-record variable) defined,
98+ argument `v_minfree` passed to `ncmpi__enddef()` is ignored. In this
99+ case, users should set `h_minfree`, if an extra header space is desired.
100+ + When there is no fix-sized variables defined and none of hints
101+ `nc_header_align_size`, `nc_var_align_size`, or argument `v_align` is set,
102+ `nc_record_align_size` or `r_align`, if set, will be used to align the
103+ header extent.
104+ + For the above update to the hint precedence, see
105+ PnetCDF See [PR #173](https://github.com/Parallel-NetCDF/PnetCDF/pull/173).
106+
107+
108+ -------------------------------------
109+ Version 1.14.0 (November 11, 2024)
110+ -------------------------------------
111+
9112* New features
10113 + Intra-node aggregation for write requests -- When the number of MPI
11114 processes allocated to a compute node is large, this feature can
0 commit comments