Add solar azimuth angle trigonometry

[jleinonen]

PhysicsNeMo Pull Request

Description

1. Add functions zenith_azimuth_angles and zenith_azimuth_angles_from_timestamp to physicsnemo.utils.cos_zenith. These return sin/cos of both solar zenith and azimuth angles, rather than just the zenith angle. They follow the existing dual numpy/torch implementation.
2. Add tests for the new functions.

Existing functionality is unaffected.

Checklist

• I am familiar with the Contributing Guidelines.
• New or existing tests cover these changes.
• The documentation is up to date with these changes.
• The CHANGELOG.md is up to date with these changes.
• An issue is linked to this pull request.
• If I am implementing a new model or modifying any existing model, I have followed the Models Implementation Coding Standards.

Dependencies

Review Process

All PRs are reviewed by the PhysicsNeMo team before merging.

Depending on which files are changed, GitHub may automatically assign a maintainer for review.

We are also testing AI-based code review tools (e.g., Greptile), which may add automated comments with a confidence score.
This score reflects the AI’s assessment of merge readiness and is not a qualitative judgment of your work, nor is
it an indication that the PR will be accepted / rejected.

AI-generated feedback should be reviewed critically for usefulness.
You are not required to respond to every AI comment, but they are intended to help both authors and reviewers.
Please react to Greptile comments with 👍 or 👎 to provide feedback on their accuracy.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[greptile-apps]

Greptile Summary

This PR adds two new public utilities, zenith_azimuth_angles and zenith_azimuth_angles_from_timestamp, to physicsnemo.utils.zenith_angle. These return (sin_zenith, cos_zenith, sin_azimuth, cos_azimuth) using the north-clockwise convention, following the existing dual numpy/torch implementation pattern.

• Adds _star_zenith_azimuth as the shared private backend, mirroring _star_cos_zenith with an added _clamp helper that dispatches between torch.Tensor.clamp and ndarray.clip for pole-safe division.
• Adds thorough tests: scalar regression values, numpy/torch parity across the globe (poles excluded with clear comments), broadcasting shape checks, and Pythagorean-identity verification for both zenith and azimuth.
• Existing cos_zenith_angle / cos_zenith_angle_from_timestamp behaviour is unchanged; all pre-existing tests continue to pass.

Important Files Changed

Filename	Overview
physicsnemo/utils/zenith_angle.py	Adds zenith_azimuth_angles, zenith_azimuth_angles_from_timestamp, _star_zenith_azimuth, and _clamp; existing logic is untouched. Docstrings correctly note the polar-singularity behaviour and the sin_zenith floor clamping.
test/utils/test_zenith_angle.py	Adds four new test functions covering scalar regression values, array broadcasting, numpy/torch dtype parity (float32 and float64), and cross-validation against cos_zenith_angle. Polar-exclusion rationale is well-commented.
CHANGELOG.md	Entry correctly describes the new functions and the north-clockwise azimuth convention.

_{Reviews (2): Last reviewed commit: "Azimuth comment improvements" | Re-trigger Greptile}

[pzharrington]

@greptileai

[pzharrington]

I recognize the same flaw in documentation comes from the original cos zenith function, but can we clarify the expected units across these different input types? datetime is self-documenting but raw floats are just numbers so here and in cos zenith we should say what the numbers indicate -- and same for ndarrays/tensors of numbers. Also, are ndarrays of numpy datetimes accepted/handled, or just raw float ndarrays?