l1models

The l1models module contains the various models used to compute the l=1 mode frequencies given a sample of model parameters from the sampler. The models currently include the ‘ms’, ‘sg’, and ‘rgb’ models.

The naming of the model approximately suggests which types of stars they might be suited for, but any model may be applied to any star. For example near the transition between sub-giants and red-giants there may be some ambiguity in which model performs best, so it is recommended to try a different model if your first choice doesn’t work.

class pbjam.l1models.Asyl1model(f, s, obs, addPriors, PCAsamples, vis={'V10': 1.22}, priorPath=None)

model(thetaU)

Computes the model given parameters thetaU.

Parameters:

thetaU (dict) – Dictionary of model parameters.

Returns:

modes – The computed model spectrum.

Return type:

array-like

nu1_frequencies(thetaU)

Computes the l=1 mode frequencies based on thetaU.

Parameters:

thetaU (dict) – Dictionary of model parameters.

Returns:

• nu (array-like) – The l=1 mode frequencies.

• zeta (array-like) – The degree of mixing for each mode. For the asymptotic model this is assumed to be 0 for all modes.

parseSamples(smp, Nmax=5000)

Parses the samples from the posterior distribution.

Parameters:

• smp (dict) – Dictionary of samples.

• Nmax (int, optional) – Maximum number of samples to process. Default is 5000.

Returns:

A dictionary containing parsed results including frequencies, heights, widths, and rotational asymmetry.

Return type:

dict

rotation(nurot_e, **kwargs)

Computes the rotational splitting for the modes.

Parameters:

nurot_e (float) – Envelope rotation rate.

Returns:

nurot_e – The rotational splitting.

Return type:

float

setPriors()

Set the prior distributions.

The prior distributions are constructed from the projection of the PCA sample onto the reduced dimensional space.

unpackParams(theta)

Cast the parameters in a dictionary

Parameters:

theta (array) – Array of parameters drawn from the posterior distribution.

Returns:

thetaU – The unpacked parameters.

Return type:

dict

class pbjam.l1models.Mixl1model(f, s, obs, addPriors, PCAsamples, PCAdims, vis={'V10': 1.22}, priorPath=None)

A class to model mixed l=1 modes using the coupling matrix formalism.

This is suitable for mode identification in sub-giant stars.

Parameters:

• f (array-like) – Frequency array.

• s (array-like) – Power spectrum data.

• obs (dict) – Dictionary containing observed values such as ‘nu0_p’, ‘mode_width’, etc.

• addPriors (dict) – Additional priors to be included.

• PCAsamples (int) – Number of samples to use for PCA.

• PCAdims (int) – Number of principal components to retain.

• vis (dict, optional) – Visibility parameters for the modes. Default is {‘V10’: 1.22}.

• priorPath (str, optional) – Path to the prior data. Default is None.

N_p

Number of p-modes (pressure modes).

Type:

int

N_g

Number of g-modes (gravity modes).

Type:

int

N_pg

Total number of p- and g-modes.

Type:

int

ell

Array of degree (l) values for the modes.

Type:

ndarray

emm

Array of azimuthal order (m) values for the modes.

Type:

ndarray

ndims

Number of dimensions (parameters) in the model.

Type:

int

priors

Dictionary of prior distributions for the model parameters.

Type:

dict

generalized_eig(A, B)

Solves the generalized eigenvalue problem.

Parameters:

• A (ndarray) – Matrix A in the generalized eigenvalue problem.

• B (ndarray) – Matrix B in the generalized eigenvalue problem.

Returns:

• U (array-like) – Eigenvalues of the problem.

• V (array-like) – Eigenvectors of the problem.

generalized_eigh(A, B)

Solves the generalized eigenvalue problem using Hermitian matrices.

Notes

This function is not currently used. generalized_eig seemed to be faster.

Parameters:

• A (ndarray) – Hermitian matrix A in the generalized eigenvalue problem.

• B (ndarray) – Hermitian matrix B in the generalized eigenvalue problem.

Returns:

• U (array-like) – Eigenvalues of the problem.

• V (array-like) – Eigenvectors of the problem.

generate_matrices(nu_p, nu_g, p_L, p_D)

Generate coupling strength matrices

Computes the coupling strength matrices based on the asymptotic p- and g-mode frequencies and the polynomial representation of the coupling strengths.

Parameters:

• nu_p (jax device array) – Array containing asymptotic l=1 p-mode frequencies.

• nu_g (jax device array) – Array containing asymptotic l=1 g-mode frequencies.

• p_L (jax device array) – Parameter vector describing 2D polynomial coefficients for coupling strengths.

• p_D (jax device array) – Parameter vector describing 2D polynomial coefficients for overlap integrals.

Returns:

• L (jax device array) – Matrix of coupling strengths.

• D (jax device array) – Matrix of overlap integrals.

makeEmpties()

Make a bunch of static matrices so we don’t need to make them during sampling

model(thetaU)

Computes the model for the given parameters, thetaU.

Parameters:

thetaU (dict) – Dictionary of model parameters.

Returns:

mod – The computed model spectrum.

Return type:

array-like

new_modes(L, D)

Solve for mixed mode frequencies

Given the matrices L and D such that we have eigenvectors

L cᵢ = -ωᵢ² D cᵢ,

with ω in Hz, we solve for the frequencies ν (μHz), mode mixing coefficient zeta.

Parameters:

• L (jax device array) – The coupling strength matrix.

• D (jax device array) – The overlap integral.

Returns:

• nu_mixed (jax device array) – Array of mixed mode frequencies.

• zeta (jax device array) – The mixing degree for each of the mixed modes.

nu1_frequencies(thetaU)

Calculate mixed nu1 values and associated zeta values.

Parameters:

thetaU (dict) – Dictionary of model parameters.

Returns:

• nu (array-like) – Array of frequencies of the mixed l=1 modes.

• zeta (array-like) – Array of mixing degrees for the modes.

parseSamples(smp, Nmax=5000)

Parses the samples from the posterior distribution.

Parameters:

• smp (dict) – Dictionary of samples.

• Nmax (int, optional) – Maximum number of samples to process. Default is 5000.

Returns:

A dictionary containing parsed results including frequencies, heights, widths, and rotational asymmetry.

Return type:

dict

rotation(zeta, nurot_c, nurot_e)

Computes the rotational splitting for the modes as a mixture model where the mixture coefficient is the degree of mixing, zeta.

Parameters:

• zeta (array-like) – Mixing degree for each mode.

• nurot_c (float) – Core rotation rate.

• nurot_e (float) – Envelope rotation rate.

Returns:

Rotational splitting values.

Return type:

array-like

setPriors()

Set the prior distributions.

The prior distributions are constructed from the projection of the PCA sample onto the reduced dimensional space.

setupDR()

Setup the latent parameters and projection functions

Notes

• The prior distributions are constructed based on the PCA sample projection onto the reduced-dimensional space.

• If the target values are too far from the viable prior sample, the prior is labeled as unreliable. This can happen if the target is very far outside the main prior sample distribution.

unpackParams(theta)

Cast the parameters in a dictionary

Parameters:

theta (array) – Array of parameters drawn from the posterior distribution.

Returns:

thetaU – The unpacked parameters.

Return type:

dict

class pbjam.l1models.RGBl1model(f, s, obs, addPriors, PCAsamples, rootiter=15, vis={'V10': 1.22}, priorPath=None, modelChoice='simple')

A class to model l=1 modes in red giant branch (RGB) stars using Dynesty sampling.

Parameters:

• f (array-like) – Frequency array.

• s (array-like) – Power spectrum data.

• obs (dict) – Dictionary containing observed values such as ‘nu0_p’, ‘mode_width’, etc. Typically from the l=2,0 model.

• addPriors (dict) – Additional priors to be included.

• PCAsamples (int) – Number of samples to use for PCA.

• rootiter (int, optional) – Number of iterations for root-finding in coupling. Default is 15.

• vis (dict, optional) – Visibility parameters for the modes. Default is {‘V10’: 1.22}.

• priorPath (str, optional) – Path to the prior data. Default is None.

• modelChoice (str, optional) – Choice of the frequency model, either ‘simple’ or ‘rotation-coupled’. Default is ‘simple’.

N_p

Number of p-modes (pressure modes).

Type:

int

N_g

Number of g-modes (gravity modes).

Type:

int

N_pg

Total number of p- and g-modes.

Type:

int

ell

Array of degree (l) values for the modes.

Type:

ndarray

emm

Array of azimuthal order (m) values for the modes.

Type:

ndarray

ndims

Number of dimensions (parameters) in the model.

Type:

int

priors

Dictionary of prior distributions for the model parameters.

Type:

dict

F(nu, nu_p, nu_g, Dnu, DPi1, q)

Compute the characteristic function F such that F(nu) = 0 yields eigenvalues.

Parameters:

• nu (ndarray) – Frequency array.

• nu_p (ndarray) – Array of p-mode frequencies.

• nu_g (ndarray) – Array of g-mode frequencies.

• Dnu (float) – Large frequency separation.

• DPi1 (float) – Period spacing for l=1 modes.

• q (float) – Coupling strength parameter.

Returns:

F – The characteristic function F.

Return type:

array-like

Fp(nu, nu_p, nu_g, Dnu, DPi1, qp=0)

Compute the first derivative dF/dnu of the characteristic function F.

Parameters:

• nu (ndarray) – Frequency array.

• nu_p (ndarray) – Array of p-mode frequencies.

• nu_g (ndarray) – Array of g-mode frequencies.

• Dnu (float) – Large frequency separation.

• DPi1 (float) – Period spacing for l=1 modes.

• qp (float, optional) – Additional parameter for the characteristic function. Default is 0.

Returns:

Fp – The first derivative of the characteristic function F.

Return type:

array-like

Fpp(nu, nu_p, nu_g, Dnu, DPi1, qpp=0)

Compute the second derivative d^2F / dnu^2of the characteristic function F.

Parameters:

• nu (ndarray) – Frequency array.

• nu_p (ndarray) – Array of p-mode frequencies.

• nu_g (ndarray) – Array of g-mode frequencies.

• Dnu (float) – Large frequency separation.

• DPi1 (float) – Period spacing for l=1 modes.

• qpp (float, optional) – Additional parameter for the characteristic function. Default is 0.

Returns:

The second derivative of the characteristic function F.

Return type:

ndarray

Theta_g(nu, DPi1, nu_g)

Compute the g-mode phase function Theta_g.

Parameters:

• nu (ndarray) – Frequency array.

• DPi1 (float) – Period spacing for l=1 modes.

• nu_g (ndarray) – Array of g-mode frequencies.

Returns:

Theta_g – The g-mode phase function Theta_g.

Return type:

array-like

Theta_p(nu, Dnu, nu_p)

Compute the p-mode phase function Theta_p.

Parameters:

• nu (ndarray) – Frequency array.

• Dnu (float) – Large frequency separation.

• nu_p (ndarray) – Array of p-mode frequencies.

Returns:

Theta_p – The p-mode phase function Theta_p.

Return type:

array-like

couple(nu_p, nu_g, q_p, q_g, DPi1, lmbda=0.5)

Solve the characteristic equation using Halley’s method to couple pure p- and g-modes to get the mixed mode frequencies. This converges even faster than Newton’s method and is capable of handling quite numerically difficult scenarios with not very much damping.

Parameters:

• nu_p (ndarray) – Array of p-mode frequencies.

• nu_g (ndarray) – Array of g-mode frequencies.

• q_p (float) – Coupling strength parameter for p-modes.

• q_g (float) – Coupling strength parameter for g-modes.

• DPi1 (float) – Period spacing for l=1 modes.

• lmbda (float, optional) – Damping factor for Halley’s method. Default is 0.5.

Returns:

num – Array of mixed mode frequencies.

Return type:

array-like

halley_iteration(x, y, yp, ypp, lmbda=1.0)

Perform Halley’s method (2nd order Householder) iteration, with damping

Parameters:

• x (ndarray) – Current estimate of the root.

• y (ndarray) – Function value at the current estimate.

• yp (ndarray) – First derivative of the function.

• ypp (ndarray) – Second derivative of the function.

• lmbda (float, optional) – Damping factor. Default is 1.

Returns:

xprime – Updated estimate of the root after one iteration.

Return type:

array-like

initRotationModel(modelChoice)

Initialize the chosen frequency model.

Parameters:

modelChoice (str) – The choice of frequency model, either ‘simple’ or ‘rotation-coupled’.

model(thetaU)

Compute the model spectrum based on the input parameters.

Parameters:

thetaU (dict) – Dictionary of model parameters.

Returns:

modes – The computed model spectrum.

Return type:

array-like

nearest(nu, nu_target)

Utility function: given 1d arrays nu and nu_target, return a 1d array with the same shape as nu, containing the nearest elements of nu_target to each element of nu.

Parameters:

• nu (ndarray) – Array of target frequencies.

• nu_target (ndarray) – Array of candidate frequencies.

Returns:

near – Array of the nearest frequencies in nu_target to each value in nu.

Return type:

array-like

parseSamples(smp, Nmax=5000)

Parse the samples from the posterior distribution.

Parameters:

• smp (dict) – Dictionary of samples.

• Nmax (int, optional) – Maximum number of samples to process. Default is 5000.

Returns:

A dictionary containing parsed results including frequencies, heights, widths, and rotational asymmetry.

Return type:

dict

rotationCoupledFrequencies(thetaU)

Compute the mixed mode frequencies using the rotation-coupled model. This model splits the pure p- and g-modes first using just the envelope and core rotation rates respectively. The mode coupling is then performed following this.

Parameters:

thetaU (dict) – Dictionary of model parameters.

Returns:

• num (array-like) – Array of mixed l=1 mode frequencies.

• zeta (array-like) – Arrays of mixing degrees.

setPriors()

Set the prior distributions for the model parameters.

The prior distributions are constructed from the projection of the PCA sample onto the reduced-dimensional space.

simpleFrequencies(thetaU)

Compute the mixed mode frequencies using the simple model. This model for rotation performs the coupling before splitting the modes by the mixing weighted rotation.

Parameters:

thetaU (dict) – Dictionary of model parameters.

Returns:

• num (array-like) – Array of mixed l=1 mode frequencies.

• zeta (array-like) – Arrays of mixing degrees.

unpackParams(theta)

Cast the parameters in a dictionary

Parameters:

theta (array) – Array of parameters drawn from the posterior distribution.

Returns:

thetaU – The unpacked parameters.

Return type:

dict

zeta(nu, q, DPi1, Dnu, nu_p, nu_g)

Compute the local mixing fraction zeta.

Parameters:

• nu (ndarray) – Frequency array.

• q (float) – Coupling strength parameter.

• DPi1 (float) – Period spacing for l=1 modes.

• Dnu (float) – Large frequency separation.

• nu_p (ndarray) – Array of p-mode frequencies.

• nu_g (ndarray) – Array of g-mode frequencies.

Returns:

zeta – The local mixing fraction zeta using only the p-mode phase function.

Return type:

array-like

zeta_g(nu, q, DPi1, Dnu, nu_g)

Compute the mixing fraction zeta using only the g-mode phase function. Agrees with zeta only at the eigenvalues (i.e. roots of the characteristic equation F(nu) = 0).

Parameters:

• nu (ndarray) – Frequency array.

• q (float) – Coupling strength parameter.

• DPi1 (float) – Period spacing for l=1 modes.

• Dnu (float) – Large frequency separation.

• nu_g (ndarray) – Array of g-mode frequencies.

Returns:

zeta_g – The mixing fraction zeta using only the g-mode phase function.

Return type:

array-like

zeta_p(nu, q, DPi1, Dnu, nu_p)

Compute the mixing fraction zeta using only the p-mode phase function. Agrees with zeta only at the eigenvalues (i.e. roots of the characteristic equation F(nu) = 0).

Parameters:

• nu (ndarray) – Frequency array.

• q (float) – Coupling strength parameter.

• DPi1 (float) – Period spacing for l=1 modes.

• Dnu (float) – Large frequency separation.

• nu_p (ndarray) – Array of p-mode frequencies.

Returns:

zeta_p – The local mixing fraction zeta.

Return type:

array-like

class pbjam.l1models.commonFuncs

A set of common functions for the l1 models, meant to be inherited by each of the model classes.

asymmetry(nulm, m=1)

Compute the asymmetry of the m=-1 and m=1 modes relative to m=0 for an l=1 multiplet.

The multiplet must be a 1D array of length 3, ordered such that m=[-1,0,1].

Notes

Using m=1 or m=-1 as optional arguments should return the same answer.

Parameters:

• nulm (array-like) – The frequencies of an l=1 multiplet.

• m (int, optional) – Azimuthal order to use for the calculation. m=-1 and m=1 returns the same value.

Returns:

asym – Asymmetry for a single l=1 triplet.

Return type:

float

asymptotic_nu_g(n_g, DPi1, eps_g)

Asymptotic relation for g-modes

Asymptotic relation for the g-mode frequencies in terms of a fundamental period offset (defined by the maximum Brunt-Vaisala frequency), the asymptotic g-mode period spacing, the g-mode phase offset, and an optional curvature term.

Parameters:

• n_g (jax device array) – Array of radial orders for the g-modes.

• DPi1 (float) – Period spacing for l=1 in seconds).

• eps_g (float) – Phase offset of the g-modes.

Returns:

Frequencies of the notionally pure g-modes of degree l.

Return type:

jax device array

asymptotic_nu_p(d01)

Computes the asymptotic l=1 mode frequencies based on a given frequency offset.

Parameters:

d01 (float) – The small frequency separation between l=0 and l=1 modes.

Returns:

nu – The l=1 mode frequencies, calculated as the observed l=0 frequencies plus the offset d01.

Return type:

array-like

heights(nu1s)

Computes the mode heights for l=1 modes using a visibility factor and an envelope function.

The mode heights are assumed to follow a Gaussian distribution centered on numax, and are modulated by a fixed visibility ratio V10.

Parameters:

nu1s (array-like) – Array of l=1 mode frequencies.

Returns:

H – The computed heights for the l=1 modes.

Return type:

array-like

modewidths(Gamma, zeta, fac=1)

Compute linewidths for mixed l1 modes

Parameters:

• modewidth0 (jax device array) – Mode widths of l=0 modes.

• zeta (jax device array) – The mixing degree

Returns:

modewidths – Mode widths of l1 modes.

Return type:

jax device array

select_n_g(fac=5)

Select and initial range for n_g

Computes the number of g-modes that are relevant near the oscillation envelope. This is based on the expected range for DPi1 and eps_g and numax.

This is used to set the number of g-modes at the start of the run, and sets the number of g-modes at or near the p-mode envelope. The range is significantly wider than the actual power distribution of the envelope so there is room for DPi1 and eps_g to change.

Returns:

• n_g_ppf (list) – The quauntile functions for DPi1 and eps_g.

• fac (float) – g-modes are considered if they fall within +/- fac * envelope_width of numax. A larger may(??) increase precision at the cost of time to perform eigendecomposition.