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.

  1. Loads base FITS data

  2. Scales coordinates using solar position

  3. Adds phase-shifted interarm components

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