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.

getarmlist()[source]: Set arm names and colours

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

model_(arm_name)[source]

Generate arm coordinates using cubic spline interpolation.

Parameters:: arm_name (String) – Must be one of: ‘Arm1’, ‘Arm2’, ‘Arm3’, ‘Arm4’.
Returns:: (x_hc, y_hc, x_gc, y_gc)
Return type:: tuple

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

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

getarmlist()[source]: Set arm names and colours

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

output_(arm)[source]

Get arm coordinates in structured format.

Parameters:: arm (String) – Arm identifier (e.g., ‘Norma’)
Returns:: self.dout = {‘xhc’:xhc,’yhc’:yhc,’xgc’:xgc,’ygc’:ygc}
Return type:: dict

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

getarmlist()[source]: Set arm names and colours

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.

getarmlist()[source]: Set arm names and colours

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.

getarmlist()[source]: Set arm names and colours

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.

getarmlist()[source]: Set arm names and colours

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

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