CPEX-0045 doc updates: IsoParametric SolutionInterpolation_t, variable-order patterns

- highorder.rst: expand IsoParametric section for SolutionInterpolation_t:
  clarify no LagrangeControlPoints child, mandatory ElementInterpolation_t
  prerequisite, and add read/write code examples
- highorder.rst: add 'Variable-Order Configurations' section documenting
  Pattern A (variable order per cell via disjoint PointRange) and Pattern B
  (variable order per field variable with same PointRange, different arrays)
  with code examples for both; includes note on combining patterns
- c_api.rst: fix example code to use cg_sol_ptset_write (not the removed
  cg_sol_write + cg_ptset_write pair); add Pattern B example showing
  Density at order 2 and VelocityX at order 3 over the same cell range

Author: brtnfld

source/standard/MLL/api/c_api.rst

@@ -535,36 +535,59 @@ ____________________________________________
       **without** a ``PointRange`` or ``PointList`` will return ``CG_ERROR``. This is enforced by the MLL to
       prevent ambiguous p-adaptive configurations.
 
-   **Example: P-Adaptation with Variable Orders**
+   **Example A: Variable Order Per Cell (P-Adaptation)**
+
+   Different cells use different polynomial orders.  Use ``cg_sol_ptset_write``
+   to create a ``FlowSolution_t`` that includes a ``PointRange`` or ``PointList``
+   in a single call:
 
    .. code-block:: c
 
-      /* Example: Zone with 100 elements using two different polynomial orders */
+      /* Zone with 100 elements using two different polynomial orders */
       int fn, B, Z, S_order3, S_order4;
-      cgsize_t range_1_to_50[2] = {1, 50};
-      cgsize_t range_51_to_100[2] = {51, 100};
+      cgsize_t range_1_to_50[2]    = {1,  50};
+      cgsize_t range_51_to_100[2]  = {51, 100};
 
-      /* 1. Create solution node for Order 3 elements (elements 1-50) */
-      cg_sol_write(fn, B, Z, "Solution_Order3", CellCenter, &S_order3);
+      /* Order-3 elements (cells 1-50): create solution with PointRange in one call */
+      cg_sol_ptset_write(fn, B, Z, "Solution_Order3",
+                         CGNS_ENUMV(CellCenter),
+                         CGNS_ENUMV(PointRange), 2, range_1_to_50, &S_order3);
+      cg_sol_interpolation_order_write(fn, B, Z, S_order3, 3, 0);
 
-      /* CRITICAL: Specify which elements use Order 3 */
-      cg_ptset_write(fn, B, Z, S_order3, PointRange, 2, range_1_to_50);
+      /* Order-4 elements (cells 51-100) */
+      cg_sol_ptset_write(fn, B, Z, "Solution_Order4",
+                         CGNS_ENUMV(CellCenter),
+                         CGNS_ENUMV(PointRange), 2, range_51_to_100, &S_order4);
+      cg_sol_interpolation_order_write(fn, B, Z, S_order4, 4, 0);
 
-      /* Write interpolation order for this subset */
-      cg_sol_interpolation_order_write(fn, B, Z, S_order3, 3, 0);
+      /* Write field data to each node using cg_field_write() */
 
-      /* 2. Create solution node for Order 4 elements (elements 51-100) */
-      cg_sol_write(fn, B, Z, "Solution_Order4", CellCenter, &S_order4);
+   **Example B: Variable Order Per Field Variable**
 
-      /* CRITICAL: Specify which elements use Order 4 */
-      cg_ptset_write(fn, B, Z, S_order4, PointRange, 2, range_51_to_100);
+   The *same* cells are present in both ``FlowSolution_t`` nodes, but each
+   node carries a different field array stored at a different polynomial order.
 
-      /* Write interpolation order for this subset */
-      cg_sol_interpolation_order_write(fn, B, Z, S_order4, 4, 0);
+   .. code-block:: c
 
-      /* Write actual solution data to each node */
-      /* Solution_Order3 will have N_DOFs = (3+1)^d per element (element-type dependent) */
-      /* Solution_Order4 will have N_DOFs = (4+1)^d per element (element-type dependent) */
+      /* Zone with 100 elements; Density stored at order 2, VelocityX at order 3 */
+      int fn, B, Z, S_density, S_vel;
+      cgsize_t range_all[2] = {1, 100};
+
+      /* Density at spatial order 2 */
+      cg_sol_ptset_write(fn, B, Z, "FS_Density",
+                         CGNS_ENUMV(CellCenter),
+                         CGNS_ENUMV(PointRange), 2, range_all, &S_density);
+      cg_sol_interpolation_order_write(fn, B, Z, S_density, 2, 0);
+      cg_field_write(fn, B, Z, S_density, CGNS_ENUMV(RealDouble),
+                     "Density", density_data, &fld);
+
+      /* VelocityX at spatial order 3 */
+      cg_sol_ptset_write(fn, B, Z, "FS_VelocityX",
+                         CGNS_ENUMV(CellCenter),
+                         CGNS_ENUMV(PointRange), 2, range_all, &S_vel);
+      cg_sol_interpolation_order_write(fn, B, Z, S_vel, 3, 0);
+      cg_field_write(fn, B, Z, S_vel, CGNS_ENUMV(RealDouble),
+                     "VelocityX", velx_data, &fld);
 
    See :ref:`High-Order Interpolation <HighOrderInterpolation>` in the SIDS for complete details on
    interpolation metadata and data layout.

source/standard/SIDS/highorder.rst

@@ -1137,13 +1137,40 @@ The interpolation space for Cartesian modal interpolations uses ordered sets of
 IsoParametric Interpolation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-:sidskey:`IsoParametric` interpolation indicates that the solution uses the same interpolation functions as the mesh geometry. In this case:
+:sidskey:`IsoParametric` interpolation indicates that the solution uses the same interpolation
+functions as the mesh geometry. This applies to :sidsref:`SolutionInterpolation_t` nodes only.
 
-* The element's own node coordinates from :sidsref:`GridCoordinates_t` serve as control points
-* No :sidskey:`LagrangeControlPoints` need to be specified in :sidsref:`SolutionInterpolation_t`
-* The interpolation type is simply marked as :sidskey:`IsoParametric`
+* The element's own node coordinates from :sidsref:`GridCoordinates_t` serve as the control points.
+* No :sidskey:`LagrangeControlPoints` child shall be present in the :sidsref:`SolutionInterpolation_t` node.
+* An :sidsref:`ElementInterpolation_t` node for the same element type **must** already exist in
+  :sidsref:`Family_t`, defining the geometric interpolation whose basis is inherited.
+* The :sidskey:`InterpolationType_t` child of :sidsref:`SolutionInterpolation_t` is set to
+  :sidskey:`IsoParametric`.
 
-This approach is commonly used in finite element methods where the solution is interpolated using the same basis functions as the geometric mapping.
+This approach is commonly used in finite element methods where the solution is expressed in the same
+basis as the geometric mapping (pure isoparametric elements).
+
+**Example**
+
+.. code-block:: c
+
+   int fam, sn;
+   /* Mesh family already has an ElementInterpolation_t for QUAD_4 */
+   cg_solution_interpolation_write(fn, B, fam, "QUAD4_IsoParam",
+                                   CGNS_ENUMV(QUAD_4), /*spatialOrder=*/1, /*temporalOrder=*/0,
+                                   CGNS_ENUMV(IsoParametric), &sn);
+   /* No cg_solution_interpolation_points_write() call required */
+
+Reading back:
+
+.. code-block:: c
+
+   char name[33];
+   CGNS_ENUMT(ElementType_t)     et;
+   CGNS_ENUMT(InterpolationType_t) it;
+   int os, ot;
+   cg_solution_interpolation_read(fn, B, fam, 1, name, &et, &os, &ot, &it);
+   /* it == IsoParametric, no LagrangeControlPoints child exists */
 
 Usage in CGNS Files
 ^^^^^^^^^^^^^^^^^^^
@@ -1807,6 +1834,68 @@ This maps :math:`\theta \in [-1, 1]`, matching the parametric time convention an
 .. important::
    **Storage**: When using normalized coordinates :math:`(\xi, \eta, \zeta, \theta)`, the normalization parameters (characteristic length :math:`h^e` and time slab bounds :math:`T_n, T_{n+1}`) must be stored to enable reconstruction of physical values. This ensures data portability and prevents ambiguity in interpreting modal coefficients.
 
+.. _variable_order_configurations:
+
+Variable-Order Configurations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+CGNS supports two distinct variable-order patterns using :sidsref:`FlowSolution_t` with
+``GridLocation = CellCenter`` and a ``PointRange`` or ``PointList``.
+
+**Pattern A: Variable order per cell (p-adaptation)**
+
+Different cells within the same zone use different polynomial orders.  Create one
+:sidsref:`FlowSolution_t` per distinct order, each with a disjoint
+``PointRange``/``PointList`` identifying its cell subset.  Each node carries an
+``InterpolationOrders`` child (written via ``cg_sol_interpolation_order_write``)
+specifying ``[SpatialOrder, TemporalOrder]`` for that subset.
+
+Example — 8 TETRA_4 elements split at order 2 and order 3:
+
+.. code-block:: c
+
+   cgsize_t lo_range[2] = {1, 4};   /* cells 1-4 at order 2 */
+   cgsize_t hi_range[2] = {5, 8};   /* cells 5-8 at order 3 */
+
+   cg_sol_ptset_write(fn, B, Z, "FS_P2", CGNS_ENUMV(CellCenter),
+                      CGNS_ENUMV(PointRange), 2, lo_range, &S1);
+   cg_sol_interpolation_order_write(fn, B, Z, S1, 2, 0);
+
+   cg_sol_ptset_write(fn, B, Z, "FS_P3", CGNS_ENUMV(CellCenter),
+                      CGNS_ENUMV(PointRange), 2, hi_range, &S2);
+   cg_sol_interpolation_order_write(fn, B, Z, S2, 3, 0);
+
+**Pattern B: Variable order per field variable**
+
+All cells share the same ``PointRange`` (typically the full zone), but individual
+field arrays (``DataArray_t`` children) are stored at different polynomial orders.
+Use a separate :sidsref:`FlowSolution_t` per distinct order, each carrying only the
+field arrays that belong to that order.
+
+Example — ``Density`` at order 2 and ``VelocityX`` at order 3, over all 8 cells:
+
+.. code-block:: c
+
+   cgsize_t all[2] = {1, 8};
+
+   cg_sol_ptset_write(fn, B, Z, "FS_Density", CGNS_ENUMV(CellCenter),
+                      CGNS_ENUMV(PointRange), 2, all, &S1);
+   cg_sol_interpolation_order_write(fn, B, Z, S1, 2, 0);
+   cg_field_write(fn, B, Z, S1, CGNS_ENUMV(RealDouble), "Density", rho, &fld);
+
+   cg_sol_ptset_write(fn, B, Z, "FS_VelocityX", CGNS_ENUMV(CellCenter),
+                      CGNS_ENUMV(PointRange), 2, all, &S2);
+   cg_sol_interpolation_order_write(fn, B, Z, S2, 3, 0);
+   cg_field_write(fn, B, Z, S2, CGNS_ENUMV(RealDouble), "VelocityX", velx, &fld);
+
+.. note::
+   Pattern A and Pattern B can be combined: a file may have some
+   ``FlowSolution_t`` nodes that differ in both cell subset *and* polynomial
+   order, while others share the same cell subset but carry different field
+   variables.  The :sidsref:`Family_t` must contain a
+   :sidsref:`SolutionInterpolation_t` entry for every (ElementType, SpatialOrder,
+   TemporalOrder) triplet that appears in the file.
+
 References
 ^^^^^^^^^^