MasterMech/WORK/README :
How to build inputs for and run the NCAR MasterMechanism.

Updated 5 Jan 2012, julial@ucar.edu
=============================================================================
STARTING FOR THE FIRST TIME:
    User MUST edit file 'setup.dat' to specify compiler and file path.
    User may need to issue command 'chmod u+x *.csh'
    User may need to switch into the C-shell environment.
    (If the C-shell is not available, the unix commands contained in the 
     scripts may 12be adapted and entered at the command line.)

-----------------------------------------------------------------------------
== TO RUN THE NCAR MASTER MECHANISM ==
issue command > run_MM.csh

run_MM.csh invokes the following steps:

Step 1: Extract a subset of the master mechanism.
 Input: input.species (lists precursor species to be included in mechanism)
Output: TMP/tmp.mech (relevant reactions from the chemical mechanism)

Step 2: Set up time & radiation conditions and calculate j-values. 
 Input: input.solar (may be created interactively or offline)
        User should select option '3' (optimized for Master Mechanism).
        Use default timing and wavelength info. Edit only the date info 
        (which sets earth-sun distance), lon/lat info and tmzone.
Output: TMP/tmp.jv (table of j-values)

Step 3: Set up other environmental constraints, generate full input file.
Inputs: input.prep (lists filenames for specific data inputs, see below)
        specific input.* files, and output.rates, as described below
Output: solv.inp, bounds_mod.f90

Step 4: Run gear solver, generate output timeseries.
Inputs: solv.inp, bounds_mod.f90 (generated in step 3, may be further edited)
Output: fort.7, fort.8, fort.9 (see end of this README file for details)

Step 5: Display results
 Input: plot.species (lists species for plot), fort.7
Output: fort.22, fort.23 (see end of this README file for details)

Each step may be run individually by specifying the step number at the prompt
generated by runMM.csh, or via its own runscript. Syntax is:
                   $> StepX.csh {run_name}
where X = 1 to 5, 
and run_name = directory name for archiving inputs/results (within WORK/).

User progresses to next step via an interactive prompt, if desired.  

If Step 5 crashes, try increasing parameter NXSPEC in POST/plotsel*.f90
Time interval dtime for tabulated output is set in POST/plotsel*.f90
=============================================================================
== Input file locations ==

- Input files (input.*) should be edited in directory WORK/ 

- If user-edited input files are named something OTHER than "input.*" they 
  must be copied manually to directory TMP/  This includes file solv.inp

- Program-generated input files (e.g. tmp.mch, solv.inp) required for 
  subsequent steps are created in directory /TMP

- Summary input file solv.inp and results files fort.* are copied by scripts 
  Step3.csh, Step4.csh and Step5.csh to log directory WORK/{run_name}/ 

=============================================================================
== Programs used in each stage (and invoked by the scripts) ==

1) MM/shrink.f, dep1.f                   > tmp.mch, tmp.dep
2) JBLOCK/TUV/tuv.f, JBLOCK/jblock.f     > tmp.jv
3) SOLV/prep.f90                         > solv.inp, bounds_mod.f90
4) SOLV/gear.f90                         > fort.n  where n = {7,8,9}
5) POST/plotsel.f90                      > fort.nn where nn = {22,23}

=============================================================================
== MasterMechanism input data files ==

General comments:
- Input data files should be named 'input.*' or 'output.*' so that the 
  runscripts can find them. 
- Input data is collated automatically into summary file solv.inp, which 
  can be edited further if only small changes are desired.
- If time-dependent data are supplied, first time must be no later than 
  run start time.
- One complete day of input data is expected (but not required).  
  If input data does not extend to end of run for run length < 1 day, 
  last input data point is extended as constant to end of run
  If input data does not extend to end of day for multi-day run, 
  data is interpolated as if part of a repeating daily cycle. 
- To change environmental conditions for subsequent days, run one day 
  at a time and use fort.9 output as initial concentrations for a new run
  with new environmental parameters.
- User comments can be added to input data files at ends of lines, and in 
  extra lines after all data.

**********************************************
input.species : list of starting species

format: vertical list, 4-character species names, one species per line
        last line must be '*******'
NOTE: List must include ALL species that appear in the lists of 
      initialised, constrained, emitted, and background species, 
      unless they are intentionally non-reactive (i.e. ballast gases).

**********************************************
input.solar : conditions for TUV run (not essential)

format: as "usrinp" file generated by TUV
     EITHER edit an existing file 
     OR respond to prompts during run,
        which creates a new file from scratch
     tstart and tstop refer to photolysis rate output NOT the box model run.
     tstart should be equal to or greater than 0.000
     tstop should be less than or equal to 24.000

**********************************************
input.prep : filenames for environmental conditions etc

format: 3 header lines 
        first data line: 2 numbers (free format)
        second data line: 1 number (integer)
        subsequent lines: filenames up to 30 characters, or 30 blank characters
        last data line: 'y' or 'n' (case insensitive)
        blanks = no file
        Input order must be retained:
0.00E+00 4.32E+05             ! a) start,stop time (s)
400                           ! b) number of save times (integer)
input.ic                      ! c) file: initial concs from prev. run (eg fort.9)
input.concs                   ! d) file: [X] vs. t
                              ! e) file: emissions
                              ! f) file: boundary layer height vs time
                              ! g) file: dilution background concentrations
                              ! h) file: dilution vs. time
                              ! i) file: cloud factor vs. time
                              ! j) file: temperature vs. time
                              ! k) file: rxn numbers for rate output
y                             ! l) switch: deposition? ('Y'/'N')
------------------------------!!fields must be <= 30 chars length   !!
NOTE1: all files are optional
NOTE2: if [N2] and [O2] are not specified as either initial or time-
       dependent, they are automatically generated from the atmospheric
       density value supplied in tmp.jv.
NOTE3: Files named "input.*" or "fort.9" are automatically copied into 
       directory TMP/.  Other input files must be copied manually to TMP/ 
       or filepaths must be specified relative to directory TMP/.
**********************************************
input file: [X] vs. t (input.concs)

format: a) Integer number of species
        b) 4-character species name, integer number of data lines c) for species
        c) time, concentration (repeat as necessary)
        [repeat format of b) and c) for each new species]
units: time of day, s
       conc, molec.cm-3

Notes:
- These concentrations OVERRIDE any input initial conditions.
- Data for each species must start at or before the run start time.
- For initial concentrations, one data line is required (conc at run start)
- For fixed concentrations, two data lines are required (conc at start and end).
- For time-varying constrained concentrations there are two options:
  a) input ends BEFORE end of first day => this input is repeated automatically
     for each day of the run.  Values are interpolated over midnight.
  b) input ends AFTER the run end time => to specify each day uniquely.
  Input timeseries are specified independently, i.e. it is possible to repeat
  the same constraints each day for one species (one day timeseries) while
  another species has unique constraints for each day (whole run timeseries).
- Multiple species ARE allowed, multiple files ARE NOT allowed.
**********************************************
input file: emissions

format: a) Integer number of species
        b) 4-character species name, integer number of data lines c) for species
        c) time, concentration (repeat as necessary)
        [repeat format of b) and c) for each new species]
units: time of day, s
       emissions, molec.cm-2.s-1

**********************************************
input file: initial concentrations (can use fort.9 output from gear.f90)

format: a) Integer number of data lines b)
        b) 4-character species name, concentration (molec.cm-3) (repeat)

**********************************************
input file: constrained concentrations

format: a) Integer number of data lines b)
        b) 4-character species name, concentration (molec.cm-3) (repeat)

NOTE: 'NOx' is a constrainable species.  The model performs the
      NO/NO2 partitioning on the fly.
**********************************************
input file: boundary layer height vs time

format: a) Integer number of data lines b)
        b) time, height (repeat b) as necessary)
units: time of day, s
       height, km

NOTE: if not used, boundary layer defaults to 1 km depth
**********************************************
input file: background concentrations

format: a) Integer number of data lines b)
        b) 4-character species name, concentration (molec.cm-3) (repeat)

**********************************************
input file: dilution vs. time

format: as pbl height vs. time
units: time of day, s
       exchange velocity, cm.s-1
       [ e.v. = eddy diffusion coefficient (cm2.s-1) 
                      divided by 
         heat/moisture transport length scale (cm) ]

**********************************************
input file: temperature vs. time

format: as pbl height vs. time
units: time of day, s
       temperature, K

NOTE: if no temperatures supplied, fixed T is taken from tmp.jv
**********************************************
input file: cloud factor vs. time

format: as pbl height vs. time
units: time of day, s
       *non*-cloudy sky fraction (0.0 = obscured, 1.0 = clear)

**********************************************
input file: reaction numbers for rate output

format: a) Integer number of data lines b)
        b) Vertical list of reaction numbers, as defined by tmp.mch

**********************************************
solv.inp : collated input to gear solver

format: is determined by program prep.f90 which constructs it.

  This file is user-editable, as long as the basic format and
  structure are retained.  Users may wish to alter initial or 
  constrained concentrations, or environmental parameters.
  The edited file can then be used as input to a gear solver run.
 
  For changes in the reaction mechanism or photolysis parameters
  we recommend that a new solv.inp file be built from scratch
  using the full Master Mechanism programming sequence.

**********************************************
plot.species : list of species for output plot

format: a) integer number of requested species / functional groups
        b) 4-character name of species / group  (repeat)
        final line: "*********"
NOTES: character names 'a(x)' and 'd(x)' refer to ALL molecules with 
       functional group 'x', and molecules with DOMINANT functional
       group 'x', respectively. Order of dominiance is:
       0123456789dpghnekaoucfblsmrtvwiq
       The key to these codes is found in MM/README. 
**********************************************
output.rates : list of reaction numbers for output rate timeseries

format : a) integer number of requested reaction rates
         b) integer corresponding to index of desired reaction in working mechanism subset
            Note that reactions are not explicitly labeled with their number. We recommend
            using the line number feature in your text editor to identify reaction indices. 

==============================================
OUTPUT / RESULTS
==============================================

from Step 4 (running the model)
fort.7: concentrations of all model species at all model output timesteps, formatted for use
        by the post-processing routines.
fort.8: all reaction rates at the end of the simulation, followed by selected rates 
        at all model output timesteps. 
fort.9: concentrations at the end of the simulation

from Step 5 (post-processing)
fort.22: a summary file giving initial, average, and final concentrations
fort.23: concentration (molec/cc) vs time (days) of the species listed in WORK/plot.species.
fort.28: reaction rates (reaction-specific units) vs time (days) of the species listed in WORK/output.rates.

fort.22, .23 & .28 are designed to be opened in a spreadsheet for easy data analysis. 
The time intervals for the tables in fort.23 & .28 are set by editing parameter 
"dtime" in program POST/plotsel.f90


End README
