Various documentation updates

Author: amorison

docs/sources/apiref/step.rst

@@ -4,4 +4,4 @@ _step
 .. automodule:: stagpy._step
    :members:
    :private-members:
-   :exclude-members: _init_shape, _get_raw_data
+   :exclude-members: _init_shape, _get_raw_data, _scale_radius_mo

docs/sources/cookbook/nura.rst

@@ -9,40 +9,38 @@ for that. The following script can be used to make a loglog plot of the Nusselt
 number as function of the Rayleigh number using all directories stored where
 the script is executed::
 
-  #!/usr/bin/env python3
-  """Nu=f(Ra) from a set of stagyy results in different directories"""
-
-  import matplotlib.pyplot as plt
-  import numpy as np
-  from stagpy import stagyydata
-  from pathlib import Path
-
-  ran = []
-  nun = []
-
-  pwd = Path('Examples')
-  for rep in pwd.glob('ra-*'):
-      print('In directory ', rep)
-      sdat = stagyydata.StagyyData(rep)
-      # get the value of the Rayleigh number
-      ran.append(sdat.par['refstate']['ra0'])
-      # get the last value of the Nusselt number
-      nun.append(sdat.steps[-1].timeinfo['Nutop'])
-
-  ran = np.array(ran)
-  nun = np.array(nun)
-
-  # sort by Ra#
-  indexes = ran.argsort()
-
-  fig = plt.figure()
-  plt.loglog(ran[indexes], nun[indexes], 'o--')
-  plt.xlabel(r'Rayleigh number')
-  plt.ylabel(r'Nusselt number')
-  plt.savefig('Ra-Nu.pdf')
-  plt.close(fig)
+    #!/usr/bin/env python3
+    """Nu=f(Ra) from a set of stagyy results in different directories"""
+
+    from pathlib import Path
+    from stagpy.stagyydata import StagyyData
+    import matplotlib.pyplot as plt
+    import numpy as np
+
+    ran = []
+    nun = []
+
+    pwd = Path('Examples')
+    for folder in pwd.glob('ra-*'):
+        print('In directory', folder)
+        sdat = StagyyData(folder)
+        # get the value of the Rayleigh number
+        ran.append(sdat.par['refstate']['ra0'])
+        # get the last value of the Nusselt number
+        nun.append(sdat.tseries['Nutop'].values[-1])
+
+    ran = np.array(ran)
+    nun = np.array(nun)
+
+    # sort by Ra#
+    indexes = ran.argsort()
+
+    plt.loglog(ran[indexes], nun[indexes], 'o--')
+    plt.xlabel('Rayleigh number')
+    plt.ylabel('Nusselt number')
+    plt.savefig('Ra-Nu.pdf')
 
 Note that this particular example is only relevant if the solutions
 have all reached a steady-state. In the case where the solution is
 only in statistical steady state, a time average is more relevant. It
-can be computed using the whole sdat.tseries table in each directory.
+can be computed using :func:`~stagpy.time_series.compstat`.

docs/sources/cookbook/vrmsra.rst

@@ -7,31 +7,26 @@ parameters. Suppose again that several directories named ra-* are present in
 your working directory. The following script will plot the RMS velocity as
 function of time for all these directories::
 
-  #!/usr/bin/env python3
-  """Nu=f(Ra) from a set of stagyy results in different directories"""
+    #!/usr/bin/env python3
+    """vrms(t) from a set of StagYY runs."""
 
-  import matplotlib.pyplot as plt
-  from stagpy import stagyydata
-  from pathlib import Path
-  from numpy import log10
+    from pathlib import Path
+    from stagpy.stagyydata import StagyyData
+    import matplotlib.pyplot as plt
+    import numpy as np
 
-  fig = plt.figure()
+    pwd = Path('Examples/')
+    for folder in pwd.glob('ra-*'):
+        print('In directory', folder)
+        sdat = StagyyData(folder)
+        # Reference Rayleigh number as a power of ten
+        ra0_log10 = int(np.log10(sdat.par['refstate']['ra0']))
+        # vrms time series object
+        vrms = sdat.tseries['vrms']
+        # plot time vs vrms values
+        plt.plot(vrms.time, vrms.values, label=f'$Ra=10^{{{ra0_log10}}}$')
 
-  pwd = Path('Examples/')
-  for rep in pwd.glob('ra-*'):
-      print('In directory ', rep)
-      sdat = stagyydata.StagyyData(rep)
-      # get the value of the Rayleigh number
-      ra0 = sdat.par['refstate']['ra0']
-      # get the time vector
-      time = sdat.tseries['t']
-      # get the vrms vector
-      vrms = sdat.tseries['vrms']
-      # plot
-      plt.plot(time, vrms, label=r'$Ra=10^{%1d}$' % log10(ra0))
-
-  plt.legend()
-  plt.xlabel(r'Time')
-  plt.ylabel(r'RMS velocity')
-  plt.savefig('time-vrms.pdf')
-  plt.close(fig)
+    plt.legend()
+    plt.xlabel('Time')
+    plt.ylabel('RMS velocity')
+    plt.savefig('time-vrms.pdf')

docs/sources/stagyydata.rst

@@ -25,15 +25,15 @@ A :class:`~stagpy.stagyydata.StagyyData` instance has two attributes to access
 time steps and snapshots in a consistent way:
 :attr:`~stagpy.stagyydata.StagyyData.steps` and
 :attr:`~stagpy.stagyydata.StagyyData.snaps`. Accessing the ``n``-th time step
-or the ``m-th`` snapshot is done using the item access notation (square
+or the ``m``-th snapshot is done using the item access notation (square
 brackets)::
 
     sdat.steps[n]
     sdat.snaps[m]
 
-These two expressions each return a :class:`~stagpy.stagyydata._Step` instance.
+These two expressions each return a :class:`~stagpy._step.Step` instance.
 Moreover, if the ``m``-th snapshot was done at the ``n``-th step, both
-expressions return the same :class:`~stagpy.stagyydata._Step` instance. In
+expressions return the same :class:`~stagpy._step.Step` instance. In
 other words, if for example the 100th snapshot was made at the 1000th step,
 ``sdat.steps[1000] is sdat.snaps[100]`` is true.  The correspondence between
 time steps and snapshots is deduced from available binary files.
@@ -134,8 +134,8 @@ Both are :class:`pandas.Series` indexed by the available variables.
 Geometry
 --------
 
-Geometry information are read from binary files.  :attr:`_Step.geom
-<stagpy.stagyydata._Step.geom>` has various attributes defining the geometry of
+Geometry information are read from binary files.  :attr:`Step.geom
+<stagpy._step.Step.geom>` has various attributes defining the geometry of
 the problem.
 
 ``cartesian``, ``curvilinear``, ``cylindrical``, ``spherical`` and ``yinyang``
@@ -152,24 +152,20 @@ are the total number of points in the various spatial directions. Note that
 ``nttot``, ``nptot`` and ``nrtot`` are the same as ``nxtot``, ``nytot`` and
 ``nztot`` regardless of whether the geometry is cartesian or curvilinear.
 
-``x_coord``, ``y_coord`` and ``z_coord`` as well as ``t_coord``, ``p_coord``
-and ``r_coord`` are the coordinates of cell centers in the three directions.
-As for the total number of points, they are the same regardless of the actual
-geometry.
+``x_centers``, ``y_centers``, and ``z_centers`` as well as ``t_centers``,
+``p_centers``, and ``r_centers`` are the coordinates of cell centers in the
+three directions.  As for the total number of points, they are the same
+regardless of the actual geometry.
 
-``x_mesh``, ``y_mesh`` and ``z_mesh`` are three dimensional meshes containing
-the **cartesian** coordinates of cell centers (even if the geometry is
-curvilinear).
-
-``t_mesh``, ``p_mesh`` and ``r_mesh`` are three dimensional meshes containing
-the **spherical** coordinates of cell centers (these are set as ``None`` if the
-geometry is cartesian).
+Similarly to ``*_centers`` attributes, ``x_walls``, ``y_walls``, and
+``z_walls`` as well as ``t_walls``, ``p_walls``, and ``r_walls`` are the
+coordinates of cell walls in the three directions.
 
 Scalar and vector fields
 ------------------------
 
-Vector and scalar fields are accessible through :attr:`_Step.fields
-<stagpy.stagyydata._Step.fields>` using their name as key. For example, the
+Vector and scalar fields are accessible through :attr:`Step.fields
+<stagpy._step.Step.fields>` using their name as key. For example, the
 temperature field of the 100th snapshot is obtained with
 ``sdat.snaps[100].fields['T']``.  Valid names of fields can be obtained by
 running ``% stagpy var``. Fields are four dimensional arrays, with indices in
@@ -179,7 +175,7 @@ Tracers data
 ------------
 
 Tracer data (position, mass, composition...) are accessible through
-:attr:`_Step.tracers<stagpy.stagyydata._Step.tracers>` using the
+:attr:`Step.tracers<stagpy._step.Step.tracers>` using the
 property name as key.  They are organized by block.  For example,
 the masses of tracers in the first block is obtained with
 ``sdat.snaps[-1].tracers['Mass'][0]``. This is a one dimensional