********************************************************************************

  E U L 1 D M G

  (c) 2004-2014 Jiri Blazek, CFD Consulting & Analysis, www.cfd-ca.de

********************************************************************************

Program for the solution of quasi 1-D Euler equations Eq. (12.4) on structured
grids using geometric multigrid (FAS). Spatial discretisation is conducted
either by the central scheme with scalar artificial dissipation, by Roe's
upwind scheme, or by the CUSP scheme. Further details are provided in Section
12.5 of the book.


This 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 2
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, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.


--------------------------------------------------------------------------------
  Files
--------------------------------------------------------------------------------

Makefile   - compilation options
README.txt - what you read now
param.inc  - include file
*.f        - source files ("main.f" contains the main program)

There are the following files in the directory "../runmg":

conver_c.v2d  - convergence history (central scheme)
conver_r.v2d  - convergence history (Roe scheme)
conver_u.v2d  - convergence history (CUSP scheme)
eul1dmg.exe   - executable for Windows 64-bit platform
input_c       - input parameters (example for the central scheme)
input_r       - input parameters (example for Roe's upwind scheme)
input_u       - input parameters (example for the CUSP scheme)
laval.grd     - grid file
plot_c.pdf    - PDF file with results (central scheme)
plot_r.pdf    - PDF file with results (Roe scheme)
plot_u.pdf    - PDF file with results (CUSP scheme)
plot_c.v2d    - plot file (central scheme)
plot_r.v2d    - plot file (Roe scheme)
plot_u.v2d    - plot file (CUSP scheme)

The files "plot_.v2d", "output_" and "conver_" were generated using the
corresponding "input_" files. The grid file "laval.grd" was obtained by
running "laval" in the directory "grid_1d".


--------------------------------------------------------------------------------
  How to compile "eul1dmg"
--------------------------------------------------------------------------------

Edit first the flags (SRC, EXEC, O, RM, LD, FC, FFLAGS, and LDFLAGS) in
"Makefile" as appropriate for your computer, compiler and/or operating system.
There are examples of settings for GNU gfortran, Mac OS X, IBM, SGI and SUN f77
compilers. Type "make" at the prompt to compile the program. All object files
and the executable can be deleted by "make clean".


--------------------------------------------------------------------------------
  How to run "eul1dmg"
--------------------------------------------------------------------------------

The program reads a number of user parameters from the standard input. The user
parameters are stored in a plain ASCII file. Examples are provided in the files
"input_...". In order to run "eul1dmg", you have to type at the prompt:

% eul1dmg < [input file]

where [input file] is the path and name of the file with parameters, e.g.:

% eul1dmg < input

The program reads in a grid file (laval.grd in the examples) previously
generated by the program "laval" from the directory "grid_1d". "eul1dmg"
outputs three files - convergence history, plot data and a restart file (in
binary format). In the example input file "input_c" they are named as
"conver_c.v2d", "plot_c.v2d" and rest_c", respectively.

The file with the convergence history contains the quantities:

iteration  - iteration number
log(resid) - log10 of density based convergence measure (see Eq. (12.1))
drho_max   - maximum difference between new and old density [kg/m^3]
node       - grid node where drmax is found
mass flow  - average mass flow rate [kg/s]
mass diff  - difference between mass flow at inlet and outlet [kg/s]
nsup pts   - number of supersonic points.

The plot file contains the variables:

x         - x-coordinate [m]
A         - nozzle area [m^2]
rho       - density [kg/m^3]
u         - velocity [m/s]
p         - static pressure [Pa]
T         - static temperature [K]
Mach      - local Mach number
mass flow - local mass flow rate [kg/s].

The data in the convergence and the plot file are stored in Vis2D format and
can be visualized using the plotting software available at www.cfd-ca.de.
Please note that all physical quantities are defined in SI units.


--------------------------------------------------------------------------------
  Main variables
--------------------------------------------------------------------------------

Names of variables ending with "f" are related to the finest grid (ilev=1),
those ending with "c" are used on all coarse grids.

Dimensions:
~~~~~~~~~~~
idims   = max. possible number of grid points (including dummy points)
ib2     = last "physical" grid point (first one = 2)
imax    = last grid point (actual value - must be <= idim)
nlevels = number of grid levels (>= 1)

Global variables:
~~~~~~~~~~~~~~~~~
a()     = local nozzle area [m^2]
cv()    = conservative variables (rho*A, rho*u*A, rho*E*A)
cvold() = previous solution (needed for update)
diss()  = artificial dissipation
dt()    = local time step [s]
ls()    = left state (density, velocity, pressure)
p()     = static pressure [Pa]
rhs()   = right-hand side (residual)
rs()    = right state (density, velocity, pressure)
vol()   = control "volume" - node centered [m^3]
x()     = x-coordinate [m]

Parameters:
~~~~~~~~~~~
ark()     = stage coefficients (Runge-Kutta scheme)
betrk()   = coefficient used for blending artificial dissipation
            of the current and the previous Runge-Kutta stage
cfl       = CFL-number
convtol   = solution accuracy
cpgas     = coeff. of specific heat at constant pressure [J/kgK]
drho      = 2-norm of density change normalized with 'drho1'
drho1     = 2-norm of density change at the 1st time step
epsentr   = Roe's scheme: entropy correction coefficient (delta in Eq. (4.96))
epsirs    = coefficient of the implicit residual smoothing
fngrid    = path & name of the file with grid
fnplot    = path & name of the file with results (Vis2D format)
fnconv    = path & name of the file with convergence history
fnrest    = path & name of the file with restart solution
gamma     = ratio of specific heats
ilevbase  = start or actual grid level (1=finest)
iorder    = Roe/central scheme: 1st-order (=1) / 2nd-order (=2) /
            kappa=1/3 (=3) only Roe and MUSCL interpolation
iter      = actual iteration
kdissip   = dissipation (C=central scheme / U=CUSP scheme / R=Roe's scheme)
kmgcyc    = type of the multigrid cycles (V or W)
ldiss()   = artif. dissipation switch (0=off, >0=on)
limfac    = limiter coefficient (Roe's scheme) - corresponds to factor K
            in Eq. (5.65)
lrest     = use previous solution (from "fnrest") to initialize flow field (Y/N)
lsmoo()   = residual smoothing switch (0=off, >0=on)
maxsgiter = max. number of single-grid iterations (before multigrid)
maxcgiter = max. number of multigrid cycles on coarse grids (if FMG)
maxfgiter = max. number of multigrid cycles on the finest grid
ncells    = number of grid cells
nrk       = number of stages (multistage time-stepping scheme)
pref      = reference pressure (limiter function) [Pa]
p2        = exit static pressure [Pa]
p01       = inlet total pressure [Pa]
rgas      = gas constant [J/kgK]
rhoref    = reference density (limiter function) [kg/m^3]
t01       = inlet total temperature [K]
uref      = reference velocity (limiter function) [m/s]
vis2      = central scheme: artificial viscosity coefficient (2nd order)
vis4      =                               - '' -             (4th order)
volref    = reference volume [m^3]

Please note that all physical quantities are in SI units.

Common blocks:
~~~~~~~~~~~~~~

"numer.inc"
  /numerc/ kdissip
  /numeri/ ldiss,lsmoo,iorder,nrk
  /numerr/ cfl,epsirs,vis2,vis4,limfac,epsentr,ark,betrk

"param.inc"
  /paramc/ fngrid,fnplot,fnconv,fnrest,lrest,kdissipf,
           kdissipc,kmgcyc
  /parami/ ldissf,ldissc,lsmoof,lsmooc,ilevbase,
           maxsgiter,maxcgiter,maxfgiter,iorderf,iorderc,
           nrkf,nrkc
  /paramr/ p01,t01,p2,gamma,gam1,gap1,cpgas,rgas,cflf,cflc,
           epsirsf,epsirsc,vis2f,vis2c,vis4f,vis4c,limfacf,
           limfacc,epsentrf,epsentrc,convtol,drho,drho1,
           volref,rhoref,uref,pref,arkf,arkc,betrkf,betrkc


--------------------------------------------------------------------------------
  Program structure
--------------------------------------------------------------------------------

Tree of subprogram calls:

EUL1DMG - main program (main.f)
    BCOND - sets boundary conditions (bcond.f)
    CONVER - writes out convergence history (conver.f)
    GET_ADDR - returns start address of the grid level (getaddr.f)
    INIFLOW - initialises flow variables and reference values (iniflow.f)
    INIGRID - computes control volumes (inigrid.f)
    INTERPOLATE - interpolates solution from coarse to fine level (interpol.f)
        BCOND - see above
    MULTIGRID - multigrid solver (mgsolver.f)
        GET_ADDR - see above
        INJECT - injects solution from fine to next coarse level (inject.f)
        PROLONGATE - prolongates solution corrections to finer grid (prolong.f)
            BCOND - see above
        RESTRICT - restricts residual to next coarser grid (restrict.f)
        SOLVER - time-stepping scheme (solver.f)
            BCOND - see above
            DISSIP - comp. artificial dissipation for central scheme (dissip.f)
            DISSIP2 - same as DISSIP but only with 2nd differences (dissip2.f)
            FLUX_CEN - computes convective fluxes for central scheme (fluxcen.f)
            FLUX_CUSP - computes total fluxes for CUSP scheme (fluxcusp.f)
            FLUX_ROE - computes total fluxes for Roe's scheme (fluxroe.f)
                ENTROPY_CORR - entropy correction due to Harten (fluxroe.f)
            GET_PARAMS - writes current values into "numer.inc" (getparms.f)
            IRSMOO - smoothes residuals (irsmoo.f)
            LR_STATE_CUSP - computes left and right state with SLIP (lrcusp.f)
            LR_STATE_ROE - computes left and right state with MUSCL (lrroe.f)
            SRCTERM - evaluates source term (srcterm.f)
            TSTEP - computes local time steps (tstep.f)
    OUTPUT - writes out solution for visualization (output.f)
    READ_CHAR - reads first character oder than " " (rchar.f)
    RGRID - reads in grid (rgrid.f)
        GET_ADDR - see above
    RSOLUT - reads in restart solution (rsolut.f)
    SOLVER - see above
    WSOLUT - writes out solution for restart (wsolut.f)


Include files:

numer.inc - actual numerical parameters valid only for one grid
param.inc - file names, numerical settings, physical constants and convergence
