Tutorial 1. Understanding Configuration File¶
[1]:
# Document Author: Dr. Vishal Sharma
# Author email: sharma_vishal14@hotmail.com
# License: MIT
# This tutorial is applicable for NAnPack version 1.0.0-alpha4
For installation instructions, see Installation page.
The very first step to start using this package is to get familiar with the configuration file “config.ini”. It is expected that the package users are familiar with the general terms, model equations etc. used in engineering simulations.
The configuration file is used as a tool to set-up the scenario that is to be solved numerically. The file accepts several inputs that are required in the pre-processing and post-processing steps of the simulation. Although users may choose to define the inputs in the scripts that they will develop without having to use the config file, however, it is highly recommended to set-up the numerical experiments using this configuration file. By doing so, users, particularly the starters in CFD, will get an idea about what information they will require beforehand in their experimentation as well as they will be able to make the best use of this package.
The structure of the config file includes the section name in square paranthesis [SECTION-NAME] and each section consists of key-value pairs in the format KEY = VALUE. The keys must not be changed by the user unless specified and user defined inputs must be specified in the value fields.
Section - [SETUP]¶
Provide the various experiment related description as inputs in this section.
[SETUP]
EXPID = xxxxxxxx-xx
UNITS_SYSTEM= BRITISH or SI
DESCRIPTION = enter short description
STATE = TRANSIENT or STEADY-STATE
MODEL = FO_WAVE
SCHEME = RUNGE-KUTTA
DIMENSION = 1D
*’EXPID’*: Experiment ID- a unique ID that you can assign to your experiments.
I always prefer to include an ID for my records so that I can distinguish my experiment outputs from one another and for any changes I make in experiment set-up, I increment this ID number. Typically, an ID may be of the format MMDDYYYY-Serial No. There may be several usages of this id, such as users may make a folder using this ID and save the output with the associated configuration file in this folder and repeat this process for each experiment. Adopting a Unique ID assigning strategy in the experiments help in efficient record management which is very important when publishing data or for reproducibility.
*’UNITS_SYSTEM’*: Mention the system of units used in the simulation. This field helps in keeping track of the unit and to stay consistent with the system. It is also wise to save the unit system for the records.
*’DESCRIPTION’*: Enter a short case description such as STEADY STATE HEAT CONDUCTION SIMULATION. Datatype = string.
*’STATE’*: Allowed inputs are STEADY-STATE or TRANSIENT. The field represents the state at which the results are desired. Depending on the case, a value must be entered. This is a required field to calculate several simulation parameters by the program setup.
*’MODEL’*: Classification of model equation. Allowed inputs are DIFFUSION, WAVE, FO_WAVE, VISC_BURGERS, INV_BURGERS. This field is required by the program setup. Please note that these model equations require only one dependent variable to be solved along X or along X and Y at each iteration level.
*’SCHEME’*: User may choose to specify the numerical method they will be using in the simulation. This field is optional in the current version.
*’DIMENSION’*: Allowed input 1D or 2D, depending on the simulation domain. This is required by the program setup.
Section - [DOMAIN]¶
The domain specification is entered in this section depending on 1D or 2D simulation.
[DOMAIN]
LENGTH = 400.0
HEIGHT = 0.0
*’LENGTH’*: Length of the domain (along X axis). Value required. Datatype = float.
*’HEIGHT’*: Height of the domain (along Y axis). If DIMENSION = 2D, value required. Datatype = float.
Section - [MESH]¶
Provide the details for meshing in this section.
[MESH]
GRID_FROM_FILE? = NO
GRID_FNAME = none
GRID_AUTO_CALC? = YES
dX = 5.0
dY = 0.05
iMax = 0
jMax = 0
*’GRID_FROM_FILE?’*: Read grid data from input file? This version does not support grid input through file, therefore keep the value as NO.
*’GRID_FNAME’*: Grid input file name. This field is used to enter the file name for the grid input. Since, we have specified GRID_FROM_FILE as NO, leave it as ‘none’.
*’GRID_AUTO_CALC?’*: Auto-calculate grid points? Enter YES or NO. If mentioned YES, grid step size- (dX) or (dX, dY) must be entered and the program will auto-compute the grid points in the mesh. If mentioned NO, maximum grid points in the mesh- (iMax) or (iMax, jMAx) must be specified. For beginners, enter YES and specify dX, dY values.
Please note that the current version supports only uniform, finite difference grid in the simulation which is good for applications with rectangular, simply connected domain. Advanced techniques will be introduced in subsequent versions.
Section - [IC]¶
Provide the option for the starting point (initial conditions) of the simulation.
[IC]
START_OPT = COLD-START
RESTART_FILE = none
*’START_OPT’*: Starting option. Allowed inputs are COLD-START or RESTART. In the present version, only COLD-START feature is available which allows the user to start the simulation from zero initial values or using user developed subroutine for initial conditions.
RESTART conditions are useful when it is desired to start the simulation from the previously stored solution, for example, consider a scenario where your simulation ran for 24 hours or thousands of iterations without converging and your application crashed or reached a maximum limit of iterations, will it be efficient to run the simulation again from the beginning or by using previously stored solution as the starting point? Another scenario- starting a simulation from a converged solution to test something new will help in faster convergence.
*’RESTART_FILE’*: Restart file name. File name for the program to read the stored solution. If START_OPT = COLD_START, leave it as none, otherwise specify the file name.
Section - [BC]¶
Provide the information whether to read the boundary conditions from a configuration file.
[BC]
BC_FROM_FILE? = NO
BC_FILE_NAME = none
*’BC_FROM_FILE?’*: Read boundary conditions from file? Allowed inputs are YES or NO. First time users- enter NO.
There is a “bc.ini” file included in this package download, however, it is recommended to write a function to assign boundary conditions. There will be a separate tutorial on the boundary condition specification through “bc.ini” file.
*’BC_FILE_NAME’*: Boundary condition input file name. If BC_FROM_FILE? = YES, the program will read the stored boundary conditions from file. If BC_FROM_FILE = NO, leave it as none.
Section - [CONST]¶
Provide the information to specify the constants in the model equations.
[CONST]
CFL = 1.0
CONV = 250.0
DIFF = 0.0
The program uses these constants to calculate coefficients in the finite difference approximations.
*’CFL’*: In nanpack we use the term CFL to represents the constant coefficient in the finite difference formulation. (This is not a true definition of CFL though). For a diffusion model, the program will treat the CFL as diffusion number to obtain time step size and in a wave equation or convection models, in general, the program will treat the CFL as the Courant number. The CFL must satisfy the corresponding stability requirement, otherwise, the solution will not converge or will fail when late time solutions are required. This is a required field. Datatype = float.
*’CONV’*: Convection coefficient. This is a required field for convection models such as WAVE equation. Datatype = float.
*’DIFF’*: Diffusion coefficient. This is a required field for diffusion models such as DIFFUSION equation. Datatype = float.
Section - [STOP]¶
Provide the information about stopping simulation.
[STOP]
SIM_TIME = 0.45
CONV_CRIT = 0.01
nMAX = 3000
*It is always helpful to restrict the simulation time or iterations to terminate the program without crashing it. Consider a scenario when the solution has converged but it continues to solve the equations because the user did not set a break point and thus, the simulation has to be stopped somehow. Consider another scenario when you desire time-dependent solution but you have to do hand computations to calculate the required time-steps. Such scenarios can be avoided by specifying values in this section and let the program handle the termination process.
*’SIM_TIME’*: Simulation time, required field for time-dependent solution. Datatype = float.
*’CONV_CRIT’*: Convergence criteria, required field for steady-state solution. Datatype = float.
*’nMax’*: Maximum iterations/time levels to terminate the program if solution didn’t converge. This is a required field. Datatype = integer.
Section - [OUTPUT]¶
Provide information about saving output or monitoring convergence.
[OUTPUT]
HIST_FILE_NAME = ./output/HISTfct1D.dat
RESTART_FNAME = none
RESULT_FNAME = ./output/fct1D.dat
WRITE_EVERY = 10
DISPLAY_EVERY = 10
SAVE_FOR_ANIM? = NO
SAVE_EVERY = 10
SAVE_1D_OUTPUT? = YES
X = 0.2,0.4,0.6,0.8,1.0
SAVE1D_FILENAME = ./output/fo-up1Dx.dat
*’HIST_FILE_NAME’*: Convergence history file name. The convergence history will be stored in this file. This is required if the user wants to store convergence data.
*’RESTART_FNAME’*: File to create a restart point. This file may be used later when the user wants to restart the solution from the stored solution. This feature is not supported in the present version.
*’RESULT_FNAME’*: Output file name. The solution of the dependent variable will be stored in this file at each grid point locations within the domain. This is a required field.
*’WRITE_EVERY’*: Write solution file after every how many iterations? Datatype = integer.
For example, value = 10 means that the solution will be saved to files after every 10 iteration steps. This is a required field. To optimize the computational processing, use larger values depending on the problem.
*’DISPLAY_EVERY’*: Write and display convergence history after every how many iterations? Datatype = integer.
*’SAVE_FOR_ANIM?’*: Save intermediate solutions in separate files for animation? Allowed inputs are YES or NO. This feature is not available in the current version, thus enter NO.
*’SAVE_EVERY’*: Save files for animation after every how many iterations? Datatype = integer. This field is required if SAVE_FOR_ANIM = YES.
*’SAVE_1D_OUTPUT’*: Save output in 1D format along X or Y in 2D simulation? Allowed inputs are YES or NO.
While validating numerical methods, it is important to plot line graphs to compare the output with the known analytical solution to benchmark the method. In such cases, plotting the colorful contour plots does not help and thus solution of the dependent variable along an axis is required, for example u(x=0.2, y) can be plotted to perform a detailed analysis. It is recommended to use this feature for 2D simulations.
*’X’* or *’Y’*: This key must be changed based on direction of the nodes at which the 1D solution is desired to be saved. The values to the key are the X or Y locations. Datatype = float.
Example: If the user wants to save the solution for u at x = 0.2, 0.4, 0.6 locations such that u(x=0.2, y), u(x=0.4, y), u(x=0.6, y), type the key as X and the values as 0.2, 0.4, 0.6 (separated by ‘,’). Vice-versa, to save u(x, y=0.3), u(x,y=0.6), u(x, y=0.9), type the key as ‘Y’ and the values as 0.3, 0.6, 0.9.
*’SAVE1D_FILENAME’*: 1D output file name. The solution of the dependent variable along the specified axis and locations will be stored in this file. This is required if SAVE_1D_OUTPUT = YES.