adam_core.photometry.magnitude module

adam_core.photometry.magnitude.calculate_phase_angle(object_coords: CartesianCoordinates, observers: Observers) → ndarray[tuple[Any, ...], dtype[float64]][source]

Calculate the solar phase angle (Sun–object–observer) in degrees.

“Phase angle” here is the angle at the object between the Sun direction and the observer direction. It is commonly used for simple photometry/visibility metrics.

Notes

This helper expects heliocentric coordinates (origin = OriginCodes.SUN) for both the object and the observer. If you have barycentric coordinates, transform first.

Parameters:

  • object_coords – Object Cartesian coordinates in AU (origin must be SUN).

  • observers – Observer states (origin must be SUN).

Returns:

Phase angle in degrees for each paired row.

Return type:

phase_angle_deg

Examples

Given an Ephemeris eph from a propagator and corresponding Observers obs:

  • Use eph.coordinates for on-sky (RA/Dec, rho) values.

  • Use eph.aberrated_coordinates for emission-time geometry, and transform to heliocentric:

```python from adam_core.coordinates.cartesian import CartesianCoordinates from adam_core.coordinates.origin import OriginCodes from adam_core.coordinates.transform import transform_coordinates from adam_core.photometry import calculate_phase_angle from adam_core.observers import Observers

observers_eph = Observers.from_codes(eph.coordinates.origin.code, eph.coordinates.time)

obj_helio = transform_coordinates(

eph.aberrated_coordinates, CartesianCoordinates, frame_out=”ecliptic”, origin_out=OriginCodes.SUN,

) obs_helio = observers_eph.set_column(

“coordinates”, transform_coordinates(

observers_eph.coordinates, CartesianCoordinates, frame_out=”ecliptic”, origin_out=OriginCodes.SUN,

),

) alpha_deg = calculate_phase_angle(obj_helio, obs_helio) ```

adam_core.photometry.magnitude.convert_magnitude(magnitude: ndarray[tuple[Any, ...], dtype[float64]], source_filter_id: ndarray[tuple[Any, ...], dtype[object_]], target_filter_id: ndarray[tuple[Any, ...], dtype[object_]], *, composition: str | tuple[float, float]) → ndarray[tuple[Any, ...], dtype[float64]][source]

Convert magnitudes between canonical bandpass filter IDs using template integrals.

Parameters:

  • magnitude (ndarray) – 1D array of magnitudes in source_filter_id.

  • source_filter_id (ndarray) – 1D array of canonical source filter IDs (e.g., ‘V’, ‘DECam_g’, ‘LSST_r’).

  • target_filter_id (ndarray) – 1D array of canonical target filter IDs.

  • composition (str or (float, float)) – Required. Either a template ID (‘C’, ‘S’, ‘NEO’, ‘MBA’, or a registered custom template), or a (weight_C, weight_S) tuple for a linear C/S mix.

Returns:

Magnitudes in target_filter_id.

Return type:

ndarray

adam_core.photometry.magnitude.calculate_apparent_magnitude_v(H_v: float | ndarray[tuple[Any, ...], dtype[float64]], object_coords: CartesianCoordinates, observer: Observers, G: float | ndarray[tuple[Any, ...], dtype[float64]] = 0.15) → ndarray[tuple[Any, ...], dtype[float64]][source]

Calculate apparent V-band magnitudes.

Notes

This function is JAX-backed (numpy-sandwich pattern) and returns a NumPy array.

adam_core.photometry.magnitude.calculate_apparent_magnitude_v_and_phase_angle(H_v: float | ndarray[tuple[Any, ...], dtype[float64]], object_coords: CartesianCoordinates, observer: Observers, G: float | ndarray[tuple[Any, ...], dtype[float64]] = 0.15) → tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]][source]

Calculate apparent V-band magnitudes and phase angles (degrees) together.

Why: when both are needed, the H-G model already computes the phase geometry. This combined function avoids redoing the same law-of-cosines computation twice.

adam_core.photometry.magnitude.predict_magnitudes(H: float | ndarray[tuple[Any, ...], dtype[float64]], object_coords: CartesianCoordinates, exposures: Exposures, G: float | ndarray[tuple[Any, ...], dtype[float64]] = 0.15, reference_filter: str = 'V', *, composition: str | tuple[float, float]) → ndarray[tuple[Any, ...], dtype[float64]][source]

Predict apparent magnitudes for objects observed during exposures using bandpass-based conversions.

This: - compute apparent V-band magnitudes using the H-G system + geometry, then - convert V -> exposure filter.

Notes

  • exposures.filter must contain canonical bandpass filter_id values (e.g. ‘LSST_i’, ‘DECam_g’).

  • The V -> target conversion is computed from precomputed template×filter integrals, and requires an explicit asteroid composition (template_id or C/S mix weights).

Parameters:

  • H (float or ndarray) – Absolute magnitude(s) of the object(s) in reference_filter (canonical bandpass filter ID).

  • object_coords (CartesianCoordinates) – Cartesian coordinates of the object(s) at the exposure times.

  • exposures (Exposures) – Exposure table. exposures.filter must be a canonical bandpass filter_id.

  • G (float or ndarray, optional) – Slope parameter for the H-G system, defaults to 0.15.

  • reference_filter (str, optional) – Canonical filter ID in which H is defined. Defaults to “V”.

  • composition (str or (float, float)) – Required. Either a template ID (‘C’, ‘S’, ‘NEO’, ‘MBA’, or a registered custom template), or a (weight_C, weight_S) tuple for a linear C/S mix.

Returns:

Predicted apparent magnitudes in the exposures’ filters.

Return type:

ndarray