Options refactoring and docs update

doc/conf.py

@@ -20,4 +20,4 @@
 extensions.extend(["numpydoc"])  # noqa: F405
 
 # mock import for autodoc
-autodoc_mock_imports = ["numpy", "mpi4py", "petsc4py"]
+autodoc_mock_imports = ["numpy", "mpi4py", "petsc4py", "baseclasses"]

doc/options.rst

@@ -3,72 +3,4 @@
 Options
 =======
 
-Here are the options currently available in IDWarp.
-
-======================================  ==========  ===========================================   ================================================================================================================================================================================
-Parameter                                  Type       Default                                       Description
-======================================  ==========  ===========================================   ================================================================================================================================================================================
-`gridFile`                              `str`       `None`                                        This is the grid file to use. It must always be spcified. It may be a structured or
-                                                                                                  unstructured CGNS file or it may be an OpenFOAM directory containing a mesh specification.
-
-`fileType`                              `str`       `CGNS`                                        Specify the type of grid file. Valid options are 'CGNS' or 'OpenFOAM'
-
-`specifiedSurfaces`                     `list`      `None`                                        This option is used to specify which surfaces are used to build the surface tree where 
-                                                                                                  deformations are to be specified. The default is 'None' which will automatically use all wall-type surfaces
-                                                                                                  in the grid file. For CGNS files this corresponds to the following boundary condtiions:
-                                                                                                  'BCWall', 'BCWallViscous', 'BCWallViscousHeatFlux', 'BCWallViscousAdiabatic', 'BCWallInviscid'.
-                                                                                                  For OpenFOAM files, all 'Patch' and 'Wall' surfaces are assumed by default. If a non-None value
-												  is given it should be list of families the use wants to use to generate the surface definition. 
-
-`symmetrySurfaces`                      `list`      `None`                                        This option is used to specify which surfaces are used to determine symmetry planes. The default
-                                                                                                  is 'None' which will automatically use the 'BCSymmetryPlane' contidions found the CGNS files. 
-                                                                                                  This option is only valid for structured CGNS files. If a non-None value is given it should be 
-												  a list of families. 
-
-`symmetryPlanes`                        `list`      `None`                                        This is sort of a "last-resort" option. It is used to overwrite and explicitly define symmetry conditions
-                                                                                                  IDWarp is to use. It is the only method for specifying symmetry for unstructured CGNS files and OpenFOAM files. 
-												  For the 'symmetrySurfaces' option to be active, 'symmetryPlanes' must be None. If 'symmetryPlanes' is not 'None' it
-												  is expected to be a list of the following form: [ [[x1, y1, z1], [nx1, ny1, nz1]], [[x2, y2, z2], [nx2, ny2, nz2]] ]. 
-												  The previous example defines two symmetry planes using a point-normal approach. The first plane is defined by pt=(x1,y1,z1) with 
-												  normal=(nx1, ny1, nz1) and the second plane is defined with pt=(x2,y2,z2), normal=(nx2, ny2, nz2). The normal direction should be 
-												  normalized to unit magnitude. Note that no symmetry may be specified with the option 'symmetryPlanes':[]. 
-
-`aExp`                                  `float`     `3.0`                                         This is the first exponent in the inverse distance calc. However, for efficiency reasons this value is 
-                                                                                                  hard-coded and not currently available to be changed by the user. 
-
-`bExp`                                  `float`     `5.0`                                         This is the second exponent in the inverse distance calc. However, for efficiency reasons this value is 
-                                                                                                  hard-coded and not currently available to be changed by the user. 
-
-`LdefFact`                              `float`     `1.0`                                         This parameter is used to determine how "far" into the field a surface deformation propagates before it is attenuated. 
-                                                                                                  For small shape modifications, such as small changes to the shape of a airfoil, the default value of 1.0 is likely to be
-												  sufficient. However, for much larger changes in the surface such as wing planform changes, much larger values tend to be more
-												  robust. For these cases, values in the range 50-100 are common. 
-
-`alpha`                                 `float`     `0.25`                                        This value determines how the two different exponent terms are blended. It determines how much of the higher exponent bExp
-                                                                                                  term is used. Typical values are between 0.1 and 0.3. A lower value 
-                                                                                                  prioritizes full blending and may result in quality reduction in the near-wall boundary layer. Higher values of alpha will 
-												  tend maintain near wall quality better, but may give unacceptable skewness in the transition region between where bExp is most
-												  significant to where aExp is more significant. 
-
-`errTol`                                `float`     `0.0001`                                      This is the relative tolerance used to the fast sum approximation. A larger tolerance is faster, but may result in small 
-                                                                                                  mesh imperfections away from the surface. If mesh edge lengths grow uniformly away from the body, small "errors" is the node 
-												  position are not an issue. However, if the mesh has small edge lengths a great distance from the body, these imperfections may cause
-												  issues and it may be required to lower the tolerance by an order of magnitude or two at the cost of more computational time. 
-
-`evalMode`                              `str`       `fast`                                        How to compute the sums. The default which should be used at all times is 'fast'. The other option is 'exact' which is only 
-                                                                                                  typically used for debugging or comparison purposes. 
-
-`useRotations`                          `boolean`   `True`                                        Flag specifying if rotations are to be interpolated in addition to displacements. For small mesh changes it may not be necessary to
-                                                                                                  interpolate rotations. However, if the surface is undergoing large changes in orientation, using rotations will help preseve 
-												  boundary layer orthogonality which is generally desirable. 
-
-`zeroCornerRotations`                   `boolean`   `True`                                        Flag specifying if rotations at sharp corners (cornerAngle defines "sharp") are to be zeroed and not contribute to the deformation. 
-                                                                                                  Since the normal direction is not well defined at a corner point, including them may cause issues on some grids. 
-
-`cornerAngle`                           `float`     `30.0`                                        The minimum deviation between surface normals surrounding a node for it to be considered a corner point. 
-
-'bucketSize`                            `int`       `8`                                           The size of the "buckets" at the last level of the KD-tree. A large bucket size reduces the number of levels in the tree and the 
-                                                                                                  overall tree size but may require more computation since a less fine granularity of leaves are available. Experiments have indicated 
-												  there is little difference in run time for bucket sizes 1, 2, 4 and 8. 
-
-======================================  ==========  ===========================================   ================================================================================================================================================================================
+.. optionstable:: idwarp.USMesh

doc/options.yaml

@@ -0,0 +1,112 @@
+gridFile:
+  desc: >
+    This is the grid file to use.
+    It must always be specified.
+    It may be a structured or unstructured grid file or it may be an OpenFOAM directory containing a mesh specification.
+
+fileType:
+  desc: Specify the type of grid file.
+  CGNS: CGNS file
+  OpenFOAM: OpenFOAM directory
+  PLOT3D: PLOT3D file
+
+specifiedSurfaces:
+  desc: >
+    This option is used to specify which surfaces are used to build the surface tree where deformations are to be specified.
+    The default is None which will automatically use all wall-type surfaces in the grid file.
+    For CGNS files this corresponds to the following boundary condtiions: ``BCWall``, ``BCWallViscous``, ``BCWallViscousHeatFlux``, ``BCWallViscousAdiabatic``, ``BCWallInviscid``.
+    For OpenFOAM files, all ``patch`` and ``wall`` surfaces are assumed by default.
+    If a non-None value is given it should be list of families the use wants to use to generate the surface definition.
+
+symmetrySurfaces:
+  desc: > 
+    This option is used to specify which surfaces are used to determine symmetry planes.
+    If None, IDwarp will automatically use the ``BCSymmetryPlane`` conditions in the CGNS files.
+    This option is only valid for structured CGNS files.
+    If a non-None value is given, it should be a list of families.
+
+symmetryPlanes:
+  desc: >
+    This is sort of a "last-resort" option.
+    It is used to overwrite and explicitly define symmetry conditions IDWarp is to use.
+    It is the only method for specifying symmetry for unstructured CGNS files and OpenFOAM files.
+    For the ``symmetrySurfaces`` option to be active, ``symmetryPlanes`` must be None.
+    If ``symmetryPlanes`` is not None, it is expected to be a list of the following form:
+    [ [[x1, y1, z1], [nx1, ny1, nz1]], [[x2, y2, z2], [nx2, ny2, nz2]] ].
+    The previous example defines two symmetry planes using a point-normal approach.
+    The first plane is defined by pt=(x1,y1,z1) with normal=(nx1, ny1, nz1) and the second plane is defined with pt=(x2,y2,z2), normal=(nx2, ny2, nz2).
+    The normal direction should be normalized to unit magnitude.
+    Note that no symmetry may be specified with an empty list.
+
+aExp:
+  desc: >
+    This is the first exponent in the inverse distance calc.
+    However, for efficiency reasons this value is hard-coded and not currently available to be changed by the user.
+
+bExp:
+  desc: >
+    This is the second exponent in the inverse distance calc.
+    However, for efficiency reasons this value is hard-coded and not currently available to be changed by the user.
+
+LdefFact:
+  desc: >
+    This parameter is used to determine how "far" into the field a surface deformation propagates before it is attenuated.
+    For small shape modifications, such as small changes to the shape of a airfoil, the default value of 1.0 is likely to be sufficient.
+    However, for much larger changes in the surface such as wing planform changes, much larger values tend to be more robust.
+    For these cases, values in the range 50-100 are common.
+
+alpha:
+  desc: >
+    This value determines how the two different exponent terms are blended.
+    It determines how much of the higher exponent ``bExp`` term is used.
+    Typical values are between 0.1 and 0.3.
+    A lower value prioritizes full blending and may result in quality reduction in the near-wall boundary layer.
+    Higher values will tend maintain near wall quality better, but may give unacceptable skewness in the transition region between where ``bExp`` is most significant to where ``aExp`` is more significant.
+
+errTol:
+  desc: > 
+    This is the relative tolerance used for the fast sum approximation.
+    A larger tolerance is faster, but may result in small mesh imperfections away from the surface.
+    If mesh edge lengths grow uniformly away from the body, small "errors" in the node position are not an issue.
+    However, if the mesh has small edge lengths a great distance from the body, these imperfections may cause issues and it may be required to lower the tolerance by an order of magnitude or two at the cost of more computational time.
+
+evalMode:
+  desc: How to compute the sums.
+  fast: This should be used for almost all purposes.
+  exact: This is typically used only for debugging or comparison purposes.
+
+symmTol:
+  desc: > 
+    Possibly deprecated option.
+    IDWarp currently uses the BC info in the CGNS meshes to figure out which nodes are on the symmetry plane.
+    This option seems to be a leftover from older implementations.
+    It was used to specify the distance from the symmetry plane for a node to tag it as a symmetry plane node.
+
+useRotations:
+  desc: >
+    Flag specifying if rotations are to be interpolated in addition to displacements.
+    For small mesh changes it may not be necessary to interpolate rotations.
+    However, if the surface is undergoing large changes in orientation, using rotations will help preserve boundary layer orthogonality which is generally desirable.
+
+zeroCornerRotations:
+  desc: >
+    Flag specifying if rotations at corners (defined by ``cornerAngle``) are to be zeroed and not contribute to the deformation.
+    Since the normal direction is not well defined at a corner point, including them may cause issues on some grids.
+
+cornerAngle:
+  desc: >
+    The minimum deviation in degrees between surface normals surrounding a node for it to be considered a corner point.
+
+restartFile:
+  desc: >
+    A restart file can be used to load the node coefficients to IDWarp to speed up initialization.
+    There are 3 execution paths:
+    If no restart file is provided, the code performs a full initialization.
+    If the restart file is provided but the file does not exist or does not match with some internal checks, the code performs a full initialization and writes the load balancing and the coefficients to this restart file for future use.
+    Finally, if the restart file is provided and it is good, the code loads the initialized coefficients and does not need to do a full initialization.
+
+bucketSize:
+  desc: >
+    The size of the "buckets" at the last level of the KD-tree.
+    A large bucket size reduces the number of levels in the tree and the overall tree size but may require more computation since a less fine granularity of leaves are available.
+    Experiments have indicated there is little difference in run time for bucket sizes 1, 2, 4 and 8.

doc/tutorial.rst

@@ -12,7 +12,7 @@ warping script and explaining the various parts. ::
 
   options = {
     'gridFile':'../../input_files/o_mesh.cgns',
-    'fileType':'CGNS',
+    'fileType':'cgns',
     'specifiedSurfaces':None,
     'symmetrySurfaces':None,
     'symmetryPlanes':[],
@@ -58,7 +58,7 @@ explained in :ref:`idwarp_options`. ::
 
   options = {
     'gridFile':'../../input_files/o_mesh.cgns',
-    'fileType':'CGNS',
+    'fileType':'cgns',
     'specifiedSurfaces':None,
     'symmetrySurfaces':None,
     'symmetryPlanes':[],

examples/AhmedBodyCoarse/run_warp.py

@@ -10,10 +10,10 @@
 
 meshOptions = {
     "gridFile": os.getcwd(),
-    "fileType": "openFoam",
+    "fileType": "OpenFOAM",
     "symmetryPlanes": [[[0, 0, 0], [0, 1, 0]]],
-    "aExp": 3,
-    "bExp": 5,
+    "aExp": 3.0,
+    "bExp": 5.0,
     "alpha": 1.0,
     "LdefFact": 0.20,
 }

idwarp/MultiUnstructuredMesh.py

@@ -28,45 +28,24 @@
 # =============================================================================
 import os
 import numpy as np
-from pprint import pprint
 from mpi4py import MPI
 from .MExt import MExt
+from baseclasses.utils import Error
 
 try:
     from cgnsutilities import cgnsutilities as cs
 except ImportError:
     cs = None
 
 
-class Error(Exception):
-    """
-    Format the error message in a box to make it clear this
-    was a expliclty raised exception.
-    """
-
-    def __init__(self, message):
-        msg = "\n+" + "-" * 78 + "+" + "\n" + "| IDWarp Error: "
-        i = 22
-        for word in message.split():
-            if len(word) + i + 1 > 78:  # Finish line and start new one
-                msg += " " * (78 - i) + "|\n| " + word + " "
-                i = 1 + len(word) + 1
-            else:
-                msg += word + " "
-                i += len(word) + 1
-        msg += " " * (78 - i) + "|\n" + "+" + "-" * 78 + "+" + "\n"
-        print(msg)
-        Exception.__init__(self)
-
-
 class Warning(object):
     """
     Format a warning message
     """
 
     def __init__(self, message):
         msg = "\n+" + "-" * 78 + "+" + "\n" + "| IDWarp Warning: "
-        i = 24
+        i = 17
         for word in message.split():
             if len(word) + i + 1 > 78:  # Finish line and start new one
                 msg += " " * (78 - i) + "|\n| " + word + " "
@@ -79,15 +58,14 @@ def __init__(self, message):
 
 
 # =============================================================================
-# UnstructuredMesh class
+# MultiUnstructuredMesh class
 # =============================================================================
 
 
 class MultiUSMesh(object):
     """
-    This is the main Unstructured Mesh. This mesh object is designed
-    to interact with an structured or unstructured CFD solver though a
-    variety of interface functions.
+    This mesh object is designed to support independent deformation of
+    multiple overset component meshes.
     """
 
     def __init__(self, CGNSFile, optionsDict, comm=None, dtype="d", debug=False):
@@ -1005,23 +983,6 @@ def writeGrid(self, baseName=None):
     #                     Utility functions
     # =========================================================================
 
-    def _printCurrentOptions(self):
-        """Prints a nicely formatted dictionary of all the current options to
-        the stdout on the root processor
-        """
-        meshCounter = 0
-        for mesh in self.meshes():
-            if self.comm.rank == 0:
-                print("")
-                print(" Options of mesh", meshCounter, "of", len(self.meshes))
-                print("")
-                print("+---------------------------------------+")
-                print("|     All IDWarp Options:               |")
-                print("+---------------------------------------+")
-                pprint(mesh.solverOptions)
-                print("")
-            meshCounter += 1
-
     def __del__(self):
         """Release all the mesh warping memory. This should be called
         automatically when the object is garbage collected."""