tessl/pypi-astropy
Astronomy and astrophysics core library providing comprehensive tools for astronomical computations and data handling
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
coordinates.mddocs/
Coordinate Systems
Comprehensive celestial coordinate system framework with transformations between reference frames, sky coordinate matching, and integration with observational astronomy.
Core Imports
from astropy.coordinates import SkyCoord
from astropy.coordinates import ICRS, Galactic, FK5, AltAz
from astropy.coordinates import EarthLocation
from astropy.coordinates import get_body, get_sun, get_moon
from astropy.coordinates import match_coordinates_sky, search_around_skyCapabilities
High-Level Sky Coordinates
High-level interface for celestial coordinates with automatic frame transformations, coordinate matching, and observational astronomy integration.
class SkyCoord:
"""
High-level representation of celestial coordinates.
Parameters:
- *args: coordinate values (ra, dec) or (lon, lat) etc.
- frame: coordinate frame (ICRS, Galactic, etc.)
- unit: units for coordinates
- **kwargs: frame-specific attributes
"""
def __init__(self, *args, frame=None, unit=None, **kwargs): ...
def transform_to(self, frame):
"""
Transform to another coordinate frame.
Parameters:
- frame: target frame class or instance
Returns:
SkyCoord: coordinates in new frame
"""
def match_to_catalog_sky(self, catalogcoord, nthneighbor=1):
"""
Match coordinates to catalog coordinates.
Parameters:
- catalogcoord: catalog coordinates to match against
- nthneighbor: which neighbor to find (1=closest)
Returns:
tuple: (indices, separations, distances_3d)
"""
def search_around_sky(self, searchcoord, seplimit):
"""
Search for coordinates within angular separation limit.
Parameters:
- searchcoord: coordinates to search around
- seplimit: maximum angular separation
Returns:
tuple: (indices_coords, indices_search, separations, distances_3d)
"""
def separation(self, other):
"""Angular separation to other coordinates."""
def separation_3d(self, other):
"""3D distance to other coordinates."""
def position_angle(self, other):
"""Position angle to other coordinates."""
def directional_offset_by(self, position_angle, separation):
"""Offset coordinates by position angle and separation."""
@property
def ra(self):
"""Right ascension."""
@property
def dec(self):
"""Declination."""
@property
def distance(self):
"""Distance (if available)."""
@property
def pm_ra_cosdec(self):
"""Proper motion in RA (including cos(dec) factor)."""
@property
def pm_dec(self):
"""Proper motion in declination."""
@property
def radial_velocity(self):
"""Radial velocity."""Coordinate Frames
Built-in coordinate reference frames for celestial coordinates with support for epochs, equinoxes, and observational parameters.
class BaseCoordinateFrame:
"""Base class for coordinate reference frames."""
def __init__(self, *args, **kwargs): ...
def transform_to(self, frame):
"""Transform to another frame."""
@property
def spherical(self):
"""Spherical representation."""
@property
def cartesian(self):
"""Cartesian representation."""
# Equatorial coordinate systems
class ICRS(BaseCoordinateFrame):
"""International Celestial Reference System."""
class FK5(BaseCoordinateFrame):
"""Fifth Fundamental Catalogue system."""
def __init__(self, equinox=None, obstime=None): ...
class FK4(BaseCoordinateFrame):
"""Fourth Fundamental Catalogue system."""
def __init__(self, equinox=None, obstime=None): ...
class FK4NoETerms(BaseCoordinateFrame):
"""FK4 coordinates without E-terms of aberration."""
# Galactic coordinates
class Galactic(BaseCoordinateFrame):
"""Galactic coordinate system."""
class Supergalactic(BaseCoordinateFrame):
"""Supergalactic coordinate system."""
# Horizontal coordinates
class AltAz(BaseCoordinateFrame):
"""Altitude-Azimuth coordinate system."""
def __init__(self, obstime=None, location=None, pressure=None, temperature=None): ...
# Geocentric and heliocentric systems
class Gcrs(BaseCoordinateFrame):
"""Geocentric Celestial Reference System."""
def __init__(self, obstime=None, obsgeoloc=None, obsgeovel=None): ...
class CIRS(BaseCoordinateFrame):
"""Celestial Intermediate Reference System."""
class ITRS(BaseCoordinateFrame):
"""International Terrestrial Reference System."""
class HCRS(BaseCoordinateFrame):
"""Heliocentric Celestial Reference System."""
# Local Standard of Rest frames
class LSR(BaseCoordinateFrame):
"""Local Standard of Rest frame."""
def __init__(self, v_bary=None): ...
class LSRK(BaseCoordinateFrame):
"""Kinematic Local Standard of Rest."""
class LSRD(BaseCoordinateFrame):
"""Dynamic Local Standard of Rest."""
class GalacticLSR(BaseCoordinateFrame):
"""Galactic Local Standard of Rest."""Coordinate Representations
Different mathematical representations for coordinates (spherical, cartesian, cylindrical) with conversion utilities.
class BaseRepresentation:
"""Base class for coordinate representations."""
def __init__(self): ...
def to_cartesian(self):
"""Convert to Cartesian representation."""
@classmethod
def from_cartesian(cls, cart):
"""Create from Cartesian coordinates."""
class SphericalRepresentation(BaseRepresentation):
"""
Spherical coordinates (longitude, latitude, distance).
Parameters:
- lon: longitude coordinate
- lat: latitude coordinate
- distance: radial distance (optional)
"""
def __init__(self, lon, lat, distance=None): ...
class UnitSphericalRepresentation(BaseRepresentation):
"""Unit sphere coordinates (longitude, latitude only)."""
def __init__(self, lon, lat): ...
class CartesianRepresentation(BaseRepresentation):
"""
Cartesian coordinates (x, y, z).
Parameters:
- x, y, z: Cartesian coordinate components
"""
def __init__(self, x, y, z): ...
def norm(self):
"""Magnitude of position vector."""
def dot(self, other):
"""Dot product with another vector."""
def cross(self, other):
"""Cross product with another vector."""
class CylindricalRepresentation(BaseRepresentation):
"""Cylindrical coordinates (rho, phi, z)."""
def __init__(self, rho, phi, z): ...
class PhysicsSphericalRepresentation(BaseRepresentation):
"""Physics convention spherical coordinates (r, theta, phi)."""
def __init__(self, r, theta, phi): ...
# Conversion utilities
def cartesian_to_spherical(x, y, z):
"""Convert Cartesian to spherical coordinates."""
def spherical_to_cartesian(r, lat, lon):
"""Convert spherical to Cartesian coordinates."""Angles and Angular Quantities
Specialized angle classes with parsing support, range constraints, and astronomical coordinate handling.
class Angle:
"""
General angle class with unit support and string parsing.
Parameters:
- angle: numerical value or string representation
- unit: angle unit (degree, radian, hourangle, etc.)
"""
def __init__(self, angle, unit=None): ...
def to(self, unit):
"""Convert to different angular unit."""
def wrap_at(self, wrap_angle):
"""Wrap angle to specified range."""
@property
def degree(self):
"""Angle in degrees."""
@property
def radian(self):
"""Angle in radians."""
@property
def hourangle(self):
"""Angle in hour angles (15 degrees)."""
@property
def hms(self):
"""Hours, minutes, seconds tuple."""
@property
def dms(self):
"""Degrees, minutes, seconds tuple."""
class Longitude(Angle):
"""
Longitude angle constrained to [0°, 360°).
Parameters:
- angle: longitude value
- unit: angular unit
- wrap_angle: wrapping reference angle
"""
def __init__(self, angle, unit=None, wrap_angle=None): ...
class Latitude(Angle):
"""
Latitude angle constrained to [-90°, +90°].
Parameters:
- angle: latitude value
- unit: angular unit
"""
def __init__(self, angle, unit=None): ...Distance and 3D Coordinates
Distance measurements with parallax and redshift support, enabling full 3D coordinate transformations.
class Distance:
"""
Distance measurement with unit support and astronomical conversions.
Parameters:
- distance: distance value
- unit: distance unit
- parallax: parallax angle (alternative specification)
- distmod: distance modulus (alternative specification)
- z: redshift (alternative specification, requires cosmology)
"""
def __init__(self, distance=None, unit=None, parallax=None, distmod=None, z=None): ...
def to(self, unit):
"""Convert to different distance unit."""
@property
def parallax(self):
"""Parallax angle corresponding to distance."""
@property
def distmod(self):
"""Distance modulus."""
@property
def z(self):
"""Cosmological redshift (if applicable)."""Earth Locations and Observatories
Earth location support for observational astronomy calculations including site coordinates and observatory databases.
class EarthLocation:
"""
Location on Earth's surface for astronomical observations.
Parameters:
- lat: geodetic latitude
- lon: longitude
- height: height above reference ellipsoid
- x, y, z: geocentric Cartesian coordinates (alternative)
"""
def __init__(self, lat=None, lon=None, height=None, x=None, y=None, z=None): ...
@classmethod
def from_geocentric(cls, x, y, z, unit=None):
"""Create from geocentric coordinates."""
@classmethod
def of_site(cls, site_name):
"""
Create from observatory name.
Parameters:
- site_name: name of observatory (e.g., 'Keck', 'VLT')
"""
@classmethod
def get_site_names(cls):
"""Get list of available observatory site names."""
def to_geocentric(self):
"""Convert to geocentric coordinates."""
def get_itrs(self, obstime=None):
"""Get ITRS coordinates at given time."""Solar System Objects
Functions for obtaining coordinates of solar system objects including planets, the Moon, and the Sun.
def get_body(body, time, location=None, ephemeris=None):
"""
Get coordinates of solar system body.
Parameters:
- body: name of body ('sun', 'moon', 'mercury', etc.)
- time: observation time
- location: observer location (EarthLocation)
- ephemeris: ephemeris to use ('builtin', 'de430', etc.)
Returns:
SkyCoord: coordinates of the body
"""
def get_moon(time, location=None, ephemeris=None):
"""Get Moon coordinates."""
def get_sun(time):
"""Get Sun coordinates."""
def solar_system_ephemeris():
"""Context manager for setting default ephemeris."""Coordinate Matching and Searching
Utilities for matching coordinate catalogs and searching for nearby objects with optimized algorithms.
def match_coordinates_3d(matchcoord, catalogcoord, nthneighbor=1):
"""
Match coordinates in 3D space.
Parameters:
- matchcoord: coordinates to match
- catalogcoord: catalog coordinates
- nthneighbor: which neighbor to return
Returns:
tuple: (indices, separations, distances_3d)
"""
def match_coordinates_sky(matchcoord, catalogcoord, nthneighbor=1):
"""Match coordinates on the sky (2D angular matching)."""
def search_around_3d(coords1, coords2, distlimit):
"""
Search for coordinates within 3D distance limit.
Parameters:
- coords1, coords2: coordinate arrays
- distlimit: maximum 3D distance
Returns:
tuple: (indices_1, indices_2, distances_3d)
"""
def search_around_sky(coords1, coords2, seplimit):
"""Search for coordinates within angular separation limit."""Name Resolution
Coordinate lookup by astronomical object names using online databases.
def get_icrs_coordinates(name):
"""
Resolve object name to ICRS coordinates.
Parameters:
- name: astronomical object name
Returns:
SkyCoord: ICRS coordinates of the object
"""
class NameResolveError(Exception):
"""Exception raised when name resolution fails."""Usage Examples
Basic Coordinate Creation and Transformation
from astropy.coordinates import SkyCoord
import astropy.units as u
# Create coordinates
c = SkyCoord(ra=10.625*u.degree, dec=41.2*u.degree, frame='icrs')
# Transform between frames
c_galactic = c.galactic
c_fk5 = c.transform_to('fk5')
print(f"ICRS: RA={c.ra}, Dec={c.dec}")
print(f"Galactic: l={c_galactic.l}, b={c_galactic.b}")
print(f"FK5: RA={c_fk5.ra}, Dec={c_fk5.dec}")Coordinate Arrays and Matching
import numpy as np
# Create coordinate arrays
ra = np.random.uniform(0, 360, 1000) * u.degree
dec = np.random.uniform(-90, 90, 1000) * u.degree
catalog = SkyCoord(ra=ra, dec=dec)
# Single target coordinate
target = SkyCoord(ra=180*u.degree, dec=45*u.degree)
# Find closest match
idx, sep2d, sep3d = target.match_to_catalog_sky(catalog)
closest_star = catalog[idx]
print(f"Closest star at separation: {sep2d.to(u.arcsec)}")Observational Astronomy
from astropy.coordinates import EarthLocation, AltAz, get_sun
from astropy.time import Time
# Set up observatory
location = EarthLocation.of_site('Keck')
time = Time('2023-08-15 10:00:00')
# Get Sun coordinates
sun = get_sun(time)
# Transform to horizontal coordinates
sun_altaz = sun.transform_to(AltAz(obstime=time, location=location))
print(f"Sun altitude: {sun_altaz.alt}")
print(f"Sun azimuth: {sun_altaz.az}")Proper Motion and 3D Coordinates
# Star with proper motion and parallax
star = SkyCoord(
ra=83.8221*u.degree, dec=-5.3911*u.degree,
distance=Distance(parallax=768.5*u.mas),
pm_ra_cosdec=28.87*u.mas/u.yr,
pm_dec=11.31*u.mas/u.yr,
radial_velocity=-17.8*u.km/u.s,
obstime=Time('J2000')
)
# Apply proper motion to current epoch
star_now = star.apply_space_motion(new_obstime=Time.now())
print(f"Current position: RA={star_now.ra}, Dec={star_now.dec}")
print(f"3D distance: {star.distance}")Custom Coordinate Frames
from astropy.coordinates import frame_transform_graph
# Define custom frame transformation
@frame_transform_graph.transform(StaticMatrixTransform, CustomFrame, ICRS)
def custom_to_icrs():
# Define transformation matrix
return rotation_matrix
# Use custom frame
coords_custom = SkyCoord(10*u.degree, 20*u.degree, frame=CustomFrame)
coords_icrs = coords_custom.transform_to(ICRS)