argos.core.catalog

Star catalogue access for photometry and solved-field identification.

Qt-free clients for the two AAVSO services this app cares about:

• VSX (Variable Star indeX) — where the variable stars are in a field.

• VSP (Variable Star Plotter) — which comparison stars are available, with calibrated magnitudes, for photometry of a target.

• Gaia DR3 — stable source identifiers for ordinary stars in a solved field.

The UI solves a frame (argos.core.imaging.platesolve), gets a FrameWCS, then queries these by the field centre + radius and projects the results back onto the image.

class argos.core.catalog.Band(band: str, mag: float, error: float | None = None)

Bases: object

One photometric band of a comparison star.

band: str

error: float | None = None

mag: float

class argos.core.catalog.CachedExoplanetHost(host_name: str, ra_degrees: float, dec_degrees: float, planet_names: tuple[str, ...], mags: tuple[tuple[str, float], ...] = ())

Bases: object

A host star represented by an already cached transit ephemeris.

This deliberately has no online fallback. It lets a solved image show previously prepared exoplanet systems while keeping field enrichment an explicit, privacy-respecting action.

dec_degrees: float

host_name: str

mags: tuple[tuple[str, float], ...] = ()

planet_names: tuple[str, ...]

ra_degrees: float

exception argos.core.catalog.CatalogError

Bases: RuntimeError

A catalog query failed (network, HTTP, or unparseable response).

class argos.core.catalog.ComparisonQuality(snr: float, inst_mag: float | None, saturated: bool = False, suspect: bool = False)

Bases: object

A candidate’s quality measured on the current pilot frame.

Catalogue magnitudes say whether a star is calibrated; they do not say whether it is measurable through the current filter, focus and sky. AcquisitionEngine supplies these values after plate-solving a real frame, while this module remains UI- and hardware-free.

inst_mag: float | None

saturated: bool = False

snr: float

suspect: bool = False

class argos.core.catalog.ComparisonStar(auid: str, ra_deg: float, dec_deg: float, label: str, bands: tuple[Band, ...] = (), comments: str | None = None)

Bases: object

One VSP comparison star. ra_deg/dec_deg are J2000 decimal degrees.

auid: str

bands: tuple[Band, ...] = ()

comments: str | None = None

dec_deg: float

label: str

mag(band: str = 'V') → float | None

Magnitude in band if measured, else None.

ra_deg: float

exception argos.core.catalog.FieldObjectLookupError

Bases: RuntimeError

A named-object field lookup could not be completed.

class argos.core.catalog.GaiaStar(source_id: str, ra_deg: float, dec_deg: float, g_mag: float | None = None, bp_mag: float | None = None, rp_mag: float | None = None)

Bases: object

A Gaia DR3 source projected onto a solved field.

bp_mag: float | None = None

dec_deg: float

property display_name: str

g_mag: float | None = None

ra_deg: float

rp_mag: float | None = None

source_id: str

class argos.core.catalog.NamedFieldObject(name: str, ra_deg: float, dec_deg: float, object_type: str = '', source: str = 'SIMBAD', mags: tuple[tuple[str, float], ...] = ())

Bases: object

One SIMBAD object with a stable identity in a solved image.

dec_deg: float

mags: tuple[tuple[str, float], ...] = ()

name: str

object_type: str = ''

ra_deg: float

source: str = 'SIMBAD'

exception argos.core.catalog.PointIdentityLookupError

Bases: RuntimeError

Neither selected catalogue could answer a point-identification query.

class argos.core.catalog.PointSourceIdentity(name: str, ra_deg: float, dec_deg: float, object_type: str = '', source: str = '', mags: tuple[tuple[str, float], ...] = (), separation_arcsec: float = 0.0, gaia_source_id: str | None = None)

Bases: object

A catalogue identity matched to one clicked image centroid.

dec_deg: float

gaia_source_id: str | None = None

mags: tuple[tuple[str, float], ...] = ()

name: str

object_type: str = ''

ra_deg: float

separation_arcsec: float = 0.0

source: str = ''

class argos.core.catalog.ScoredComparison(star: ComparisonStar, separation_arcmin: float, delta_mag: float | None)

Bases: object

A comparison star scored against a target.

delta_mag: float | None

separation_arcmin: float

star: ComparisonStar

class argos.core.catalog.VariableStar(name: str, ra_deg: float, dec_deg: float, auid: str | None = None, var_type: str | None = None, category: str | None = None, max_mag: str | None = None, min_mag: str | None = None, period: float | None = None, constellation: str | None = None, oid: str | None = None)

Bases: object

One VSX entry. ra_deg/dec_deg are J2000 decimal degrees.

auid: str | None = None

property brightest_mag: float | None

Numeric part of max_mag (the brightest magnitude), band ignored.

VSX strings look like "13.5 B", "<14.5", "16.1 V". Used to sort/cut a field down to what a frame could actually show.

category: str | None = None

constellation: str | None = None

dec_deg: float

property is_suspected: bool

max_mag: str | None = None

min_mag: str | None = None

name: str

oid: str | None = None

period: float | None = None

ra_deg: float

var_type: str | None = None

argos.core.catalog.auto_comparison_stars(target_ra_deg: float, target_dec_deg: float, comparisons: list[ComparisonStar], *, wcs=None, green_shape: tuple[int, int] | None = None, count: int = 5, candidate_quality: Mapping[str, ComparisonQuality] | None = None, target_inst_mag: float | None = None, min_snr: float = 0.0, max_delta_inst_mag: float | None = None, max_separation_arcmin: float | None = None) → list[TargetStar]

The count best comparisons for a target, as ready-to-save TargetStars.

Closest-first via rank_comparisons(). Stars outside the current frame are dropped when wcs + green_shape are given — an off-frame comparison can never be measured, and it would poison the aperture tracker’s anchor set.

argos.core.catalog.cached_exoplanet_hosts_in_cone(ra_degrees: float, dec_degrees: float, radius_deg: float, *, cache_path: Path | None = None) → list[CachedExoplanetHost]

Return unique cached transiting-planet hosts inside a solved field.

The small local ephemeris cache is not a complete planet catalogue. This function therefore never claims that an empty result means there are no exoplanets in the field; it only exposes objects the observer has already downloaded or prepared.

argos.core.catalog.comparisons_for_variable(variable: VariableStar, comparisons: list[ComparisonStar], *, band: str = 'V', mag_tol: float | None = None, max_results: int | None = None) → list[ScoredComparison]

rank_comparisons() for a VariableStar, using its brightest magnitude as the reference for the (optional) magnitude-similarity filter.

argos.core.catalog.exoplanet_hosts_in_cone(ra_degrees: float, dec_degrees: float, radius_deg: float, *, allow_network: bool = True, timeout_s: float = 15.0, session=None) → list[CachedExoplanetHost]

Find confirmed exoplanet hosts in a solved field, with local caching.

A field lookup uses NASA’s pscomppars table and groups its one-row-per- planet results by host. It is intentionally separate from lookup_exoplanet(): a field inspection should tell the observer what is there, while a prepared target needs a full transit ephemeris.

argos.core.catalog.gaia_cone_search(ra_deg: float, dec_deg: float, radius_deg: float, *, mag_limit: float = 13.5, max_results: int = 200, allow_network: bool = True, timeout_s: float = 20.0, session: Any = None) → list[GaiaStar]

Return the brightest Gaia DR3 sources in a field cone.

Values are validated before being interpolated in ADQL, and only four columns are requested from Gaia DR3 to keep the response compact.

argos.core.catalog.identify_point_source(ra_deg: float, dec_deg: float, *, radius_arcsec: float = 10.0, gaia_mag_limit: float = 21.0, use_gaia: bool = True, use_simbad: bool = True, allow_gaia_network: bool = True, allow_simbad_network: bool = True) → PointSourceIdentity | None

Identify the nearest catalogue source to one WCS coordinate.

Gaia owns the returned position whenever it has a match. A SIMBAD name or physical type is attached only when its position is within 3 arcsec of the Gaia source. This prevents a nearby radio/X-ray object in a crowded field from donating its name to the clicked star.

argos.core.catalog.rank_comparisons(target_ra_deg: float, target_dec_deg: float, comparisons: list[ComparisonStar], *, target_mag: float | None = None, band: str = 'V', mag_tol: float | None = None, max_results: int | None = None) → list[ScoredComparison]

Rank comparisons for photometry of a target, closest first.

target_mag + mag_tol (if both given) drops comparisons whose band magnitude differs from the target by more than mag_tol (and any lacking that band, since they can’t be judged). max_results caps the list.

argos.core.catalog.separation_arcmin(ra1_deg: float, dec1_deg: float, ra2_deg: float, dec2_deg: float) → float

Great-circle separation between two J2000 points, in arcminutes.

argos.core.catalog.simbad_field_objects(ra_deg: float, dec_deg: float, radius_deg: float, *, max_results: int = 500, allow_network: bool = True, include_ordinary_stars: bool = False, timeout_s: float = 15.0, session: Any = None) → list[NamedFieldObject]

Return named SIMBAD objects in a cone, preferring its local cache.

SIMBAD is not a complete stellar catalogue: Gaia remains the layer for all sources. This result supplies conventional identifiers and object types where SIMBAD has an entry.

argos.core.catalog.vsp_chart(ra_deg: float, dec_deg: float, fov_arcmin: float, *, maglimit: float = 16.0, target_name: str | None = None, timeout: float = 20.0, session: Any = None) → list[ComparisonStar]

Comparison stars from a VSP photometry chart.

target_name asks VSP for the comparison sequence of a known variable target, rather than a generic chart around its coordinates. This matters when the mount is offset from the requested target: VSX still describes the actually imaged field, while VSP must retain the observer’s selected scientific target to return its calibrated sequence.

argos.core.catalog.vsx_cone_search(ra_deg: float, dec_deg: float, radius_deg: float, *, include_suspected: bool = True, mag_limit: float | None = None, max_results: int | None = None, timeout: float = 20.0, session: Any = None) → list[VariableStar]

Variable stars within radius_deg of (ra_deg, dec_deg), J2000.

mag_limit keeps only stars at least that bright (a dense field like M42 has >1500 faint variables; a frame shows few). max_results caps the count, keeping the brightest. Results are returned brightest-first.

Modules

Embedded catalogue search used when Argos is away from the internet.

The essential catalogue is deliberately small and immutable: Messier, NGC and IC identifiers with positions, type, magnitude where available and common aliases. It supports target naming and a first GoTo; it does not pretend to be a precision astrometric or stellar-photometry catalogue.

class argos.core.catalog.offline.OfflineCatalogueObject(name: str, aliases: tuple[str, ...], ra_degrees: float, dec_degrees: float, object_type: str = '', magnitude: float | None = None)

Bases: object

One name-resolvable entry from the bundled essential catalogue.

aliases: tuple[str, ...]

dec_degrees: float

magnitude: float | None = None

name: str

object_type: str = ''

ra_degrees: float

argos.core.catalog.offline.essential_catalogue_info() → dict[str, str | int]

Public version/provenance summary for the Settings panel and support bundle.

argos.core.catalog.offline.essential_catalogue_objects() → tuple[OfflineCatalogueObject, ...]

Return the immutable bundled records for coordinate-near matching.

argos.core.catalog.offline.essential_catalogue_suggestions(query: str, *, limit: int = 8) → list[str]

Return user-facing aliases (M 42 before NGC 1976) for completion.

argos.core.catalog.offline.normalise_catalogue_query(value: str) → str

Case/space/punctuation-insensitive key for common target designations.

argos.core.catalog.offline.resolve_essential_object(query: str) → OfflineCatalogueObject | None

Resolve an exact bundled designation, never guessing a prefix.

argos.core.catalog.offline.search_essential_catalogue(query: str, *, limit: int = 8) → list[OfflineCatalogueObject]

Find matching bundled targets, with exact aliases before prefix matches.

AAVSO VSX + VSP HTTP clients (Qt-free, network-isolated).

Two public calls, both cone/field queries around a solved field centre:

• vsx_cone_search() → VariableStar list (the variables).

• vsp_chart() → ComparisonStar list (the comparison stars).

Network/parse failures raise CatalogError with a human message; the worker turns that into a status line instead of crashing the UI. Coordinates are normalised to decimal degrees (J2000) on the way out — VSX already returns degrees, VSP returns sexagesimal, so both are handled here, once.

Offline cache. Every successful response is cached on disk (~/.argos/cache/catalog); a fresh entry short-circuits the network, and a stale one is served when the network is down — so a field previously observed (or pre-fetched at home) keeps its variables/comparisons with no internet in the field (docsrc/field_connectivity.md). Query coordinates are quantised to a small grid so re-solves of the same field land on the same cache entry; the cone radius is padded by the worst-case quantisation shift to compensate.

class argos.core.catalog.aavso.Band(band: str, mag: float, error: float | None = None)

Bases: object

One photometric band of a comparison star.

band: str

error: float | None = None

mag: float

exception argos.core.catalog.aavso.CatalogError

Bases: RuntimeError

A catalog query failed (network, HTTP, or unparseable response).

class argos.core.catalog.aavso.ComparisonStar(auid: str, ra_deg: float, dec_deg: float, label: str, bands: tuple[Band, ...] = (), comments: str | None = None)

Bases: object

One VSP comparison star. ra_deg/dec_deg are J2000 decimal degrees.

auid: str

bands: tuple[Band, ...] = ()

comments: str | None = None

dec_deg: float

label: str

mag(band: str = 'V') → float | None

Magnitude in band if measured, else None.

ra_deg: float

class argos.core.catalog.aavso.VariableStar(name: str, ra_deg: float, dec_deg: float, auid: str | None = None, var_type: str | None = None, category: str | None = None, max_mag: str | None = None, min_mag: str | None = None, period: float | None = None, constellation: str | None = None, oid: str | None = None)

Bases: object

One VSX entry. ra_deg/dec_deg are J2000 decimal degrees.

auid: str | None = None

property brightest_mag: float | None

Numeric part of max_mag (the brightest magnitude), band ignored.

VSX strings look like "13.5 B", "<14.5", "16.1 V". Used to sort/cut a field down to what a frame could actually show.

category: str | None = None

constellation: str | None = None

dec_deg: float

property is_suspected: bool

max_mag: str | None = None

min_mag: str | None = None

name: str

oid: str | None = None

period: float | None = None

ra_deg: float

var_type: str | None = None

argos.core.catalog.aavso.configure_cache_directory(path: Path | str) → None

Set the persistent VSX/VSP field-cache folder for future queries.

argos.core.catalog.aavso.vsp_chart(ra_deg: float, dec_deg: float, fov_arcmin: float, *, maglimit: float = 16.0, target_name: str | None = None, timeout: float = 20.0, session: Any = None) → list[ComparisonStar]

Comparison stars from a VSP photometry chart.

target_name asks VSP for the comparison sequence of a known variable target, rather than a generic chart around its coordinates. This matters when the mount is offset from the requested target: VSX still describes the actually imaged field, while VSP must retain the observer’s selected scientific target to return its calibrated sequence.

argos.core.catalog.aavso.vsx_cone_search(ra_deg: float, dec_deg: float, radius_deg: float, *, include_suspected: bool = True, mag_limit: float | None = None, max_results: int | None = None, timeout: float = 20.0, session: Any = None) → list[VariableStar]

Variable stars within radius_deg of (ra_deg, dec_deg), J2000.

mag_limit keeps only stars at least that bright (a dense field like M42 has >1500 faint variables; a frame shows few). max_results caps the count, keeping the brightest. Results are returned brightest-first.

Comparison-star selection for differential photometry (Qt-free).

Given a variable star (the target) and the field’s VSP comparison stars, rank the comparisons for photometry of that target. The standard differential-photometry criteria are: comparisons close to the target (same region of the chip, same airmass/vignetting) and of similar brightness. VSP already guarantees they are non-variable and calibrated, so this module just scores + orders them.

class argos.core.catalog.photometry.ComparisonQuality(snr: float, inst_mag: float | None, saturated: bool = False, suspect: bool = False)

Bases: object

A candidate’s quality measured on the current pilot frame.

Catalogue magnitudes say whether a star is calibrated; they do not say whether it is measurable through the current filter, focus and sky. AcquisitionEngine supplies these values after plate-solving a real frame, while this module remains UI- and hardware-free.

inst_mag: float | None

saturated: bool = False

snr: float

suspect: bool = False

class argos.core.catalog.photometry.ScoredComparison(star: ComparisonStar, separation_arcmin: float, delta_mag: float | None)

Bases: object

A comparison star scored against a target.

delta_mag: float | None

separation_arcmin: float

star: ComparisonStar

argos.core.catalog.photometry.auto_comparison_stars(target_ra_deg: float, target_dec_deg: float, comparisons: list[ComparisonStar], *, wcs=None, green_shape: tuple[int, int] | None = None, count: int = 5, candidate_quality: Mapping[str, ComparisonQuality] | None = None, target_inst_mag: float | None = None, min_snr: float = 0.0, max_delta_inst_mag: float | None = None, max_separation_arcmin: float | None = None) → list[TargetStar]

The count best comparisons for a target, as ready-to-save TargetStars.

Closest-first via rank_comparisons(). Stars outside the current frame are dropped when wcs + green_shape are given — an off-frame comparison can never be measured, and it would poison the aperture tracker’s anchor set.

argos.core.catalog.photometry.comparisons_for_variable(variable: VariableStar, comparisons: list[ComparisonStar], *, band: str = 'V', mag_tol: float | None = None, max_results: int | None = None) → list[ScoredComparison]

rank_comparisons() for a VariableStar, using its brightest magnitude as the reference for the (optional) magnitude-similarity filter.

argos.core.catalog.photometry.rank_comparisons(target_ra_deg: float, target_dec_deg: float, comparisons: list[ComparisonStar], *, target_mag: float | None = None, band: str = 'V', mag_tol: float | None = None, max_results: int | None = None) → list[ScoredComparison]

Rank comparisons for photometry of a target, closest first.

target_mag + mag_tol (if both given) drops comparisons whose band magnitude differs from the target by more than mag_tol (and any lacking that band, since they can’t be judged). max_results caps the list.

argos.core.catalog.photometry.separation_arcmin(ra1_deg: float, dec1_deg: float, ra2_deg: float, dec2_deg: float) → float

Great-circle separation between two J2000 points, in arcminutes.

Persistent target / comparison set for a session (notes/photometry_plan.md §5 B4).

Qt-free. The set is the night’s selection: the variable target(s), the comparison stars, and any check stars, each with RA/Dec + catalog id so they can be projected onto every solved frame and (later) aperture-measured. Persisted as targets.json (atomic write, mirrors session_log) so it survives restarts.

class argos.core.catalog.targets.TargetSet(object_name: str = '', stars: list[TargetStar] = <factory>)

Bases: object

The session’s selected stars; load/save targets.json.

append_selection_history(path, *, generated_by: str = 'Argos') → None

Append one immutable selection snapshot to a session JSONL history.

by_role(role: str) → list[TargetStar]

classmethod from_dict(d: dict) → TargetSet

classmethod load(path) → TargetSet

Load targets.json; return an empty set if missing/unreadable.

object_name: str = ''

remove(key: str) → None

save(path) → None

Atomically write targets.json (temp + os.replace).

save_selection_manifest(path, *, generated_by: str = 'Argos') → None

Atomically write the session photometry selection hand-off.

selection_manifest(*, generated_by: str = 'Argos') → dict

Return the explicit, auditable target/comparison hand-off.

targets.json is mutable application state. This separate manifest records the exact selection active during acquisition. It is deliberately labelled as a live-preview selection: final calibrated validation belongs to registered frames in Siril / star_var_script.

set_role(star: TargetStar) → None

Add star or replace the existing one with the same identity.

stars: list[TargetStar]

summary() → dict

A display/readiness summary of the selection (Qt-free).

Differential photometry needs at least one target (T1) and one comparison; a check star is recommended but optional. complete captures that minimum so the UI can tell the user what is missing.

to_dict() → dict

class argos.core.catalog.targets.TargetStar(role: str, ra_deg: float, dec_deg: float, auid: str | None = None, name: str | None = None, source: str = 'manual', mags: dict = <factory>, note: str = '')

Bases: object

One selected star, identified by AUID when known else by position.

auid: str | None = None

dec_deg: float

property display_name: str

key() → str

Stable identity used to dedup/update (AUID, else rounded position).

mags: dict

name: str | None = None

note: str = ''

ra_deg: float

role: str

source: str = 'manual'

Resolve astronomical object designations to ICRS coordinates.

Argos first searches its embedded Messier/NGC/IC catalogue, then the local CDS cache, and finally CDS Sesame for broader designations such as HD/HIP or free-text names. Successful online lookups are cached locally, so a target used during preparation remains available at the telescope without a network connection.

The module is Qt-free. Call it from argos.workers.object_resolver_worker when used by the UI.

class argos.core.catalog.object_resolver.NearbyObject(object: ResolvedObject, separation_arcsec: float)

Bases: object

A catalogue candidate near a requested ICRS coordinate.

object: ResolvedObject

separation_arcsec: float

exception argos.core.catalog.object_resolver.ObjectResolutionError

Bases: RuntimeError

The designation could not be resolved to an astronomical position.

class argos.core.catalog.object_resolver.ResolvedObject(name: str, ra_degrees: float, dec_degrees: float, object_type: str = '', source: str = 'CDS Sesame')

Bases: object

One coordinate-bearing catalogue object in ICRS/J2000.

dec_degrees: float

name: str

object_type: str = ''

ra_degrees: float

property ra_hours: float

source: str = 'CDS Sesame'

argos.core.catalog.object_resolver.cached_object_suggestions(query: str, *, cache_path: Path | None = None, limit: int = 8) → list[str]

Return offline autocomplete candidates from prior CDS resolutions.

argos.core.catalog.object_resolver.configure_cache_path(path: Path | str) → None

Set the persistent CDS/SIMBAD cache location for future lookups.

argos.core.catalog.object_resolver.display_designation(name: str, *, fallback: str = '') → str

Return a human/FITS-ready catalogue designation.

SIMBAD commonly prefixes the primary identifier of a variable star with V* (for example V* XX Cyg). That prefix is an object type, not part of the star’s designation; retaining it made Argos look as if it had resolved a different object and produced needlessly awkward FITS OBJECT values. Keep the type separately in ResolvedObject.object_type and present the conventional designation everywhere else.

fallback is deliberately normalised too, so an older cached result is repaired as soon as it is read.

argos.core.catalog.object_resolver.is_variable_object_type(object_type: str) → bool

Whether a SIMBAD object type denotes a photometric variable star.

argos.core.catalog.object_resolver.nearby_cached_objects(ra_degrees: float, dec_degrees: float, *, radius_arcsec: float = 90.0, cache_path: Path | None = None) → list[NearbyObject]

Return cached catalogue objects around a coordinate, nearest first.

argos.core.catalog.object_resolver.nearby_essential_objects(ra_degrees: float, dec_degrees: float, *, radius_arcsec: float = 90.0) → list[NearbyObject]

Find bundled Messier/NGC/IC entries around a Stellarium coordinate.

argos.core.catalog.object_resolver.normalize_designation(query: str) → str

Normalise common compact stellar/deep-sky designations for Sesame.

argos.core.catalog.object_resolver.object_type_label(object_type: str) → str

Expand terse catalogue type codes for an observer-facing interface.

argos.core.catalog.object_resolver.resolve_nearby_objects(ra_degrees: float, dec_degrees: float, *, radius_arcsec: float = 90.0, allow_network: bool = True, timeout_s: float = 8.0, cache_path: Path | None = None) → list[NearbyObject]

Find names near a Stellarium target, preferring the local cache.

The caller must show the returned candidates and let the observer choose. A coordinate is not a unique object designation, particularly in a dense stellar field. If online lookup was not explicitly allowed, this is a strictly offline cache lookup.

argos.core.catalog.object_resolver.resolve_object(query: str, *, timeout_s: float = 8.0, cache_path: Path | None = None) → ResolvedObject

Resolve a catalogue designation, preferring a prior local result.

Raises ObjectResolutionError for an empty, unknown or temporarily unavailable designation. Coordinates are J2000/ICRS decimal degrees.

Exoplanet ephemerides from the NASA Exoplanet Archive.

Argos uses this catalogue only to prepare an observing run. The download is explicitly requested by the observer and successful results are cached locally so a prepared target remains usable away from the internet. Transit fitting and the science-grade light curve remain post-processing work.

class argos.core.catalog.exoplanets.CachedExoplanetHost(host_name: str, ra_degrees: float, dec_degrees: float, planet_names: tuple[str, ...], mags: tuple[tuple[str, float], ...] = ())

Bases: object

A host star represented by an already cached transit ephemeris.

This deliberately has no online fallback. It lets a solved image show previously prepared exoplanet systems while keeping field enrichment an explicit, privacy-respecting action.

dec_degrees: float

host_name: str

mags: tuple[tuple[str, float], ...] = ()

planet_names: tuple[str, ...]

ra_degrees: float

exception argos.core.catalog.exoplanets.ExoplanetLookupError

Bases: RuntimeError

The requested planet has no usable published transit ephemeris.

class argos.core.catalog.exoplanets.ExoplanetTarget(planet_name: str, host_name: str, ra_degrees: float, dec_degrees: float, period_days: float, epoch_bjd_tdb: float, duration_hours: float | None = None, depth_percent: float | None = None, period_error_days: float | None = None, epoch_error_days: float | None = None, epoch_system: str = 'BJD_TDB', source: str = 'NASA Exoplanet Archive / PSCompPars', retrieved_utc: str = '')

Bases: object

Published host-star coordinates and a transit ephemeris.

epoch_bjd_tdb is deliberately retained in BJD_TDB: silently treating a published HJD/UTC epoch as BJD_TDB can shift a predicted transit by minutes. The source table’s time-system reference is shown to the user before an acquisition plan is generated.

dec_degrees: float

depth_percent: float | None = None

duration_hours: float | None = None

epoch_bjd_tdb: float

epoch_error_days: float | None = None

epoch_system: str = 'BJD_TDB'

host_name: str

period_days: float

period_error_days: float | None = None

planet_name: str

ra_degrees: float

property ra_hours: float

retrieved_utc: str = ''

source: str = 'NASA Exoplanet Archive / PSCompPars'

argos.core.catalog.exoplanets.cached_exoplanet_hosts_in_cone(ra_degrees: float, dec_degrees: float, radius_deg: float, *, cache_path: Path | None = None) → list[CachedExoplanetHost]

Return unique cached transiting-planet hosts inside a solved field.

The small local ephemeris cache is not a complete planet catalogue. This function therefore never claims that an empty result means there are no exoplanets in the field; it only exposes objects the observer has already downloaded or prepared.

argos.core.catalog.exoplanets.cached_exoplanet_suggestions(query: str, *, cache_path: Path | None = None, limit: int = 8) → list[str]

Return offline autocomplete candidates from previously fetched planets.

argos.core.catalog.exoplanets.configure_cache_path(path: Path | str) → None

Set the persistent NASA ephemeris cache location for future lookups.

argos.core.catalog.exoplanets.configure_field_cache_directory(path: Path | str) → None

Set the cache folder used by NASA solved-field host queries.

argos.core.catalog.exoplanets.exoplanet_hosts_in_cone(ra_degrees: float, dec_degrees: float, radius_deg: float, *, allow_network: bool = True, timeout_s: float = 15.0, session=None) → list[CachedExoplanetHost]

Find confirmed exoplanet hosts in a solved field, with local caching.

A field lookup uses NASA’s pscomppars table and groups its one-row-per- planet results by host. It is intentionally separate from lookup_exoplanet(): a field inspection should tell the observer what is there, while a prepared target needs a full transit ephemeris.

argos.core.catalog.exoplanets.lookup_exoplanet(query: str, *, timeout_s: float = 12.0, cache_path: Path | None = None) → ExoplanetTarget

Fetch a confirmed planet’s ephemeris from NASA’s pscomppars table.

The query intentionally asks for only the columns Argos shows and stores. A cached exact name is preferred; clearing the local cache is the explicit way to refresh a previously prepared target.

argos.core.catalog.exoplanets.normalize_exoplanet_designation(query: str) → str

Accept common compact/case-insensitive planet designations.

hd189733b, HD 189733 B and hd 189733 b all become HD 189733 b. Other designations retain their internal spelling while whitespace is made predictable for the archive and local cache.

Cache-backed SIMBAD field identification for a solved Argos frame.

Gaia identifies sources but most Gaia IDs do not have a human-facing stellar name. SIMBAD is the complementary identifier and object-type service. A field query is intentionally bounded and cached: it is made when the observer asks Argos to identify a field, never for telemetry or background tracking.

exception argos.core.catalog.field_objects.FieldObjectLookupError

Bases: RuntimeError

A named-object field lookup could not be completed.

class argos.core.catalog.field_objects.NamedFieldObject(name: str, ra_deg: float, dec_deg: float, object_type: str = '', source: str = 'SIMBAD', mags: tuple[tuple[str, float], ...] = ())

Bases: object

One SIMBAD object with a stable identity in a solved image.

dec_deg: float

mags: tuple[tuple[str, float], ...] = ()

name: str

object_type: str = ''

ra_deg: float

source: str = 'SIMBAD'

argos.core.catalog.field_objects.configure_cache_directory(path: Path | str) → None

Set the folder used for cached SIMBAD field responses.

argos.core.catalog.field_objects.simbad_field_objects(ra_deg: float, dec_deg: float, radius_deg: float, *, max_results: int = 500, allow_network: bool = True, include_ordinary_stars: bool = False, timeout_s: float = 15.0, session: Any = None) → list[NamedFieldObject]

Return named SIMBAD objects in a cone, preferring its local cache.

SIMBAD is not a complete stellar catalogue: Gaia remains the layer for all sources. This result supplies conventional identifiers and object types where SIMBAD has an entry.

Small, cache-backed Gaia DR3 field-star queries for solved Argos frames.

Gaia is used here for identification and navigation only: it supplies a stable source identifier, position and G magnitude for stars visible in the solved field. It does not replace AAVSO VSP calibrated comparison sequences. The query is intentionally narrow (position, magnitude and a row cap) and its CSV response is cached locally for offline re-use.

class argos.core.catalog.gaia.GaiaStar(source_id: str, ra_deg: float, dec_deg: float, g_mag: float | None = None, bp_mag: float | None = None, rp_mag: float | None = None)

Bases: object

A Gaia DR3 source projected onto a solved field.

bp_mag: float | None = None

dec_deg: float

property display_name: str

g_mag: float | None = None

ra_deg: float

rp_mag: float | None = None

source_id: str

argos.core.catalog.gaia.configure_cache_directory(path: Path | str) → None

Set the local directory used for Gaia field-query responses.

argos.core.catalog.gaia.gaia_cone_search(ra_deg: float, dec_deg: float, radius_deg: float, *, mag_limit: float = 13.5, max_results: int = 200, allow_network: bool = True, timeout_s: float = 20.0, session: Any = None) → list[GaiaStar]

Return the brightest Gaia DR3 sources in a field cone.

Values are validated before being interpolated in ADQL, and only four columns are requested from Gaia DR3 to keep the response compact.

On-demand catalogue identity for one clicked source in a solved frame.

Whole-field queries are deliberately budgeted. This module provides the complementary precise operation: query a very small cone around a measured image centroid, use Gaia as the astrometric source of truth, and enrich it with SIMBAD only when both positions describe the same physical source.

exception argos.core.catalog.point_identity.PointIdentityLookupError

Bases: RuntimeError

Neither selected catalogue could answer a point-identification query.

class argos.core.catalog.point_identity.PointSourceIdentity(name: str, ra_deg: float, dec_deg: float, object_type: str = '', source: str = '', mags: tuple[tuple[str, float], ...] = (), separation_arcsec: float = 0.0, gaia_source_id: str | None = None)

Bases: object

A catalogue identity matched to one clicked image centroid.

dec_deg: float

gaia_source_id: str | None = None

mags: tuple[tuple[str, float], ...] = ()

name: str

object_type: str = ''

ra_deg: float

separation_arcsec: float = 0.0

source: str = ''

argos.core.catalog.point_identity.identify_point_source(ra_deg: float, dec_deg: float, *, radius_arcsec: float = 10.0, gaia_mag_limit: float = 21.0, use_gaia: bool = True, use_simbad: bool = True, allow_gaia_network: bool = True, allow_simbad_network: bool = True) → PointSourceIdentity | None

Identify the nearest catalogue source to one WCS coordinate.

Gaia owns the returned position whenever it has a match. A SIMBAD name or physical type is attached only when its position is within 3 arcsec of the Gaia source. This prevents a nearby radio/X-ray object in a crowded field from donating its name to the clicked star.