coconut_tools.tools.rotation_angle¶

Compute Carrington to Stonyhurst rotation angle from magnetogram filenames.

This module parses magnetogram names from different providers (GONG, ADAPT, HMI) and computes the longitudinal rotation needed to align their maps with the Stonyhurst frame used by heliospheric models like EUHFORIA.

Supports: - GONG synoptic and ADAPT (CM/CAR modes), - HMI (with explicit observation time), - Angle computation based on the central meridian difference.

Used during preprocessing to rotate coronal boundary data into the appropriate HEEQ frame.

Functions

`compute_carrington_central_meridian`(date)	Return the Carrington longitude of Earth's central meridian.
`compute_rotation_angle`(mag_name_path[, date_hmi])	Compute the rotation angle from magnetogram filename.
`increasing_longitude_axis`(path)	Return the native longitude axis ordered like a normalized Br map.
`is_br_longitude_increasing`(path)	Return whether Br columns follow increasing native longitude.

coconut_tools.tools.rotation_angle.compute_carrington_central_meridian(date)[source]¶

Return the Carrington longitude of Earth’s central meridian.

Return type:: float
Parameters:: date (str | datetime)

coconut_tools.tools.rotation_angle.compute_rotation_angle(mag_name_path, date_hmi=None)[source]¶

Compute the rotation angle from magnetogram filename.

Supports GONG, ADAPT (CM and CAR), and HMI.

Parameters:

mag_name_path (str) – Path to the magnetogram file.
date_hmi (str, optional) – ISO datetime string used for HMI (e.g. ‘2024-07-01T00:00:00’)

Returns:

Angle alpha in degrees such that lon_heeq = lon_mag - alpha (mod 360) datetime: Observation date of the magnetogram

Return type:

float

coconut_tools.tools.rotation_angle.increasing_longitude_axis(path)[source]¶

Return the native longitude axis ordered like a normalized Br map.

Return type:: ndarray
Parameters:: path (str)

coconut_tools.tools.rotation_angle.is_br_longitude_increasing(path)[source]¶

Return whether Br columns follow increasing native longitude.

The longitude axis is reconstructed without wrapping it into [0, 360), so crossing the Carrington origin does not affect the direction check.

Parameters:: path (str) – Path to the FITS magnetogram file.
Returns:: True when longitude increases with the Br column index.
Return type:: bool
Raises:: ValueError – If the longitude direction cannot be determined.