API
- class SpiralMap.models_.TaylorCordesSpiral[source]
Taylor & Cordes (1993) Galactic spiral arm model, based on radio pulsar observations. The model defines four major spiral arms.
- getparams()[source]
Load original spiral parameters from Taylor & Cordes (1993) Table 1.
- Returns:
self.params[‘Arm1’,’Arm2’,’Arm3’,’Arm4’], nested dictionary such that, self.params[‘Arm’][‘theta_deg’] -> Anchor points in galactic longitude (degrees). self.params[‘Arm’][‘r_kpc’] ->Corresponding galactocentric radii (kiloparsecs).
- Return type:
dict
- class SpiralMap.models_.main_(Rsun=8.277, print_=True)[source]
The main executor that calls the individual models to grab the spiral traces. It is also used to set plot preferences and make plots.
- getinfo(model='', print_=True)[source]
prints (model list, tracers) & default plot attributes are defined here.
- Parameters:
model (String) – Optional - ‘’ by default so lists all models. otherwise provide a model (ex: Drimmel_Ceph_2024) to list out all arms and default colours.
print_ (Boolean) – Optional - if set to False does not print to screen.
- listmodels()[source]
Defines list of available models/maps Constructs dictionaries to initialise individual model classes
- readout(plotattrs={}, model='', arm='', print_=False)[source]
reads out individual models/ makes plots etc.
- Parameters:
plotattrs (dict) – Optional - if not provided, uses default plot attributes.
model (String) – (required otherwise raises exception)
arm (String) – Optional - (default = ‘’ so reads all arms)
print_ (Boolean) – Optional - if set to False does not print to screen.
- Raises:
RuntimeError – if no model is provided.
- class SpiralMap.models_.reid_spiral(kcor=False)[source]
Reid et al. (2019) kinked logarithmic spiral arm model
Implements the Milky Way spiral structure model from: “Trigonometric Parallaxes of High Mass Star Forming Regions: The Structure and Kinematics of the Milky Way” using kinked logarithmic spirals with varying pitch angles. Models 7 major arm features.
- arms
Array of arm identifiers [‘3-kpc’, ‘Norma’, ‘Sct-Cen’, ‘Sgr-Car’, ‘Local’, ‘Perseus’, ‘Outer’]
- Type:
ndarray
- getparams(arm)[source]
Load spiral parameters for specified arm from Reid et al. (2019) Table 4.
- Parameters:
arm (str) – Valid arm identifier from class arms list
- Returns:
Dictionary containing: - beta_kink: Kink angle position in degrees
pitch_low: Pitch angle before kink (degrees)
pitch_high: Pitch angle after kink (degrees)
R_kink: Galactocentric radius at kink (kpc)
beta_min/max: Angular range in degrees
width: Arm width parameter (kpc)
- Return type:
dict
Notes
Applies correction to R_kink if kcor=True during initialization
- model_(params)[source]
Generate kinked logarithmic spiral coordinates.
- Parameters:
params (dict) – Spiral parameters dictionary from getparams()
- Returns:
(x, y, x1, y1, x2, y2) coordinate arrays where:
x,y: Arm center coordinates (GC)
x1,y1: Inner arm boundary
x2,y2: Outer arm boundary
- Return type:
tuple
Notes
Implements modified logarithmic spiral equation with pitch angle kink: R(β) = R_kink * exp[-(β - β_kink) * tan(pitch)] where pitch changes at β_kink
- class SpiralMap.models_.spiral_drimmel_nir[source]
Drimmel (2000) Near-Infrared (NIR) spiral arm model
Implements the 2-arm spiral structure model from: Drimmel, R. (2000) “Evidence for a two-armed spiral in the Milky Way” using COBE/DIRBE near-infrared data. Includes main arms and phase-shifted interarms.
- arms
Array of arm identifiers [‘1_arm’, ‘2_arm’, ‘3_interarm’, ‘4_interarm’]
- Type:
ndarray
- armcolour
Color mapping for visualization: - Main arms: black - Interarms: red
- Type:
dict
- getdata()[source]
Load and preprocess spiral arm data from FITS file.
Loads base FITS data
Scales coordinates using solar position
Adds phase-shifted interarm components
Calculates galactocentric radii
Notes
Original data scaled by solar galactocentric distance
Phase-shifted arms loaded from separate numpy files
- output_(arm)[source]
Retrieve spiral arm coordinates in specified format.
- Parameters:
arm (str) – Arm identifier or selection mode: - ‘1’, ‘2’ for main arms - ‘3’, ‘4’ for interarms - ‘all’ for all components - ‘main’ for just main arms
typ ({'cartesian', 'polar', 'polargrid'}, default 'cartesian') – Output format: - cartesian: Returns x,y coordinates - polar/polargrid: Generates polar coordinate plots
- Returns:
For cartesian type contains: - xhc, yhc: Heliocentric coordinates (kpc) - xgc, ygc: Galactocentric coordinates (kpc)
- Return type:
dict
Notes
Polar modes create matplotlib plots directly using: - phi1: Angle from negative x-axis (GC frame) - phi4: Galactic longitude (0-360 degrees)
- class SpiralMap.models_.spiral_houhan[source]
Hou & Han (2014) polynomial-logarithmic spiral arm model, all tracers
Implements the Milky Way spiral structure model from: “The spiral structure of the Milky Way from classical Cepheids” (Hou & Han 2014) using polynomial-logarithmic spiral functions. Provides 6 major arm segments.
- getparams()[source]
Load spiral parameters from Hou & Han (2014) Table 4 (vcirc=239, Z =0.16), all tracers.
- Returns:
params ( Nested dictionary containing for each arm).
a, b, c, d: Polynomial coefficients.
θ_start: Start angle in degrees (Galactic longitude).
θ_end: End angle in degrees.
- Return type:
dict
- output_(arm)[source]
Get arm coordinates in structured format.
- Parameters:
arm (String) – Arm identifier (e.g., ‘Arm1’)
- Returns:
self.dout = {‘xhc’:xhc,’yhc’:yhc,’xgc’:xgc,’ygc’:ygc}
- Return type:
dict
- polynomial_log_spiral(θ, a, b, c, d)[source]
Calculate radius using polynomial-logarithmic spiral equation.
- Parameters:
θ (float or ndarray) – Galactic longitude angle in degrees
a (float) – Polynomial coefficients from Hou & Han Table 4
b (float) – Polynomial coefficients from Hou & Han Table 4
c (float) – Polynomial coefficients from Hou & Han Table 4
d (float) – Polynomial coefficients from Hou & Han Table 4
- Returns:
Galactocentric radius in kiloparsecs
- Return type:
float or ndarray
Notes
Implements equation: R(θ) = exp(a + bθ_rad + cθ_rad² + dθ_rad³) where θ_rad = np.radians(θ)
- class SpiralMap.models_.spiral_houhan_HII[source]
Hou & Han (2014) polynomial-logarithmic spiral arm model, HII regions only.
Implements the Milky Way spiral structure model from: “The spiral structure of the Milky Way from classical Cepheids” (Hou & Han 2014) using polynomial-logarithmic spiral functions. Provides 6 major arm segments.
- getparams()[source]
Load spiral parameters from Hou & Han (2014) Table 4 (vcirc=239, Z =0.16), HII regions only.
- Returns:
params ( Nested dictionary containing for each arm).
a, b, c, d: Polynomial coefficients.
θ_start: Start angle in degrees (Galactic longitude).
θ_end: End angle in degrees.
- Return type:
dict
- output_(arm)[source]
Get arm coordinates in structured format.
- Parameters:
arm (String) – Arm identifier (e.g., ‘Arm1’)
- Returns:
self.dout = {‘xhc’:xhc,’yhc’:yhc,’xgc’:xgc,’ygc’:ygc}
- Return type:
dict
- polynomial_log_spiral(θ, a, b, c, d)[source]
Calculate radius using polynomial-logarithmic spiral equation.
- Parameters:
θ (float or ndarray) – Galactic longitude angle in degrees
a (float) – Polynomial coefficients from Hou & Han Table 4
b (float) – Polynomial coefficients from Hou & Han Table 4
c (float) – Polynomial coefficients from Hou & Han Table 4
d (float) – Polynomial coefficients from Hou & Han Table 4
- Returns:
Galactocentric radius in kiloparsecs
- Return type:
float or ndarray
Notes
Implements equation: R(θ) = exp(a + bθ_rad + cθ_rad² + dθ_rad³) where θ_rad = np.radians(θ)
- class SpiralMap.models_.spiral_levine[source]
Levine et al (2006) logarithmic spiral arm model for the Milky Way.
- getparams()[source]
- Returns:
self.params[‘Arm1’,’Arm2’,’Arm3’,’Arm4’], nested dictionary such that,
self.params[‘Arm’][‘pitch’] -> pitch angle
self.params[‘Arm’][‘phi0’] -> Solar crossing angle)
- Return type:
dict
- model_(arm_name, R_max=25, n_points=1000)[source]
Generate logarithmic spiral coordinates for specified arm.
- Parameters:
arm_name (str) – Name of arm to model (must be in [‘Arm1’, ‘Arm2’, ‘Arm3’, ‘Arm4’])
R_max (float, optional) – Maximum galactocentric radius to model (kpc), default=25
n_points (int, optional) – Number of points to sample along the spiral, default=1000
- Returns:
(x_hc, y_hc, x_gc, y_gc) coordinate arrays where: - x_hc, y_hc: Heliocentric coordinates (kpc) - x_gc, y_gc: Galactocentric coordinates (kpc)
- Return type:
tuple
- Raises:
ValueError – If invalid arm_name is provided
Notes
- Implements the logarithmic spiral equation:
R(φ) = R₀ * exp[(φ - φ₀) * tan(i)]
where: - R₀ is solar galactocentric distance - i is pitch angle - φ₀ is solar crossing angle - φ is the angular coordinate