Title:	Mars Solar Radiation
Version:	1.0.0
Description:	A set of functions to calculate solar irradiance and insolation on Mars horizontal and inclined surfaces. Based on NASA Technical Memoranda 102299, 103623, 105216, 106321, and 106700, i.e. the canonical Mars solar radiation papers.
License:	GPL-3
URL:	https://georges.fyi/marsrad/, https://github.com/georgeslabreche/marsrad
BugReports:	https://github.com/georgeslabreche/marsrad/issues
Encoding:	UTF-8
LazyData:	true
RoxygenNote:	7.3.3
Depends:	R (≥ 2.10)
Imports:	stats
Suggests:	testthat, covr, DT, htmltools
NeedsCompilation:	no
Packaged:	2025-11-24 05:33:29 UTC; georgeslabreche
Author:	Georges Labrèche [aut, cre]
Maintainer:	Georges Labrèche <georges@tanagraspace.com>
Repository:	CRAN
Date/Publication:	2025-11-27 19:10:07 UTC

marsrad: Mars Solar Radiation

Description

A set of functions to calculate solar irradiance and insolation on Mars horizontal and inclined surfaces. Based on NASA Technical Memoranda 102299, 103623, 105216, 106321, and 106700, i.e. the canonical Mars solar radiation papers.

Details

The package provides three types of solar radiation calculations:

• Instantaneous irradiance (G_* functions) — Power per unit area at a specific moment

• Daily insolation (H_* functions) — Energy per unit area over one Martian sol

• Period insolation (I_* functions) — Energy per unit area over multiple sols

All calculations support both horizontal and inclined surfaces. The package includes functions for optimal tilt angle calculation, sunrise/sunset times, and atmospheric optical depth modeling.

Package Information

Version

1.0.0

License

GPL-3

Website

https://georges.fyi/marsrad/

Author

Georges Labrèche

Affiliation

Tanagra Space

Depends

R (>= 2.10)

Citation

If you use this package in your research or publication, please cite the paper it was developed for:

Labrèche, G., & Cordes, F. (2020). Using a Rover's Active Suspension System as a 2-Axis Solar Tracker Mechanism. 15th International Symposium on Artificial Intelligence, Robotics and Automation in Space (i-SAIRAS '20). https://www.hou.usra.edu/meetings/isairas2020fullpapers/pdf/5035.pdf

Links

Package website

https://georges.fyi/marsrad/

Package GitHub repository

https://github.com/georgeslabreche/marsrad

Author LinkedIn

https://www.linkedin.com/in/georgeslabreche/

Author website

https://georges.fyi

Author(s)

Maintainer: Georges Labrèche georges@tanagraspace.com (ORCID)

References

Appelbaum, J., & Flood, D. J. (1989). Solar Radiation on Mars. NASA Technical Memorandum 102299. https://ntrs.nasa.gov/citations/19890018252

Appelbaum, J., & Flood, D. J. (1990). Solar radiation on Mars: Update 1990. NASA Technical Memorandum 103623. https://ntrs.nasa.gov/citations/19910005804

Appelbaum, J., & Flood, D. J. (1991). Solar radiation on Mars: Update 1991. NASA Technical Memorandum 105216. https://ntrs.nasa.gov/citations/19910023732

Appelbaum, J., Sherman, I., & Landis, G. A. (1993). Solar radiation on Mars: Stationary photovoltaic array. NASA Technical Memorandum 106321. https://ntrs.nasa.gov/citations/19940010257

Appelbaum, J., Flood, D. J., & Norambuena, M. (1994). Solar radiation on Mars: Tracking photovoltaic array. NASA Technical Memorandum 106700. https://ntrs.nasa.gov/citations/19950004977

See Also

Labrèche, G. (2020). Exploiting the SherpaTT Rover Active Suspension System to Enable Optimal Solar Array Inclination and Orientation for Long Traverses in a Martian Environment. Master's Thesis, Luleå University of Technology. https://www.diva-portal.org/smash/record.jsf?pid=diva2:1413245

Examples

# Calculate horizontal irradiance at Viking 1 landing site on Ls 90 (northern summer solstice)
G_h(Ls = 90, phi = 22.48, longitude = -48, Ts = 12, tau = 0.5)

# Find optimal panel tilt angle for the same location and season
optimal_angle(Ls = 90, phi = 22.48)

# Calculate daily insolation on a horizontal surface
H_h(Ls = 90, phi = 22.48, longitude = -48, tau = 0.5)

# Calculate insolation over a 24-hour period on an inclined surface
I_i(Ls = 90, phi = 22.48, longitude = -48, tau = 0.5, Ts_start = 0,
    Ts_end = 24, beta = 25, gamma_c = 0)

Albedo-reflected irradiance on Mars inclined surface

Description

Calculates the solar irradiance reflected from the Martian surface (ground-reflected radiation) incident on an inclined surface. Accounts for the view factor of the ground from the tilted surface.

Usage

G_ali(
  Ls,
  phi,
  longitude,
  Ts,
  z = Z(Ls = Ls, Ts = Ts, phi = phi),
  tau,
  al = albedo(latitude = phi, longitude = longitude, tau = tau),
  beta
)

Arguments

Value

Albedo-reflected irradiance on inclined surface [W/m²]

Direct beam irradiance on Mars surface normal to solar rays

Description

Calculates the direct beam solar irradiance on the Martian surface normal to the solar rays (i.e., perpendicular to the sun's direction). Uses Beer's law to account for atmospheric attenuation. Implements Equation 14 from Appelbaum & Flood (1990).

Usage

G_b(Ls, phi = NULL, Ts = NULL, z = Z(Ls = Ls, phi = phi, Ts = Ts), tau)

Arguments

Value

Direct beam irradiance normal to sun [W/m²]

Direct beam irradiance on Mars horizontal surface

Description

Calculates the direct beam solar irradiance incident on a horizontal surface on Mars. Accounts for the angle of incidence on the horizontal plane. Implements Equation 18 from Appelbaum & Flood (1990).

Usage

G_bh(Ls, phi, Ts, z = Z(Ls = Ls, phi = phi, Ts = Ts), tau)

Arguments

Value

Direct beam irradiance on horizontal surface [W/m²]

Direct beam irradiance on Mars inclined surface

Description

Calculates the direct beam solar irradiance incident on an inclined surface on Mars. Accounts for the sun's angle of incidence on the tilted and oriented surface. Based on Appelbaum, Flood & Norambuena (1994).

Usage

G_bi(Ls, phi, Ts, z = Z(Ls = Ls, phi = phi, Ts = Ts), tau, beta, gamma_c)

Arguments

Value

Direct beam irradiance on inclined surface [W/m²]

Diffuse irradiance on Mars horizontal surface

Description

Calculates the diffuse solar irradiance (scattered by atmospheric dust) incident on a horizontal surface on Mars. Computed as the difference between global and direct beam irradiance. Implements Equation 16 from Appelbaum & Flood (1990).

Usage

G_dh(
  Ls,
  phi,
  longitude,
  Ts = NULL,
  z = Z(Ls = Ls, phi = phi, Ts = Ts),
  tau,
  al = albedo(latitude = phi, longitude = longitude, tau = tau)
)

Arguments

Value

Diffuse irradiance on horizontal surface [W/m²]

Diffuse irradiance on Mars inclined surface

Description

Calculates the diffuse solar irradiance (scattered by atmospheric dust) incident on an inclined surface on Mars. Accounts for the view factor of the sky from the tilted surface.

Usage

G_di(
  Ls,
  phi,
  longitude,
  Ts,
  z = Z(Ls = Ls, phi = phi, Ts = Ts),
  tau,
  al = albedo(latitude = phi, longitude = longitude, tau = tau),
  beta
)

Arguments

Value

Diffuse irradiance on inclined surface [W/m²]

Global irradiance on Mars horizontal surface

Description

Calculates the total solar irradiance (direct beam + diffuse + albedo) incident on a horizontal surface on Mars. Implements Equation 17 from Appelbaum & Flood (1990).

Usage

G_h(
  Ls,
  phi,
  longitude,
  Ts = NULL,
  z = Z(Ls = Ls, phi = phi, Ts = Ts),
  tau,
  al = albedo(latitude = phi, longitude = longitude, tau = tau)
)

Arguments

Value

Global irradiance [W/m²]

Global irradiance on Mars inclined surface

Description

Calculates the total solar irradiance (direct beam + diffuse + albedo-reflected) incident on an inclined surface on Mars. Implements Equation 3 from Appelbaum, Flood & Norambuena (1994).

Usage

G_i(
  Ls,
  phi,
  longitude,
  Ts,
  z = Z(Ls = Ls, phi = phi, Ts = Ts),
  tau,
  al = albedo(latitude = phi, longitude = longitude, tau = tau),
  beta,
  gamma_c
)

Arguments

Value

Global irradiance on inclined surface [W/m²]

Beam irradiance at top of Martian atmosphere

Description

Calculates the solar beam irradiance at the top of the Martian atmosphere (before any atmospheric effects) as a function of Mars' orbital position. Accounts for Mars' elliptical orbit which causes seasonal variation in solar intensity. Implements Equation 4 from Appelbaum & Flood (1990).

Usage

G_ob(Ls)

Arguments

Value

Beam irradiance at top of atmosphere [W/m²]

Beam irradiance on horizontal surface at top of Mars atmosphere

Description

Calculates the solar beam irradiance on a horizontal surface at the top of the Martian atmosphere (before atmospheric attenuation). Implements Equation 5 from Appelbaum & Flood (1990).

Usage

G_obh(Ls, phi = NULL, Ts = NULL, z = Z(Ls = Ls, phi = phi, Ts = Ts))

Arguments

Value

Beam irradiance at top of atmosphere [W/m²]

Albedo-reflected daily insolation on Mars inclined surface

Description

Calculates the ground-reflected solar energy received over a full Martian day on an inclined surface. Obtained by integrating albedo-reflected irradiance from sunrise to sunset.

Usage

H_ali(
  Ls,
  phi,
  longitude,
  tau,
  al = albedo(latitude = phi, longitude = longitude, tau = tau),
  beta,
  gamma_c
)

Arguments

Value

Albedo-reflected daily insolation on inclined surface [Wh/m²-day]

Beam daily insolation on Mars horizontal surface

Description

Calculates the direct beam solar energy received over a full Martian day on a horizontal surface. Obtained by integrating beam irradiance from sunrise to sunset.

Usage

H_bh(Ls, phi, tau)

Arguments

Value

Beam daily insolation [Wh/m²-day]

Beam daily insolation on Mars inclined surface

Description

Calculates the direct beam solar energy received over a full Martian day on an inclined surface. Obtained by integrating beam irradiance from sunrise to sunset.

Usage

H_bi(Ls, phi, tau, beta, gamma_c)

Arguments

Value

Beam daily insolation on inclined surface [Wh/m²-day]

Diffuse daily insolation on Mars horizontal surface

Description

Calculates the diffuse solar energy (scattered by atmospheric dust) received over a full Martian day on a horizontal surface. Obtained by integrating diffuse irradiance from sunrise to sunset.

Usage

H_dh(
  Ls,
  phi,
  longitude,
  tau,
  al = albedo(latitude = phi, longitude = longitude, tau = tau)
)

Arguments

Value

Diffuse daily insolation [Wh/m²-day]

Diffuse daily insolation on Mars inclined surface

Description

Calculates the diffuse solar energy (scattered by atmospheric dust) received over a full Martian day on an inclined surface. Obtained by integrating diffuse irradiance from sunrise to sunset.

Usage

H_di(
  Ls,
  phi,
  longitude,
  tau,
  al = albedo(latitude = phi, longitude = longitude, tau = tau),
  beta,
  gamma_c
)

Arguments

Value

Diffuse daily insolation on inclined surface [Wh/m²-day]

Global daily insolation on Mars horizontal surface

Description

Calculates the total solar energy received over a full Martian day on a horizontal surface. Obtained by integrating global hourly insolation from sunrise to sunset.

Usage

H_h(
  Ls,
  phi,
  longitude,
  tau,
  al = albedo(latitude = phi, longitude = longitude, tau = tau)
)

Arguments

Value

Global daily insolation [Wh/m²-day]

Global daily insolation on Mars inclined surface

Description

Calculates the total solar energy received over a full Martian day on an inclined surface. Obtained by integrating global hourly insolation from sunrise to sunset. Based on Appelbaum, Flood & Norambuena (1994).

Usage

H_i(
  Ls,
  phi,
  longitude,
  tau,
  al = albedo(latitude = phi, longitude = longitude, tau = tau),
  beta,
  gamma_c
)

Arguments

Value

Global daily insolation on inclined surface [Wh/m²-day]

Daily beam insolation at top of Mars atmosphere

Description

Calculates the solar beam energy over a full Martian day on a horizontal surface at the top of the Martian atmosphere (before atmospheric attenuation). Implements Equation 13 from Appelbaum & Flood (1990).

Usage

H_obh(Ls, phi)

Arguments

Value

Daily beam insolation at top of atmosphere [Wh/m²-day]

Albedo-reflected insolation on Mars inclined surface over time period

Description

Calculates the ground-reflected solar energy received on an inclined surface between specified start and end times. Obtained by integrating albedo-reflected irradiance over the time period.

Usage

I_ali(
  Ls,
  phi,
  longitude,
  tau,
  Ts_start,
  Ts_end,
  al = albedo(latitude = phi, longitude = longitude, tau = tau),
  beta,
  gamma_c
)

Arguments

Value

Albedo-reflected insolation on inclined surface over specified time period [Wh/m²]

Beam insolation on Mars horizontal surface over time period

Description

Calculates the direct beam solar energy received on a horizontal surface between specified start and end times. Implements Equation 19 from Appelbaum & Flood (1990).

Usage

I_bh(Ls, phi, tau, Ts_start, Ts_end)

Arguments

Value

Beam insolation over specified time period [Wh/m²]

Beam insolation on Mars inclined surface over time period

Description

Calculates the direct beam solar energy received on an inclined surface between specified start and end times. Obtained by integrating beam irradiance over the time period.

Usage

I_bi(Ls, phi, tau, Ts_start, Ts_end, beta, gamma_c)

Arguments

Value

Beam insolation on inclined surface over specified time period [Wh/m²]

Diffuse insolation on Mars horizontal surface over time period

Description

Calculates the diffuse solar energy (scattered by atmospheric dust) received on a horizontal surface between specified start and end times. Computed as difference between global and beam insolation.

Usage

I_dh(
  Ls,
  phi,
  longitude,
  tau,
  Ts_start,
  Ts_end,
  al = albedo(latitude = phi, longitude = longitude, tau = tau)
)

Arguments

Value

Diffuse insolation over specified time period [Wh/m²]

Diffuse insolation on Mars inclined surface over time period

Description

Calculates the diffuse solar energy (scattered by atmospheric dust) received on an inclined surface between specified start and end times. Obtained by integrating diffuse irradiance over the time period.

Usage

I_di(
  Ls,
  phi,
  longitude,
  tau,
  Ts_start,
  Ts_end,
  al = albedo(latitude = phi, longitude = longitude, tau = tau),
  beta,
  gamma_c
)

Arguments

Value

Diffuse insolation on inclined surface over specified time period [Wh/m²]

Global insolation on Mars horizontal surface over time period

Description

Calculates the total solar energy received on a horizontal surface between specified start and end times. Obtained by integrating global irradiance over the time period.

Usage

I_h(
  Ls,
  phi,
  longitude,
  tau,
  Ts_start,
  Ts_end,
  al = albedo(latitude = phi, longitude = longitude, tau = tau)
)

Arguments

Value

Global insolation over specified time period [Wh/m²]

Global insolation on Mars inclined surface over time period

Description

Calculates the total solar energy received on an inclined surface between specified start and end times. Obtained by integrating global irradiance over the time period.

Usage

I_i(
  Ls,
  phi,
  longitude,
  tau,
  Ts_start,
  Ts_end,
  al = albedo(latitude = phi, longitude = longitude, tau = tau),
  beta,
  gamma_c
)

Arguments

Value

Global insolation on inclined surface over specified time period [Wh/m²]

Beam insolation at top of Mars atmosphere over time period

Description

Calculates the solar beam energy on a horizontal surface at the top of the Martian atmosphere (before atmospheric attenuation) between specified start and end times. Implements Equation 11 from Appelbaum & Flood (1990).

Usage

I_obh(Ls, phi, Ts_start, Ts_end)

Arguments

Value

Beam insolation at top of atmosphere over specified time period [Wh/m²]

Number of Mars daylight hours

Description

Calculates the duration of daylight (time between sunrise and sunset) for a given location and season on Mars. Implements Equation 10 from Appelbaum & Flood (1990).

Usage

T_d(Ls, phi)

Arguments

Value

Number of daylight hours [h]

Solar zenith angle

Description

Calculates the angle between the sun's rays and the vertical (zenith) direction. A zenith angle of 0° means the sun is directly overhead, while 90° means the sun is at the horizon. Implements Equation 6 from Appelbaum & Flood (1990).

Usage

Z(Ls, phi, Ts)

Arguments

Value

Sun zenith angle [deg]

The albedo function.

Description

Calculate the albedo value given geographical location and tau factor. Source: Appelbaum, Joseph & Landis, Geoffrey & Sherman, I. (1991). Solar radiation on Mars — Update 1991.

Usage

albedo(latitude, longitude, tau, coordinates_rounding = TRUE)

Arguments

Value

Surface albedo value (dimensionless, 0-1)

Solar declination angle on Mars

Description

Calculates the angular position of the Sun at solar noon with respect to the plane of the Martian equator. For Mars: -24.936° <= delta <= 24.936°. The declination is 0° at vernal (Ls=0°) and autumnal equinoxes (Ls=180°), +24.936° at summer solstice (Ls=90°), and -24.936° at winter solstice (Ls=270°). Implements Equation 7 from Appelbaum & Flood (1990).

Usage

declination(Ls, unit = 1)

Arguments

Value

Declination angle [rad] or [deg] depending on unit parameter

Albedo lookup table

Description

Lookup table for Mars surface albedo based on latitude and longitude. Based on NASA Technical Memorandum data.

Usage

df_albedo

Format

A data frame with albedo values indexed by latitude and longitude

Net flux lookup table (albedo 0.1, version 1)

Description

Lookup table for normalized net flux function with albedo fixed at 0.1. From NASA TM-102299 (Appelbaum & Flood, 1989).

Usage

df_netflux_0p1_lookup_v1

Format

A data frame with net flux values indexed by zenith angle and optical depth

Net flux lookup table (albedo 0.1, version 2)

Description

Lookup table for normalized net flux function with albedo 0.1. From NASA TM-103623 (Appelbaum & Flood, 1990).

Usage

df_netflux_0p1_lookup_v2

Format

A data frame with net flux values indexed by zenith angle and optical depth

Net flux lookup table (albedo 0.4, version 2)

Description

Lookup table for normalized net flux function with albedo 0.4. From NASA TM-103623 (Appelbaum & Flood, 1990).

Usage

df_netflux_0p4_lookup_v2

Format

A data frame with net flux values indexed by zenith angle and optical depth

Net flux polynomial coefficients (k=0)

Description

Polynomial coefficients for normalized net flux function calculation (albedo-independent terms). Based on Appelbaum & Flood analytical expression.

Usage

df_netflux_k0_coeffs

Format

A data frame with polynomial coefficients

Net flux polynomial coefficients (k=1)

Description

Polynomial coefficients for normalized net flux function calculation (albedo-dependent terms). Based on Appelbaum & Flood analytical expression.

Usage

df_netflux_k1_coeffs

Format

A data frame with polynomial coefficients

Normalized net flux function

Description

Calculates the normalized net solar flux on the Martian surface accounting for multiple wavelength and multiple scattering in the atmosphere. Based on Pollack's calculations presented in Appelbaum & Flood (1990). Can use polynomial expression or lookup tables.

Usage

f(z, tau, al = 0.1)

Arguments

Value

Normalized net flux (dimensionless)

Environment Variables

The function behavior can be configured via environment variables:

NET_FLUX_FUNCTION_TYPE: Controls which implementation to use:

• "polynomial" (default) - Analytical polynomial expression with ~0.7% mean error. Maximum error ~7% at zenith angles 80-85° and tau > 5.

• "lookup_v1" - Lookup table from NASA TM-102299. Albedo fixed at 0.1.

• "lookup_v2" - Lookup table from NASA TM-103623. Supports albedo 0.1 and 0.4.

Set with: Sys.setenv(NET_FLUX_FUNCTION_TYPE = "polynomial")

NET_FLUX_FUNCTION_SHOW_WARNINGS: Controls warning display (TRUE/FALSE, default: TRUE). Warnings are shown when polynomial calculations may have notable error margin (tau > 5 or z >= 80°).

Set with: Sys.setenv(NET_FLUX_FUNCTION_SHOW_WARNINGS = TRUE)

Check if surface is receiving solar irradiance

Description

Determines whether a surface at a given location and time is receiving solar irradiance. Accounts for polar night/day conditions, sunrise/sunset times, and sun position below horizon.

Usage

is_irradiated(Ls, phi, Ts, z = Z(Ls, Ts, phi), beta = NULL, gamma_c = NULL)

Arguments

Value

TRUE if surface is receiving irradiance, FALSE otherwise

Check if location is experiencing polar day

Description

Determines whether a given location on Mars is experiencing polar day (24-hour sunlight) for the specified season. During polar day, the sun remains above the horizon continuously.

Usage

is_polar_day(Ls, phi)

Arguments

Value

TRUE if experiencing polar day, FALSE otherwise

Check if location is experiencing polar night

Description

Determines whether a given location on Mars is experiencing polar night (24-hour darkness) for the specified season. During polar night, the sun remains below the horizon continuously.

Usage

is_polar_night(Ls, phi)

Arguments

Value

TRUE if experiencing polar night, FALSE otherwise

Atmospheric optical depth on Mars

Description

Calculates the optical depth of the Martian atmosphere as a function of latitude and season. The optical depth varies spatially and temporally, with peaks during global dust storms. Implements Equations 1 and 2 from Appelbaum, Landis & Sherman (1991).

Usage

optical_depth(Ls, phi, model = 1)

Arguments

Value

Atmospheric optical depth (dimensionless, minimum 0.5)

Examples

# Calculate optical depth at Viking Lander 1 site during dust storm season
tau <- optical_depth(Ls = 215, phi = 22.3, model = 1)

Optimal tilt angle for maximum daily insolation

Description

Calculates the optimal surface tilt angle (beta) that maximizes daily solar energy collection for a given location and season on Mars. The surface is assumed to face the equator. Based on Equations 40 and 43 from Appelbaum (1993).

Usage

optimal_angle(Ls, phi, unit = 1)

Arguments

Value

Optimal tilt angle [rad] or [deg] depending on unit parameter

Sunrise time on Mars

Description

Calculates the sunrise time for a horizontal or inclined surface on Mars. Returns NA during polar night/day periods.

Usage

sunrise(Ls, phi, beta = NULL, gamma_c = NULL, unit = 1)

Arguments

Value

Sunrise time [rad], [deg], or [h] depending on unit parameter, or NA during polar night/day

Sunset time on Mars

Description

Calculates the sunset time for a horizontal or inclined surface on Mars. Returns NA during polar night/day periods.

Usage

sunset(Ls, phi, beta = NULL, gamma_c = NULL, unit = 1)

Arguments

Value

Sunset time [rad], [deg], or [h] depending on unit parameter, or NA during polar night/day