Merge pull request #4075 from pnorbert/update-docs-python-doe

- Restructure python API doc in separate main topic, add working exam…

docs/user_guide/source/api_full/api_full.rst

@@ -71,4 +71,3 @@ The following sections provide a summary of the API calls on each language and l
 .. include:: cxx11.rst
 .. include:: fortran.rst
 .. include:: c.rst
-.. include:: python.rst

docs/user_guide/source/api_high/api_high.rst

@@ -28,14 +28,11 @@ Currently ADIOS2 support bindings for the following languages and their minimum
 +----------+----------+-----------------------+-------------+
 | C++      | 11/newer | ``#include adios2.h`` | ``fstream`` |
 +----------+----------+-----------------------+-------------+
-| Python   | 2.7/3    | ``import adios2``     | Python IO   |
-+----------+----------+-----------------------+-------------+
 | Matlab   |          |                       |             |
 +----------+----------+-----------------------+-------------+
 
 The following sections provide a summary of the API calls on each language and links to Write and Read examples to put it all together.
 
 .. include:: cxx11.rst
-.. include:: python.rst
 .. include:: matlab.rst
 

docs/user_guide/source/api_python/adios2-doc-read-filereader.py

@@ -0,0 +1,31 @@
+import numpy as np
+from adios2 import FileReader
+
+with FileReader("cfd.bp") as s:
+    # inspect variables
+    vars = s.available_variables()
+    for name, info in vars.items():
+        print("variable_name: " + name, end=" ")
+        for key, value in info.items():
+            print("\t" + key + ": " + value, end=" ")
+        print()
+
+    nproc = s.read("nproc")
+    print(f"nproc is {nproc} of type {type(nproc)}")
+
+    # read variables return a numpy array with corresponding selection
+    steps = int(vars["physical_time"]["AvailableStepsCount"])
+    physical_time = s.read("physical_time", step_selection=[0, steps])
+    print(f"physical_time is {physical_time} of type {type(physical_time)}")
+
+    steps = int(vars["temperature"]["AvailableStepsCount"])
+    temperature = s.read("temperature", step_selection=[0, steps])
+    temp_unit = s.read_attribute("temperature/unit")
+    print(f"temperature array size is {temperature.size} of shape {temperature.shape}")
+    print(f"temperature unit is {temp_unit} of type {type(temp_unit)}")
+
+    steps = int(vars["pressure"]["AvailableStepsCount"])
+    pressure = s.read("pressure", step_selection=[0, steps])
+    press_unit = s.read_attribute("pressure/unit")
+
+    print()

docs/user_guide/source/api_python/adios2-doc-read.py

@@ -0,0 +1,31 @@
+import numpy as np
+from adios2 import Stream
+
+with Stream("cfd.bp", "r") as s:
+    # steps comes from the stream
+    for _ in s.steps():
+        # track current step
+        print(f"Current step is {s.current_step()}")
+
+        # inspect variables in current step
+        for name, info in s.available_variables().items():
+            print("variable_name: " + name, end=" ")
+            for key, value in info.items():
+                print("\t" + key + ": " + value, end=" ")
+            print()
+
+        if s.current_step() == 0:
+            nproc = s.read("nproc")
+            print(f"nproc is {nproc} of type {type(nproc)}")
+
+        # read variables return a numpy array with corresponding selection
+        physical_time = s.read("physical_time")
+        print(f"physical_time is {physical_time} of type {type(physical_time)}")
+        temperature = s.read("temperature")
+        temp_unit = s.read_attribute("temperature/unit")
+        print(f"temperature array size is {temperature.size} of shape {temperature.shape}")
+        print(f"temperature unit is {temp_unit} of type {type(temp_unit)}")
+        pressure = s.read("pressure")
+        press_unit = s.read_attribute("pressure/unit")
+        print(f"pressure unit is {press_unit} of type {type(press_unit)}")
+        print()

docs/user_guide/source/api_python/adios2-doc-write.py

@@ -0,0 +1,34 @@
+from mpi4py import MPI
+import numpy as np
+from adios2 import Stream
+
+comm = MPI.COMM_WORLD
+rank = comm.Get_rank()
+size = comm.Get_size()
+
+nx = 10
+shape = [size * nx]
+start = [rank * nx]
+count = [nx]
+
+temperature = np.zeros(nx, dtype=np.double)
+pressure = np.ones(nx, dtype=np.double)
+delta_time = 0.01
+physical_time = 0.0
+nsteps = 5
+
+with Stream("cfd.bp", "w", comm) as s:
+    # NSteps from application
+    for _ in s.steps(nsteps):
+        if rank == 0 and s.current_step() == 0:
+            # write a Python integer
+            s.write("nproc", size)
+
+        # write a Python floating point value
+        s.write("physical_time", physical_time)
+        # temperature and pressure are numpy arrays
+        s.write("temperature", temperature, shape, start, count)
+        s.write_attribute("temperature/unit", "K")
+        s.write("pressure", pressure, shape, start, count)
+        s.write_attribute("pressure/unit", "Pa")
+        physical_time += delta_time

docs/user_guide/source/api_python/api_python.rst

@@ -0,0 +1,8 @@
+####################################
+Python APIs
+####################################
+
+.. include:: python_example.rst
+.. include:: python.rst
+.. include:: python_bindings.rst
+.. include:: python_transition_from_high.rst

docs/user_guide/source/api_python/python.rst

@@ -0,0 +1,29 @@
+*************************
+adios2 classes for Python
+*************************
+
+``Stream`` is a high-level class that can perform most of the ADIOS functionality. ``FileReader`` is just a convenience class and is the same as Stream with "rra" (ReadRandomAccess) mode. FileReaders do not work with for loops as opposed to Streams that work step-by-step, rather one can access any step of any variable at will. The other classes, ``Adios``, ``IO``, ``Engine``, ``Variable``, ``Attribute`` and ``Operator`` correspond to the C++ classes. One needs to use them to extend the capabilities of the ``Stream`` class (e.g. using an external XML file for runtime configuration, changing the engine for the run, setting up a compression operator for an output variable, etc.)
+
+.. autoclass:: adios2::Stream
+    :members:
+
+.. autoclass:: adios2::FileReader
+    :members:
+
+.. autoclass:: adios2::Adios
+    :members:
+
+.. autoclass:: adios2::IO
+    :members:
+
+.. autoclass:: adios2::Engine
+    :members:
+
+.. autoclass:: adios2::Variable
+    :members:
+
+.. autoclass:: adios2::Attribute
+    :members:
+
+.. autoclass:: adios2::Operator
+    :members:

docs/user_guide/source/api_python/python_bindings.rst

@@ -0,0 +1,61 @@
+**********************
+Python bindings to C++
+**********************
+
+.. note::
+
+   The bindings to the C++ functions is the basis of the native Python API described before. It is still accessible to users who used the "Full Python API" pre-2.10. In order to make old scripts working with 2.10 and later versions, change the import line in the python script.
+
+.. code-block:: python
+
+    import adios2.bindings as adios2
+
+The full Python APIs follows very closely the full C++11 API interface. All of its functionality is now in the native API as well, so its use is discouraged for future scripts.
+
+Examples using the Python bindings in the ADIOS2 repository
+-----------------------------------------------------------
+
+- Simple file-based examples
+    - examples/hello/helloWorld/hello-world-bindings.py
+    - examples/hello/bpReader/bpReaderHeatMap2D-bindings.py
+    - examples/hello/bpWriter/bpWriter-bindings.py
+
+- Staging examples using staging engines SST and DataMan
+    - examples/hello/sstWriter/sstWriter-bindings.py
+    - examples/hello/sstReader/sstReader-bindings.py
+
+
+ADIOS class
+--------------
+.. autoclass:: adios2.bindings::ADIOS
+    :members:
+
+IO class
+--------------
+.. autoclass:: adios2.bindings::IO
+    :members:
+
+Variable class
+--------------
+.. autoclass:: adios2.bindings::Variable
+    :members:
+
+Attribute class
+---------------
+.. autoclass:: adios2.bindings::Attribute
+    :members:
+
+Engine class
+--------------
+.. autoclass:: adios2.bindings::Engine
+    :members:
+
+Operator class
+--------------
+.. autoclass:: adios2.bindings::Operator
+    :members:
+
+Query class
+--------------
+.. autoclass:: adios2.bindings::Query
+    :members: