From 4ec046eeab07246f54fd7f93679a0b8b5e0708ae Mon Sep 17 00:00:00 2001 From: Wei-keng Liao Date: Tue, 10 Sep 2024 01:15:31 -0500 Subject: [PATCH] doc: rewording --- docs/source/api/attribute_api.rst | 13 +++-- docs/source/api/dimension_api.rst | 12 +++-- docs/source/api/file_api.rst | 16 +++--- docs/source/api/function_api.rst | 2 +- docs/source/api/variable_api.rst | 16 +++--- docs/source/copyright.rst | 6 +-- docs/source/index.rst | 18 ++++--- docs/source/tutorial/basic.rst | 84 ++++++++++++++--------------- docs/source/tutorial/datatypes.rst | 2 +- docs/source/tutorial/read_write.rst | 10 ++-- 10 files changed, 93 insertions(+), 86 deletions(-) diff --git a/docs/source/api/attribute_api.rst b/docs/source/api/attribute_api.rst index de01492..0547137 100644 --- a/docs/source/api/attribute_api.rst +++ b/docs/source/api/attribute_api.rst @@ -1,8 +1,11 @@ =========== -Attribute +Attributes =========== -In the library, netCDF attributes can be created, accessed, and manipulated -using python dictionary-like syntax. A Pythonic interface for metadata operations -is provided both in the ``File`` class (for global attributes) and the -``Variable`` class (for variable attributes). +NetCDF attributes can be created, accessed, and manipulated using python +dictionary-like syntax. An attribute can be associated to the file, referred to +as ``golbal attribute``, as well as to individual variable, referred to as +``variable's attribute``. Pythonic interfaces for accessing attributes are is +provided both in :class:`pnetcdf.File` (for global attributes) and the +:class:`pnetcdf.Variable` (for variable attributes). + diff --git a/docs/source/api/dimension_api.rst b/docs/source/api/dimension_api.rst index 65e5c29..96afdb0 100644 --- a/docs/source/api/dimension_api.rst +++ b/docs/source/api/dimension_api.rst @@ -1,10 +1,11 @@ ============== -Dimension +Dimensions ============== -Dimension defines the shape and structure of variables and stores coordinate -data for multidimensional arrays. The ``Dimension`` object, which is also a key -component of ``File`` class, provides an interface to access dimensions. +Class ``Dimension`` is used to define the shape of NetCDF variables. In NetCDF, +a variable, an instance of :class:`pnetcdf.Variable`, is a multi-dimensional +array. Methods in :class:`pnetcdf.Dimension` provide an interface to access +dimensions objects stored in the file. .. autoclass:: pnetcdf::Dimension :members: getfile, isunlimited @@ -24,7 +25,8 @@ Read-only Python Attributes of Dimension Class .. attribute:: size - The current size of Dimension (calls ``len`` on Dimension instance). + The current size of Dimension (its value can be obtained by calling + python function ``len()`` on the Dimension instance). **Type:** `int` diff --git a/docs/source/api/file_api.rst b/docs/source/api/file_api.rst index 80f5a2d..db7d793 100644 --- a/docs/source/api/file_api.rst +++ b/docs/source/api/file_api.rst @@ -1,12 +1,12 @@ ================ -File +Files ================ -``pnetcdf.File`` is a high-level object representing an netCDF file, -which provides a Pythonic interface to create, read and write within -an netCDF file. A File object serves as the root container for dimensions, -variables, and attributes. Together they describe the meaning of data and -relations among data fields stored in a netCDF file. +An instance of class ``pnetcdf.File`` is a high-level object representing a +netCDF file. The class methods provide a set of Pythonic interfaces to create, +read and write a netCDF file. A ``File`` instance serves as the root container +for dimensions, variables, and attributes. Together they describe the meaning +of data and relations among data objects stored in a netCDF file. .. autoclass:: pnetcdf::File :members: __init__, close, filepath, redef, enddef, begin_indep, end_indep, @@ -24,14 +24,14 @@ Read-only Python Attributes of File Class .. attribute:: dimensions The dimensions dictionary maps the names of dimensions defined in this - file as an instance of the ``pnetcdf.Dimension`` class. + file as an instance of the :class:`pnetcdf.Dimension`. **Type:** `dict` .. attribute:: variables The variables dictionary maps the names of variables defined in this file - as an instance of the ``pnetcdf.Variable`` class. + as an instance of the :class:`pnetcdf.Variable`. **Type:** `dict` diff --git a/docs/source/api/function_api.rst b/docs/source/api/function_api.rst index 07acfaa..16b3549 100644 --- a/docs/source/api/function_api.rst +++ b/docs/source/api/function_api.rst @@ -1,5 +1,5 @@ ================ -Utility Functions +Other PnetCDF Utility Functions ================ .. autofunction:: pnetcdf::libver diff --git a/docs/source/api/variable_api.rst b/docs/source/api/variable_api.rst index 350906b..4343418 100644 --- a/docs/source/api/variable_api.rst +++ b/docs/source/api/variable_api.rst @@ -1,14 +1,16 @@ ========= -Variable +Variables ========= -Variable is a core component of a netCDF file representing an array of data +``Variable`` is a core component of a netCDF file representing an array of data values organized along one or more dimensions, with associated metadata in the -form of attributes. The ``Variable`` object in the library provides operations -to read and write the data and metadata of a variable within a netCDF file. -Particularly, data mode operations have a flexible interface, where reads and -writes can be done through either explicit function-call style methods or -indexer-style (numpy-like) syntax. +form of attributes. An instance of class :class:`pnetcdf.Variable` represents a +NetCDF variable stored in the file. The class methods provide I/O operations to +read and write the data and metadata of a NetCDF variable. + +Reading and writing a subarray of a variable can be done through either +explicit function-call style methods or Python indexer-style (numpy-like) +syntax. .. autoclass:: pnetcdf::Variable :members: ncattrs, put_att, get_att, del_att, rename_att, get_dims, diff --git a/docs/source/copyright.rst b/docs/source/copyright.rst index ef12b1c..6ae10ac 100644 --- a/docs/source/copyright.rst +++ b/docs/source/copyright.rst @@ -2,10 +2,8 @@ Copyright Statement ================ -:: - - Copyright (c) 2024 Northwestern University and Argonne National - Laboratory All rights reserved. + Copyright (c) 2024 Northwestern University and Argonne National Laboratory + All rights reserved. Portions of this software were developed by the Unidata Program at the University Corporation for Atmospheric Research. diff --git a/docs/source/index.rst b/docs/source/index.rst index 920fcd5..16c0949 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -3,16 +3,17 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -PnetCDF-Python Documentation +PnetCDF-Python User Guide ============================ **Release:** |release| -.. toctree:: - :maxdepth: 2 - :caption: Introduction - - introduction/overview +PnetCDF-python is a Python interface to PnetCDF, a high-performance parallel +I/O library for accessing netCDF files. This integration with Python allows +for easy manipulation, analysis, and visualization of netCDF data using the +rich ecosystem of Python's scientific computing libraries, making it a valuable +tool for python-based applications that require high-performance access to +netCDF files. .. toctree:: :maxdepth: 2 @@ -32,15 +33,16 @@ PnetCDF-Python Documentation .. toctree:: :maxdepth: 3 - :caption: API Documentation + :caption: API Reference api/file_api api/dimension_api api/variable_api + api/attribute_api api/function_api .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :caption: Copyright Statement copyright diff --git a/docs/source/tutorial/basic.rst b/docs/source/tutorial/basic.rst index b80c737..8e4c999 100644 --- a/docs/source/tutorial/basic.rst +++ b/docs/source/tutorial/basic.rst @@ -6,12 +6,12 @@ Basics Running Python scripts with MPI ------------------------------- - Python programs with PnetCDF-Python can be run with the command - :program:`mpiexec`. In practice, running Python programs looks like: + Python programs using PnetCDF-Python can be run with the command + :program:`mpiexec`. In practice, running a Python program looks like: - $ mpiexec -n 4 Python script.py + $ mpiexec -n 4 python script.py - to run the program with 4 processors. + to run the program with 4 MPI processes. Creating/Opening/Closing a netCDF file -------------------------------------- @@ -27,24 +27,24 @@ Creating/Opening/Closing a netCDF file Closing the netCDF file is accomplished via the :meth:`File.close` method of the ``File`` instance. - Here's an example: + Here is an example of creating a new file: .. code-block:: Python - from pnetcdf import File from mpi4py import MPI - comm = MPI.COMM_WORLD - f = File(filename="testfile.nc", mode='w', comm=comm, info=None) + import pnetcdf + + f = pnetcdf.File(filename="testfile.nc", mode='w', comm=MPI.COMM_WORLD, info=None) f.close() - Equivalent example codes in ``netCDF4-python``: + Equivalent example codes when using ``netCDF4-python``: .. code-block:: Python from mpi4py import MPI - from netCDF4 import Dataset - comm = MPI.COMM_WORLD - f = Dataset(filename="testfile.nc", mode="w", comm=comm, parallel=True) + import netCDF4 + + f = netCDF4.Dataset(filename="testfile.nc", mode="w", comm=MPI.COMM_WORLD, parallel=True) f.close() For the full example program, see ``examples/craete_open.py``. @@ -54,11 +54,11 @@ Dimensions NetCDF variables are multi-dimensional arrays. Before creating any variables, the dimensions they depend on must be established. To create a dimension, the - :meth:`File.def_dim` method is called on a File instance under define mode. + :meth:`File.def_dim` method is called on a ``File`` instance under define mode. The dimension's name is set using a Python string, while the size is defined using an integer value. To create an unlimited dimension (a dimension that can - be expanded), the size can be omitted or assigned as -1. A "Dimension" object - will be returned as a handler for this dimension. + be expanded), the parameter size can be omitted or assigned as -1. A + ``Dimension`` instance will be returned as a handler for this dimension. Here's an example (same if using netcdf4-python): @@ -70,8 +70,8 @@ Dimensions lat_dim = f.def_dim(LAT_NAME, LAT_LEN) time_dim = f.def_dim(TIME_NAME, -1) - All of the Dimension instances are stored in a dictionary as an Python - attribute of File. + All of the ``Dimension`` instances are stored in a Python dictionary as an + attribute of ``File``. .. code-block:: Python @@ -94,13 +94,13 @@ Variables ------------ NetCDF variables are similar to multidimensional array objects in Python - provided by the numpy module. To define a netCDF variable, you can utilize the - :meth:`File.def_var` method within a File instance under define mode. The - mandatory arguments for this methods include the variable name (a string in - Python) and dimensions (either a tuple of dimension names or dimension + provided by the ``numpy`` module. To define a netCDF variable, you can utilize + the :meth:`File.def_var` method within a ``File`` instance under define mode. + The mandatory arguments for this methods include the variable name (a string + in Python) and dimensions (either a tuple of dimension names or dimension instances). In addition, the user need to specify the datatype of the variable - using module-level NC constants (e.g. pnetcdf.NC_INT). The supported - data types given each file format can be found :ref:`here`. + using module-level constants (e.g. ``pnetcdf.NC_INT``). The supported data + types given each file format can be found :ref:`here`. Here's an example (same if using netcdf4-python): @@ -132,7 +132,7 @@ Attributes In a netCDF file, there are two types of attributes: global attributes and variable attributes. Global attributes are usually related to the netCDF file as a whole and may be used for purposes such as providing a title or - processing history for a netCDF file. Variable's attributes are used to + processing history for a netCDF file. ``Variable``'s attributes are used to specify properties related to the variable, such as units, special values, maximum and minimum valid values, and annotation. @@ -144,11 +144,11 @@ Attributes .. code-block:: Python # set global attributes - f.floatatt = math.pi # Option1: Python attribute assignment - f.put_att("intatt", np.int32(1)) # Option2: method put_att() + f.floatatt = math.pi # Option 1: Python attribute assignment + f.put_att("intatt", np.int32(1)) # Option 2: method put_att() f.seqatt = np.int32(np.arange(10)) - # set variable attributes + # write variable attributes var = f.variables['var'] var.floatatt = math.pi var.put_att("int_att", np.int32(1)) @@ -159,8 +159,8 @@ Attributes .. code-block:: Python # set root group attributes - f.floatatt = math.pi # Option1: Python attribute assignment - f.setncattr("intatt", np.int32(1)) # Option2: method setncattr() + f.floatatt = math.pi # Option 1: Python attribute assignment + f.setncattr("intatt", np.int32(1)) # Option 2: method setncattr() f.seqatt = np.int32(np.arange(10)) # set variable attributes @@ -169,10 +169,10 @@ Attributes var.setncattr("int_att", np.int32(1)) var.seqatt = np.int32(np.arange(10)) - The :meth:`File.ncattrs` method of a File or Variable instance can be used to - retrieve the names of all the netCDF attributes. And the __dict__ attribute of - a File or Variable instance provides all the netCDF attribute name/value pairs - in a python dictionary: + The :meth:`File.ncattrs` method of a ``File`` or ``Variable`` instance can be + used to retrieve the names of all the netCDF attributes. And the __dict__ + attribute of a ``File`` or ``Variable`` instance provides all the netCDF + attribute name/value pairs in a python dictionary: .. code-block:: Python @@ -184,14 +184,14 @@ Attributes For the full example program, see ``examples/global_attributes.py``. -Writing to variable +Writing to a variable -------------------- Once a netCDF variable instance is created, writing the variable must be done while the file is in data mode. Then for writing, there are two options: -Option1 Indexer (or slicing) syntax - You can just treat the variable like an numpy array and assign data +Option 1 Indexer (or slicing) syntax + You can just treat the variable like an ``numpy`` array and assign data to a slice. Slices are specified as a `start:stop:step` triplet. .. code-block:: Python @@ -202,9 +202,9 @@ Option1 Indexer (or slicing) syntax The indexer syntax is the same as in ``netcdf4-python`` library for writing to netCDF variable. -Option2 Method calls of put_var()/get_var() - Alternatively you can also leverage Variable.put/get_var() method of a - Variable instance to perform I/O according to specific access pattern needs. +Option 2 Method calls of put_var()/get_var() + Alternatively you can also leverage ``Variable.put/get_var()`` method of a + ``Variable`` instance to perform I/O according to specific access pattern needs. Here is the example below to write an array to the netCDF variable. The part of the netCDF variable to write is specified by giving a corner (`start`) and @@ -218,7 +218,7 @@ Option2 Method calls of put_var()/get_var() # The above line is equivalent to var[10:20, 0:50] = buff -Reading from variable +Reading from a variable ---------------------- Symmetrically, users can use two options with different syntaxes to retrieve @@ -228,10 +228,10 @@ Reading from variable .. code-block:: Python var = f.variables['var'] - # Option1 Indexer: read the topleft 10*10 corner from variable var + # Option 1 Indexer: read the top-left 10*10 corner from variable var buf = var[:10, :10] - # Option2 Method Call: equivalent to var[10:20, 0:50] + # Option 2 Method Call: equivalent to var[10:20, 0:50] buf = var.get_var_all(start = [10, 0], count = [10, 50]) Similarly, :meth:`Variable.get_var` takes the same set of optional arguments diff --git a/docs/source/tutorial/datatypes.rst b/docs/source/tutorial/datatypes.rst index 205c857..e96ae67 100644 --- a/docs/source/tutorial/datatypes.rst +++ b/docs/source/tutorial/datatypes.rst @@ -26,7 +26,7 @@ NetCDF Variable Data Types +-------+----------------+-------+----------------------------------------+---------------------+ - New data types supported in CDF-5 format: + Additional data types supported in CDF-5 format: +---------------------+----------------+-------+----------------------------------------+---------------------+ | Type | C #define | Bits | Intent of use | Numpy Equivalent | diff --git a/docs/source/tutorial/read_write.rst b/docs/source/tutorial/read_write.rst index 34b1e8f..4b30b2d 100644 --- a/docs/source/tutorial/read_write.rst +++ b/docs/source/tutorial/read_write.rst @@ -6,10 +6,10 @@ Parallel Read and Write NumPy Slicing Syntax -------------------------------------- - PnetCDF-python datasets re-use the numpy slicing syntax to read and write to - the file. Slice specifications are translated directly to PnetCDF “start, - count, stride” selections, and are a fast and efficient way to access data in - the file. The following slicing arguments are recognized: + PnetCDF-python datasets re-use the ``numpy`` slicing syntax to read and write + to the file. Slice specifications are translated directly to PnetCDF-C style + of subarray selection, i.e. using index arrays of “start, count, stride”. + The following slicing arguments are recognized: - Indices (var[1,5]) - Slices (i.e. [:] or [0:10]) @@ -29,7 +29,7 @@ NumPy Slicing Syntax # put values to the entire variable var[:] = buff - # read the topleft 10*10 corner from variable var + # read the top-left 10*10 corner from variable var print(var[:10, :10])