Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

moved options documentation to separate page #24

Merged
merged 4 commits into from
Sep 9, 2020
Merged

moved options documentation to separate page #24

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
0da0ffd
moved options documentation to separate page
sseraj Sep 7, 2020
a169619
split usage page
sseraj Sep 7, 2020
dfae24e
formatting fixes
sseraj Sep 8, 2020
545f49e
double backtick
sseraj Sep 9, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions doc/_static/theme_overrides.css
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
/* override table width restrictions for RTD */
@media screen and (min-width: 767px) {

.wy-table-responsive table td {
/* !important prevents the common CSS stylesheets from overriding
this as on RTD they are loaded after this stylesheet */
white-space: normal !important;
}

.wy-table-responsive {
overflow: visible !important;
}
}
224 changes: 2 additions & 222 deletions doc/usage.rst → doc/cgns.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,229 +1,9 @@
.. _pyhyp_usage:

Usage with Plot3d Files
=======================

A complete sample script to generate a grid is given below. This
particular example is available under `python/examples/sphere/runSphere.py`::

from pyhyp import pyHyp
fileName = 'even_sphere.fmt'
#fileName = 'uneven_sphere.fmt'
#fileName = 'uneven_sphere_large.fmt'

options= {

# ---------------------------
# Input File
# ---------------------------
'inputFile':fileName,
'fileType':'Plot3d',

# ---------------------------
# Grid Parameters
# ---------------------------
'N': 73,
's0':1e-4,
'rMin':10,

# ---------------------------
# Pseudo Grid Parameters
# ---------------------------
'ps0':1e-4,
'pGridRatio':1.1,
'cMax': 5,

# ---------------------------
# Smoothing parameters
# ---------------------------
'epsE': 1.0,
'epsI': 2.0,
'theta': 3.0,
'volCoef': .16,
'volBlend': 0.0001,
'volSmoothIter': 20,

# ---------------------------
# Solution Parameters
# ---------------------------
'kspRelTol': 1e-10,
'kspMaxIts': 1500,
'preConLag': 5,
'kspSubspaceSize':50,
}

hyp = pyHyp(options=options)
hyp.run()
hyp.writeCGNS('sphere.cgns')

Each section of the example is now described::

from pyhyp import pyHyp

is the preferred way of importing the `pyHyp` module into python.

The options dictionary is used to provide all run-time options to
pyHyp to control the generation of the grid. Each option, its
description and the general effect on the grid generation process is
now described:

=================== ======== =======================================================================================
Parameter Type Description
=================== ======== =======================================================================================
`inputFile` `char` Name of the file that contains the surface mesh. Here we have a 3D problem and we are
using the surface mesh `uneven_sphere.fmt`. This is a plot3d file which 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<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.
=================== ======== =======================================================================================

The next line of code::

hyp = pyHyp(options=options)

generates the pyHyp object.

.. NOTE:: When exporting a surface mesh from ICEMCFD in plot3d format
use the following options:

* Formatted
* Whole
* Double
* No IBLANK Array

.. WARNING:: It is essential that the normals of each of the surface
patches point in the *OUTWARD* direction, i.e. the marching
direction.

The next two lines perform the actual generation and write the
resulting grid to a cgns file::

hyp.run()
hyp.writeCGNS('sphere.cgns')


The output of the run should look similar to the following::

#--------------------#
Total Nodes: 150
Unique Nodes: 98
Total Faces: 96
#--------------------#
Normal orientation check ...
Normals seem correct!
#--------------------#
Grid Ratio: 1.1420
#--------------------#
#-------------------------------------------------------------------------------------------------------------------------------------------
# Grid | CPU | Sub | KSP | Sl | Grid | Grid | Min | deltaS | cMax | min R | max |
# Level | Time | Iter | Its | | Sensor Max | Sensor Min | Quality | | | | KStretch |
#-------------------------------------------------------------------------------------------------------------------------------------------

2 0.26410E-02 1 10 0.17783E+00 0.10000E+01 0.10000E+01 0.65528E+00 0.11000E-03 0.32833E-03 0.10000E-03 0.00000E+00
3 0.60689E-02 2 10 0.21280E+00 0.99943E+00 0.99923E+00 0.64792E+00 0.13310E-03 0.39724E-03 0.33100E-03 0.10552E+01
4 0.81701E-02 1 10 0.22387E+00 0.99941E+00 0.99919E+00 0.64731E+00 0.14641E-03 0.43693E-03 0.46410E-03 0.11350E+01
5 0.10073E-01 1 10 0.23327E+00 0.99938E+00 0.99915E+00 0.64681E+00 0.16105E-03 0.48059E-03 0.61051E-03 0.11364E+01
6 0.11975E-01 1 10 0.24160E+00 0.99934E+00 0.99910E+00 0.64637E+00 0.17716E-03 0.52861E-03 0.77156E-03 0.11371E+01
7 0.13715E-01 1 10 0.24921E+00 0.99930E+00 0.99904E+00 0.64596E+00 0.19487E-03 0.58143E-03 0.94872E-03 0.11376E+01
8 0.15457E-01 1 10 0.25630E+00 0.99926E+00 0.99898E+00 0.64558E+00 0.21436E-03 0.63951E-03 0.11436E-02 0.11379E+01
9 0.17204E-01 1 10 0.26299E+00 0.99921E+00 0.99891E+00 0.64521E+00 0.23579E-03 0.70340E-03 0.13579E-02 0.11381E+01
10 0.20547E-01 2 10 0.27554E+00 0.99909E+00 0.99874E+00 0.64482E+00 0.28531E-03 0.85092E-03 0.18531E-02 0.11379E+01
< iterations skipped for brevity>
70 0.17639E+00 1 13 0.94933E+00 0.91466E+00 0.90983E+00 0.44618E+00 0.70716E+00 0.85351E+00 0.70706E+01 0.10857E+01
71 0.17845E+00 1 13 0.96300E+00 0.91433E+00 0.90996E+00 0.44321E+00 0.77788E+00 0.89981E+00 0.77778E+01 0.10933E+01
72 0.18323E+00 2 15 0.99094E+00 0.91399E+00 0.91040E+00 0.44094E+00 0.94123E+00 0.99767E+00 0.94113E+01 0.10859E+01
73 0.18649E+00 1 15 0.10052E+01 0.91396E+00 0.91071E+00 0.43894E+00 0.10354E+01 0.10493E+01 0.10353E+02 0.10874E+01


Several important parameters are displayed to inform the user of the
solution progress. The most of important of which is the `Min Quality`
column. This column displays the minimum quality of all the cells in
the most recently computed layer of cells. For a valid mesh, these
must be all greater than zero.
.. _pyhyp_cgns:

.. pyHyp boundary conditions example.
Written by: Ney Secco (February 2016)
Edited by:

.. _pyhyp_cgns:

Usage with CGNS Files
=====================

Expand Down Expand Up @@ -521,7 +301,7 @@ 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 `python/examples/plate/generate_grid.py`, and just the file name was
the same folder (This script is also available in `examples/plate/generate_grid.py`, and just the file name was
adjusted for this example)::

from pyhyp import pyHyp
Expand Down
6 changes: 6 additions & 0 deletions doc/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,3 +62,9 @@
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ["_static"]

html_context = {
"css_files": [
"_static/theme_overrides.css", # override wide tables in RTD theme
],
}
4 changes: 3 additions & 1 deletion doc/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,5 +30,7 @@ Contents:
:maxdepth: 2

install
usage
plot3d
cgns
options
API
Loading