diff --git a/doc/BC.rst b/doc/BC.rst new file mode 100644 index 0000000..894fde1 --- /dev/null +++ b/doc/BC.rst @@ -0,0 +1,31 @@ +.. _pyhyp_BC: + +Using the BC option +=================== + +This page describes how to use the ``BC`` option to specify boundary conditions at boundary edges of the surface mesh. + +Here is an example of a dictionary that can be used with ``BC``:: + + "BC":{1:{"iLow":"ySymm"}, 3:{"jHigh":"splay", "iHigh":"xConst"}} + +Each entry in the dictionary has a key and at least one nested key-value pair. +The key is the 1-based block number, the nested key is the boundary edge specification, and the value is the boundary condition. +For the first entry, these are ``1``, ``iLow``, and ``ySymm``, respectively. + +The 1-based block number and boundary edge specification for a boundary edge can be determined using Tecplot: + +#. Load the surface mesh file into Tecplot. +#. Use the Probe tool to select a point on the boundary edge of interest. + Use Ctrl+click to snap on to a boundary edge. +#. Select Zone/Cell Info in the toolbar on the right. +#. The number shown after Zone is the 1-based block number. +#. The edge specification depends on the values of I and J. + The edge is ``iLow`` if I=1, ``iHigh`` if I=I-Max, ``jLow`` if J=1, or ``jHigh`` if J=J-Max. + Only one of these is true for any boundary edge. + +The supported boundary conditions are: + +* ``splay`` for free edges +* ``xSymm``, ``ySymm``, ``zSymm`` for symmetry planes +* ``xConst``, ``yConst``, ``zConst``, ``xyConst``, ``yzConst``, ``xzConst`` for constant planes diff --git a/doc/index.rst b/doc/index.rst index e81b6da..7ac49df 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -32,5 +32,6 @@ Contents: install plot3d cgns + BC options API diff --git a/doc/options.rst b/doc/options.rst index ae171b3..f37c10b 100644 --- a/doc/options.rst +++ b/doc/options.rst @@ -5,94 +5,162 @@ Options Here are the options currently available in pyHyp. -=================== ========== ======================================================================================= -Parameter Type Description -=================== ========== ======================================================================================= -``inputFile`` ``char`` 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`` ``char`` Type of the input file. Use either ``Plot3d`` or ``CGNS``. - -``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` 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` 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` 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` 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. -=================== ========== ======================================================================================= \ No newline at end of file +.. 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` 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` 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` 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` 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` 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. diff --git a/pyhyp/pyHyp.py b/pyhyp/pyHyp.py index 12f660d..4ff7549 100644 --- a/pyhyp/pyHyp.py +++ b/pyhyp/pyHyp.py @@ -619,14 +619,15 @@ def __init__(self, comm=None, options=None, debug=False): ) BCToSet = BCs[blkBC][edgeKey].lower() if BCToSet.lower() not in BCMap.keys(): + raise Error( "Boundary condition specification unknown. Must be one of: " - "'splay', 'BCXSymm', 'BCYSymm', 'BCZSymm', " - "'BCXConst', 'BCYConst', 'BCZConst, 'BCXYConst, " - "'BCYZConst or BCXZConst'. %s" % helpStr + "'splay', 'xSymm', 'ySymm', 'zSymm', " + "'xConst', 'yConst', 'zConst, 'xyConst, " + "'yzConst or xzConst'. %s" % helpStr ) - fBCs[edgeMap[lKey], blkBC - 1] = BCMap[BCToSet] + fBCs[edgeMap[lKey], blkBC - 1] = BCMap[BCToSet] # Set the boundary condition information into fortran self.hyp.hypinput.bcs = fBCs