\(\newcommand{\p}[1]{\frac{\partial }{\partial #1}}\) \(\newcommand{\pp}[2]{\frac{\partial #1}{\partial #2}}\) \(\newcommand{\dd}[2]{\frac{d #1}{d #2}}\) \(\newcommand{\h}{\frac{1}{2}}\) \(\newcommand{\op}[1]{\operatorname{#1}}\)

8.7.6. OASIM package

8.7.6.1. Introduction

The oasim package computes spectral, sea-surface light fields, separate for beam and diffuse components, based on data for aerosols, clouds and atmospheric gas concentrations, usually from satellite observations. The code is based on the OASIM software available from the Goddard Space Flight Center: https://gmao.gsfc.nasa.gov/reanalysis/MERRA-NOBM/software/ [GC90, GC09].

8.7.6.2. Compiling and Running

8.7.6.2.1. Compiling

Include the word oasim in packages.conf in your code directory. Unless OASIM_READ_UNFORMATTED is defined in OASIM_OPTIONS.h, the exf package is needed too.

Set compile-time options for oasim in file OASIM_OPTIONS.h (see table below).

Table 8.79 CPP options for the oasim package

CPP option

description

OASIM_INST_ZENITH_ANGLE

compute solar zenith angle at myTime instead of averaging over time step

OASIM_READ_UNFORMATTED

read combined fortran-unformatted files as in original OASIM; these are used constant-in-time for each month

OASIM_OUTPUT_FORCING

write preprocessed forcing data

OASIM_DAILY_NUTATE

compute nutation correction only on day change 1

OASIM_SCALAR_ZENITH_ANGLE_COMP

do not vectorize zenith angle computation 1
1(1,2)

To emulate original oasim code as closely as possible, set these two CPP options, set oasim_fixedLon=0 and set oasim_timeInterp=0 in data.oasim or #define OASIM_READUNFORMATTED.

8.7.6.2.2. Running

You will need to set useOASIM = .TRUE. (and also useEXF unless OASIM_READ_UNFORMATTED) in data.pkg.

Runtime Parameters

Runtime parameters are set in data.oasim in these namelists:

Namelist

Description

OASIM_FORCING_PARM

parameters related to forcing and initialization

OASIM_INTERP_PARM

parameters for interpolation of forcing fields (only used if USE_EXF_INTERPOLATION is defined)

OASIM_PARM

general parameters

Forcing fields are generally read in using the exf package, though there is an option to read the forcing from unformatted files as in the original OASIM code. How files are read by the exf package is controlled by the namelist OASIM_FORCING_PARAMS. The following parameters affect all OASIM forcing fields:

Table 8.80 OASIM forcing options

Name

Default

Description

useOasimYearlyFields

useExfYearlyFields

append current year postfix of form _YYYY on filename

oasimTimeInterp

1

order of time interpolation; for piecewise constant, set to 0

The forcing fields are:

Table 8.81 OASIM forcing fields

Name

Units

Description

aerTau(l)

1

aerosol optical thickness for wavewand l

asymp(l)

1

aerosol asymmetry parameter for waveband l

ssalb(l)

1

single-scattering albedo for waveband l

cldcov

percent

cloud cover

cldlwp

g/m2

cloud liquid water path

cldre

µm

effective droplet radius

pres

mbar

pressure

oawind

m/s

wind speed

relhum

percent

relative humidity

ozone

DU

ozone concentration

wv

kg/m2

water vapor concentration

Each forcing field has a set of parameters. These work as in the exf package, see Table 8.12, except some of the aerTau, asymp and ssalb parameters are spectral, e.g.

Table 8.82 Namelist OASIM_FORCING_PARAMS: spectral example for aerTau, asymp and ssalb

Name

Default

Description

aerTaufile

‘ ‘

file name for aerosol optical thickness; actual file name will be aerTau### for waveband ###

aerTauConst(l)

0.0

constant that will be used if no file is read

aerTauPeriod

0.0

interval in seconds between two records

aerTauRepCycle

repeatCycle

repeat cycle in seconds; only available if useOasimYearlyFields is .FALSE.

aerTauStartTime

UNSET_RL

time in seconds of first record from the beginning of the model integration or, if useOasimYearlyFields, from the beginning of year

aerTaustartdate1

0

date/time of first record when using the cal package; format: YYYYMMDD; start year (YYYY), month (MM), day (YY)

aerTaustartdate2

0

format: HHMMSS; start hour (HH), minute (MM), second(SS)

aerTaumask

‘c’

grid point for masking: ‘ ‘ = no masking; ‘c’ = centered mask; ‘w’ = western mask; ‘s’ = southern

aerTau_exfremo_intercept(l)

0.0

can be used to remove global mean

aerTau_exfremo_slope(l)

0.0

can be used to remove global trend

aerTau_inscal(l)

1.0

optional rescaling of input fields to adjust units

Interpolation parameters are set in namelist OASIM_INTERP_PARAMS. See the exf package on how to set them.

General parameters are set in namelist OASIM_PARAMS:

Table 8.83 Namelist OASIM_PARAMS

Name

Default

Units

Description

oasim_atmoFile

‘ ‘

name of file with fixed atmospheric spectra

oasim_waterFile

‘ ‘

name of file with water spectra

oasim_slingoFile

‘ ‘

name of file with spectra for clouds

oasim_startYear

year of iteration 0 when cal package is not used

oasim_dTsolz

900.0

s

time step for solar zenith angle averaging

oasim_am

1.0

air-mass parameter for navaer aerosol model

oasim_Vi

25.0

km

visibility for navaer aerosol model

oasim_fixedSolz

fixed solar zenith angle to use (for debugging)

oasim_fixedLon

degrees

fixed longitude to use (for legacy mode)

oasim_monitorFreq

monitorFreq

monitor frequency for OASIM package

oasim_rmus

1/0.83

inverse mean zenith cosine of diffuse downwelling irradiance

oasim_wbEdges(:)

nm

waveband boundaries 2

oasim_PARminWL

400

nm

lower end of wavelength range for sPARblw diagnostic

oasim_PARmaxWL

700

nm

upper end of wavelength range for sPARblw diagnostic
2

For nlt=33, the default waveband boundaries are 200, 300, 350, 362.5, 387.5, 412.5, 437.5, 462.5, 487.5, 512.5, 537.5, 562.5, 587.5, 612.5, 637.5, 662.5, 687.5, 700, 750, 800, 900, 1000, 1100, 1200, 1300, 1400, 1500, 1600, 1700, 1800, 2000, 2400, 3400, 4000 nm.

The following variables are automatically computed and can be used by including OASIM_SIZE.h and OASIM_FIELDS.h:

Table 8.84 OASIM pkg output fields

variable

description

oasim_solz

above-water solar zenith angle (degrees)

oasim_rmud

inverse cosine of below-water beam zenith angle

oasim_Edabove

downwelling beam irradiance above sea surface

oasim_Esabove

downwelling diffuse irradiance above sea surface

oasim_Edbelow

downwelling beam irradiance below sea surface

oasim_Esbelow

downwelling diffuse irradiance below sea surface

8.7.6.3. Diagnostics

Name

Code

Units

Description

OASIMsol

SM______L1

degrees

solar zenith angle above water

OASIMrmd

SM______L1

1

inverse cosine of beam zenith angle below water

taua###

SM______L1

1

aerosol optical thickness used in waveband ###

asymp###

SM______L1

1

aerosol asymmetry parameter used in waveband ###

ssalb###

SM______L1

1

aerosol single-scattering albedo used in waveband ###

Edclr###

SM______L1

W/m2

direct-beam clear-sky irradiance in waveband ###

Esclr###

SM______L1

W/m2

diffuse clear-sky irradiance in waveband ###

Edcld###

SM______L1

W/m2

direct-beam cloudy-sky irradiance in waveband ###

Escld###

SM______L1

W/m2

diffuse cloudy-sky irradiance in waveband ###

Edabv###

SM______L1

W/m2

direct-beam irradiance above sea surface in wvbd ###

Esabv###

SM______L1

W/m2

diffuse irradiance above sea surface in waveband ###

Edblw###

SM______L1

W/m2

direct-beam irradiance below sea surface in wvbd ###

Esblw###

SM______L1

W/m2

diffuse irradiance below sea surface in waveband ###

E0blw###

SM______L1

W/m2

scalar irradiance below sea surface in waveband ###

OArod###

SM______L1

1

sea-surface reflectance for direct beam in wvbd ###

OAros###

SM______L1

1

sea-surface reflectance for diffuse light in wvbd ###

sPARblw

SM______L1

µEin/m2/s

downwelling scalar irradiance below surface

8.7.6.4. Call tree

the_model_main
  initialise_fixed
    packages_readparms
      oasim_readparms
        oasim_exf_readparms
    packages_init_fixed
      oasim_init_fixed
        oasim_init_atmow
        oasim_init_clear
        oasim_init_aer
        oasim_init_slingo
          oasim_rdslingo
        oasim_init_vec
        oasim_exf_init_fixed
        oasim_diagnostics_init
    packages_check
      oasim_check
  the_main_loop
    initialise_varia
      packages_init_variables
        oasim_init_varia
          oasim_exf_init_varia
    main_do_loop
      forward_step
        load_fields_driver
          oasim_fields_load
            oasim_load_unformatted
              oasim_read
                oasim_read_clouds
                oasim_read_gases
                oasim_read_aerosols
            oasim_exf_load
              oasim_set_fld
                oasim_getmonthsrec
            oasim_forcing
              oasim_calc_solz
                oasim_sfcsolz_inst
                  oasim_sun_vector
                    oasim_ephparms
                    oasim_nutate
                    oasim_sun2000
                    oasim_gha2000
                    oasim_julian_day
                oasim_sfcsolz
                  oasim_sun_vector...
              oasim_calc_above
                oasim_navaer
                oasim_light
                  oasim_clrtrans
                  oasim_slingo
              oasim_calc_below
                oasim_sfcrfl
            oasim_monitor