Organization of SOPALE source code
include files and commented list of source files


©P.Fullsack


This document presents a global view of the SOPALE code :

It provides a list of

  1. Include files (.h) and the most important parameters set some of these files. These parameters will fix the maximum storage available for the Eulerian grid and Lagrangian grid/cloud fields.
  2. A list of routines grouped in several categories according to their functions
  3. For the most important routine, a one line description of their function
  4. Children of (routines called by) a routine are indicated by : parent > child

    WARNING : only the most important variables or routine functions are outlined here.
    Feel free to complete this document with your own comments.


    1. Memory allocation, include files

    1. SOPALE1_h.f
    2. Other include files

    2. SOURCE files

    1. Main program
    2. Mechanical FE computation
    3. Thermal FE computation
    4. Arbitrary-Lagrangian-Eulerian (ALE) routines
    5. Initialization of grids/geometric operations
    6. External processes/constraints
    7. Solver (External Library : BLKFCT)
    8. OUTPUTS
    9. Utilities
    10. Obsolete files

    1 : memory allocation and Include files

    All variables are allocated statically. There is one important include file (SOPALE1_h.f) where the array sizes are set by a parameter value statement. All other (small) include files are typically left unchanged

    1.1 SOPALE1_h.f (module)

    used in files :
    • SOPALE1_ALE_lib.f >{ser_plt3,eulerian_recolor}
    • SOPALE1dmtm.f>{ program sopale1}
    • SOPALE1_plus.f >{vylifts}
    • laglist.f (all routines)
    • rotate_vel.f
    We extract here the most important information contained in this file :

    Eulerian grid maximum number of nodes (x/y) :

    parameter (mnx1=1601,mny1=121,mn1=mnx1*mny1) :

    Lagrangian grid/cloud maximum number of nodes ( x/y) :

    note that here an additional number of particles up to 20 times the grid size is allowed for future injection in the Lagrangian cloud arrays

    parameter (mn2inject=mn1*20,mn2=mnx2*mny2+mn2inject)
    parameter (mne=2*mnx2*mny2)

    Material colors :

    NOTE THAT SEVERAL 'COLORS' MAY CORRESPOND TO THE SAME MATERIAL (PHYSICAL) SET

    parameter (MAXCOLORS = 300)
    parameter (MAX_MATSETS = 30) ! maximum number of materialsets
    parameter (MAXITERS=1000)

    Linear Solver (BLKFCT) :

    THE FOLLOWING ARRAYS ARE NEEDED BY THE LINEAR SPARSE CHOLESKY SOLVER BLKFCT

    • NMAX should be greater than the expected number of equations in the Stokes system (2*mnx1*mny1)
    • ANZMAX should be bigger than the number of nonzeros in the matrix (18*mnx1*mny1)
    • LNZMAX is the critical number and hard to guess exactly.
      It should be bigger than the (a priori unknown) number of nonzeros in the Cholesky factor L.
      The value here is set to a number compatible with most runs by users of SOPALE in the Dalhousie Geodynamics Group, on Dalhousie's IBM sp4 (p690.ucis.dal.ca)
      Would you exceed this number, the program would stop and BLKFCT would return the expected number that should be used in the file : blkfct.out

    PARAMETER ( NMAX = 210000,
    & ANZMAX = 3700000,
    & SUBMAX = MAX(ANZMAX,100000),
    & LNZMAX = 20000000,
    & TMPMAX = 200000,
    & IWMAX = 7*NMAX + 3 )

    Remarks :

    Some variables never used : e.g. parameter (mnxt1=201,mnyt1=101)

    1.2. Other include files

    They are :
    • SOPALE1_bc.h
    • SOPALE1_numcontrol.h
    • gxycom.h
    • laglist.h
    • prograde.h
    • sediment.h

    Because these files are seldom changed, they are secondary and are not discussed here.
    Feel free however to edit this file and add your comments if needed.

    2 : List of SOURCE files

    t line -->

    2.1.MAIN program :

    file : SOPALE1dmtm.f :

    2.2.Mechanical FE computation (Stokes problem) :

    file : SOPALE1_mechanical_felib.f :

    1. compute_body_forces (computes the body forces, lithostatic pressure, water load,hydrostatic pressure)
    2. compute_stresses (computes stresses at the nodes of the Eulerian grid)
    3. compute_viscosities (computes viscosities at Gauss points of the Eulerian cells or elements)
    4. compute_stiffness (computes the global finite-element matrix )
    5. Ke (computes the Stokes finite-element matrix of s single cell)
    6. make_mass (computes the mass matrix of a single cell and the cell body forces)
    7. make_stresses (compute the stresses at the cell Gauss points)
    8. viscosities1 (compute the viscosities at the cell Gauss points)
    9. rsmooth (averages the pressure from elements to nodes)
    10. pgauss1 (determines Gauss integration parameters)
    11. pstres1 (computes the principal stresses)
    12. shape1 (computes the shape functions in a cell)
    13. rconnec1 (calculates the global nodes and equations of a cell)
    14. to1_aij (calculates the index of a nonzero matrix element in the BLFKCT array LNZ)

    Again, feel free to edit this file and add links to other parts of the documentation (e.g. flowcharts),
    or modify it to include routines variables etc.

    2.3.Thermal FE computation (advection-diffusion-production) :

    file : SOPALE1_thermal_felib.f :

    1. TOPALE_derivatives (computes the shape functions at all nodes of a cell)
    2. TOPALE_conductance (computes the conductance or diffusion matrix)
    3. TOPALE_capacitance (compute the capacitance or thermal mass matrix)
    4. TOPALE_center (computes the average diffusivity in a cell)
    5. TOPALE_advection (not used)
    6. TOPALE_4advection (computes the advection matrix with a Petrov-Galerkin upwind scheme)
    7. TOPALE_source ()
    8. TOPALE_source (computes the radioactive heat sources)
    9. TOPALE_material (selects the thermal material set to be used in a cell)
    10. TOPALE_properties (extracts the values of thermal properties used in the cell)
    11. shapeb (computes shape functions)
    12. pgauss (computes gauss point positions and integration weights)

    Again, feel free to edit this file and add links to other parts of the documentation (e.g. flowcharts),
    or modify it to include routines variables etc.

    2.4.Arbitrary-Lagrangian-Eulerian (ALE) routines :

    file : SOPALE1_ALE_lib.f :

    1. ser_plt3 (computes the Eulerian grid cell -if any- containing each node of the Lagrangian cloud)
    2. eulerian_recolor (recomputes the uniform color of each eulerian cell)
    3. ser_fastsearch (cell searching routine used by each particle)
    4. ser_fastinterp (interpolates velocities from the Eulerian nodes onto the Lagrangian particles)
    5. ser_plt3s (the interpolation routine used by each particle)
    6. num_receip_spline (this routine and the following come from the Book Numerical Recipes )
    7. num_receip_splint (the first routine prepares, the second evaluates, cubic spline interpolation from data)

    The main function of these routines is to search cells containing lagrangian particles
    , to interpolate eulerian fields at lagrangian locations and to map lagrangian material onto eulerian cells.

    One should note that the linked list routines (in file laglist.f, see below) are used.

    The following routines are now obsolete

    • make_scir
    • make_sseg
    • sersinterp
    • fragm
    • make_sgri
    • stringrecolor
    • writes

    The files crpit.f (for lagrangian cleanup along interfaces) and laglist.f (for linked list are not commented here)
    We just give the list of routines of the linked list library:

    The file : laglist.f :

    1. laglist_initall
    2. laglist_add
    3. laglist_getfirst
    4. laglist_getnext
    5. laglist_getlast
    6. laglist_colors
    7. laglist_dumpall
    8. laglist_dump

    Again, feel free to edit this file and add links to other parts of the documentation (e.g. flowcharts),
    or modify it to include routines variables etc.

    2.5.Initialization of grids/geometric operations :

    file : SOPALE1_plus.f :

  5. vylifts (computes the regridding displacement of all interfaces and applies surface processes)
  6. zeremesh (deforms the Eulerian grid to conform to the vertical displacement of interfaces)
  7. init_sediment
  8. logical function is_sediment
  9. init_waterload
  10. import_grid
  11. initmesh
  12. get_surface
  13. read_sinusoidal
  14. pert_sinusoidal
  15. read_LehnerNormal
  16. pert_LehnerNormal
  17. read_lvlslope
  18. pert_lvlslope
  19. import_gridfield
    > fxy > my_temperatures (1d steady T)
    (one way to impose initial temperatures)
  20. gxy
  21. read_extra_injection
  22. init_injection
  23. init_ylagshift

    Again, feel free to edit this file and add links to other parts of the documentation (e.g. flowcharts),
    or modify it to include routines variables etc.

  24. 2.6.External processes/constraints :

    file : erosion.f :
    (computes a vertical displacement interpreted as erosion)

    1. init_erode
    2. erode_row
    3. double precision function get_erosion
    4. double precision function linear_interp

    file : pressure_pump.f :
    (initializes the pressure pump, computes a -pump- vertical velocity correction)

    1. init_pump
    2. pump_calculate_deltav

    file : isost_module.f :
    (computes the vertical deflection coming from local or regional isostatic compensation)

    1. init_isostasy
    2. isostasy
    3. beam

    file : matchange.f :
    (change material set according to rule in temperature,pressure space)

    1. matchange_read_rules
    2. integer function matchange_rule
    3. matchange_which_mat
    4. matchange_phase_change

    file : prograde.f :
    (computes a geometric update of the surface analog to a progradation sequence)

  25. init_prograde
  26. prograde_row
  27. double precision half_gaussian

    file : rotate_vel.f :
    (rotate velocities to the base tangent )

    1. rotate_vel_setflag
    2. rotate_get_alphas
    3. rotate_Ke
    4. rotatevelocities

    Again, feel free to edit this file and add links to other parts of the documentation (e.g. flowcharts),
    or modify it to include routines variables etc.

  28. 2.7.Solver (External Library : BLKFCT) :

    This external library is accessed through the 6 following blkfct routines :

    1. ordmmd (compute the multiple minimum degree reordering of the equations)
    2. sfinit (initializes the symbolic factorization)
    3. symfct (performs the symbolic factorization)
    4. bfinit (initializes the numerical factorization)
    5. blkfct (computes the numerical factorization)
    6. blkslv (solves the system by a forward and backward back-substitution)

    Again, feel free to edit this file and add links to other parts of the documentation (e.g. flowcharts),
    or modify it to include routines variables etc.

    2.8.OUTPUTS:

    Outputs are perfomed by one routine for each grid type
    1. Pwrite1 (E)
    2. Pwrite2 (L)
    Typically the output is a set of equally sized records
    Each record typically corresponds to a double precision scalar field on the nodes of the grid.
    For convenience (...), some records are used for elemental fields or other information.

    See the output files manual.

    Nota-Bene : Feel free to edit this file and put a link here to the webpage (named here output manual) which documents the structure of and information saved in, output files. Or : just append this list here.

    file : SOPALE1_INOUT.f :

    1. open_key1
    2. open_key11
    3. close_key
    4. bopen_key1
    5. bopen_key11
    6. Pwrite_1 main routine for Eulerian grid output
    7. local1_write
    8. blocal1_write
    9. Pwrite_2 main routine for Lagrangian cloud output
    10. local2_write
    11. local1_read
    12. binread_E
    13. blocal1_read
    14. local2_read
    15. binread_L
    16. wxy
    17. write_int4_output
    18. write_real8to4_output
    19. write_real8to8_output
    20. find_section_in_file
    21. get_line_from_file

    Again, feel free to edit this file and add links to other parts of the documentation (e.g. flowcharts),
    or modify it to include routines variables etc.

    2.9.Utilities:

    file : pointinpoly.f :

    1. real function isLeft
    2. integer functionis wn_PnPoly

    Again, feel free to edit this file and add links to other parts of the documentation (e.g. flowcharts),
    or modify it to include routines variables etc.

    2.10.Files which are obsolete or seldom used:

    (X-Plots) :

    1. SOPALE1_Xplot.f
    2. SOPALE1_plot_off.f
    3. SOPALE1_plot_on.f
    4. SOPALE1_analytical_lib.f

    (Non-symmetric solver)

    LINPACK_nonsym_solver.f

    Again, feel free to edit this file and add links to other parts of the documentation (e.g. flowcharts),
    or modify it to include routines variables etc.