Package: convergence
convergenceA Python program to Perform Calculations Associated with a Grid Convergence
Study.IntroductionThis is a port of verify.f90, a program provided as part of the NASA Examining
Spatial (Grid) Convergence tutorial.http://www.grc.nasa.gov/WWW/wind/valid/tutorial/spatconv.htmlAdditional changes have been made to reflect the recommendations in:Celik, I. B., Ghia, U., & Roache, P. J. (2008). Procedure for estimation and
reporting of uncertainty due to discretization in CFD applications. Journal of
fluids Engineering-Transactions of the ASME, 130(7).This code was written by Mathew Topper between 2009 and 2011 as part of the
Supergen Marine Research Consortium project. I was younger then and would
do many things differently now. I am working on updating this code to make
the main class and functions more easy to use and also integrate into other
projects. Watch this space.InstallationThe package requires no dependencies and is currently available for Pythons
2.7, 3.7, 3.8, 3.9 and 3.10.The latest stable version of the package can be downloaded from PyPI usingpip:pip install convergenceThe development version of the package can be installed by cloning or
downloading the source code, and using the command prompt as follows:cd /path/to/convergence
python setup.py installNote that the stable version may not contain all of the features found in the
development version but it should be more reliable.Basic UsageThe most straightforward method of using convergence is to generate a report
which details the grid convergence metrics for a given set of grids.Command LineThe package provides a command line interface. The input data must be a space
delimited text file with the first column being the grid spacing and the second
column being the metric of interest. An example can be found in thedatafolder of the source code. The program can then be executed as follows:grid-convergence /path/to/data/fileBy default, the results of the program are written to a file calledverify_report.txtin the calling directory. The file name can be changed
using the-oor--outcommand line options.ScriptingThe package can also be used from within a script. Grids are provided in a
list of pairs, i.e[(size1, value1), (size2, value2), ...]. Example usage
is:>>>from__future__importprint_function>>>fromconvergenceimportConvergence>>>grids=[(1.000000,0.970500),...(2.000000,0.968540),...(4.000000,0.961780)]>>>convergence=Convergence()>>>convergence.add_grids(grids)>>>print(convergence)# doctest:+ELLIPSIS<BLANKLINE>Numberofgridstobeexamined=3...Expected OutputThe result, contained in the output file when using the command line interface
or when printing aConvergenceobject, will resemble the following:Number of grids to be examined = 3 

     Grid Size     Quantity 

     1.000000      0.970500 
     2.000000      0.968540 
     4.000000      0.961780 


Discretisation errors for fine grids:

       Grids |     e_approx |     e_extrap |      f_exact |   gci_coarse | 
 =========================================================================
       1 2 3 |     0.002020 |     0.000824 |     0.971300 |     0.003555 | 
 -------------------------------------------------------------------------

       Grids |     gci_fine |            p |          r21 |          r32 | 
 =========================================================================
       1 2 3 |     0.001031 |     1.786170 |     2.000000 |     2.000000 | 
 -------------------------------------------------------------------------


Discretisation errors for coarse grids:

       Grids |     e_approx |     e_extrap |      f_exact |   gci_coarse | 
 =========================================================================
       1 2 3 |     0.006980 |     0.002842 |     0.971300 |     0.012287 | 
 -------------------------------------------------------------------------

       Grids |     gci_fine |            p |          r21 |          r32 | 
 =========================================================================
       1 2 3 |     0.003562 |     1.786170 |     2.000000 |     2.000000 | 
 -------------------------------------------------------------------------


Asymptotic ratio test:

           Grids | Asymptotic ratio | 
 ====================================
           1 2 3 |         0.997980 | 
 ------------------------------------In the first table the input data is displayed. The second table shows the
fine analysis results for each trio of grids and the second table shows the
coarse analysis results for each trio. The final table shows the asymptotic
ratio.The headers of the tables have the following meanings:Grids: the trio of grids being analysede_approx: approximate relative errore_extrap: extrapolated relative errorf_exact: the estimated value at zero grid spacinggci_coarse: coarse grid convergence indexgci_finefine grid convergence indexp: order of convergencer21: ratio of the middle to fine grid spacingr32: ratio of the coarse to middle grid spacingAdvanced UsageKnown Analytical ResultIf there is a known zero spacing value for the convergence study this value
can be added to the analysis using the-aor--analyticalcommand line
option. To illustrate, the basic example would now become:grid-convergence /path/to/data/file -a 0.12345Alternatively, when using theConvergenceclass, add the analytical value
when instantiating the object, using thef_analargument:>>>convergence=Convergence(f_anal=0.9713)>>>convergence.add_grids(grids)>>>print(convergence)# doctest:+SKIPAdditional headers now appear in the fine and coarse analysis tables with the
following meanings:e_analytic: analytical relative errorf_analytic: the analytical value at zero grid spacingf_delta: the different between the analytical and estimated zero grid
spacing valuesReport Attribute AccessValues for the report attributes can be accessed through theConvergenceclass. A namespace containing the values for each triplet of grids is stored in
the items of aConvergenceobject, ordered from finest to coarsest. For
example:>>>len(convergence)1>>>convergence[0]# doctest:+ELLIPSISNamespace(...Values associated the both the fine and coarse grids are available at the
first level of the namespace. For example, to get the asymptotic ratio of the
finest triplet of grids:>>>convergence[0].asymptotic_ratio0.997980422462648Values associated to either the fine of coarse analysis, are stored under thefineandcoarsekeys. For example, to examine the extrapolated relative
errors:>>>convergence[0].fine.e_extrap0.0008239813226325151>>>convergence[0].coarse.e_extrap0.002841894765814084Required Grid ResolutionTo determine the required grid resolution for a given GCI value theget_resolutionmethod can be used. For example:>>>convergence.get_resolution(0.001)0.9831461212423797By default the GCI for the fine grid is used. To use the coarse grid estimate
pass"coarse"as the second optional argument:>>>convergence.get_resolution(0.001,"coarse")0.49157306062118994Note that the equation in the NASA tutorial is incorrect. Ifis the desired accuracy andis the required resolution, then:LicenseCopyright 2011 SuperGen Marine Energy Research ConsortiumCopyright 2013 SuperGen UK Centre for Marine Energy ResearchCopyright 2017-2022 Mathew TopperThis program is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version.This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the GNU General Public License for more details.You should have received a copy of the GNU General Public License along with
this program. If not, seehttps://www.gnu.org/licenses/.