ModelCorona#

class corona_lab.corona.ModelCorona(data=None, masked=False, names=None, dtype=None, meta=None, copy=True, rows=None, copy_indices=True, units=None, descriptions=None, **kwargs)[source]#

Bases: QTable

Table of model coronal field–line data with computed properties and metadata.

Wraps an ~astropy.table.QTable containing stellar corona field‐line columns (e.g., radius, theta, phi, Bmag, ndens, temperature, line_num) and adds methods and metadata for modeling coronal emission, absorption, geometry, and dynamics.

Notes

Many properties and methods assume the presence of specific metadata entries; missing keys typically return None or raise an error if required.
All quantities stored in meta should be ~astropy.units.Quantity where appropriate, and methods will interpret plain numerics in standard units (parsecs, solar radii, GHz, degrees) when setting metadata.
The class uses MD5 hashing of core data arrays to generate stable UIDs.

Attributes Summary

`bb_corona`
`bb_prominence`
`cor_only`	returns: Boolean mask for model cells that are in the closed corona (not the wind)
`corona_temp`	returns: The temperature of the corona.
`distance`	returns: * ~astropy.units.Quantity -- Distance to the star in parsecs.
`observation_angle`	returns: * ~astropy.units.Quantity or None -- The observation angle (phi, theta) in degrees, used to compute the
`observation_freqs`	returns: Observation frequencies for which the free-free
`phase`	returns: Value in degrees giving the phase offset applied to the
`prom`	returns: Boolean mask for prominence cells in the corona model.
`prom_temp`	returns: The temperature of the stellar prominences.
`radius`	returns: The stellar radius.
`rss`	returns: The model extent, i.e. source surface radius.
`uid`	returns: Unique identifier string for this model.
`wind`	returns: Boolean mask for wind cells in the corona model.

Methods Summary

`add_cartesian_coords`(obs_angle[, phase, ...])	Compute and add Cartesian coordinates (x, y, z) from spherical coordinates.
`add_observation_freq`(obs_freq[, cache])	Add a frequency-specific column for free-free absorption coefficient.
`add_plasma_beta`()	Calculate and add the plasma β (ratio of plasma pressure to magnetic pressure) for each cell:
`clear_observation_freqs`([obs_freqs])	Remove one or more observation frequencies and their associated data.
`dynamic_spectrum`(freqs, phases, field_lines, tau)	Generate the electron cyclotron maser (ECM) dynamic spectrum.
`freefree_image`(obs_freq, sidelen_pix, *[, ...])	Make a (square) radio image given the current object parameters.
`from_field_lines`(input_table, **model_parms)	Build a ModelCorona object from an field lines table and optional additional metadata.
`print_meta`()
`radio_phase_cube`(obs_freq, num_steps, ...[, ...])	Generate a cube of radio images across a range of rotational phases.

Attributes Documentation

bb_corona#

bb_prominence#

cor_only#

returns: Boolean mask for model cells that are in the closed corona (not the wind): but do not contain prominences.

Return type:: numpy.ndarray

corona_temp#

returns: The temperature of the corona.: Calculated from the table, and therefore not settable.

Return type:: ~astropy.units.Quantity

distance#: returns: * ~astropy.units.Quantity – Distance to the star in parsecs. * When setting this property, if the input is not a ~astropy.units.Quantity, * it is assumed to be in parsecs and converted accordingly.

observation_angle#

returns: * ~astropy.units.Quantity or None – The observation angle (phi, theta) in degrees, used to compute the: Cartesian coordinate (x, y, z) columns. None if not set.

When setting, if no units are given degrees is assumed.

observation_freqs#

returns: Observation frequencies for which the free-free: absoption coefficient has been calculated.

Return type:: ~astropy.units.Quantity

phase#

returns: Value in degrees giving the phase offset applied to the

coordinate transformation for the Cartesian coordinate (x, y, z) columns.: None if not set.

Return type:: ~astropy.units.Quantity or None

prom#: returns: Boolean mask for prominence cells in the corona model. :rtype: numpy.ndarray

prom_temp#

returns: The temperature of the stellar prominences.: Calculated form the table, and therefore not settable.

Return type:: ~astropy.units.Quantity

radius#

returns: The stellar radius.: Intrinsic to the model and therefore not settable.

Return type:: ~astropy.units.Quantity

rss#

returns: The model extent, i.e. source surface radius.: Intrinsic to the model and therefore not settable.

Return type:: ~astropy.units.Quantity

uid#: returns: Unique identifier string for this model. :rtype: str

wind#: returns: Boolean mask for wind cells in the corona model. :rtype: numpy.ndarray

Methods Documentation

add_cartesian_coords(obs_angle, phase=0, recalculate=False)[source]#

Compute and add Cartesian coordinates (x, y, z) from spherical coordinates.

Given a viewing angle (obs_angle) and an optional rotation (phase), this function computes the Cartesian coordinates assuming a right-handed coordinate system and stores them in columns (‘x’, ‘y’, ‘z’) in the table.

The transformation assumes the existence of radius, theta, and phi columns. If the coordinates have already been computed for the given angle and phase and recalculate is False, the computation is skipped.

Parameters:

obs_angle (float, tuple, or Quantity) – Observation angle as a tuple (phi, theta) or parsable input. Units should be convertible to degrees.
phase (float or Quantity, optional) – Rotation to apply around the z-axis (in degrees). Default is 0.
recalculate (bool, optional) – If False, avoids recomputation when current coordinates already match the provided angle and phase. Default is False.

add_observation_freq(obs_freq, cache=True)[source]#

Add a frequency-specific column for free-free absorption coefficient.

Computes the free-free absorption coefficient (kappa_ff) at a given observation frequency and stores the result in a column named “<obs_freq> Kappa_ff”. If the frequency has already been computed and cache is True, the method skips recomputation.

Parameters:

obs_freq (float or astropy.units.Quantity) – The observation frequency to compute kappa_ff for. If not a Quantity,
GHz. (the value is assumed to be in)
cache (bool, optional) – Whether to skip recomputation if the frequency already exists in
True. (the metadata. Default is)

add_plasma_beta()[source]#

Calculate and add the plasma β (ratio of plasma pressure to magnetic pressure) for each cell:

\[\beta = \frac{n k_B T}{B^2 / 2 \mu_0}\]

where:

\(n\) is the number density,
\(k_B\) is the Boltzmann constant,
\(T\) is the temperature,
\(B\) is the magnetic field magnitude,
\(\mu_0\) is the permeability of free space.

The value is only computed for non-wind cells, since wind regions have Bmag = 0 and would result in a division by zero.

Adds a new column “plasma_beta” to the table.

clear_observation_freqs(obs_freqs='all')[source]#

Remove one or more observation frequencies and their associated data.

Deletes the <freq> Kappa_ff columns and removes the corresponding frequencies from the metadata. By default, all frequencies are cleared.

Parameters:: obs_freqs (str, scalar, Quantity, or list of Quantity, optional) – The observation frequency or list of frequencies to remove. Can be: - “all” (default): removes all stored observation frequencies. - Single frequency (e.g., 5.0 or 5.0 * u.GHz). - List or array of frequencies.

dynamic_spectrum(freqs, phases, field_lines, tau, epsilon=1e-05, sigma=<Quantity 1. deg>, harmonic=1, distance=None, obs_angle=None)[source]#

Generate the electron cyclotron maser (ECM) dynamic spectrum.

This method calculates the ECM emission resulting from the election of stellar prominences for a given set of frequencies and rotational phases.

Parameters:

freqs (int or astropy.units.Quantity) – Frequencies for the dynamic spectra. Can be: - int: number of frequency bins spanning the range of ECM emission - Quantity: Array of frequency bin edges
phases (int or astropy.units.Quantity) – Phases for the dynamic spectra. Can be: - int: number of phase bins (0-360 deg) - Quantity: Array of phases
field_lines (str, int, or array-like) – Magnetic field lines to include in the calculation. Can be: - “prom”: selects all lines marked as prominences in the model, - int: a single field line number, - list of ints: specific field lines.
tau (astropy.units.Quantity) – Disipation timescale
epsilon (float, optional) – ECM efficiency factor, default 1e-5.
sigma (Quantity or float, optional) – A Width of the ECM emission cone, by default 1 deg, per TODO: citation.
harmonic (int, optional) – Harmonic number to use for ECM emission, by default 1 (fundamental).
distance (Quantity, optional) – Distance to the object. If None, uses self.distance.
obs_angle (Quantity or float, optional) – Observation angle. If None, uses self.observation_angle.

Returns:

The computed dynamic spectrum, with metadata including observation angle, frequencies, field lines, tau, and harmonic.

Return type:

ModelDynamicSpectrum

Raises:

AttributeError – If distance or observation angle is not provided and not set on the object.
ValueError – If ECM fraction is zero for all field lines.

freefree_image(obs_freq, sidelen_pix, *, sidelen_rad=None, obs_angle=None, phase=None)[source]#

Make a (square) radio image given the current object parameters.

Parameters:

sidelen_pix (int) – Image side length in pixels (image will be sidelen_pix x sidelen_pix pixels)
sidelen_rad (float) – Optional. Image side length in stellar radii. If not given the source surface radius will be used.
obs_angle (2 lonrg array of float or astropy.units.Quantity) – Optional. Format is (ra, dec). If not given the current observation angle stored in meta will be used.
phase (float or astropy.units.Quantity) – Optional. The stellar rotation phase/latitude. If not given the current phase stored in meta will be used.

Returns:

The calculated radio image as a RadioImage object, which is a astropy.units.Quantity array with metadata.

Return type:

ModelImage

classmethod from_field_lines(input_table, **model_parms)[source]#

Build a ModelCorona object from an field lines table and optional additional metadata.

Parameters:

input_table (Any valid input to astropy.table.QTable()) – The table object containing a set of model corona field lines
**model_parms – Optional. Additional model parameters to go in the table meta data. If these parameters also appear in the input_table meta object, the argument values will be perfered (i.e. these inputs override anything already in the table metadata) The valid names for parameters used throughout this class are: distance, radius, rss, obs_freq, obs_angle, phase

Returns:

ModelCorona object with the given field lines and metadata.

Return type:

ModelCorona

print_meta()[source]#

radio_phase_cube(obs_freq, num_steps, sidelen_pix, beam_size, *, sidelen_rad=None, obs_angle=None, min_phi=<Quantity 0. deg>, max_phi=<Quantity 360. deg>)[source]#

Generate a cube of radio images across a range of rotational phases.

This method computes free-free emission images at a given observation frequency and viewing angle across num_steps rotational phases. The resulting data includes flux, lobe separations, peak counts, and angular separations for each phase.

Parameters:

obs_freq (float or ~astropy.units.Quantity) – The observation frequency. Will be converted to GHz if not already.
num_steps (int) – Number of evenly spaced phases to generate between min_phi and max_phi.
sidelen_pix (int) – Number of pixels per side of the square image.
beam_size (float or ~astropy.units.Quantity) – Size of the synthetic observational beam (for peak/lobe identification).
sidelen_rad (float or ~astropy.units.Quantity, optional) – Physical size of the image in angular units (radians). If not provided, computed from the source surface radius and stellar radius.
obs_angle (float, tuple, or ~astropy.units.Quantity, optional) – Observation angle as (phi, theta) in degrees. If None, will use previously set value.
min_phi (~astropy.units.Quantity, optional) – Starting rotational phase angle in degrees. Default is 0°.
max_phi (~astropy.units.Quantity, optional) – Ending rotational phase angle in degrees. Default is 360°.

Returns:

PhaseCube –
A PhaseCube object containing:
- phi: phase angle for each image
- flux: total flux from each image
- separation: maximum peak separation
- num_peaks: number of emission peaks
- ang_sep: maximum angular separation
- image: 2D flux image (or intensity if distance is not set)
Metadata includes observation frequency, angles, image specs, and summary stats.

Raises:

AttributeError – If no observation angle is provided or previously set.

Warning

UserWarning: If the stellar distance is missing, intensity is returned instead of flux.