adam_core.photometry package

adam_core.photometry.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]]

Calculate apparent V-band magnitudes.

Notes

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

adam_core.photometry.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]]]

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.calculate_phase_angle(object_coords: CartesianCoordinates, observers: Observers) → ndarray[tuple[Any, ...], dtype[float64]]

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.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]]

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.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]]

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

adam_core.photometry.estimate_absolute_magnitude_v_from_detections(detections: PointSourceDetections, exposures: Exposures, object_coords: CartesianCoordinates, *, composition: str | tuple[float, float], G: float = 0.15, strict_band_mapping: bool = False, reference_filter: str = 'V') → PhysicalParameters

Estimate V-band absolute magnitude H from observed apparent magnitudes.

Assumptions

• Orbit has already been fit; object_coords are the heliocentric object coordinates at the observation times (aligned 1:1 with detections).

• We estimate H only; G and composition are treated as fixed inputs.

param detections:

Point-source detections. Uses mag and (optionally) mag_sigma.

param exposures:

Exposures referenced by detections.exposure_id. Uses observatory_code and filter.

param object_coords:

Object coordinates aligned with detections (same length and ordering).

param composition:

Required. Bandpass template ID (e.g. ‘NEO’) or (weight_C, weight_S) mix.

param G:

Fixed H-G slope parameter.

param strict_band_mapping:

If True, disallow SDSS/PS1 fallback filters when mapping reported bands.

param reference_filter:

Must be ‘V’ for this function.

adam_core.photometry.estimate_absolute_magnitude_v_from_detections_grouped(detections: PointSourceDetections, exposures: Exposures, object_coords: CartesianCoordinates, object_ids: Array | ChunkedArray | Sequence[str | None], *, composition: str | tuple[float, float], G: float = 0.15, strict_band_mapping: bool = False, reference_filter: str = 'V') → GroupedPhysicalParameters

Vectorized grouped H-fit for many objects in one pass.

Parameters:

• detections – Point-source detections for all groups.

• exposures – Exposure table referenced by detections.exposure_id.

• object_coords – Object coordinates aligned 1:1 with detections.

• object_ids – Group label for each detection row (same length as detections).

Returns:

One row per object_id with nested physical parameters and fit row counts.

Return type:

GroupedPhysicalParameters

class adam_core.photometry.GroupedPhysicalParameters(table: Table, **kwargs: int | float | str)

Bases: Table

n_fit_detections

A column for storing 64-bit integers.

object_id

A column for storing large strings (over 2<sup>31</sup> bytes long). Large string data is stored in variable-length chunks.

physical_parameters

A column which represents an embedded quivr table.

Parameters:

• table_type – The type of the table to embed.

• nullable – Whether the column can contain null values.

• metadata – A dictionary of metadata to attach to the column.

schema: ClassVar[pa.Schema] = object_id: large_string not null physical_parameters: struct<H_v: double, H_v_sigma: double, G: double, G_sigma: double, sigma_eff: double, chi2_red: doub (... 3 chars omitted)   child 0, H_v: double   child 1, H_v_sigma: double   child 2, G: double   child 3, G_sigma: double   child 4, sigma_eff: double   child 5, chi2_red: double n_fit_detections: int64 not null

Subpackages

• adam_core.photometry.bandpasses package
  • BandpassCurves
    • BandpassCurves.band
    • BandpassCurves.filter_id
    • BandpassCurves.instrument
    • BandpassCurves.schema
    • BandpassCurves.source
    • BandpassCurves.throughput
    • BandpassCurves.wavelength_nm
  • ObservatoryBandMap
    • ObservatoryBandMap.filter_id
    • ObservatoryBandMap.key
    • ObservatoryBandMap.observatory_code
    • ObservatoryBandMap.reported_band
    • ObservatoryBandMap.schema
  • AsteroidTemplates
    • AsteroidTemplates.citation
    • AsteroidTemplates.reflectance
    • AsteroidTemplates.schema
    • AsteroidTemplates.template_id
    • AsteroidTemplates.wavelength_nm
    • AsteroidTemplates.weight_C
    • AsteroidTemplates.weight_S
  • TemplateBandpassIntegrals
    • TemplateBandpassIntegrals.filter_id
    • TemplateBandpassIntegrals.integral_photon
    • TemplateBandpassIntegrals.schema
    • TemplateBandpassIntegrals.template_id
  • load_bandpass_curves()
  • load_observatory_band_map()
  • load_asteroid_templates()
  • load_template_integrals()
  • map_to_canonical_filter_bands()
  • assert_filter_ids_have_curves()
  • get_integrals()
  • compute_mix_integrals()
  • bandpass_delta_mag()
  • bandpass_color_terms()
  • register_custom_template()
  • Submodules
    • adam_core.photometry.bandpasses.api module
      • load_bandpass_curves()
      • load_observatory_band_map()
      • load_asteroid_templates()
      • load_template_integrals()
      • map_to_canonical_filter_bands()
      • assert_filter_ids_have_curves()
      • get_integrals()
      • compute_mix_integrals()
      • bandpass_delta_mag()
      • bandpass_color_terms()
      • register_custom_template()
    • adam_core.photometry.bandpasses.constants module
      • TemplateSpec
    • adam_core.photometry.bandpasses.tables module
      • BandpassCurves
      • ObservatoryBandMap
      • AsteroidTemplates
      • TemplateBandpassIntegrals
    • adam_core.photometry.bandpasses.vendor module
      • build_bandpass_curves()
      • build_observatory_band_map()
      • build_asteroid_templates()
      • build_solar_spectrum()
      • build_template_bandpass_integrals()

Submodules

• adam_core.photometry.absolute_magnitude module
  • GroupedPhysicalParameters
    • GroupedPhysicalParameters.object_id
    • GroupedPhysicalParameters.physical_parameters
    • GroupedPhysicalParameters.n_fit_detections
    • GroupedPhysicalParameters.schema
    • GroupedPhysicalParameters.table
  • estimate_absolute_magnitude_v_from_detections()
  • estimate_absolute_magnitude_v_from_detections_grouped()
• adam_core.photometry.magnitude module
  • calculate_phase_angle()
  • convert_magnitude()
  • calculate_apparent_magnitude_v()
  • calculate_apparent_magnitude_v_and_phase_angle()
  • predict_magnitudes()
• adam_core.photometry.magnitude_common module
  • bandpass_filter_id_table()
  • bandpass_integrals_for_composition()
  • bandpass_composition_key()
  • bandpass_delta_table_for_composition_cached()
  • bandpass_delta_table_jax_for_composition_cached()
  • bandpass_delta_table_for_composition()