MAPL_SunMod Module

MODULE: MAPL_SunMod

Author: GMAO SI-Team

This class is intended to manage the suns position and provide the insolation at the top of the atmosphere. The main method isGEOS_SunGetInsolation, which depends on an Orbit object. The Orbit object defines this class and has public opaque typeGEOS_SunOrbit`. Methods are provided for creating it, destroying it, and making various queries.


Uses

  • module~~mapl_sunmod~~UsesGraph module~mapl_sunmod MAPL_SunMod ESMF ESMF module~mapl_sunmod->ESMF iso_fortran_env iso_fortran_env module~mapl_sunmod->iso_fortran_env module~mapl_basemod MAPL_BaseMod module~mapl_sunmod->module~mapl_basemod module~mapl_commsmod MAPL_CommsMod module~mapl_sunmod->module~mapl_commsmod module~mapl_constants MAPL_Constants module~mapl_sunmod->module~mapl_constants module~mapl_exceptionhandling MAPL_ExceptionHandling module~mapl_sunmod->module~mapl_exceptionhandling module~mapl_iomod MAPL_IOMod module~mapl_sunmod->module~mapl_iomod module~pflogger pflogger module~mapl_sunmod->module~pflogger netcdf netcdf module~mapl_sunmod->netcdf module~mapl_basemod->module~mapl_constants module~mapl_base MAPL_Base module~mapl_basemod->module~mapl_base module~mapl_maplgrid mapl_MaplGrid module~mapl_basemod->module~mapl_maplgrid module~mapl_rangemod MAPL_RangeMod module~mapl_basemod->module~mapl_rangemod module~mapl_commsmod->ESMF module~mapl_commsmod->module~mapl_basemod module~mapl_commsmod->module~mapl_constants module~mapl_commsmod->module~mapl_exceptionhandling module~mapl_shmemmod MAPL_ShmemMod module~mapl_commsmod->module~mapl_shmemmod mpi mpi module~mapl_commsmod->mpi module~mapl_constants->iso_fortran_env module~mapl_internalconstantsmod MAPL_InternalConstantsMod module~mapl_constants->module~mapl_internalconstantsmod module~mapl_mathconstantsmod MAPL_MathConstantsMod module~mapl_constants->module~mapl_mathconstantsmod module~mapl_physicalconstantsmod MAPL_PhysicalConstantsMod module~mapl_constants->module~mapl_physicalconstantsmod module~mapl_errorhandlingmod mapl_ErrorHandlingMod module~mapl_exceptionhandling->module~mapl_errorhandlingmod module~mapl_throwmod MAPL_ThrowMod module~mapl_exceptionhandling->module~mapl_throwmod module~biniomod BinIOMod module~mapl_iomod->module~biniomod module~fileiosharedmod FileIOSharedMod module~mapl_iomod->module~fileiosharedmod module~nciomod NCIOMod module~mapl_iomod->module~nciomod module~pfl_keywordenforcermod PFL_KeywordEnforcerMod module~pflogger->module~pfl_keywordenforcermod module~pfl_logger PFL_Logger module~pflogger->module~pfl_logger module~pfl_loggermanager PFL_LoggerManager module~pflogger->module~pfl_loggermanager module~pfl_severitylevels PFL_SeverityLevels module~pflogger->module~pfl_severitylevels module~pfl_wraparray PFL_WrapArray module~pflogger->module~pfl_wraparray

Used by

  • module~~mapl_sunmod~~UsedByGraph module~mapl_sunmod MAPL_SunMod module~mapl_genericcplcompmod MAPL_GenericCplCompMod module~mapl_genericcplcompmod->module~mapl_sunmod module~mapl_genericmod MAPL_GenericMod module~mapl_genericmod->module~mapl_sunmod module~mapl_genericmod->module~mapl_genericcplcompmod module~maplbase_mod MAPLBase_Mod module~maplbase_mod->module~mapl_sunmod module~cubedspheregeomspec_smod CubedSphereGeomSpec_smod module~cubedspheregeomspec_smod->module~maplbase_mod module~equal_to_smod~3 equal_to_smod module~equal_to_smod~3->module~maplbase_mod module~historytrajectorymod HistoryTrajectoryMod module~historytrajectorymod->module~mapl_genericmod module~make_decomposition_smod make_decomposition_smod module~make_decomposition_smod->module~maplbase_mod module~make_distribution_smod make_distribution_smod module~make_distribution_smod->module~maplbase_mod module~make_latlongeomspec_from_hconfig_smod make_LatLonGeomSpec_from_hconfig_smod module~make_latlongeomspec_from_hconfig_smod->module~maplbase_mod module~make_latlongeomspec_from_metadata_smod make_LatLonGeomSpec_from_metadata_smod module~make_latlongeomspec_from_metadata_smod->module~maplbase_mod module~mapl MAPL module~mapl->module~mapl_genericmod module~mapl->module~maplbase_mod module~mapl_capgridcompmod MAPL_CapGridCompMod module~mapl_capgridcompmod->module~mapl_genericmod module~mapl_extdatagridcomp2g MAPL_ExtDataGridComp2G module~mapl_extdatagridcomp2g->module~mapl_genericmod module~mapl_extdatagridcompmod MAPL_ExtDataGridCompMod module~mapl_extdatagridcompmod->module~mapl_genericmod module~mapl_historygridcompmod MAPL_HistoryGridCompMod module~mapl_historygridcompmod->module~mapl_genericcplcompmod module~mapl_historygridcompmod->module~mapl_genericmod module~mapl_nuopcwrappermod MAPL_NUOPCWrapperMod module~mapl_nuopcwrappermod->module~maplbase_mod module~mapl_orbgridcompmod MAPL_OrbGridCompMod module~mapl_orbgridcompmod->module~mapl_genericmod module~masksamplergeosatmod MaskSamplerGeosatMod module~masksamplergeosatmod->module~mapl_genericmod module~rutmod RUTMod module~rutmod->module~maplbase_mod module~stationsamplermod StationSamplerMod module~stationsamplermod->module~mapl_genericmod module~supports_hconfig_smod~3 supports_hconfig_smod module~supports_hconfig_smod~3->module~maplbase_mod module~supports_metadata_smod~3 supports_metadata_smod module~supports_metadata_smod~3->module~maplbase_mod module~test_cfio_bundle Test_CFIO_Bundle module~test_cfio_bundle->module~maplbase_mod program~comp_testing_driver comp_testing_driver program~comp_testing_driver->module~mapl_genericmod program~tstqsat tstqsat program~tstqsat->module~maplbase_mod program~ut_extdata ut_ExtData program~ut_extdata->module~maplbase_mod program~utcfio~3 utCFIO program~utcfio~3->module~maplbase_mod

Variables

Type Visibility Attributes Name Initial
integer, public, parameter :: MAPL_SunAnnualMean = 6
integer, public, parameter :: MAPL_SunAutumnalEquinox = 1
integer, public, parameter :: MAPL_SunDailyMean = 5
integer, public, parameter :: MAPL_SunSummerSolstice = 4
integer, public, parameter :: MAPL_SunVernalEquinox = 3
integer, public, parameter :: MAPL_SunWinterSolstice = 2

Interfaces

public interface MAPL_SunGetInsolation

  • private recursive subroutine SOLAR_1D(LONS, LATS, ORBIT, ZTH, SLR, INTV, CLOCK, TIME, currTime, DIST, ZTHB, ZTHD, ZTH1, ZTHN, ZTHP, STEPSIZE, RC)

    GEOS_SunGetInsolation returns the cosine of the solar zenith angle and the insolation at the top of the atmosphere for the given reference time, latitudes, longitudes, and orbit. It is overloaded to accept either 1d or 2d FORTRAN arrays or ESMF arrays of lats and lons and to produce the corresponding outputs.

    The reference time is obtained as follows. If CurrTime is specified, it is used; otherwise, if the optional clock is specified, it is set to the time on that clock. If neither currTime nor clock are given, the time on the attached clock is used.

    If the optional time interval is specified, the return values are averages over that interval following the reference time. In this case, the cosine of the solar zenith angle is an insolation-weighted average. The straight average of the zenith angle and the average over the daylight part of the interval (ZTHB,ZTHD) and the values at the beginning and end of the interval (ZTH1,ZTHN) are also optionally available. The last two are supported only for first two (non-ESMF) overloads. PMN Jun 2020: Added optional ZTHP, like ZTHB a pure average of the cosine of the solar zenith angle, except that for ZTHP the value averaged is allowed to be negative (below the horizon). It will be used for Photolysis calculations. Not implemented for ESMF overload.

    If the interval is not specified, the values are instantaneous values valid at the reference time.

    The optional TIME argument is used to return some specialized insolations. For example, the orbit at any of four Equinox or Solstice positions. If TIME is present, only the time of day is used from the clock, and a time interval, if specified, must be less than 24 hours. It can also be used to return daily-mean insolation for the date on the clock, or the annual-mean insolation for the year on the clock.

    The TIME argument can be any of the following:

          MAPL_SunAutumnalEquinox
      MAPL_SunWinterSolstice
      MAPL_SunVernalEquinox
      MAPL_SunSummerSolstice
      MAPL_SunDailyMean
      MAPL_SunAnnualMean

    @note Note If ORBIT%EOT is .TRUE., an Equation of Time correction will be applied. This shifts the actual daylight period w.r.t. to mean solar noon, to account for small but cumulative eccentricity and obliquity effects on the actual length of the solar day.

    Arguments

    Type IntentOptional Attributes Name
    real, intent(in) :: LONS(:)
    real, intent(in) :: LATS(:)
    type(MAPL_SunOrbit), intent(in) :: ORBIT
    real, intent(out) :: ZTH(:)
    real, intent(out) :: SLR(:)
    type(ESMF_TimeInterval), intent(inout), optional :: INTV
    type(ESMF_Clock), intent(in), optional :: CLOCK
    integer, intent(in), optional :: TIME
    type(ESMF_Time), intent(in), optional :: currTime
    real, intent(out), optional :: DIST
    real, intent(out), optional :: ZTHB(:)
    real, intent(out), optional :: ZTHD(:)
    real, intent(out), optional :: ZTH1(:)
    real, intent(out), optional :: ZTHN(:)
    real, intent(out), optional :: ZTHP(:)
    real, intent(in), optional :: STEPSIZE
    integer, intent(out), optional :: RC

  • private recursive subroutine SOLAR_2D(LONS, LATS, ORBIT, ZTH, SLR, INTV, CLOCK, TIME, currTime, DIST, ZTHB, ZTHD, ZTH1, ZTHN, ZTHP, STEPSIZE, RC)

    Arguments

    Type IntentOptional Attributes Name
    real, intent(in) :: LONS(:,:)
    real, intent(in) :: LATS(:,:)
    type(MAPL_SunOrbit), intent(in) :: ORBIT
    real, intent(out) :: ZTH(:,:)
    real, intent(out) :: SLR(:,:)
    type(ESMF_TimeInterval), intent(inout), optional :: INTV
    type(ESMF_Clock), intent(in), optional :: CLOCK
    integer, intent(in), optional :: TIME
    type(ESMF_Time), intent(in), optional :: currTime
    real, intent(out), optional :: DIST
    real, intent(out), optional :: ZTHB(:,:)
    real, intent(out), optional :: ZTHD(:,:)
    real, intent(out), optional :: ZTH1(:,:)
    real, intent(out), optional :: ZTHN(:,:)
    real, intent(out), optional :: ZTHP(:,:)
    real, intent(in), optional :: STEPSIZE
    integer, intent(out), optional :: RC

  • private subroutine SOLAR_ARR_INT(LONS, LATS, ORBIT, ZTH, SLR, INTV, CLOCK, TIME, currTime, DIST, ZTHB, ZTHD, RC)

    Arguments

    Type IntentOptional Attributes Name
    type(ESMF_Array), intent(in) :: LONS
    type(ESMF_Array), intent(in) :: LATS
    type(MAPL_SunOrbit), intent(in) :: ORBIT
    type(ESMF_Array), intent(out) :: ZTH
    type(ESMF_Array), intent(out) :: SLR
    type(ESMF_TimeInterval), intent(inout), optional :: INTV
    type(ESMF_Clock), intent(in), optional :: CLOCK
    integer, intent(in), optional :: TIME
    type(ESMF_Time), intent(in), optional :: currTime
    real, intent(out), optional :: DIST
    type(ESMF_Array), intent(out), optional :: ZTHB
    type(ESMF_Array), intent(out), optional :: ZTHD
    integer, intent(out), optional :: RC

    $ character(len=ESMF_MAXSTR) :: IAm = “SunGetInsolationArr”

public interface MAPL_SunGetSolarConstant

  • private subroutine MAPL_SunGetSolarConstantByYearDoY(Year, DayOfYear, SC, HK, rc)

    Given the year and day-of-year, this function returns the CMIP5 solar constant and the 8 band fractions for the Chou solar code. These are based on annual values from 1610 to 2008 and a repeating cycle after 2008. For dates prior tp 1 January 1610, it returns the value at the start of 1610.

    DayOfYear is expected to have a value of 1.00 at 0:00 UTC Jan 1 and leap years are acounted for by repeating the 366th day on January first of the following year.

    The SC values have been multiplied by .9965 to calibrate to the SOURCE/TIM scale. The SC values include the “background” variation.

    @note Bug Band values for RRTMG not implemented

    Arguments

    Type IntentOptional Attributes Name
    integer, intent(in) :: Year
    integer, intent(in) :: DayOfYear
    real, intent(out) :: SC
    real, intent(out), optional :: HK(:)
    integer, intent(out), optional :: rc

  • private subroutine MAPL_SunGetSolarConstantByTime(Time, SC, HK, rc)

    Arguments

    Type IntentOptional Attributes Name
    type(ESMF_Time), intent(inout) :: Time
    real, intent(out) :: SC
    real, intent(out), optional :: HK(:)
    integer, intent(out), optional :: rc

  • private subroutine MAPL_SunGetSolarConstantFromNetcdfFile(CLOCK, fileName, SC, HK, MESOPHOT, JCALC4, rc)

    Acquire the solar constant and the eight band fractions for the Chou solar code from an external NetCDF file. The initial configuration assumes monthly values beginning in January, and does not interpolate beyond the range of available data.

    Bug

    Band values for RRTMG not implemented

    Arguments

    Type IntentOptional Attributes Name
    type(ESMF_Clock), intent(in) :: CLOCK
    character(len=*), intent(in) :: fileName
    real, intent(out) :: SC
    real, intent(out), optional :: HK(:)
    real, intent(out), optional :: MESOPHOT(:)
    real, intent(out), optional :: JCALC4(:)
    integer, intent(out), optional :: rc

  • private subroutine MAPL_SunGetSolarConstantFromNRLFile(CLOCK, filename_in, SC, MG, SB, PersistSolar, rc)

    Acquire the TSI, Mg, and SB from file.

    @note Bug Band values for RRTMG not implemented

    Arguments

    Type IntentOptional Attributes Name
    type(ESMF_Clock), intent(in) :: CLOCK
    character(len=*), intent(in) :: filename_in
    real, intent(out) :: SC
    real, intent(out) :: MG
    real, intent(out) :: SB
    logical, intent(in), optional :: PersistSolar
    integer, intent(out), optional :: rc

Derived Types

type, public ::  MAPL_SunOrbit


Functions

public function MAPL_SunOrbitCreated(ORBIT, RC)

The function MAPL_SunOrbitCreated returns .true. if the given orbit object has been initilized.

Arguments

Type IntentOptional Attributes Name
type(MAPL_SunOrbit), intent(in) :: ORBIT
integer, intent(out), optional :: RC

Return Value logical

public function MAPL_SunOrbitCreate(CLOCK, ECCENTRICITY, OBLIQUITY, PERIHELION, EQUINOX, EOT, ORBIT_ANAL2B, ORB2B_YEARLEN, ORB2B_REF_YYYYMMDD, ORB2B_REF_HHMMSS, ORB2B_ECC_REF, ORB2B_ECC_RATE, ORB2B_OBQ_REF, ORB2B_OBQ_RATE, ORB2B_LAMBDAP_REF, ORB2B_LAMBDAP_RATE, ORB2B_EQUINOX_YYYYMMDD, ORB2B_EQUINOX_HHMMSS, FIX_SUN, RC)

Integrates the earths orbit and stores the necessary parameters to easily compute the earths position for each day of the full (usually 4-year) intercalation cycle. The orbital parameters are passed as arguments. The full calendar intercalation cycle is obtained from the ESMF clock passed as an argument. This becomes the orbit`s attached clock. Currently we assume a single intercalation.

Read more…

Arguments

Type IntentOptional Attributes Name
type(ESMF_Clock), intent(in) :: CLOCK
real, intent(in) :: ECCENTRICITY
real, intent(in) :: OBLIQUITY
real, intent(in) :: PERIHELION
integer, intent(in) :: EQUINOX
logical, intent(in) :: EOT
logical, intent(in) :: ORBIT_ANAL2B
real, intent(in) :: ORB2B_YEARLEN
integer, intent(in) :: ORB2B_REF_YYYYMMDD
integer, intent(in) :: ORB2B_REF_HHMMSS
real, intent(in) :: ORB2B_ECC_REF
real, intent(in) :: ORB2B_ECC_RATE
real, intent(in) :: ORB2B_OBQ_REF
real, intent(in) :: ORB2B_OBQ_RATE
real, intent(in) :: ORB2B_LAMBDAP_REF
real, intent(in) :: ORB2B_LAMBDAP_RATE
integer, intent(in) :: ORB2B_EQUINOX_YYYYMMDD
integer, intent(in) :: ORB2B_EQUINOX_HHMMSS
logical, intent(in), optional :: FIX_SUN
integer, intent(out), optional :: RC

Return Value type(MAPL_SunOrbit)

public function MAPL_SunOrbitCreateFromConfig(CF, CLOCK, FIX_SUN, RC) result(ORBIT)

The function MAPL_SunOrbitCreateFromConfig works like MAPL_SunOrbitCreate() but gets orbital parameters from Config CF.

Arguments

Type IntentOptional Attributes Name
type(ESMF_Config), intent(inout) :: CF
type(ESMF_Clock), intent(in) :: CLOCK
logical, intent(in) :: FIX_SUN
integer, intent(out), optional :: RC

Return Value type(MAPL_SunOrbit)


Subroutines

public subroutine MAPL_SunGetDaylightDuration(ORBIT, LATS, DAYL, currTime, CLOCK, RC)

Return the daylight duration in seconds (i.e, the time between sunrise and sunset) for a day around the specified time. The routine is accurate enough for most purposes, but does not solve for precise sunrise/sunset times influenced by changes in the orbital parameters between those times. The time input does NOT need to be noon — it is used simply to evaluate the solar declination needed for the daylight duration calculation. In order of preference, time is taken from currTime, if present, or else the currTime of CLOCK, if present, or else the currTime of the ORBIT’s associated clock.

Arguments

Type IntentOptional Attributes Name
type(MAPL_SunOrbit), intent(in) :: ORBIT
real, intent(in), dimension(:) :: LATS
real, intent(out), dimension(:) :: DAYL
type(ESMF_Time), intent(in), optional :: currTime
type(ESMF_Clock), intent(in), optional :: CLOCK
integer, intent(out), optional :: RC

public subroutine MAPL_SunGetDaylightDurationMax(ORBIT, LATS, DAYL, currTime, CLOCK, RC)

Return the daylight duration in seconds (i.e, the time between sunrise and sunset) for its MAXIMUM at the summer solstice. The routine is accurate enough for most purposes, but does not solve for precise sunrise/sunset times influenced by changes in the orbital parameters between those times. The time input does NOT need to be noon — it is used simply to evaluate the obliquity needed for the maximum daylight duration calculation. In order of preference, time is taken from currTime, if present, or else the currTime of CLOCK, if present, or else the currTime of the ORBIT’s associated clock. Note: Unless ORBIT_ANAL2B, the obliquity is fixed and the time is irrelevant.

Arguments

Type IntentOptional Attributes Name
type(MAPL_SunOrbit), intent(in) :: ORBIT
real, intent(in), dimension(:) :: LATS
real, intent(out), dimension(:) :: DAYL
type(ESMF_Time), intent(in), optional :: currTime
type(ESMF_Clock), intent(in), optional :: CLOCK
integer, intent(out), optional :: RC

public subroutine MAPL_SunGetLocalSolarHourAngle(ORBIT, LONS, LSHA, TIME, CLOCK, FORCE_MLSHA, RC)

Returns the local solar hour angle (in radians) at the single time and multiple longitudes specified. In order of preference, time is taken from TIME, if present, or else the CURRTIME of CLOCK, if present, or else the CURRTIME of the ORBIT’s associated clock.

Read more…

Arguments

Type IntentOptional Attributes Name
type(MAPL_SunOrbit), intent(in) :: ORBIT
real, intent(in), dimension(:) :: LONS
real, intent(out), dimension(:) :: LSHA
type(ESMF_Time), intent(in), optional :: TIME
type(ESMF_Clock), intent(in), optional :: CLOCK
logical, intent(in), optional :: FORCE_MLSHA
integer, intent(out), optional :: RC

public subroutine MAPL_SunOrbitDestroy(ORBIT, RC)

The routine MAPL_SunOrbitDestroy Destroys a GEOS_SunOrbit object, deallocating the space used to save the ephemeris.

Arguments

Type IntentOptional Attributes Name
type(MAPL_SunOrbit), intent(inout) :: ORBIT
integer, intent(out), optional :: RC

public subroutine MAPL_SunOrbitQuery(ORBIT, ECCENTRICITY, OBLIQUITY, PERIHELION, EQUINOX, YEAR_LENGTH, YEARS_PER_CYCLE, DAYS_PER_CYCLE, CLOCK, ZS, ZC, TH, PP, ET, RC)

Query for quantities in an orbit object. Optionally returns the parameters of the orbit and its associated ESMF_Clock. It fails if the orbit has not been created.

Read more…

Arguments

Type IntentOptional Attributes Name
type(MAPL_SunOrbit), intent(in) :: ORBIT
real, intent(out), optional :: ECCENTRICITY
real, intent(out), optional :: OBLIQUITY
real, intent(out), optional :: PERIHELION
integer, intent(out), optional :: EQUINOX
real, intent(out), optional :: YEAR_LENGTH
integer, intent(out), optional :: YEARS_PER_CYCLE
integer, intent(out), optional :: DAYS_PER_CYCLE
type(ESMF_Clock), intent(out), optional :: CLOCK
real, optional, pointer, dimension(:) :: ZS
real, optional, pointer, dimension(:) :: ZC
real, optional, pointer, dimension(:) :: TH
real, optional, pointer, dimension(:) :: PP
real, optional, pointer, dimension(:) :: ET
integer, intent(out), optional :: RC