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
is
GEOS_SunGetInsolation, which depends on an Orbit object.
The Orbit object defines this class and has public opaque type
GEOS_SunOrbit`.
Methods are provided for creating it, destroying it, and making various queries.
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 |
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.
Type | Intent | Optional | 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 |
Type | Intent | Optional | 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 |
Type | Intent | Optional | 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” |
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
Type | Intent | Optional | Attributes | Name | ||
---|---|---|---|---|---|---|
integer, | intent(in) | :: | Year | |||
integer, | intent(in) | :: | DayOfYear | |||
real, | intent(out) | :: | SC | |||
real, | intent(out), | optional | :: | HK(:) | ||
integer, | intent(out), | optional | :: | rc |
Type | Intent | Optional | Attributes | Name | ||
---|---|---|---|---|---|---|
type(ESMF_Time), | intent(inout) | :: | Time | |||
real, | intent(out) | :: | SC | |||
real, | intent(out), | optional | :: | HK(:) | ||
integer, | intent(out), | optional | :: | 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
Type | Intent | Optional | 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 |
Acquire the TSI, Mg, and SB from file.
@note Bug Band values for RRTMG not implemented
Type | Intent | Optional | 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 |
The function MAPL_SunOrbitCreated
returns .true.
if the given orbit object has been initilized.
Type | Intent | Optional | Attributes | Name | ||
---|---|---|---|---|---|---|
type(MAPL_SunOrbit), | intent(in) | :: | ORBIT | |||
integer, | intent(out), | optional | :: | RC |
Integrates the earths orbit and stores the necessary
parameters to easily compute the earth
s 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.
Type | Intent | Optional | 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 |
The function MAPL_SunOrbitCreateFromConfig
works like MAPL_SunOrbitCreate()
but gets orbital parameters from Config CF.
Type | Intent | Optional | 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 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.
Type | Intent | Optional | 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 |
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.
Type | Intent | Optional | 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 |
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.
Type | Intent | Optional | 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 |
The routine MAPL_SunOrbitDestroy
Destroys a GEOS_SunOrbit object,
deallocating the space used to save the ephemeris.
Type | Intent | Optional | Attributes | Name | ||
---|---|---|---|---|---|---|
type(MAPL_SunOrbit), | intent(inout) | :: | ORBIT | |||
integer, | intent(out), | optional | :: | 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.
Type | Intent | Optional | 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 |