Options refactoring and docs update (#36)

doc/conf.py

@@ -21,4 +21,4 @@
 numpydoc_show_class_members = False
 
 # mock import for autodoc
-autodoc_mock_imports = ["numpy", "mpi4py"]
+autodoc_mock_imports = ["numpy", "mpi4py", "baseclasses"]

doc/cgns.rst → doc/icem.rst

@@ -1,28 +1,21 @@
-.. _pyhyp_cgns:
+.. _pyhyp_icem:
 
 .. pyHyp boundary conditions example.
    Written by: Ney Secco (February 2016)
    Edited by: 
 
-Usage with CGNS Files
-=====================
+Specifying BCs using ICEM
+=========================
 
-If the initial surface is given in a CGNS file, we can specify boundary conditions
-at each open edge of the geometry. The boundary conditions currently supported are:
+This section will show how we can use ICEM to specify boundary conditions at each open edge of a CGNS surface geometry.
+The boundary conditions currently supported are:
 
 * Constant X, Y, or Z planes;
 * Symmetry X, Y, or Z planes;
 * Splay (free edge).
 
-This section will show how we can use ICEM to specify boundary conditions in a CGNS file.
-
-.. NOTE::
-   It is still not possible to specify boundary conditions when plot3d files are
-   used as inputs. In this case, the surface should be entirely closed or it should
-   end at a symmetry plane with the 'mirror' option enabled.
-
 Flat square example
------------------------------------
+-------------------
 
 .. NOTE::
   If you have a surface geometry, this step is not required, and you
@@ -135,7 +128,7 @@ is the one used as an example of boundary conditions setup.
    See if everything looks right in your Pre-mesh.
 
 Preparing to export the mesh
------------------------------------
+----------------------------
 
 Just to recap, we have done the following procedures: 
 
@@ -301,15 +294,14 @@ Running pyHyp with the generated mesh
 -------------------------------------
 
 Create another empty folder and copy the CGNS file exported by ICEM to it. We can add the following Python script to
-the same folder (This script is also available in `examples/plate/generate_grid.py`, and just the file name was
-adjusted for this example)::
+the same folder::
 
   from pyhyp import pyHyp
 
   fileName = 'plate.cgns'
-  fileType = 'CGNS'
+  fileType = 'cgns'
 
-  options= {
+  options = {
       # ---------------------------
       #        Input File
       # ---------------------------
@@ -321,14 +313,14 @@ adjusted for this example)::
       # ---------------------------
       'N': 65, 
       's0': 1e-6,
-      'rMin': 2.5,
+      'marchDist': 2.5,
 
       # ---------------------------
       #   Pseudo Grid Parameters
       # ---------------------------
       'ps0': 1e-6,
       'pGridRatio': 1.15,
-      'cMax': 5,
+      'cMax': 5.0,
 
       # ---------------------------
       #   Smoothing parameters
@@ -340,19 +332,12 @@ adjusted for this example)::
       'volBlend': 0.001,
       'volSmoothIter': 10,
 
-      # ---------------------------
-      #   BC parameters
-      # ---------------------------
-      'sigmaSplay': 0.4,
-      'nuSplay': 0.95,
-
       # ---------------------------
       #   Solution Parameters
       # ---------------------------
       'kspRelTol': 1e-15,
       'kspMaxIts': 1500,
-      'preConLag': 10,
-      'kspSubspaceSize':50,
+      'kspSubspaceSize': 50,
       'writeMetrics': False,
       }
 
@@ -376,7 +361,7 @@ You can also run pyHyp in parallel with the following command::
 The option '-np 4' indicates that 4 processors will be used. The results may vary slight due to the parallel solution of the linear system.
 
 Visualizing the mesh in TecPlot 360
--------------------------------------
+-----------------------------------
 
 If you have TecPlot 360 installed in your computer you can visualize the volume mesh. Open a terminal and navigate to the folder
 than contains the newly generated CGNS file with the volume mesh. Then type the following command::

doc/index.rst

@@ -20,7 +20,9 @@ line) corresponding to the geometry of interest and then *grow* or
 distance from the original surface. In the process, the entire space
 surrounding the geometry is meshed.
 
-Most the theory for `pyHyp` was taken from `Chan and Steger <https://www.sciencedirect.com/science/article/pii/009630039290073A>`_.
+.. _pyhyp_theory:
+
+Most of the theory for `pyHyp` was taken from `Chan and Steger <https://www.sciencedirect.com/science/article/pii/009630039290073A>`_.
 
 
 
@@ -30,8 +32,8 @@ Contents:
    :maxdepth: 2
 
    install
-   plot3d
-   cgns
+   tutorial
+   icem
    BC
    options
    API

doc/install.rst

@@ -49,9 +49,6 @@ Finally, install the Python interface with::
 
     pip install .
 
-
-.. _pyhyp_theory:
-
 Testing Your Installation
 -------------------------
 

doc/options.rst

@@ -3,164 +3,4 @@
 Options
 =======
 
-Here are the options currently available in pyHyp.
-
-.. list-table::
-   :widths: 5 5 90
-   :header-rows: 1
-
-   * - Parameter
-     - Type
-     - Description
-
-   * - ``inputFile``
-     - ``str``
-     - Name of the file that contains the surface mesh.
-       This is a file that has been generated in an external meshing program, typically ICEMCFD.
-
-   * - ``fileType``
-     - ``str``
-     - Type of the input file.
-       Use either ``Plot3d`` or ``CGNS``.
-
-   * - ``unattachedEdgesAreSymmetry``
-     - ``bool``
-     - Automatically applies symmetry boundary conditions to any edges that do not interface with another block.
-       This option works in many cases but does not work for all surface meshes.
-       If you encounter negative volumes near the symmetry plane, try explicitly setting the symmetry boundary conditions using the ``BC`` option.
-
-   * - ``outerFaceBC``
-     - ``str``
-     - Specifies the boundary condition at the outermost face of the extruded mesh.
-       Use either ``farfield`` or ``overset``.
-
-   * - ``BC``
-     - ``dict``
-     - Specifies boundary condition information for specific block edges. See :ref:`here<pyhyp_BC>` for details.
-
-   * - ``families``
-     - ``str`` / ``dict``
-     - Name given to wall surfaces.
-       If a dictionary is submitted, each wall patch can be named separately.
-       This can help with applying operations to specific wall patches.
-
-   * - ``N``
-     - ``int``
-     - Number of grid levels to march.
-       This determines the grid dimension in the off-wall direction.
-       Typically this should be a "multi-grid" friendly number.
-
-   * - ``s0``
-     - ``float``
-     - Initial off-wall (normal) spacing of grid.
-       This is taken to be constant across the entire geometry.
-       The units are consistent with the rest of the geometry.
-
-   * - ``rMin``
-     - ``float``
-     - Relative distance in the normal direction to march.
-       It is specified as a multiple of the radius of the sphere enclosing the initial surface geometry.
-       If symmetry is specified, the full mirrored geometry is used to compute the sphere's radius.
-       Most wing geometries will have ``rMin`` between 10 and 20, that is the farfield boundary is 20 spans away from the geometry.
-
-   * - ``cMax``
-     - ``float``
-     - The maximum permissible ratio of marching direction length to the any other in-plane edge.
-       This parameter effectively operates as a CFL-type limit.
-       If a step would require a step which would result in a ratio ``c`` greater than ``cMax``, the step is automatically split internally to respect this user-supplied limit.
-       Typical values of ``cMax`` are around 6-8.
-       Increased robustness can be achieved at the expense of computational cost by lowering ``cMax``.
-
-   * - ``nonLinear``
-     - ``float``
-     - Use the nonlinear formulation.
-       This is experimental and not currently recommended and may not work at all.
-
-   * - ``slExp``
-     - ``float``
-     - Exponent for the :math:`S_l` computation.
-       The :math:`S_l` value serves the same purpose as found in Chan et al. but the computation is different.
-       The :math:`S_l` computation in Chan is given as :math:`\sqrt{\frac{N-1}{l-1}}` for :math:`l > 2`.
-
-   * - ``ps0``
-     - ``float``
-     - Initial pseudo offwall spacing.
-       This spacing **must** be less than or equal to ``s0``.
-       This is actual spacing the hyperbolic scheme uses.
-       The solver may take many pseudo steps before the first real grid level at ``s0``.
-
-   * - ``pGridRatio``
-     - ``float``
-     - The ratio between successive levels in the pseudo grid.
-       This will be typically somewhere between ~1.05 for large grids to 1.2 for small grids.
-       This number is **not** the actual grid spacing of the final grid; that spacing ratio is computed and displayed at the beginning of a calculation.
-       The ``pGridRatio`` **must** be smaller than that number.
-
-   * - ``epsE``
-     - ``float``
-     - The explict smoothing parameter.
-       See the :ref:`Theory<pyhyp_theory>` section for more information.
-       Typical values are approximately 1.0. Increasing the explicit smoothing may result in a smoother grid, at the expense of orhtogonality.
-       If the geometry is very sharp corners, too much explicit smoothing will cause the solver to rapidly "soften" the corner and the grid will fold back on itself.
-       In concave corners, additional smoothing will prevent lines from crossing (avoiding negative cells).
-
-   * - ``epsI``
-     - ``float``
-     - Implicit smoothing parameter.
-       See the :ref:`Theory<pyhyp_theory>` section for more information.
-       Typical values are from 2.0 to 6.0.
-       Generally increasing the implicit coefficient results in a more stable solution procedure.
-       Usually this value should be twice the explicit smoothing parameter.
-
-   * - ``theta``
-     - ``float``
-     - Kinsley-Barth coefficient See the :ref:`Theory<pyhyp_theory>` section for more information.
-       Only a single theta value is used for both directions.
-       Typical values are ~2.0 to ~4.0.
-
-   * - ``volCoef``
-     - ``float``
-     - Coefficient used in point-Jacobi local volume smoothing algorithm.
-       Typically this value is 0.16 and need not be modified.
-       Use more ``volSmoothIter`` for stronger local smoothing.
-
-   * - ``volBlend``
-     - ``float``
-     - The global volume blending coefficient.
-       See the :ref:`Theory<pyhyp_theory>` section for more information.
-       This value will typically be very small, especially if you widely varying cell sizes.
-       Typically values are from ~0 to 0.001.
-       Default is 0.0001.
-
-   * - ``volSmoothIter``
-     - ``int``
-     - The number of point-Jacobi local volume smoothing iterations to perform.
-       Typical values are ~5 to ~25.
-       Default is 10.
-
-   * - ``kspRelTol``
-     - ``float``
-     - Tolerance for the solution of the linear system at each iteration.
-       Typically :math:`1\times 10^{-8}` is sufficient.
-       Very difficult cases may benefit from a tighter convergence tolerance.
-
-   * - ``kspMaxIts``
-     - ``int``
-     - Maximum number of iterations to perform for each step.
-       Default is 500 which should be sufficient for most cases.
-
-   * - ``preConLag``
-     - ``int``
-     - Lag the update of the preconditioner by this number of iterations.
-       The default value of 10 will typically not need to be changed.
-
-   * - ``kspSubspaceSize``
-     - ``int``
-     - Size of the ksp subspace.
-       Default is 50.
-       Very large and difficult problems may befefit from a larger subspace size.
-
-   * - ``writeMetrics``
-     - ``bool``
-     - Flag to write the mesh gradients to the solution file.
-       This option should only be used for debugging purposes.
+.. optionstable:: pyhyp.pyHyp