R-CMD-check

marsrad: Mars Solar Radiation

Overview

An R package to calculate solar irradiance (instantaneous power) and insolation (energy over time) on the Martian surface for both horizontal and inclined surfaces. This package is essential in designing solar power systems for Mars missions and mission planning. Based on NASA Technical Memoranda 102299, 103623, 105216, 106321, and 106700, i.e. the canonical Mars solar radiation papers.

Citation

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

Labrèche, Georges and Cordes, Florian. (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), October 2020. https://www.hou.usra.edu/meetings/isairas2020fullpapers/pdf/5035.pdf

BibTeX

@inproceedings{Labreche2020_iSAIRAS20_MarsRoverSherpaTT,
  title={Using a Rover's Active Suspension System as a 2-Axis Solar Tracker Mechanism},
  author={Labrèche, Georges and Cordes, Florian},
  booktitle={15th International Symposium on Artificial Intelligence, Robotics and Automation in Space (i-SAIRAS '20)},
  month={October},
  year={2020},
  url={https://www.hou.usra.edu/meetings/isairas2020fullpapers/pdf/5035.pdf}
}

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, March 2020. https://www.diva-portal.org/smash/record.jsf?pid=diva2:1413245

Key Features

What’s Included

The package implements equations for:

For a complete list of all functions with descriptions, see FUNCTIONS.md.

Parameters

Calculate and plot solar radiation on Mars as a function of the following parameters: - Areocentric Longitude (Ls) - Planetary Latitude (phi) - Solar Time (omega) - Atmospheric Opacity (tau) - Albedo (al) - Slope Angle (beta) - Slope Orientation (gamma)

Getting Started

Installation

Install the package from GitHub using devtools:

# Install devtools if you haven't already
install.packages("devtools")

# Install the mars package
devtools::install_github("georgeslabreche/marsrad")

Basic Usage

library(marsrad)

# Calculate global irradiance on a horizontal surface
# Example: Mars surface at Viking Lander 1 site during northern summer
Ls <- 120           # Areocentric longitude (degrees)
phi <- 22.3         # Latitude (degrees) - VL1 location
longitude <- -48    # Longitude (degrees) - VL1 at 48°W
Ts <- 12            # Solar time (hours) - noon
tau <- 0.4          # Atmospheric optical depth
al <- 0.1           # Albedo

# Global irradiance on horizontal surface (W/m²)
Gh <- G_h(Ls = Ls, phi = phi, longitude = longitude, Ts = Ts, tau = tau, al = al)
print(paste("Global irradiance:", round(Gh, 2), "W/m²"))

# Daily insolation on horizontal surface (Wh/m²-day)
Hh <- H_h(Ls = Ls, phi = phi, longitude = longitude, tau = tau, al = al)
print(paste("Daily insolation:", round(Hh, 2), "Wh/m²-day"))

# Calculate for an inclined surface (e.g., tilted solar panel)
beta <- 30          # Tilt angle (degrees)
gamma_c <- 0        # Surface azimuth angle (degrees, 0 = facing equator)

# Global irradiance on inclined surface (W/m²)
Gi <- G_i(Ls = Ls, phi = phi, longitude = longitude, Ts = Ts,
          tau = tau, al = al, beta = beta, gamma_c = gamma_c)
print(paste("Inclined surface irradiance:", round(Gi, 2), "W/m²"))

# Find optimal tilt angle for maximum daily insolation
optimal <- optimal_angle(Ls = Ls, phi = phi, unit = 2)
print(paste("Optimal tilt angle:", round(optimal, 2), "degrees"))

# Calculate sunrise and sunset times (in solar hours, 0-24)
sunrise_time <- sunrise(Ls = Ls, phi = phi, unit = 3)
sunset_time <- sunset(Ls = Ls, phi = phi, unit = 3)
print(paste("Sunrise:", round(sunrise_time, 2), "hours"))
print(paste("Sunset:", round(sunset_time, 2), "hours"))

Environment Variables

The package can be configured via environment variables to control calculation methods and behavior:

NET_FLUX_FUNCTION_TYPE

Controls which implementation of the normalized net flux function to use. Affects all radiation calculations.

Options:

Usage:

# Use polynomial implementation (default)
Sys.setenv(NET_FLUX_FUNCTION_TYPE = "polynomial")

# Use lookup table v2
Sys.setenv(NET_FLUX_FUNCTION_TYPE = "lookup_v2")

NET_FLUX_FUNCTION_SHOW_WARNINGS

Controls whether to display warnings about potential calculation errors.

Options:

Warnings are shown when:

Usage:

# Show warnings (default)
Sys.setenv(NET_FLUX_FUNCTION_SHOW_WARNINGS = TRUE)

# Suppress warnings
Sys.setenv(NET_FLUX_FUNCTION_SHOW_WARNINGS = FALSE)

Development

Running Tests

To run the package tests during development:

# Install devtools if you haven't already
install.packages("devtools")

# Option 1: Run tests only (faster for quick testing)
devtools::test()

# Option 2: Run a full package check (includes tests, documentation, examples)
devtools::check()

devtools::test() is recommended for quick iteration during development - it loads your package and runs all tests without requiring installation.

devtools::check() performs a comprehensive package check including tests, documentation, examples, and package structure validation - use this before submitting to CRAN or creating releases.

Generating Documentation

Generating man/ Files

The man/ directory contains R documentation files (.Rd) generated from roxygen2 comments in the source code. To regenerate these files after modifying function documentation:

# Install roxygen2
install.packages("roxygen2")

# Generate documentation
roxygen2::roxygenize()

This updates all .Rd files in the man/ directory based on the #' roxygen2 comments in R source files.

Generating PDF Reference Manual

The package reference manual is a comprehensive PDF containing documentation for all exported functions.

For Apple Silicon Macs (M1/M2/M3):

# Build the Docker image (first time only, from repository root)
docker build --platform linux/amd64 -t marsrad-manual -f Dockerfile-manual .

# Generate the PDF
docker run --rm --platform linux/amd64 -v $(pwd):/output marsrad-manual

For Intel Macs and Linux:

# Build the Docker image (first time only, from repository root)
docker build -t marsrad-manual -f Dockerfile-manual .

# Generate the PDF
docker run --rm -v $(pwd):/output marsrad-manual

The marsrad-manual.pdf PDF will be created in the repository’s root directory.

References

Based on the following excellent work:

mirror server hosted at Truenetwork, Russian Federation.