.. include:: ../defs.hrst .. _sub_phys_pkg_oasim: OASIM package ------------- 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/ :cite:`gregg:1990,gregg:2009`. Compiling and Running ~~~~~~~~~~~~~~~~~~~~~ Compiling ^^^^^^^^^ Include the word ``oasim`` in ``packages.conf`` in your code directory. Unless OASIM_READ_UNFORMATTED is defined in :filelink:`~pkg/radtrans/OASIM_OPTIONS.h`, the exf package is needed too. Set compile-time options for oasim in file :filelink:`~pkg/oasim/OASIM_OPTIONS.h` (see table below). .. tabularcolumns:: |l|L| .. csv-table:: CPP options for the oasim package :delim: & :widths: auto :header: CPP option, description :varlink:`OASIM_INST_ZENITH_ANGLE` & compute solar zenith angle at myTime instead of averaging over time step :varlink:`OASIM_READ_UNFORMATTED` & read combined fortran-unformatted files as in original OASIM; these are used constant-in-time for each month :varlink:`OASIM_OUTPUT_FORCING` & write preprocessed forcing data :varlink:`OASIM_DAILY_NUTATE` & compute nutation correction only on day change [#compat]_ :varlink:`OASIM_SCALAR_ZENITH_ANGLE_COMP` & do not vectorize zenith angle computation [#compat]_ .. [#compat] 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. Running ^^^^^^^ You will need to set :varlink:`useOASIM` = .TRUE. (and also useEXF unless OASIM_READ_UNFORMATTED) in ``data.pkg``. Runtime Parameters '''''''''''''''''' Runtime parameters are set in ``data.oasim`` in these namelists: .. csv-table:: :delim: & :widths: auto :header: Namelist, Description :varlink:`OASIM_FORCING_PARM` & parameters related to forcing and initialization :varlink:`OASIM_INTERP_PARM` & parameters for interpolation of forcing fields (only used if :varlink:`USE_EXF_INTERPOLATION` is defined) :varlink:`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: .. csv-table:: OASIM forcing options :delim: & :widths: auto :header: Name, Default, Description :varlink:`useOasimYearlyFields` & :varlink:`useExfYearlyFields` & append current year postfix of form ``_YYYY`` on filename :varlink:`oasimTimeInterp` & 1 & order of time interpolation; for piecewise constant, set to 0 The forcing fields are: .. csv-table:: OASIM forcing fields :delim: & :widths: 10,12,78 :header: 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/m\ :sup:`2` & 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/m\ :sup:`2` & water vapor concentration Each forcing field has a set of parameters. These work as in the exf package, see :numref:`tab_phys_pkg_exf_runtime_attributes`, except some of the aerTau, asymp and ssalb parameters are spectral, e.g. .. csv-table:: Namelist OASIM_FORCING_PARAMS: spectral example for aerTau, asymp and ssalb :delim: & :widths: auto :header: Name, Default, Description :varlink:`aerTaufile` & ' ' & file name for aerosol optical thickness; actual file name will be aerTau### for waveband ### :varlink:`aerTauConst`\ (l) & 0.0 & constant that will be used if no file is read :varlink:`aerTauPeriod` & 0.0 & interval in seconds between two records :varlink:`aerTauRepCycle` & :varlink:`repeatCycle` & repeat cycle in seconds; only available if :varlink:`useOasimYearlyFields` is .FALSE. :varlink:`aerTauStartTime` & UNSET_RL & time in seconds of first record from the beginning of the model integration or, if useOasimYearlyFields, from the beginning of year :varlink:`aerTaustartdate1` & 0 & date/time of first record when using the cal package; format: YYYYMMDD; start year (YYYY), month (MM), day (YY) :varlink:`aerTaustartdate2` & 0 & format: HHMMSS; start hour (HH), minute (MM), second(SS) :varlink:`aerTaumask` & 'c' & grid point for masking: ' ' = no masking; 'c' = centered mask; 'w' = western mask; 's' = southern :varlink:`aerTau_exfremo_intercept`\ (l) & 0.0 & can be used to remove global mean :varlink:`aerTau_exfremo_slope`\ (l) & 0.0 & can be used to remove global trend :varlink:`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: .. csv-table:: Namelist OASIM_PARAMS :delim: & :widths: auto :header: Name, Default, Units, Description :varlink:`oasim_atmoFile` & ' ' & & name of file with fixed atmospheric spectra :varlink:`oasim_waterFile` & ' ' & & name of file with water spectra :varlink:`oasim_slingoFile` & ' ' & & name of file with spectra for clouds :varlink:`oasim_startYear` & & & year of iteration 0 when cal package is not used :varlink:`oasim_dTsolz` & 900.0 & s & time step for solar zenith angle averaging :varlink:`oasim_am` & 1.0 & & air-mass parameter for navaer aerosol model :varlink:`oasim_Vi` & 25.0 & km & visibility for navaer aerosol model :varlink:`oasim_fixedSolz` & & & fixed solar zenith angle to use (for debugging) :varlink:`oasim_fixedLon` & & degrees & fixed longitude to use (for legacy mode) :varlink:`oasim_monitorFreq` & monitorFreq & & monitor frequency for OASIM package :varlink:`oasim_rmus` & 1/0.83 & & inverse mean zenith cosine of diffuse downwelling irradiance :varlink:`oasim_wbEdges(:)` & & nm & waveband boundaries [#edges]_ :varlink:`oasim_PARminWL` & 400 & nm & lower end of wavelength range for sPARblw diagnostic :varlink:`oasim_PARmaxWL` & 700 & nm & upper end of wavelength range for sPARblw diagnostic .. [#edges] 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: .. tabularcolumns:: |l|L| .. csv-table:: OASIM pkg output fields :delim: & :widths: auto :header: 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 Diagnostics ~~~~~~~~~~~ .. table:: :widths: 15,16,12,57 +-------------+------------------+-------------------------+----------------------------------------------------------+ | **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/m\ :sup:`2` | direct-beam clear-sky irradiance in waveband ### | +-------------+------------------+-------------------------+----------------------------------------------------------+ | Esclr### | ``SM______L1`` | W/m\ :sup:`2` | diffuse clear-sky irradiance in waveband ### | +-------------+------------------+-------------------------+----------------------------------------------------------+ | Edcld### | ``SM______L1`` | W/m\ :sup:`2` | direct-beam cloudy-sky irradiance in waveband ### | +-------------+------------------+-------------------------+----------------------------------------------------------+ | Escld### | ``SM______L1`` | W/m\ :sup:`2` | diffuse cloudy-sky irradiance in waveband ### | +-------------+------------------+-------------------------+----------------------------------------------------------+ | Edabv### | ``SM______L1`` | W/m\ :sup:`2` | direct-beam irradiance above sea surface in wvbd ### | +-------------+------------------+-------------------------+----------------------------------------------------------+ | Esabv### | ``SM______L1`` | W/m\ :sup:`2` | diffuse irradiance above sea surface in waveband ### | +-------------+------------------+-------------------------+----------------------------------------------------------+ | Edblw### | ``SM______L1`` | W/m\ :sup:`2` | direct-beam irradiance below sea surface in wvbd ### | +-------------+------------------+-------------------------+----------------------------------------------------------+ | Esblw### | ``SM______L1`` | W/m\ :sup:`2` | diffuse irradiance below sea surface in waveband ### | +-------------+------------------+-------------------------+----------------------------------------------------------+ | E0blw### | ``SM______L1`` | W/m\ :sup:`2` | 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/m\ :sup:`2`/s | downwelling scalar irradiance below surface | +-------------+------------------+-------------------------+----------------------------------------------------------+ Call tree ~~~~~~~~~ .. parsed-literal:: 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