celestial.h File Reference

#include <stdbool.h>
#include <stdint.h>

Classes
struct	CelestialJulianDay
struct	CelestialUT1Time
struct	CelestialUTCTime
	A UTC civil result; before 1972-01-01 its fields use the UT1 substitute. More...
struct	CelestialSunCoordinate
struct	CelestialMoonCoordinate
struct	CelestialMoonIllumination
struct	CelestialMoonPositionAngle
struct	CelestialDiscriminant
struct	CelestialEquationOfTime
struct	CelestialApparentSolarTime
struct	CelestialSiderealTime
struct	CelestialJieqiMomentQuery
struct	CelestialSupportedLunarYearRange
struct	CelestialLunarYearInfo
struct	CelestialLunarDate
struct	CelestialGregorianDate
struct	CelestialDeltaT
struct	CelestialChartBody
	One geocentric target in the true ecliptic and equinox of date. More...
struct	CelestialChartHouses
	Four axes and twelve cusps in degrees, each in [0, 360); cusps are houses 1-12. More...
struct	CelestialChartSnapshot
	A complete independent value; consume the payload only when valid is true. More...
struct	CelestialLongitudeEventRecord
	One longitude crossing or exact numerical contact at the supplied level. More...
struct	CelestialStationEventRecord
	One stationary instant of the seven-point ephemeris::longitude_rate. More...
struct	CelestialLongitudeDifferenceEventRecord
	One event of the directed, canonical longitude difference first minus second. More...
struct	CelestialCapabilityRecord
	One TT operation's input bounds for one target. More...
struct	CelestialModelIdentityRecord
	One registered model identity with its applicability. More...
struct	CelestialPositionRecord
	One selected target's apparent geocentric position in the true ecliptic of date. More...
struct	CelestialEquatorialPositionRecord
	One selected target's apparent geocentric equatorial position of date. More...
struct	CelestialHouseQueryResult
	Independent house geometry with resolved explicit model identities. More...
struct	CelestialCivilHouseCapability
	The adopted civil-house admission policy, separate from geometric solvability. More...

Macros
#define	CELESTIAL_API
#define	CELESTIAL_ERROR_NONE
#define	CELESTIAL_ERROR_INVALID_INPUT
#define	CELESTIAL_ERROR_COMPUTATION
#define	CELESTIAL_ERROR_RESOURCE
#define	CELESTIAL_ERROR_INTERNAL
#define	CELESTIAL_CIVIL_SCALE_UTC
#define	CELESTIAL_CIVIL_SCALE_UT1
#define	CELESTIAL_HOUSE_SYSTEM_EQUAL
#define	CELESTIAL_HOUSE_SYSTEM_WHOLE_SIGN
#define	CELESTIAL_HOUSE_SYSTEM_PLACIDUS
#define	CELESTIAL_DELTA_T_MODEL_DEFAULT
#define	CELESTIAL_DELTA_T_MODEL_ALGO1
#define	CELESTIAL_DELTA_T_MODEL_ALGO2
#define	CELESTIAL_DELTA_T_MODEL_ALGO3
#define	CELESTIAL_DELTA_T_MODEL_ALGO4
#define	CELESTIAL_DELTA_T_MODEL_ALGO5
#define	CELESTIAL_TARGET_SUN
#define	CELESTIAL_TARGET_MOON
#define	CELESTIAL_TARGET_MERCURY
#define	CELESTIAL_TARGET_VENUS
#define	CELESTIAL_TARGET_MARS
#define	CELESTIAL_TARGET_JUPITER
#define	CELESTIAL_TARGET_SATURN
#define	CELESTIAL_TARGET_URANUS
#define	CELESTIAL_TARGET_NEPTUNE
#define	CELESTIAL_TARGET_PLUTO
#define	CELESTIAL_TARGET_MEAN_ASCENDING
#define	CELESTIAL_TARGET_MEAN_DESCENDING
#define	CELESTIAL_TARGET_TRUE_ASCENDING
#define	CELESTIAL_TARGET_TRUE_DESCENDING
#define	CELESTIAL_TARGET_ALL
#define	CELESTIAL_POSITION_SOURCE_SUN_VSOP87D
#define	CELESTIAL_POSITION_SOURCE_MOON_ELP2000_82B_TRUNC
#define	CELESTIAL_POSITION_SOURCE_PLANET_VSOP87D
#define	CELESTIAL_POSITION_SOURCE_PLUTO_PLUTO95_APPARENT
#define	CELESTIAL_POSITION_SOURCE_NODE_MEAN
#define	CELESTIAL_POSITION_SOURCE_NODE_TRUE_MEEUS_FIVE_TERM
#define	CELESTIAL_NUTATION_MODEL_DEFAULT
#define	CELESTIAL_NUTATION_MODEL_MEEUS
#define	CELESTIAL_NUTATION_MODEL_IAU_1980
#define	CELESTIAL_PRESENT_LATITUDE
#define	CELESTIAL_PRESENT_DISTANCE
#define	CELESTIAL_EVENT_DIRECTION_INCREASING
#define	CELESTIAL_EVENT_DIRECTION_DECREASING
#define	CELESTIAL_EVENT_DIRECTION_TANGENT
#define	CELESTIAL_EVENT_MOTION_DIRECT
#define	CELESTIAL_EVENT_MOTION_RETROGRADE
#define	CELESTIAL_OPERATION_POSITION
#define	CELESTIAL_OPERATION_LONGITUDE_RATE
#define	CELESTIAL_OPERATION_EVENTS
#define	CELESTIAL_OPERATION_HOUSES
#define	CELESTIAL_OPERATION_EQUATORIAL
#define	CELESTIAL_OPERATION_CHART
#define	CELESTIAL_OPERATION_DELTA_T
#define	CELESTIAL_STATUS_SOURCE_WINDOW
#define	CELESTIAL_STATUS_IMPLEMENTATION_WINDOW
#define	CELESTIAL_STATUS_FINITE_INPUT_EVALUATION
#define	CELESTIAL_MODEL_KIND_DELTA_T
#define	CELESTIAL_MODEL_KIND_NUTATION
#define	CELESTIAL_MODEL_KIND_POSITION_SOURCE
#define	CELESTIAL_MODEL_KIND_ALL
#define	CELESTIAL_MODEL_STATUS_CURRENT
#define	CELESTIAL_MODEL_STATUS_FROZEN

Typedefs
typedef struct CelestialJulianDay	CelestialJulianDay
typedef struct CelestialUT1Time	CelestialUT1Time
typedef struct CelestialUTCTime	CelestialUTCTime
	A UTC civil result; before 1972-01-01 its fields use the UT1 substitute.
typedef struct CelestialSunCoordinate	CelestialSunCoordinate
typedef struct CelestialMoonCoordinate	CelestialMoonCoordinate
typedef struct CelestialMoonIllumination	CelestialMoonIllumination
typedef struct CelestialMoonPositionAngle	CelestialMoonPositionAngle
typedef struct CelestialDiscriminant	CelestialDiscriminant
typedef struct CelestialEquationOfTime	CelestialEquationOfTime
typedef struct CelestialApparentSolarTime	CelestialApparentSolarTime
typedef struct CelestialSiderealTime	CelestialSiderealTime
typedef struct CelestialJieqiMomentQuery	CelestialJieqiMomentQuery
typedef struct CelestialSupportedLunarYearRange	CelestialSupportedLunarYearRange
typedef struct CelestialLunarYearInfo	CelestialLunarYearInfo
typedef struct CelestialLunarDate	CelestialLunarDate
typedef struct CelestialGregorianDate	CelestialGregorianDate
typedef struct CelestialDeltaT	CelestialDeltaT
typedef struct CelestialChartBody	CelestialChartBody
	One geocentric target in the true ecliptic and equinox of date.
typedef struct CelestialChartHouses	CelestialChartHouses
	Four axes and twelve cusps in degrees, each in [0, 360); cusps are houses 1-12.
typedef struct CelestialChartSnapshot	CelestialChartSnapshot
	A complete independent value; consume the payload only when valid is true.
typedef struct CelestialLongitudeEventRecord	CelestialLongitudeEventRecord
	One longitude crossing or exact numerical contact at the supplied level.
typedef struct CelestialStationEventRecord	CelestialStationEventRecord
	One stationary instant of the seven-point ephemeris::longitude_rate.
typedef struct CelestialLongitudeDifferenceEventRecord	CelestialLongitudeDifferenceEventRecord
	One event of the directed, canonical longitude difference first minus second.
typedef struct CelestialCapabilityRecord	CelestialCapabilityRecord
	One TT operation's input bounds for one target.
typedef struct CelestialModelIdentityRecord	CelestialModelIdentityRecord
	One registered model identity with its applicability.
typedef struct CelestialPositionRecord	CelestialPositionRecord
	One selected target's apparent geocentric position in the true ecliptic of date.
typedef struct CelestialEquatorialPositionRecord	CelestialEquatorialPositionRecord
	One selected target's apparent geocentric equatorial position of date.
typedef struct CelestialHouseQueryResult	CelestialHouseQueryResult
	Independent house geometry with resolved explicit model identities.
typedef struct CelestialCivilHouseCapability	CelestialCivilHouseCapability
	The adopted civil-house admission policy, separate from geometric solvability.

Functions
CELESTIAL_API const char *	celestial_last_error (void)
	Get the last-error message of the calling thread.
CELESTIAL_API uint32_t	celestial_last_error_kind (void)
	Read the calling thread's CELESTIAL_ERROR_* code without clearing its error.
CELESTIAL_API CelestialJulianDay	celestial_ut1_to_jd (int32_t y, uint32_t m, uint32_t d, double fraction)
	Convert UT1 datetime to Julian Day Number (JD).
CELESTIAL_API CelestialJulianDay	celestial_ut1_to_jde (int32_t y, uint32_t m, uint32_t d, double fraction)
	Convert UT1 datetime to Julian Ephemeris Day Number (JDE).
CELESTIAL_API CelestialUT1Time	celestial_jde_to_ut1 (double jde)
	Convert Julian Ephemeris Day Number (JDE) to UT1 datetime.
CELESTIAL_API CelestialJulianDay	celestial_utc_to_jde (int32_t y, uint32_t m, uint32_t d, double fraction)
	Convert UTC civil fields to TT-based Julian Ephemeris Day (JDE).
CELESTIAL_API CelestialUTCTime	celestial_jde_to_utc (double jde_tt)
	Convert TT-based Julian Ephemeris Day (JDE) to UTC civil fields.
CELESTIAL_API CelestialSunCoordinate	celestial_sun_apparent_geocentric_coord (double jde)
	Calculate the apparent geocentric position of the Sun.
CELESTIAL_API CelestialMoonCoordinate	celestial_moon_apparent_geocentric_coord (double jde)
	Calculate the apparent geocentric position of the Moon.
CELESTIAL_API CelestialMoonIllumination	celestial_moon_illumination (double jde)
	Compute the Moon's illuminated fraction k and elongation at a JDE (Meeus ch. 48: k from (48.2)+(48.3)+(48.1)).
CELESTIAL_API CelestialMoonPositionAngle	celestial_moon_position_angle (double jde)
	Compute the position angle of the Moon's bright limb at a JDE (Meeus ch. 48, (48.5)).
CELESTIAL_API uint32_t	celestial_moon_phase_moments (int32_t year, uint8_t phase_kind, uint32_t *root_count, double *slots, uint32_t slot_count)
	Find the moments of a given Moon phase in year; the total count goes to root_count, up to slot_count of them are written to slots.
CELESTIAL_API CelestialDiscriminant	celestial_solar_lon_root_discriminant (int32_t year, double longitude)
	Calculate the JDE discriminant — count how many times the Sun reaches the given geocentric longitude in the given year.
CELESTIAL_API uint32_t	celestial_solar_lon_roots (int32_t year, double longitude, double *slots, uint32_t slot_count)
	Find the JDE(s) at which the Sun reaches longitude in year, written to slots.
CELESTIAL_API uint32_t	celestial_new_moons_after_jde (double jde, double *slots, uint32_t slot_count)
	Find the next slot_count new-moon JDE(s) after jde, written to slots.
CELESTIAL_API uint32_t	celestial_new_moons_in_year (int32_t year, uint32_t *root_count, double *slots, uint32_t slot_count)
	Find the new-moon JDE(s) in year; the total count goes to root_count, up to slot_count of them are written to slots.
CELESTIAL_API CelestialEquationOfTime	celestial_equation_of_time (double jde)
	Compute the equation of time E = apparent solar time - mean solar time (Meeus ch. 28).
CELESTIAL_API CelestialApparentSolarTime	celestial_apparent_solar_time (int32_t y, uint32_t m, uint32_t d, double fraction, double longitude)
	Convert a civil UTC moment to local apparent (true) solar time.
CELESTIAL_API CelestialSiderealTime	celestial_local_apparent_sidereal_time (double jd_ut1, double longitude)
	Compute the Local Apparent Sidereal Time (LAST) for an observer.
CELESTIAL_API CelestialJieqiMomentQuery	celestial_query_jieqi_moment (int32_t year, uint8_t jq_idx)
	Query the accurate UT1 moment of the Jieqi in the given year.
CELESTIAL_API uint32_t	celestial_get_jieqi_name (uint8_t jq_idx, char *buf, uint32_t buf_size)
	Size or write the UTF-8 Chinese name of the Jieqi.
CELESTIAL_API CelestialSupportedLunarYearRange	celestial_get_supported_lunar_year_range (uint8_t algo)
	Get the supported lunar year range of the algorithm.
CELESTIAL_API CelestialLunarYearInfo	celestial_get_lunar_year_info (uint8_t algo, int32_t year)
	Get the lunar year information for the given year.
CELESTIAL_API CelestialLunarDate	celestial_gregorian_to_lunar (uint8_t algo, int32_t year, uint8_t month, uint8_t day)
	Convert a Gregorian date to a lunar date.
CELESTIAL_API CelestialGregorianDate	celestial_lunar_to_gregorian (uint8_t algo, int32_t year, uint8_t month, bool is_leap, uint8_t day)
	Convert a lunar date to a Gregorian date.
CELESTIAL_API CelestialDeltaT	celestial_delta_t (double year, uint32_t model_code)
	Compute TT - UT1 in seconds using the selected Delta T model.
CELESTIAL_API CelestialChartSnapshot	celestial_chart_snapshot (int32_t year, uint32_t month, uint32_t day, double fraction, uint32_t civil_scale_code, double latitude_deg, double longitude_deg, uint32_t house_system_code, uint32_t delta_t_model_code)
	Calculate a complete chart at an explicitly scaled civil instant.
CELESTIAL_API uint32_t	celestial_longitude_events (uint32_t target_code, double target_longitude_deg, double start_jde_tt, double end_jde_tt, uint32_t *event_count, CelestialLongitudeEventRecord *slots, uint32_t slot_count)
	Find the JDE(TT)s where target's apparent geocentric longitude reaches target_longitude_deg in the half-open interval [start, end), written to slots.
CELESTIAL_API uint32_t	celestial_longitude_stations (uint32_t target_code, double start_jde_tt, double end_jde_tt, uint32_t *event_count, CelestialStationEventRecord *slots, uint32_t slot_count)
	Find the JDE(TT)s where target's seven-point ephemeris::longitude_rate is stationary in the half-open interval [start, end), written to slots.
CELESTIAL_API uint32_t	celestial_longitude_difference_events (uint32_t first_target_code, uint32_t second_target_code, double target_difference_deg, double start_jde_tt, double end_jde_tt, uint32_t *event_count, CelestialLongitudeDifferenceEventRecord *slots, uint32_t slot_count)
	Find the JDE(TT)s where the directed difference (first - second) of the two targets' apparent geocentric longitudes reaches target_difference_deg in the half-open interval [start, end), written to slots.
CELESTIAL_API uint32_t	celestial_capabilities (uint32_t operation_code, uint32_t subject_code, uint32_t *record_count, CelestialCapabilityRecord *slots, uint32_t slot_count)
	List declared TT input bounds and sources for target operations.
CELESTIAL_API uint32_t	celestial_model_identities (uint32_t kind_code, uint32_t *record_count, CelestialModelIdentityRecord *slots, uint32_t slot_count)
	Enumerate the registered model identities (Delta T, nutation, position sources).
CELESTIAL_API uint32_t	celestial_model_identity_text (uint32_t kind_code, uint32_t identity_code, char *buffer, uint32_t capacity)
	Describe one model by the exact pair returned by celestial_model_identities.
CELESTIAL_API uint32_t	celestial_capability_text (uint32_t operation_code, uint32_t subject_code, char *buffer, uint32_t capacity)
	Describe an operation's source, input policy and model use.
CELESTIAL_API uint32_t	celestial_positions (const uint32_t *target_codes, uint32_t target_count, double jde_tt, uint32_t *record_count, CelestialPositionRecord *slots, uint32_t slot_count)
	Selected-target apparent geocentric positions at one JDE(TT) instant.
CELESTIAL_API uint32_t	celestial_equatorial_positions (const uint32_t *target_codes, uint32_t target_count, double jde_tt, uint32_t *record_count, CelestialEquatorialPositionRecord *slots, uint32_t slot_count)
	Selected-target geocentric apparent RA/Dec at JDE(TT), in caller order.
CELESTIAL_API CelestialHouseQueryResult	celestial_house_query (int32_t year, uint32_t month, uint32_t day, double fraction, uint32_t civil_scale_code, uint32_t delta_t_model_code, uint32_t nutation_model_code, double latitude_deg, double longitude_deg, uint32_t house_system_code)
	House geometry at a civil instant, independent of any body evaluation.
CELESTIAL_API CelestialCivilHouseCapability	celestial_house_capability (uint32_t delta_t_model_code)
	Describe the civil-house policy for one selected Delta T model.

Macro Definition Documentation

CELESTIAL_API

#define CELESTIAL_API

CELESTIAL_CIVIL_SCALE_UT1

#define CELESTIAL_CIVIL_SCALE_UT1

CELESTIAL_CIVIL_SCALE_UTC

#define CELESTIAL_CIVIL_SCALE_UTC

CELESTIAL_DELTA_T_MODEL_ALGO1

#define CELESTIAL_DELTA_T_MODEL_ALGO1

CELESTIAL_DELTA_T_MODEL_ALGO2

#define CELESTIAL_DELTA_T_MODEL_ALGO2

CELESTIAL_DELTA_T_MODEL_ALGO3

#define CELESTIAL_DELTA_T_MODEL_ALGO3

CELESTIAL_DELTA_T_MODEL_ALGO4

#define CELESTIAL_DELTA_T_MODEL_ALGO4

CELESTIAL_DELTA_T_MODEL_ALGO5

#define CELESTIAL_DELTA_T_MODEL_ALGO5

CELESTIAL_DELTA_T_MODEL_DEFAULT

#define CELESTIAL_DELTA_T_MODEL_DEFAULT

CELESTIAL_ERROR_COMPUTATION

#define CELESTIAL_ERROR_COMPUTATION

CELESTIAL_ERROR_INTERNAL

#define CELESTIAL_ERROR_INTERNAL

CELESTIAL_ERROR_INVALID_INPUT

#define CELESTIAL_ERROR_INVALID_INPUT

CELESTIAL_ERROR_NONE

#define CELESTIAL_ERROR_NONE

CELESTIAL_ERROR_RESOURCE

#define CELESTIAL_ERROR_RESOURCE

CELESTIAL_EVENT_DIRECTION_DECREASING

#define CELESTIAL_EVENT_DIRECTION_DECREASING

CELESTIAL_EVENT_DIRECTION_INCREASING

#define CELESTIAL_EVENT_DIRECTION_INCREASING

CELESTIAL_EVENT_DIRECTION_TANGENT

#define CELESTIAL_EVENT_DIRECTION_TANGENT

CELESTIAL_EVENT_MOTION_DIRECT

#define CELESTIAL_EVENT_MOTION_DIRECT

CELESTIAL_EVENT_MOTION_RETROGRADE

#define CELESTIAL_EVENT_MOTION_RETROGRADE

CELESTIAL_HOUSE_SYSTEM_EQUAL

#define CELESTIAL_HOUSE_SYSTEM_EQUAL

CELESTIAL_HOUSE_SYSTEM_PLACIDUS

#define CELESTIAL_HOUSE_SYSTEM_PLACIDUS

CELESTIAL_HOUSE_SYSTEM_WHOLE_SIGN

#define CELESTIAL_HOUSE_SYSTEM_WHOLE_SIGN

CELESTIAL_MODEL_KIND_ALL

#define CELESTIAL_MODEL_KIND_ALL

CELESTIAL_MODEL_KIND_DELTA_T

#define CELESTIAL_MODEL_KIND_DELTA_T

CELESTIAL_MODEL_KIND_NUTATION

#define CELESTIAL_MODEL_KIND_NUTATION

CELESTIAL_MODEL_KIND_POSITION_SOURCE

#define CELESTIAL_MODEL_KIND_POSITION_SOURCE

CELESTIAL_MODEL_STATUS_CURRENT

#define CELESTIAL_MODEL_STATUS_CURRENT

CELESTIAL_MODEL_STATUS_FROZEN

#define CELESTIAL_MODEL_STATUS_FROZEN

CELESTIAL_NUTATION_MODEL_DEFAULT

#define CELESTIAL_NUTATION_MODEL_DEFAULT

CELESTIAL_NUTATION_MODEL_IAU_1980

#define CELESTIAL_NUTATION_MODEL_IAU_1980

CELESTIAL_NUTATION_MODEL_MEEUS

#define CELESTIAL_NUTATION_MODEL_MEEUS

CELESTIAL_OPERATION_CHART

#define CELESTIAL_OPERATION_CHART

CELESTIAL_OPERATION_DELTA_T

#define CELESTIAL_OPERATION_DELTA_T

CELESTIAL_OPERATION_EQUATORIAL

#define CELESTIAL_OPERATION_EQUATORIAL

CELESTIAL_OPERATION_EVENTS

#define CELESTIAL_OPERATION_EVENTS

CELESTIAL_OPERATION_HOUSES

#define CELESTIAL_OPERATION_HOUSES

CELESTIAL_OPERATION_LONGITUDE_RATE

#define CELESTIAL_OPERATION_LONGITUDE_RATE

CELESTIAL_OPERATION_POSITION

#define CELESTIAL_OPERATION_POSITION

CELESTIAL_POSITION_SOURCE_MOON_ELP2000_82B_TRUNC

#define CELESTIAL_POSITION_SOURCE_MOON_ELP2000_82B_TRUNC

CELESTIAL_POSITION_SOURCE_NODE_MEAN

#define CELESTIAL_POSITION_SOURCE_NODE_MEAN

CELESTIAL_POSITION_SOURCE_NODE_TRUE_MEEUS_FIVE_TERM

#define CELESTIAL_POSITION_SOURCE_NODE_TRUE_MEEUS_FIVE_TERM

CELESTIAL_POSITION_SOURCE_PLANET_VSOP87D

#define CELESTIAL_POSITION_SOURCE_PLANET_VSOP87D

CELESTIAL_POSITION_SOURCE_PLUTO_PLUTO95_APPARENT

#define CELESTIAL_POSITION_SOURCE_PLUTO_PLUTO95_APPARENT

CELESTIAL_POSITION_SOURCE_SUN_VSOP87D

#define CELESTIAL_POSITION_SOURCE_SUN_VSOP87D

CELESTIAL_PRESENT_DISTANCE

#define CELESTIAL_PRESENT_DISTANCE

CELESTIAL_PRESENT_LATITUDE

#define CELESTIAL_PRESENT_LATITUDE

CELESTIAL_STATUS_FINITE_INPUT_EVALUATION

#define CELESTIAL_STATUS_FINITE_INPUT_EVALUATION

CELESTIAL_STATUS_IMPLEMENTATION_WINDOW

#define CELESTIAL_STATUS_IMPLEMENTATION_WINDOW

CELESTIAL_STATUS_SOURCE_WINDOW

#define CELESTIAL_STATUS_SOURCE_WINDOW

CELESTIAL_TARGET_ALL

#define CELESTIAL_TARGET_ALL

CELESTIAL_TARGET_JUPITER

#define CELESTIAL_TARGET_JUPITER

CELESTIAL_TARGET_MARS

#define CELESTIAL_TARGET_MARS

CELESTIAL_TARGET_MEAN_ASCENDING

#define CELESTIAL_TARGET_MEAN_ASCENDING

CELESTIAL_TARGET_MEAN_DESCENDING

#define CELESTIAL_TARGET_MEAN_DESCENDING

CELESTIAL_TARGET_MERCURY

#define CELESTIAL_TARGET_MERCURY

CELESTIAL_TARGET_MOON

#define CELESTIAL_TARGET_MOON

CELESTIAL_TARGET_NEPTUNE

#define CELESTIAL_TARGET_NEPTUNE

CELESTIAL_TARGET_PLUTO

#define CELESTIAL_TARGET_PLUTO

CELESTIAL_TARGET_SATURN

#define CELESTIAL_TARGET_SATURN

CELESTIAL_TARGET_SUN

#define CELESTIAL_TARGET_SUN

CELESTIAL_TARGET_TRUE_ASCENDING

#define CELESTIAL_TARGET_TRUE_ASCENDING

CELESTIAL_TARGET_TRUE_DESCENDING

#define CELESTIAL_TARGET_TRUE_DESCENDING

CELESTIAL_TARGET_URANUS

#define CELESTIAL_TARGET_URANUS

CELESTIAL_TARGET_VENUS

#define CELESTIAL_TARGET_VENUS

Typedef Documentation

CelestialApparentSolarTime

typedef struct CelestialApparentSolarTime CelestialApparentSolarTime

CelestialCapabilityRecord

typedef struct CelestialCapabilityRecord CelestialCapabilityRecord

One TT operation's input bounds for one target.

Note

Domain ends are NaN where no explicit JDE(TT) bound exists. With CELESTIAL_STATUS_FINITE_INPUT_EVALUATION, finite input is admitted to evaluation, but coordinate checks or computation can still fail. These bounds promise neither accuracy nor physical plausibility; validation coverage is described separately by celestial_capability_text. Civil houses use celestial_house_capability instead.

CelestialChartBody

typedef struct CelestialChartBody CelestialChartBody

One geocentric target in the true ecliptic and equinox of date.

CelestialChartHouses

typedef struct CelestialChartHouses CelestialChartHouses

Four axes and twelve cusps in degrees, each in [0, 360); cusps are houses 1-12.

CelestialChartSnapshot

typedef struct CelestialChartSnapshot CelestialChartSnapshot

A complete independent value; consume the payload only when valid is true.

CelestialCivilHouseCapability

typedef struct CelestialCivilHouseCapability CelestialCivilHouseCapability

The adopted civil-house admission policy, separate from geometric solvability.

CelestialDeltaT

typedef struct CelestialDeltaT CelestialDeltaT

CelestialDiscriminant

typedef struct CelestialDiscriminant CelestialDiscriminant

CelestialEquationOfTime

typedef struct CelestialEquationOfTime CelestialEquationOfTime

CelestialEquatorialPositionRecord

typedef struct CelestialEquatorialPositionRecord CelestialEquatorialPositionRecord

One selected target's apparent geocentric equatorial position of date.

CelestialGregorianDate

typedef struct CelestialGregorianDate CelestialGregorianDate

CelestialHouseQueryResult

typedef struct CelestialHouseQueryResult CelestialHouseQueryResult

Independent house geometry with resolved explicit model identities.

CelestialJieqiMomentQuery

typedef struct CelestialJieqiMomentQuery CelestialJieqiMomentQuery

CelestialJulianDay

typedef struct CelestialJulianDay CelestialJulianDay

CelestialLongitudeDifferenceEventRecord

typedef struct CelestialLongitudeDifferenceEventRecord CelestialLongitudeDifferenceEventRecord

One event of the directed, canonical longitude difference first minus second.

CelestialLongitudeEventRecord

typedef struct CelestialLongitudeEventRecord CelestialLongitudeEventRecord

One longitude crossing or exact numerical contact at the supplied level.

CelestialLunarDate

typedef struct CelestialLunarDate CelestialLunarDate

CelestialLunarYearInfo

typedef struct CelestialLunarYearInfo CelestialLunarYearInfo

CelestialModelIdentityRecord

typedef struct CelestialModelIdentityRecord CelestialModelIdentityRecord

One registered model identity with its applicability.

Note

Both domain ends are NaN where no explicit bound exists. Evaluation-instant guards do not imply a universal limit on converted TT output; see celestial_model_identity_text.

CelestialMoonCoordinate

typedef struct CelestialMoonCoordinate CelestialMoonCoordinate

CelestialMoonIllumination

typedef struct CelestialMoonIllumination CelestialMoonIllumination

CelestialMoonPositionAngle

typedef struct CelestialMoonPositionAngle CelestialMoonPositionAngle

CelestialPositionRecord

typedef struct CelestialPositionRecord CelestialPositionRecord

One selected target's apparent geocentric position in the true ecliptic of date.

CelestialSiderealTime

typedef struct CelestialSiderealTime CelestialSiderealTime

CelestialStationEventRecord

typedef struct CelestialStationEventRecord CelestialStationEventRecord

One stationary instant of the seven-point ephemeris::longitude_rate.

CelestialSunCoordinate

typedef struct CelestialSunCoordinate CelestialSunCoordinate

CelestialSupportedLunarYearRange

typedef struct CelestialSupportedLunarYearRange CelestialSupportedLunarYearRange

CelestialUT1Time

typedef struct CelestialUT1Time CelestialUT1Time

CelestialUTCTime

typedef struct CelestialUTCTime CelestialUTCTime

A UTC civil result; before 1972-01-01 its fields use the UT1 substitute.

Function Documentation

celestial_apparent_solar_time()

CELESTIAL_API CelestialApparentSolarTime celestial_apparent_solar_time	(	int32_t	y,
		uint32_t	m,
		uint32_t	d,
		double	fraction,
		double	longitude )

Convert a civil UTC moment to local apparent (true) solar time.

Parameters

y	The year (UTC), in [1, 32767]; the shifted TT instant must also stay representable.
m	The month (UTC).
d	The day (UTC).
fraction	The fraction of the day (UTC). Must be in the range [0.0, 1.0).
longitude	The observer's geographic longitude in degrees, positive east, in [-180, 180].

Returns

A CelestialApparentSolarTime struct; the local apparent solar date may differ from the input UTC date — a large enough longitude shifts the moment across midnight.

celestial_capabilities()

CELESTIAL_API uint32_t celestial_capabilities	(	uint32_t	operation_code,
		uint32_t	subject_code,
		uint32_t *	record_count,
		CelestialCapabilityRecord *	slots,
		uint32_t	slot_count )

List declared TT input bounds and sources for target operations.

Parameters

operation_code	CELESTIAL_OPERATION_POSITION, CELESTIAL_OPERATION_LONGITUDE_RATE, CELESTIAL_OPERATION_EVENTS or CELESTIAL_OPERATION_EQUATORIAL. Unknown codes and operations without TT target records fail.
subject_code	A CELESTIAL_TARGET_* code, or CELESTIAL_TARGET_ALL for every target; unknown target codes fail.
record_count	Where the total count of records is written. Must not be null. On every failure *record_count is set to 0.
slots	The output slots, allocated and freed by the caller; may be null only when slot_count is 0.
slot_count	The count of slots.

Returns

How many slots are written, at most min(total, slot_count); records follow CELESTIAL_TARGET_* code order.

Note

Bounds come from the operation's defining constants; passing them does not promise successful computation or accuracy. For HOUSES use celestial_house_capability; HOUSES, CHART and DELTA_T model use is described by celestial_capability_text.

celestial_capability_text()

CELESTIAL_API uint32_t celestial_capability_text	(	uint32_t	operation_code,
		uint32_t	subject_code,
		char *	buffer,
		uint32_t	capacity )

Describe an operation's source, input policy and model use.

Parameters

operation_code	A CELESTIAL_OPERATION_* code. Target operations describe TT inputs; HOUSES, CHART and DELTA_T describe their operation-specific model use. Unknown operations fail. Model identity text uses celestial_model_identity_text.
subject_code	Target operations require one CELESTIAL_TARGET_* code (not ALL). HOUSES, CHART and DELTA_T require CELESTIAL_TARGET_ALL because they have no target. Unknown or inapplicable subjects fail. Use kind/identity pairs with celestial_model_identity_text to describe individual models.
buffer	Caller-owned UTF-8 buffer; may be null only when capacity is zero.
capacity	Available bytes, including the NUL terminator; zero queries the size.

Returns

Required bytes including NUL, or zero on failure. Positive capacity writes at most capacity - 1 payload bytes and a terminating NUL, truncating if needed.

Note

Coordinate descriptions name origin, frame, units and corrections. Model-use descriptions name source/version, status and role. Validation owners are cited separately; coordinate validity does not establish accuracy or physical plausibility.

celestial_chart_snapshot()

CELESTIAL_API CelestialChartSnapshot celestial_chart_snapshot	(	int32_t	year,
		uint32_t	month,
		uint32_t	day,
		double	fraction,
		uint32_t	civil_scale_code,
		double	latitude_deg,
		double	longitude_deg,
		uint32_t	house_system_code,
		uint32_t	delta_t_model_code )

Calculate a complete chart at an explicitly scaled civil instant.

Parameters

year	Gregorian civil year in [1885, 2100).
month	Gregorian month in [1, 12].
day	A valid day of the Gregorian month.
fraction	Finite fraction of the civil day in [0, 1); inserted leap seconds are outside the input.
civil_scale_code	CELESTIAL_CIVIL_SCALE_UTC (from 1972-01-01) or CELESTIAL_CIVIL_SCALE_UT1.
latitude_deg	North-positive latitude in (-90, 90).
longitude_deg	East-positive longitude in [-180, 180].
house_system_code	A CELESTIAL_HOUSE_SYSTEM_* code; Placidus rejects polar geometry. All systems reject an Ascendant direction unresolved at round-off.
delta_t_model_code	A CELESTIAL_DELTA_T_MODEL_* selector; DEFAULT resolves to the core default.

Returns

A CelestialChartSnapshot by value. On failure valid is false; read celestial_last_error_kind and celestial_last_error for the cause. Invalid payload and padding bytes have no contract. There is no partial result.

Note

JDE(TT) must be in [2409543.875, 2488069.125); Algo4 additionally requires JDE(TT) < 2464328.5. UT1 derived from UTC is modelled through the selected Delta T, not observed DUT1. Location affects houses only; timezone conversion is the caller's responsibility. Houses use the house operation's default nutation; bodies use fixed IAU 1980.

celestial_delta_t()

CELESTIAL_API CelestialDeltaT celestial_delta_t	(	double	year,
		uint32_t	model_code )

Compute TT - UT1 in seconds using the selected Delta T model.

Parameters

year	A finite decimal Gregorian year at which the model is evaluated.
model_code	A CELESTIAL_DELTA_T_MODEL_* selector; DEFAULT resolves to the core default.

Returns

The value and resolved model identity; valid is false on failure.

Note

Algo1 requires year >= -4000, Algo3 year < 3000, and Algo4 year < 2035. These are evaluation-instant guards, not a universal bound on a converted TT value.

celestial_equation_of_time()

CELESTIAL_API CelestialEquationOfTime celestial_equation_of_time

(

double

jde

)

Compute the equation of time E = apparent solar time - mean solar time (Meeus ch. 28).

Parameters

jde	The julian ephemeris day number, which is based on TT.

Returns

A CelestialEquationOfTime struct; value is E in degrees of hour angle (x240 = seconds of time).

celestial_equatorial_positions()

CELESTIAL_API uint32_t celestial_equatorial_positions	(	const uint32_t *	target_codes,
		uint32_t	target_count,
		double	jde_tt,
		uint32_t *	record_count,
		CelestialEquatorialPositionRecord *	slots,
		uint32_t	slot_count )

Selected-target geocentric apparent RA/Dec at JDE(TT), in caller order.

Parameters

target_codes	A non-null, nonempty selection of distinct CELESTIAL_TARGET_* values.
target_count	The number of selected targets.
jde_tt	Finite JDE(TT); declared provider windows apply independently to each target.
record_count	Non-null total-count output, set to zero on failure.
slots	Caller-owned output, null only when slot_count is zero.
slot_count	Output capacity in records.

Returns

Number written, at most min(total, slot_count); a failed target fails the whole query.

Note

Fixed IAU 1980 longitude nutation and true obliquity; no rate, civil or house evaluation. Coordinate validity does not establish accuracy or physical plausibility at remote epochs.

celestial_get_jieqi_name()

CELESTIAL_API uint32_t celestial_get_jieqi_name	(	uint8_t	jq_idx,
		char *	buf,
		uint32_t	buf_size )

Size or write the UTF-8 Chinese name of the Jieqi.

Parameters

jq_idx	The Jieqi index in [0, 24), in ecliptic order: 0 = 立春 (Lichun) … 23 = 大寒.
buf	Caller-owned buffer; may be null only when buf_size is zero.
buf_size	Available bytes, including the NUL terminator; zero queries the size.

Returns

Required bytes including NUL, or zero on failure. Positive buf_size writes at most buf_size - 1 payload bytes and a terminating NUL, truncating if needed.

Note

The current names need at most 7 bytes including NUL; bindings query the size dynamically.

celestial_get_lunar_year_info()

CELESTIAL_API CelestialLunarYearInfo celestial_get_lunar_year_info	(	uint8_t	algo,
		int32_t	year )

Get the lunar year information for the given year.

Parameters

algo	The algorithm profile described by celestial_get_supported_lunar_year_range.
year	The lunar year. Outside the range celestial_get_supported_lunar_year_range reports for algo, the result is valid = false.

Returns

A CelestialLunarYearInfo struct.

celestial_get_supported_lunar_year_range()

CELESTIAL_API CelestialSupportedLunarYearRange celestial_get_supported_lunar_year_range

(

uint8_t

algo

)

Get the supported lunar year range of the algorithm.

Parameters

algo	The algorithm. Expected to be 1, 2, or 3.

Returns

A CelestialSupportedLunarYearRange struct.

Algorithm profiles:

• 1: preserves the published HKO calendar-date labels for 1901-2099;
• 2: computation from VSOP87D/ELP2000-82B for 410-2500, with TT moments rendered through the library's UTC model and then a fixed east-eight offset; that model uses UT1 as a pre-1972 proxy, the ΔAT table from 1972 through its final announced step, and a frozen ΔAT of 37 s afterward;
• 3: a baked table for 1600-2199, using algorithm 1 for 1901-2099 and algorithm 2 for the other years.

celestial_gregorian_to_lunar()

CELESTIAL_API CelestialLunarDate celestial_gregorian_to_lunar	(	uint8_t	algo,
		int32_t	year,
		uint8_t	month,
		uint8_t	day )

Convert a Gregorian date to a lunar date.

Parameters

algo	The algorithm profile described by celestial_get_supported_lunar_year_range.
year	The Gregorian year, in [-32767, 32767]; an unrepresentable integer is rejected, never narrowed to an aliased year.
month	The Gregorian month.
day	The Gregorian day of the month.

Returns

A CelestialLunarDate struct; valid = false when algo is unknown, the input is not a real Gregorian date, or it falls outside the Gregorian span the algorithm covers — that span runs from the first day of lunar year start to the last day of lunar year end (start/end as celestial_get_supported_lunar_year_range reports them), so it begins and ends mid-Gregorian-year at both ends.

Note

The lunar month is in traditional numbering (1-12) plus the is_leap flag — a leap month carries its predecessor's number with is_leap = true: in lunar 2023 (leap 2nd month), the leap 2nd month is month = 2, is_leap = true, and the traditional 3rd month is month = 3, is_leap = false. This is NOT the positional month index that CelestialLunarYearInfo.month_len is indexed by.

The Gregorian input is a calendar-date label on the selected algorithm's basis, not an instant.

celestial_house_capability()

CELESTIAL_API CelestialCivilHouseCapability celestial_house_capability

(

uint32_t

delta_t_model_code

)

Describe the civil-house policy for one selected Delta T model.

Parameters

delta_t_model_code

A CELESTIAL_DELTA_T_MODEL_* selector; DEFAULT resolves to the core default.

Returns

Policy facts and resolved model identity; invalid on an unknown selector.

Note

The policy is [1885, 2100), with UTC from 1972-01-01 and an exclusive derived-TT cutoff of 2464328.5 for Algo4 only. Admission does not promise geometric success. There is no chart target/rate window here; this is not a numeric TT house-domain record.

celestial_house_query()

CELESTIAL_API CelestialHouseQueryResult celestial_house_query	(	int32_t	year,
		uint32_t	month,
		uint32_t	day,
		double	fraction,
		uint32_t	civil_scale_code,
		uint32_t	delta_t_model_code,
		uint32_t	nutation_model_code,
		double	latitude_deg,
		double	longitude_deg,
		uint32_t	house_system_code )

House geometry at a civil instant, independent of any body evaluation.

Parameters

year	Gregorian civil year in [1885, 2100) — the same civil contract as the snapshot.
month	Gregorian month in [1, 12].
day	A valid day of the Gregorian month.
fraction	Finite fraction of the civil day in [0, 1); inserted leap seconds are outside the input.
civil_scale_code	CELESTIAL_CIVIL_SCALE_UTC (from 1972-01-01) or CELESTIAL_CIVIL_SCALE_UT1.
delta_t_model_code	A CELESTIAL_DELTA_T_MODEL_* selector; DEFAULT resolves to the core default.
nutation_model_code	A CELESTIAL_NUTATION_MODEL_* selector; DEFAULT resolves to the house operation's default.
latitude_deg	North-positive latitude in (-90, 90).
longitude_deg	East-positive longitude in [-180, 180].
house_system_code	A CELESTIAL_HOUSE_SYSTEM_* code; Placidus rejects polar geometry, and every system rejects an Ascendant direction unresolved at round-off.

Returns

A CelestialHouseQueryResult by value. On failure valid is false; read celestial_last_error_kind and celestial_last_error for the cause. Invalid payload and padding bytes have no contract. There is no partial result.

Note

The shared civil admission policy requires derived JDE(TT) < 2464328.5 for Algo4. No chart joint target/rate window applies; conversion and geometric failures remain possible. The result records the resolved Delta T and nutation identities.

celestial_jde_to_ut1()

CELESTIAL_API CelestialUT1Time celestial_jde_to_ut1

(

double

jde

)

Convert Julian Ephemeris Day Number (JDE) to UT1 datetime.

Parameters

jde	The julian ephemeris day number, which is based on TT.

Returns

A CelestialUT1Time struct.

celestial_jde_to_utc()

CELESTIAL_API CelestialUTCTime celestial_jde_to_utc

(

double

jde_tt

)

Convert TT-based Julian Ephemeris Day (JDE) to UTC civil fields.

Parameters

jde_tt

Finite JDE(TT) in [1867522.5, 13689325.5).

Returns

A CelestialUTCTime struct; the lower endpoint can return a date in year 400.

Note

Before 1972-01-01 the result uses the UT1 substitute with fixed Algo5. The final leap-second offset is retained beyond the table; leap seconds and the 1972 seam do not promise an exact inverse, including round-off at leap-step midnights.

See also

celestial_utc_to_jde

celestial_last_error()

CELESTIAL_API const char * celestial_last_error

(

void

)

Get the last-error message of the calling thread.

Returns

A pointer to a thread-local C string, empty if there is no recorded error. The pointer remains valid until the next recording call on this thread. Neither error reader clears the kind or message.

Note

A failure can have an empty message if message allocation failed; read the kind.

celestial_last_error_kind()

CELESTIAL_API uint32_t celestial_last_error_kind

(

void

)

Read the calling thread's CELESTIAL_ERROR_* code without clearing its error.

celestial_local_apparent_sidereal_time()

CELESTIAL_API CelestialSiderealTime celestial_local_apparent_sidereal_time	(	double	jd_ut1,
		double	longitude )

Compute the Local Apparent Sidereal Time (LAST) for an observer.

Parameters

jd_ut1	The julian day number, which is based on UT1. Declared domain: Gregorian years in [401, 32766].
longitude	The observer's geographic longitude in degrees, positive east, in [-180, 180].

Returns

A CelestialSiderealTime struct. The ΔT model is fixed Algo5 and the nutation model is fixed IAU 1980.

celestial_longitude_difference_events()

CELESTIAL_API uint32_t celestial_longitude_difference_events	(	uint32_t	first_target_code,
		uint32_t	second_target_code,
		double	target_difference_deg,
		double	start_jde_tt,
		double	end_jde_tt,
		uint32_t *	event_count,
		CelestialLongitudeDifferenceEventRecord *	slots,
		uint32_t	slot_count )

Find the JDE(TT)s where the directed difference (first - second) of the two targets' apparent geocentric longitudes reaches target_difference_deg in the half-open interval [start, end), written to slots.

Parameters

first_target_code	A CELESTIAL_TARGET_* code.
second_target_code	A CELESTIAL_TARGET_* code, distinct from the first.
target_difference_deg	A finite signed angle in degrees, canonicalized to (-180, 180].
start_jde_tt	Inclusive start, finite, within the intersection of the two targets' longitude-rate domains.
end_jde_tt	Exclusive end; the nonempty span must not exceed 3660 TT days.
event_count	Where the total count of events is written. Must not be null. On every failure *event_count is set to 0.
slots	The output slots, allocated and freed by the caller; may be null only when slot_count is 0.
slot_count	The count of slots.

Returns

How many slots are written, in chronological order, at most min(total, slot_count).

Note

A constant mismatch (antipodal node pairs whose opposition angle is not the target) is a legal empty list; a continuously satisfied relation fails.

Reversing the two targets reverses the requested angle and crossing direction. Self-pairs and continuously satisfied relations are invalid; numerical ambiguity or work-limit exhaustion fails the whole query. The floating-point premises are the same as for celestial_longitude_events.

celestial_longitude_events()

CELESTIAL_API uint32_t celestial_longitude_events	(	uint32_t	target_code,
		double	target_longitude_deg,
		double	start_jde_tt,
		double	end_jde_tt,
		uint32_t *	event_count,
		CelestialLongitudeEventRecord *	slots,
		uint32_t	slot_count )

Find the JDE(TT)s where target's apparent geocentric longitude reaches target_longitude_deg in the half-open interval [start, end), written to slots.

Parameters

target_code	A CELESTIAL_TARGET_* code.
target_longitude_deg	A finite angle in degrees; whole-turn shifts denote the same level.
start_jde_tt	Inclusive start, finite, within the target's longitude-rate domain.
end_jde_tt	Exclusive end; the nonempty span must not exceed 3660 TT days.
event_count	Where the total count of events is written. Must not be null. On every failure *event_count is set to 0; a zero total is also the legal no-event outcome, disambiguated by celestial_last_error_kind.
slots	The output slots, allocated and freed by the caller; may be null only when slot_count is 0.
slot_count	The count of slots.

Returns

How many slots are written, in chronological order, at most min(total, slot_count).

Note

Longitudes are apparent, geocentric and tropical; node longitudes follow lunar_node::position. Exact numerical contacts are reported for a target equal to the query-independent stationary output, never within an angular window. Numerical ambiguity or work-limit exhaustion fails the whole query — no partial list is ever returned. See docs/EPHEMERIS_EVENTS.md for domains and the conditional floating-point contract.

celestial_longitude_stations()

CELESTIAL_API uint32_t celestial_longitude_stations	(	uint32_t	target_code,
		double	start_jde_tt,
		double	end_jde_tt,
		uint32_t *	event_count,
		CelestialStationEventRecord *	slots,
		uint32_t	slot_count )

Find the JDE(TT)s where target's seven-point ephemeris::longitude_rate is stationary in the half-open interval [start, end), written to slots.

Parameters

target_code	A CELESTIAL_TARGET_* code.
start_jde_tt	Inclusive start, finite, within the target's longitude-rate domain.
end_jde_tt	Exclusive end; the nonempty span must not exceed 3660 TT days.
event_count	Where the total count of events is written. Must not be null. On every failure *event_count is set to 0.
slots	The output slots, allocated and freed by the caller; may be null only when slot_count is 0.
slot_count	The count of slots.

Returns

How many slots are written, in chronological order, at most min(total, slot_count).

Note

Targets whose certified rate bounds exclude a station return a legal empty list. The motion codes describe the certified sign on each side; the reported rate need not be bitwise zero. The floating-point premises are the same as for celestial_longitude_events.

celestial_lunar_to_gregorian()

CELESTIAL_API CelestialGregorianDate celestial_lunar_to_gregorian	(	uint8_t	algo,
		int32_t	year,
		uint8_t	month,
		bool	is_leap,
		uint8_t	day )

Convert a lunar date to a Gregorian date.

Parameters

algo	The algorithm profile described by celestial_get_supported_lunar_year_range.
year	The lunar year.
month	The lunar month, in traditional numbering (1-12) — see celestial_gregorian_to_lunar.
is_leap	Whether the month is the leap month. true is accepted only on the year's actual leap month — month = 2 in lunar 2023, and no month at all in a year that has none.
day	The day of the lunar month.

Returns

A CelestialGregorianDate struct; valid = false when the input does not name a real lunar date (bad algo, year out of range, no such leap month, day out of range).

Note

The returned Gregorian value is a calendar-date label on the selected algorithm's basis, not an instant; see celestial_gregorian_to_lunar.

celestial_model_identities()

CELESTIAL_API uint32_t celestial_model_identities	(	uint32_t	kind_code,
		uint32_t *	record_count,
		CelestialModelIdentityRecord *	slots,
		uint32_t	slot_count )

Enumerate the registered model identities (Delta T, nutation, position sources).

Parameters

kind_code	A CELESTIAL_MODEL_KIND_* code, or CELESTIAL_MODEL_KIND_ALL for every kind. Unknown kinds fail.
record_count	Where the total count of records is written. Must not be null. On every failure *record_count is set to 0.
slots	The output slots, allocated and freed by the caller; may be null only when slot_count is 0.
slot_count	The count of slots.

Returns

How many slots are written, at most min(total, slot_count); records follow the registry order (Delta T algo1-5, nutation, position sources).

Note

Explicit identity values are stable within a major and start at 1 within each kind. DEFAULT (0) is never a returned identity; its resolution belongs to each operation.

celestial_model_identity_text()

CELESTIAL_API uint32_t celestial_model_identity_text	(	uint32_t	kind_code,
		uint32_t	identity_code,
		char *	buffer,
		uint32_t	capacity )

Describe one model by the exact pair returned by celestial_model_identities.

Parameters

kind_code	A concrete CELESTIAL_MODEL_KIND_* value, not ALL.
identity_code	A nonzero explicit value within that kind; unknown pairs fail.
buffer	Caller-owned UTF-8 buffer; may be null only when capacity is zero.
capacity	Available bytes, including the NUL terminator; zero queries the size.

Returns

Required bytes including NUL. Positive capacity writes at most capacity - 1 payload bytes and a terminating NUL, truncating if needed.

Note

Read the error kind after sizing or filling; zero required bytes signals failure.

celestial_moon_apparent_geocentric_coord()

CELESTIAL_API CelestialMoonCoordinate celestial_moon_apparent_geocentric_coord

(

double

jde

)

Calculate the apparent geocentric position of the Moon.

Parameters

jde	The julian ephemeris day number, which is based on TT.

Returns

A CelestialMoonCoordinate struct.

celestial_moon_illumination()

CELESTIAL_API CelestialMoonIllumination celestial_moon_illumination

(

double

jde

)

Compute the Moon's illuminated fraction k and elongation at a JDE (Meeus ch. 48: k from (48.2)+(48.3)+(48.1)).

Parameters

jde	The julian ephemeris day number, which is based on TT.

Returns

A CelestialMoonIllumination struct. elongation_deg is the apparent ecliptic longitude difference that defines the phases: 0° new, 90° first quarter, 180° full, 270° last quarter.

celestial_moon_phase_moments()

CELESTIAL_API uint32_t celestial_moon_phase_moments	(	int32_t	year,
		uint8_t	phase_kind,
		uint32_t *	root_count,
		double *	slots,
		uint32_t	slot_count )

Find the moments of a given Moon phase in year; the total count goes to root_count, up to slot_count of them are written to slots.

Parameters

year	The Gregorian year, in [1, 32766].
phase_kind	The phase kind: 0 = New Moon, 1 = First Quarter, 2 = Full Moon, 3 = Last Quarter.
root_count	Where the total count of the roots is written. Must not be null. On every failure *root_count is set to 0.
slots	The output slots, allocated and freed by the caller; may be null only when slot_count is 0.
slot_count	The count of slots.

Returns

How many slots are written.

celestial_moon_position_angle()

CELESTIAL_API CelestialMoonPositionAngle celestial_moon_position_angle

(

double

jde

)

Compute the position angle of the Moon's bright limb at a JDE (Meeus ch. 48, (48.5)).

Parameters

jde	The julian ephemeris day number, which is based on TT.

Returns

A CelestialMoonPositionAngle struct; angle_deg is measured eastward from the north point of the disk, in [0, 360).

celestial_new_moons_after_jde()

CELESTIAL_API uint32_t celestial_new_moons_after_jde	(	double	jde,
		double *	slots,
		uint32_t	slot_count )

Find the next slot_count new-moon JDE(s) after jde, written to slots.

Parameters

jde	The julian ephemeris day number, which is based on TT.
slots	The output slots, allocated and freed by the caller; may be null only when slot_count is 0.
slot_count	The count of slots.

Returns

How many slots are written.

celestial_new_moons_in_year()

CELESTIAL_API uint32_t celestial_new_moons_in_year	(	int32_t	year,
		uint32_t *	root_count,
		double *	slots,
		uint32_t	slot_count )

Find the new-moon JDE(s) in year; the total count goes to root_count, up to slot_count of them are written to slots.

Parameters

year	The Gregorian year, in [1, 32766].
root_count	Where the total count of the roots is written. Must not be null. On every failure *root_count is set to 0.
slots	The output slots, allocated and freed by the caller; may be null only when slot_count is 0.
slot_count	The count of slots.

Returns

How many slots are written.

celestial_positions()

CELESTIAL_API uint32_t celestial_positions	(	const uint32_t *	target_codes,
		uint32_t	target_count,
		double	jde_tt,
		uint32_t *	record_count,
		CelestialPositionRecord *	slots,
		uint32_t	slot_count )

Selected-target apparent geocentric positions at one JDE(TT) instant.

Parameters

target_codes	The caller's selection: an array of CELESTIAL_TARGET_* codes, allocated and freed by the caller; must not be null. Output records follow this order.
target_count	The selection size; must be positive, with no duplicated target.
jde_tt	A finite JDE(TT). Each target's provider window applies (Pluto and the nodes publish one; see celestial_capabilities); no rate stencil is evaluated, so the snapshot joint window and the rate reach do not constrain this query.
record_count	Where the total count of records is written. Must not be null. On every failure *record_count is set to 0.
slots	The output slots, allocated and freed by the caller; may be null only when slot_count is 0 (a count-only pass).
slot_count	The count of slots.

Returns

How many slots are written, at most min(total, slot_count).

Note

One failed target fails the whole query: no partial list is ever returned, and the legal empty outcome never occurs (target_count is positive). A subset query may succeed where a complete snapshot would reject an excluded target's window.

celestial_query_jieqi_moment()

CELESTIAL_API CelestialJieqiMomentQuery celestial_query_jieqi_moment	(	int32_t	year,
		uint8_t	jq_idx )

Query the accurate UT1 moment of the Jieqi in the given year.

Parameters

year	The Gregorian year, in [401, 32766].
jq_idx	The Jieqi index in [0, 24), in ecliptic order: 0 = 立春 (Lichun) … 23 = 大寒.

Returns

A CelestialJieqiMomentQuery struct.

Note

The returned civil moment is UT1 (from TT through ΔT algo5), not UTC. While leap seconds are applied, |UT1 − UTC| < 0.9 s; past the last ΔAT table step the modelled UT1 − UTC is (ΔAT + 32.184 s) − ΔT, no longer bounded by 0.9 s (#115). The gap by era: docs/DESIGN.md#time-scales.

The returned date is not an east-eight wall date; rendering the same instant at a fixed UTC+8 offset can change its calendar date.

celestial_solar_lon_root_discriminant()

CELESTIAL_API CelestialDiscriminant celestial_solar_lon_root_discriminant	(	int32_t	year,
		double	longitude )

Calculate the JDE discriminant — count how many times the Sun reaches the given geocentric longitude in the given year.

Parameters

year	The Gregorian year, in [1, 32766].
longitude	The geocentric longitude in degrees, in [0, 360).

Returns

A CelestialDiscriminant struct; count is 0, 1, or 2: the Sun won't reach the longitude in the year, reaches it once, or reaches it twice.

celestial_solar_lon_roots()

CELESTIAL_API uint32_t celestial_solar_lon_roots	(	int32_t	year,
		double	longitude,
		double *	slots,
		uint32_t	slot_count )

Find the JDE(s) at which the Sun reaches longitude in year, written to slots.

Parameters

year	The Gregorian year, in [1, 32766].
longitude	The geocentric longitude in degrees, in [0, 360).
slots	The output slots, allocated and freed by the caller; may be null only when slot_count is 0.
slot_count	The count of slots.

Returns

How many slots are written.

celestial_sun_apparent_geocentric_coord()

CELESTIAL_API CelestialSunCoordinate celestial_sun_apparent_geocentric_coord

(

double

jde

)

Calculate the apparent geocentric position of the Sun.

Parameters

jde	The julian ephemeris day number, which is based on TT.

Returns

A CelestialSunCoordinate struct.

celestial_ut1_to_jd()

CELESTIAL_API CelestialJulianDay celestial_ut1_to_jd	(	int32_t	y,
		uint32_t	m,
		uint32_t	d,
		double	fraction )

Convert UT1 datetime to Julian Day Number (JD).

Parameters

y	The year, in [1, 32767].
m	The month.
d	The day.
fraction	The fraction of the day. Must be in the range [0.0, 1.0).

Returns

A CelestialJulianDay struct. JD is based on UT1.

celestial_ut1_to_jde()

CELESTIAL_API CelestialJulianDay celestial_ut1_to_jde	(	int32_t	y,
		uint32_t	m,
		uint32_t	d,
		double	fraction )

Convert UT1 datetime to Julian Ephemeris Day Number (JDE).

Parameters

y	The year, in [1, 32767]; the ΔT-shifted TT instant must also stay representable.
m	The month.
d	The day.
fraction	The fraction of the day. Must be in the range [0.0, 1.0).

Returns

A CelestialJulianDay struct. JDE is based on TT.

celestial_utc_to_jde()

CELESTIAL_API CelestialJulianDay celestial_utc_to_jde	(	int32_t	y,
		uint32_t	m,
		uint32_t	d,
		double	fraction )

Convert UTC civil fields to TT-based Julian Ephemeris Day (JDE).

Parameters

y	The year, in [1, 32767]; the shifted TT instant must also stay representable.
m	The month.
d	The day.
fraction	The fraction of the UTC day, in [0.0, 1.0); 23:59:60 is not representable.

Returns

A CelestialJulianDay struct containing JDE(TT).

Note

Before 1972-01-01 the input is treated as UT1 using fixed Algo5. Modern dates use the fixed leap-second table, retaining its final offset after the last entry.

The 1972 model seam and leap-second boundaries are not generally invertible.

See also

celestial_jde_to_utc