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