Adding a New Solar Position Algorithm

This tutorial walks you through the process of adding a new solar positioning algorithm to SolarPosition.jl. We'll implement a simplified algorithm step by step, covering all the necessary components: the algorithm struct, core computation, refraction handling, exports, and tests.

Overview

Adding a new algorithm involves these steps:

1. Create the algorithm struct - Define a type that subtypes SolarAlgorithm.
2. Implement the core function - Write _solar_position for your algorithm.
3. Handle refraction - Define how your algorithm interacts with DefaultRefraction.
4. Export the algorithm - Make it available to users.
5. Write tests - Validate correctness against reference values.
6. Document - Add docstrings and update documentation.
7. Run pre-commit checks - Ensure code quality and formatting.

Step 1: Create the Algorithm Struct

Create a new file in src/Positioning/ for your algorithm. For this example, we'll create a simplified algorithm called SimpleAlgorithm.

The struct must:

• Subtype SolarAlgorithm
• Include a docstring with TYPEDEF and TYPEDFIELDS macros
• Document accuracy and provide literature references

# src/Positioning/simple.jl

"""
    \$(TYPEDEF)

Simple solar position algorithm for demonstration purposes.

This algorithm uses basic spherical trigonometry to compute solar positions.
It is provided as a teaching example and is NOT suitable for production use.

# Accuracy
This is a simplified algorithm with limited accuracy (±1°).

# Literature
Based on basic solar geometry principles.

# Fields
\$(TYPEDFIELDS)
"""
struct SimpleAlgorithm <: SolarAlgorithm
    "Optional configuration parameter"
    param::Float64
end

# Provide a default constructor
SimpleAlgorithm() = SimpleAlgorithm(1.0)

Step 2: Implement the Core Function

The core of any algorithm is the _solar_position function. This function:

• Takes an Observer, DateTime, and your algorithm type
• Returns a SolPos{T} with azimuth, elevation, and zenith angles
• Should be type-stable and performant

Here's the basic structure:

function _solar_position(obs::Observer{T}, dt::DateTime, alg::SimpleAlgorithm) where {T}
    # 1. Take the time base at the observer's precision
    n = julian_day_j2000(T, dt)    # days since J2000.0
    hour = fractional_hour(T, dt)  # decimal hours

    # 2. Compute solar coordinates (declination, hour angle, etc.)
    # ... your algorithm's calculations here ...

    # 3. Calculate local horizontal coordinates, clamping the inverse trig argument
    elevation = asind(unit_clamp(sin_δ * obs.sin_lat + cos_δ * obs.cos_lat * cos_ω))
    # ... azimuth calculation ...

    # 4. Return the result
    return SolPos{T}(azimuth_deg, elevation_deg, zenith_deg)
end

Key Implementation Notes

1. Use helper functions from utils.jl and timebase.jl:

   • fractional_hour(T, dt) - Convert time to decimal hours at precision T
   • julian_day_j2000(T, dt) / julian_century(T, dt) - Magnitude-safe day/century counts since J2000.0
   • unit_clamp(x) - Clamp inverse-trig arguments into [-1, 1]
   • deg2rad(x) / rad2deg(x) - Angle conversions

2. Observer properties are pre-computed for efficiency:

   • obs.latitude, obs.longitude, obs.altitude - Input values
   • obs.latitude_rad, obs.longitude_rad - Radians versions
   • obs.sin_lat, obs.cos_lat - Precomputed trigonometric values

3. Type parameter T ensures numerical precision is preserved from the Observer

4. Angle conventions:

   • Azimuth: 0° = North, positive clockwise, normalized to [0°, 360°)
   • Elevation: angle above horizon, range [-90°, 90°]
   • Zenith: 90° - elevation, range [0°, 180°]

Step 3: Handle Default Refraction

Each algorithm must specify how it handles DefaultRefraction. There are two common patterns:

Pattern A: No Refraction by Default (like PSA)

If your algorithm should NOT apply refraction by default:

function _solar_position(obs, dt, alg::SimpleAlgorithm, ::DefaultRefraction)
    return _solar_position(obs, dt, alg, NoRefraction())
end

# Return type for DefaultRefraction
result_type(::Type{SimpleAlgorithm}, ::Type{DefaultRefraction}, ::Type{T}) where {T} =
    SolPos{T}

Pattern B: Apply Refraction by Default (like NOAA)

If your algorithm should apply a specific refraction model by default:

using ..Refraction: HUGHES, DefaultRefraction

function _solar_position(obs::Observer{T}, dt, alg::SimpleAlgorithm, ::DefaultRefraction) where {T}
    return _solar_position(obs, dt, alg, HUGHES{T}())
end

# Return type for DefaultRefraction
result_type(::Type{SimpleAlgorithm}, ::Type{DefaultRefraction}, ::Type{T}) where {T} =
    ApparentSolPos{T}

The result_type function tells the system what return type to expect, enabling type-stable code for vectorized operations.

Step 4: Export the Algorithm

After implementing your algorithm, you need to export it so users can access it.

4.1 Include in Positioning Module

Edit src/Positioning/Positioning.jl to include your new file:

# Near the bottom of the file, with other includes
include("simple.jl")  # Add your new file

# Add your algorithm to the export list
export SimpleAlgorithm

4.2 Nothing to Do in the Main Module

src/SolarPosition.jl pulls the submodules in with @reexport using .Positioning, so anything the Positioning module exports is available from SolarPosition automatically. Exporting from src/Positioning/Positioning.jl in step 4.1 is the only export you need.

Step 5: Write Tests

Create a test file following the naming convention test/positioning/test-simple.jl. Any file matching test-*.jl anywhere under test/ is discovered automatically and wrapped in a @testset named after the file.

Add your algorithm to test_algorithms() in test/positioning/expected-values.jl as well. That list is shared, so a single entry enrolls it in the type stability, precision, automatic differentiation, and uncertainty testsets without touching any of them.

Running Tests

Tests are automatically discovered by runtests.jl. Run them with:

julia --project=. -e 'using Pkg; Pkg.test()'

Or from the Julia REPL:

using Pkg
Pkg.activate(".")
Pkg.test()

Step 6: Document Your Algorithm

Add to Documentation Pages

Update docs/src/positioning.md to include your algorithm in the algorithm reference section, and add a row to the algorithm tables in docs/src/index.md and README.md.

Record it in the Changelog

Add an entry under ## unreleased in CHANGELOG.md. A pull request that touches no changelog fails the Enforce changelog workflow unless it carries the skip-changelog label, and a new algorithm is exactly the kind of change the file exists to record.

Add Literature References

If your algorithm is based on published work, add the reference to docs/src/refs.bib:

@article{YourReference,
    author = {Author Name},
    title = {Algorithm Title},
    journal = {Journal Name},
    year = {2024},
    volume = {1},
    pages = {1-10}
}

Then cite it in your docstring using [YourReference](@cite).

Step 7: Run Pre-commit Checks (Recommended)

Before submitting a pull request, it's recommended to run pre-commit hooks locally to catch formatting and linting issues early. This saves time during code review and ensures your code meets the project's quality standards. The pre-commit configuration is defined in the .pre-commit-config.yaml file at the root of the repository.

Installing Pre-commit

# Install pre-commit (requires Python)
pip install pre-commit

# Install the git hooks (run once per clone)
pre-commit install

Running Pre-commit

# Run all hooks on all files
pre-commit run --all-files

# Or run on staged files only
pre-commit run

Pre-commit runs several checks including:

• Runic - Ensures consistent code formatting
• ExplicitImports - Checks for explicit imports
• markdownlint - Lints markdown files
• typos - Catches common spelling mistakes

If any checks fail, fix the issues and run pre-commit again until all checks pass.

Checklist

Before submitting your algorithm for review, ensure you've completed the following:

Additional Resources

• See existing implementations in src/Positioning/ for reference:
  • psa.jl - Simple algorithm with no default refraction (PSA)
  • noaa.jl - Algorithm with default HUGHES refraction (NOAA)
  • spa.jl - Complex algorithm with additional output fields (SPA)
• Check the Contributing Guidelines for general contribution workflow
• Review the Solar Positioning Algorithms page for context