ADIPLS

Functions and classes for reading and writing ADIPLS binary output. Many return or contain what I call cs arrays. These are defined in Section 8.2 of the ADIPLS documentation. They are structured arrays containing various scalar results from the frequency calculation.

tomso.adipls.read_one_cs(f)

Utility function to parse one cs array from a binary file handle f.

tomso.adipls.load_pointwise_data(filename, ncols)

Utility function for common structure of ADIPLS data that has a value at each point in a stellar model. e.g. eigenfunction or kernel files.

Parameters:

• filename (str) – Name of the file to be read.

• ncols (int) – Number of columns in the data.

Returns:

• css (structured array) – The cs arrays for each mode.

• data (list of arrays) – The point-wise data arrays for each mode.

tomso.adipls.load_agsm(filename)

Reads an ADIPLS grand summary file and returns an ADIPLSGrandSummary object.

Parameters:

filename (str) – Name of the grand summary file, usually starting or ending with agsm.

Returns:

agsm – Contains data from the cs arrays for each mode.

Return type:

ADIPLSGrandSummary object

tomso.adipls.load_amde(filename, nfmode=1)

Reads an ADIPLS eigenfunction file written with the specified value of nfmode in the input file (either 1, 2 or 3) and returns an ADIPLSEigenfunctions object.

Parameters:

• filename (str) – Name of the eigenfunction file, usually starting or ending with amde.

• nfmode (int, optional) – ADIPLS’s nfmode parameter, which determines the format of the eigenfunction data. See Section 8.4 of the ADIPLS documentation for details of the output.

Returns:

amde – The eigenfunction data for the modes.

Return type:

ADIPLSEigenfunctions

tomso.adipls.load_amdl(filename, live_dangerously=False, G=6.6743e-08)

Reads an ADIPLS model file and returns an ADIPLSStellarModel object. See Section 5 of the ADIPLS documentation for details.

Parameters:

• filename (str) – Name of the model file, usually starting or ending with amdl.

• live_dangerously (bool, optional) – If True, load the file even if it looks like it might be too large for an AMDL file (i.e. has more than a million points).

• G (float, optional) – Value for the gravitational constant, in cgs units. If not given (which is the default behaviour), we use the module-wise default value.

Returns:

amdl – Contains the model data.

Return type:

ADIPLSStellarModel object

tomso.adipls.load_rkr(filename)

Reads an ADIPLS rotational kernel file and returns an ADIPLSRotationKernels object.

Parameters:

filename (str) – Name of the kernel file, usually starting or ending with rkr.

Returns:

rkr – The kernel arrays for each mode.

Return type:

ADIPLSRotationKernels object

tomso.adipls.kernels(cs, eig, D, A, G=6.6743e-08, alpha=None, pair='cs2,rho')

Returns inversion kernels for variables specified using pair. I have tried to make this as notationally similar to Gough & Thompson (1991) as possible. The kernels are normalized to have unit integrals over the radius r.

Parameters:

• cs (structured array) – The cs array for the mode.

• eig (np.array, shape(N,7)) – Eigenfunction data for the mode, as returned by load_amde().

• D (1-d array) – Global data, as defined by eq. (5.2) of the ADIPLS documentation and returned by load_amdl().

• A (2-d array) – Point-wise data, as defined by eq. (5.1) of the ADIPLS documentation and returned by load_amdl().

• G (float, optional) – Value for the gravitational constant, in cgs units. If not given (which is the default behaviour), we use the module-wise default value.

• alpha (float, optional) – Coefficient of the complementary function. If None, computed as in Michael Thompson’s kernel code.

• pair (str, optional) – Variable pair for which to compute kernels. Options are cs2,rho for squared sound speed and density or Gamma1,rho for first adiabatic index and density. This also defines the order in which the kernels are returned.

Returns:

• K_cs2 (np.array, length N) – The sound speed squared structure kernel.

• K_rho (np.array, length N) – The density structure kernel.

class tomso.adipls.ADIPLSStellarModel(D, A, nmod=0, G=6.6743e-08)

A class that contains and allows one to manipulate the data in a stellar model stored in ADIPLS’s internal binary model format. See Section 5 of the ADIPLS documentation for details.

This will usually be provided from a file by using load_amdl() but an object can be constructed from any similarly structured arrays.

The main attributes are the D and A arrays, which follow the definitions in the ADIPLS documentation. The data in these arrays can be accessed via the attributes with more physically-meaningful names (e.g. the radius is ADIPLSStellarModel.r).

Some of these values can also be set via the attributes if doing so is unambiguous. For example, the fractional radius x is not a member of the var array but setting x will assign the actual radius r, which is the first column of var. Values that are settable are indicated in the list of parameters.

Parameters:

• D (1-d array) – Global data, as defined by eq. (5.2) of the ADIPLS documentation.

• A (2-d array) – Point-wise data, as defined by eq. (5.1) of the ADIPLS documentation.

• nmod (int, optional) – The model number. I’m not sure what it’s used for but it doesn’t seem to matter.

• G (float, optional) – Value for the gravitational constant, in cgs units. If not given (which is the default behaviour), we use the module-wise default value.

Variables:

• nn (int) – number of points in stellar model (i.e. number of rows in A)

• M (float, settable) – total mass

• R (float, settable) – photospheric radius

• P_c (float, settable) – central pressure

• rho_c (float, settable) – central density

• x (NumPy array, settable) – fractional radius co-ordinate

• q (NumPy array, settable) – fractional mass co-ordinate

• lnq (NumPy array, settable) – natural logarithm of the fractional mass co-ordinate

• Vg (NumPy array) – homology invariant V/Gamma_1

• Gamma_1 (NumPy array, settable) – first adiabatic index, aliased by G1

• G1 (NumPy array, settable) – first adiabatic index, alias of Gamma_1

• AA (NumPy array, settable) – Ledoux discriminant

• U (NumPy array) – homology invariant dlnm/dlnr

• V (NumPy array) – homology invariant dlnP/dlnr

• r (NumPy array, settable) – radius co-ordinate

• m (NumPy array, settable) – mass co-ordinate

• P (NumPy array) – pressure

• rho (NumPy array) – density

• g (NumPy array) – local gravitational acceleration

• Hp (NumPy array) – pressure scale height

• Hrho (NumPy array) – density scale height

• N2 (NumPy array) – squared Brunt–Väisälä (angular) frequency

• cs2 (NumPy array) – squared adiabatic sound speed

• cs (NumPy array) – adiabatic sound speed

• tau (NumPy array) – acoustic depth

to_file(filename)

Save the model to an ADIPLS binary stellar model file (usually either starting or ending with amdl).

Parameters:

filename (str) – Filename to which the data is written.

to_fgong(reverse=True, ivers=1300)

Convert the model to an FGONG object.

Note that the ADIPLS binary format only has the data necessary to compute adiabiatic stellar oscillations, so the FGONG will be missing some data (e.g. temperature, luminosity).

Parameters:

reverse (bool, optional) – If True (the default), store the FGONG data ordered from the surface to the centre. Otherwise, store the FGONG data ordered from the centre to the surface.

to_gyre(version=None)

Convert the model to an PlainGYREStellarModel object.

Note that the ADIPLS binary format only has the data necessary to compute adiabiatic stellar oscillations, so the GYRE stellar model will be missing some data (e.g. temperature, luminosity).

Parameters:

version (int, optional) – Specify GYRE format version number times 100. i.e., version=101 produces a file with data version 1.01. If None (the default), the latest version available in TOMSO is used.

class tomso.adipls.ADIPLSGrandSummary(css)

A class that represents the information for a set of mode frequencies, loaded from an ADIPLS grand summary file (often starting or ending with agsm). The main data is stored in the css attribute, which is a structured array. This will usually be provided from a file by using load_agsm() but an object can be constructed from any similarly structured array.

A subset of the information in the css array is made available through attributes.

Parameters:

css (structured NumPy array) – The cs arrays for each mode.

Variables:

• G (float) – gravitational constant

• M (float) – total mass

• R (float) – photospheric radius

• l (NumPy array of ints) – angular degrees

• n (NumPy array of ints) – radial orders

• sigma2 (NumPy array of floats) – square of the dimensionless angular eigenfrequency

• sigma2_c (NumPy array of floats) – square of the dimensionless angular eigenfrequency corrected for the Cowling approximation

• Pi_E (NumPy array of floats) – eigenperiod, in seconds

• Pi_V (NumPy array of floats) – variational period, in seconds

• nu_Ri (NumPy array of floats) – cyclic eigenfrequency corrected using Richardson extrapolation, in Hz

• nu_V (NumPy array of floats) – variational cyclic frequency, in Hz

• nu_E (NumPy array of floats) – cyclic eigenfrequency, in seconds

• nu_c (NumPy array of floats) – cyclic eigenfrequency corrected for the Cowling approximation, in Hz

• nu (NumPy array of floats) – alias of nu_c

• E (NumPy array of floats) – Normalised mode inertia (see eq. (4.3) of ADIPLS notes). Note that ADIPLS’s definition is smaller than GYRE’s by a factor of 4π.

• beta (NumPy array of floats) – Weight for rotation kernel (see eq. (4.7) of ADIPLS notes or (8.43) of JCD’s oscillation notes).

index_ln(l, n)

Returns the index of mode with angular degree l and radial order n.

index_nl(n, l)

Returns the index of mode with radial order n and angular degree l.

class tomso.adipls.ADIPLSEigenfunctions(css, eigs, nfmode=1, x=None)

A class that represents the information for a set of eigenfunction data kernels produced by ADIPLS. This will usually be provided from a file by using load_amde() but an object can be constructed from any similarly structured array.

Parameters:

• css (structured NumPy array) – The cs arrays for each mode.

• eigs (3-d NumPy array) – The eigenfunction arrays for each mode. The nth element of the array has the eigenfunction data for the nth mode, in the same order as the summary data in css. The number of rows in the array for a given mode is the number of meshpoints in the model. The number of columns is either 6 or 2, depending on nfmode.

• nfmode (int) – The output mode used by ADIPLS’ when the data was stored.

• x (NumPy array, optional) – If nfmode is 2 or 3, the fractional radius must be provided separately. If nfmode is 1, it will be inferred from the eigenfunction data if not explicitly provided.

This class has all the attributes of ADIPLSGrandSummary as well as the following extras.

Variables:

• x (NumPy array) – fractional radius co-ordinate

• eigs (list of NumPy arrays) – The nth row is the eigenfunction data for the nth mode, in the same order as the summary data in css.

eig_ln(l, n)

Load eigenfunction by l and n.

eig_nl(n, l)

Load eigenfunction by n and l.

class tomso.adipls.ADIPLSRotationKernels(css, rkr)

A class that represents the information for a set of rotational kernels produced by ADIPLS. This will usually be provided from a file by using load_rkr() but an object can be constructed from any similarly structured array.

Parameters:

• css (structured NumPy array) – The cs arrays for each mode.

• rkrs (list of arrays) – The kernel arrays for each mode. Each array has two columns: the fractional radius and the kernel .

This class has all the attributes of ADIPLSGrandSummary as well as the following extras.

Variables:

• x (NumPy array) – fractional radius co-ordinate

• K (list of NumPy arrays) – The nth row is the rotation kernel for the nth mode, in the same order as the summary data in css. The mode with radial order n and angular degree l can be accessed by the functions K_ln(l,n) or K_nl(n,l).

K_ln(l, n)

Load kernel by angular degree l and radial order n.

K_nl(n, l)

Load kernel by radial order n and angular degree l.