LAPMOD code structure

Source organization, execution flow and routine responsibilities for omp_parallel.

The omp_parallel version

This page describes the current omp_parallel source tree. The main program coordinates meteorology, emissions, particle movement and output; OpenMP distributes the computational loops among threads.

Main call sequence

LAPMOD
  SETUP
    INIT
      LAP_RAND_SEED / RANDOM_SEED
    READINP / RNPCHK
    OPNFIL
    SETMET or SETNMET
    OPNFIL_OUT
    SETTIM / SETSUB / SETEMI
    BUILDINGS_SET
      BUILDINGS_CHK
    ODORING (when requested)
    SETREC / WRHEAD

  Time loop:
    MET
    METTI
      TURPROC2 (OpenMP)
    EMI
      RDEMI
      PRJJ or PRWT
      PAPLPE
    CLOCKS
    GENERA
      LAP_RAND_INIT_NEW_PARTICLE
      LAP_RAND_LOAD_STATE
      GENXYZ / GENXYZPOL
      LAP_RAND_SAVE_STATE
    PMOVE (OpenMP unless LDBG)
      LAP_RAND_LOAD_STATE
      FNDXYZ / GETVAR2 / FNDTS
      NEWFLU
        RND_GAUSS / LAP_RANDU
      DEPOSD / DEPOSW
      INTERPWIND / PRIME2
      MOVE / RND_GAUSS_PR / RBNDS
      LAP_RAND_SAVE_STATE
    UPDATE
    CCA1: OUTPUT
      OUTPUT_P
      OUTPUT_D (grid output interval)
      Parallel sampling and reduction
      OUTPUT_C (output interval)
    CCA2/3: OUTPUTK
      OUTPUT_P
      Parallel sampling and reduction
      OUTPUT_C (output interval)

  PROGRESS / PRINT_DTZ / ENDSIM

The call sequence summarizes the main stages and selected descendants. Calls within a stage depend on the active options. The routine catalogue below covers both omp_parallel routines and shared routines reached through its main program.

Routine catalogue

Routine Scope
LAPMOD Main program of LAPMOD.
PRINT_DTZ This routine prints date, time and time zone on open output units. It is called at simulation start and simulation end.
SETUP Coordinates initialization, input validation, file opening, meteorology, emission and substance setup, building geometry and receptors. INIT initializes the random generators before the simulation starts.
INIT Initializes model arrays, constants and counters. Calls LAP_RAND_SEED for particle random states and RANDOM_SEED once for the separate capped-stack generator.
READINP This routine reads an input file, extracts the record between two text delimiters (generally two exclamation marks) and it reads the input value contained in the record.
READREC This routine reads from a string the pair of variables description and value. Values must be separated from their descriptions with an equal sign '=' (for example number of grids = 33). Values can be REAL, INTEGER, CHARACTER or LOGICAL, as specified from the input variable IVAR.
LSTRIM This routine gives the length of a string after removing the ending blanks and the non-printable characters.
RNPCHK This routine checks for the correctness of input values (dates, parameters exceeding limit values, ...) and it makes assignments based on input values.
OPNFIL It opens the intermediate output file, if requested. It opens the CALMET output file (that is the meteorological input to LAPMOD) and it writes an error message if it does not find it. It opens the input file containing the emissions and it issues an error message if it does not find them.
WRITINP This routine writes the input values in the log file.
WRHEAD This routine writes the headers of the concentration binary file (if LBINC = T)
SETMET This routine starts reading the CALMET binary file when NMET=1. It reads the title record and the data records up to the hour preceding the one when the dispersion simulation starts. It estimates how many hours of meteorological data must be read before the simulation starts. The simulation start and end hours are LST, as in the CALMET binary output. The routine computes the turbulent parameters (sigmas and Lagrangian times) in every point of the grid. It computes the mean pressure and relative humidity values at ground using measurements.
SETNMET This routine manages the initial reading of CALMET files, in case NMET > 1. It reads the headers of all files and it checks that they refer to the same domain. Moreover, it checks that the CALMET files are listed in the correct time sequence, and that they cover the LAMOD simulation time interval. The routine starts reading from the first CALMET binary file the title record and the records with data until the hour preceding the hour when the dispersion simulation starts. The routine computes the turbulent parameters (sigmas and Lagrangian times) in every point of the grid. It computes the mean pressure and relative humidity values at ground using measurements.
STACKTIP This routine computes the reduced stack height, due to the stack tip downwash.
ODORING This routine controls and suggests specific options for odor emissions.
METHDR This routine reads the title record from the CALMET binary file. After the call to this routine, topography, landuse data and variables are stored in memory and the pointer is ready to read the meterological data.
ADD_DELTA_HOURS This routine increments a given date and time by a given number of hours.
DAYNUM This routine computes a day number. One of the more useful applications for this routine is to compute the number of days between two dates.
LEAPYR Logical function returning TRUE if it is a leap year, FALSE otherwise.
GET_DATE This routine computes the day (YEAR, MONTH, DAY) from the Julian day DAY_NUMBER. A DAY_NUMBER of unity will return Oct. 15, 1582.
LUSELAB This routine determines the labels to assign to each LANDUSE category. Assignments are made using the CALMET default categories (p 4-85 of the CALMET users' guide)
SETDOM This routine verifies that the output domain is within the meteorological domain of CALMET. It calculates the initial and final indices of meteorological grids to use. It computes dispersion domain parameters. It computes the index of the meteorological grids within which falls each LAPMOD output point.
LATLON This routine calculates latitude and longitude of a generic point (x,y) in the UTM zone IZ
UTM2LL This routine transforms UTM coordinates into longitude and latitude.
METDAT This routine reads the meteorological data from the CALMET binary output file. It reads one hour of meteorological data every time it is called. The Monin Obukhov length is read and immediately transformed to its inverse that will be used during the simulation. The vertical velocity exiting from this routine is in terrain following coordinates.
SETREC This routine reads the coordinates of the discrete receptors, if any exists, and it converts the coordinates in input to relative coordinates within the computational domain.
CAPTOSM This routine converts the file names substituting capital letters with small letters.
SETTIM This routine sets all the times that are needed for the simulation (about emissions, output...)
GETDUR This routine calculates the duration of a time interval, in seconds, between an initial date and a final date.
SETSUB This routine initializes the properties of radioactive substances.
RTBIS This function implements the erfc function diminished by a constant C
SETEMI This routine initializes the emission parameters.
SOUCHK This routine checks the validity of source parameters read in SETEMI.
RECOGN This routine recognizes the name of the substance and stores its position in the substances database. If the substance is not found in the database the code stops.
MET This routine reads a record from the CALMET meteorological binary file.
RDEMI This routine reads the sources' emission data: emission rate for each substance, temperature and emission speed, date and time of emission.
CLOCKS This routine computes the longest integration interval that is possible with current input value (IDT). It updates the current date of the simulation (IDCURS) and it updates the current Julian day. This routine also updates the main "clocks" of the model, all expressed in seconds:
  • ITDURM: it is consumed when CLOCKS is called and meteorology is read when it is equal to zero;
  • ITDURE: it is consumed when CLOCKS is called and emissions are read when it is equal to zero;
  • ITDURO: it is consumed when CLOCKS is called and when it is equal to zero output variables are written;
  • ITDUROS: it is consumed when CLOCKS is called and when it is equal to zero a new concentration sampling is made;
  • ITDURPW: it is consumed when CLOCKS is called and when it is equal to zero the particles output file is written;
  • ITDURS: it is consumed when CLOCKS is called and when it is equal to zero the simulation ends.
IDSET This routine updates the vector storing the date by the integration interval in seconds, IDT.
GENERA Creates particles in available storage slots, assigns their tags and initial random states, initializes coordinates and properties, and saves their random-generator caches. This stage runs sequentially.
FHOLE This routine finds the first empty slot in the particles vector IHOLE.
GENXYZ This routine assigns the coordinates to the generated particles.
GENXYZPOL This routine assigns the coordinates to the generated particles, for polygon sources.
LOCPT This routine evaluates if a point is within a polygon.
FNDXYZ This routine finds the lower left indexes of the meteorological cell containing the particle.
PMOVE Integrates active particles in parallel unless LDBG is enabled. Interpolates meteorology, chooses local integration steps, updates fluctuations, deposition and decay, applies building-wake corrections and boundary handling, and saves each particle's random state.
GETVAR2 This routine extracts the value of the meteorological variables in correspondence of the particle position for the FLB scheme.
FNDTS This routine computes the short integration time step to be used to move the particle.
NEWFLU This routine updates the random components of the particle velocity.
RND_GAUSS Returns a Gaussian variate using LAP_RANDU and a thread-private cached value. The cache is loaded from and saved to the current particle.
RND_GAUSS_PR Provides Gaussian variates for plume-induced turbulence, with a separate thread-private cache stored in the current particle state.
DEPOSD This routine computes the dry deposition of gases and aerosols.
AERRES This routine computes the aerodynamic resistance as proposed in Seinfeld and Pandis (1998), p. 963.
VSETTL This routine computes the deposition velocity of particles with given diameter and the Schmidt number.
VDEPAER This routine computes the deposition velocity for aerosols.
DEPOSW This routine computes the wet deposition velocity for gases and aerosols as sum of the scavenging effects of rainout and washout processes.
MOVE Advances the particle using the local wind, turbulent velocity, settling velocity and building-wake corrections. Rotates horizontal fluctuations into the model coordinate system.
RBNDS This routine computes the reflection of the particle in case the particle is below ZMIN (e.g. the roughness length is a possible choice) or if the particle is above ZINV. If the particle is above ZINV there are two possibilities and consequences: if (1) the particle was within the PBL at previous step, the vertical velocity fluctuation is set to 0. (2) If the particle was already outside, no action is taken.
UPDATE Updates NP and compacts the active-address array IADDR after movement. The particle property and random-state arrays remain indexed by their original storage slots.
OUTPUT Computes CCA1 samples on the documented path using thread-local contribution buffers. Coordinates particle output and gridded deposition output, accumulates temporal statistics, and calls OUTPUT_C at the output interval.
OUTPUT_P Writes particle files at the requested output times. IPWRITE selects no ASCII output (0), detailed ASCII (1) or reduced ASCII (2); LPBIN independently controls binary output.
WRINFO This routine writes information about particles and substances.
OUTPUT_D This routine saves depositions on file.
CALCDEP Converts deposition fields to output arrays and computes extrema with OpenMP minimum/maximum reductions.
WROUT This routine writes on output files (concentration or deposition).
WROUT_BIN This routine writes on binary output file.
PREPNAME This routine prepares the name of the output file.
A2TOA1 This routine extracts ARRAY1D = ARRAY2D(*,ISU) and optionally inverts the order of the elements.
WRITE_ESRI_GRD_1D This routine writes an ESRI ASCII GRID file.
WRITE_SURFER_GRD_1D This routine writes an ASCII Sufer GRD file.
CALCCONCR This routine computes the concentrations in correspondence of discrete receptors.
CALCCONCR_SA This routine computes the concentrations due to each source in correspondence of a single receptor, when the source attribution algorithm is activated.
WROUTR This routine writes concentrations for discrete receptors.
WROUTR_SA This subroutine prepares the contributions of each single source to the concentration at a single discrete receptor.
WROUTR_BIN This routine writes on binary file the output at receptors (concentration)
WRITE_REC This routine writes on output file the concentrations in correspondence of discrete receptors.
OUTPUT_C Converts accumulated grid and receptor fields through CALCCONC, CALCCONCR or CALCCONCR_SA, writes concentration outputs and resets sampling accumulators. Handles each requested grid level and mean or maximum-sample normalization.
CALCCONC Converts a selected grid level to an output array using substance conversion, volume normalization and the sample divisor. Uses OpenMP over grid cells with minimum/maximum reductions.
ENDSIM This routine closes the files and creates the empty .ok file in the output directory.
OUTPUTKComputes CCA2/3 samples on the documented path, including bandwidth selection, BWMAX for CCA3, the gradual AGELIM transition, parallel reduction and source attribution. Calls OUTPUT_C at the output interval.
TURPROC2Calculates turbulence statistics over meteorological grid columns using OpenMP.
LAP_RAND_INIT_NEW_PARTICLEDerives a new particle seed from the base seed and its tag.
LAP_RAND_LOAD_STATE / LAP_RAND_SAVE_STATETransfer the particle seed and both Gaussian caches between particle arrays and thread-private working state.
LAP_RANDUUpdates the thread-private uniform random-generator state.
BUILDINGS_SET / BUILDINGS_CHKRead and validate building geometry during SETUP.
PRIME2Evaluates velocity deficit and turbulence enhancements for a particle in a building wake.
CALC_BUILDING_DIMENSIONSObtains the building dimensions projected along and across the local wind.
WAKE_SCALES / WITHIN_WAKE / FAR_WAKE_DIMDetermine cavity and wake scales, locate a point relative to those regions, and calculate far-wake dimensions.