Optimal Stellar Models (OSM)

OSM is a python program that implements the Levenberg-Marquardt method for the calculation of optimal stellar models with the CESTAM code. The minimization takes into account fundamental constraints as well as seismic constraints. Cross-correlations between the seismic constraints are also take into account in the minimization criterion.

Requirements

  • CESTAM (version 3.2 or newer) : a free code for the calculation of the structures and evolutions of stars ;

  • python-cestam, a Python library associated with CESTAM (developed by J. Marques), this module is included in the CESTAM package ;

  • ADIPLS : a code for computing adiabatic stellar modes (http://astro.phys.au.dk/~jcd/adipack.n/) ;

  • Python (2.7 or newer) , Numpy and Scipy.

Installation

You must first install CETSTAM and ADIPLS, please refer to their associated documentations. To install OSM in your home directory for you own use, type:

python setup.py install –-home=$HOME/

The components of the OSM library will be installed, depending on your architecture, in $HOME/lib/python or $HOME/lib64/python, while the osm.py executable will be installed in $HOME/bin/.

You can also install OSM as root for all the users, in that case type:

sudo python setup.py install

Quick tutorial

For each model you want to compute, you must first edit an associated configuration file (XML format). The package contains various examples.

You must also setup the .don file where you fix the parameters and options associated with CESTAM code. This file must have the same prefix than the .xml file. For example: mymodel.xml and mymodel.don.
All the files produced by OSM are stored in a repertory named mymodel.

Here below a simple example of a configuration file (without seismic constraints):

<!--
This is the configuration file for OSM
-->
<config>
<!-- 
********************************************
 the free parameters
********************************************
-->
<parameter name="agemax">
<value> 320.  </value>
<step> 20. </step>
<rate> 5. </rate>
<bounds> 10. , 10000.</bounds>
</parameter>

<parameter name="mtot">
<value>1.03 </value>
<step> 0.03 </step>
<rate> 3. </rate>
<bounds> 0.5 , 5.</bounds>
</parameter>

<!-- 
********************************************
 the constraints (referred as 'targets')
********************************************
-->
<target name="logg">
<value>4.53588</value>
<sigma> 0.01</sigma>
</target>

<target name="teff">
<value>5569.27</value>
<sigma> 50. </sigma>
</target>

<!-- 
*****************************************
 the settings
*****************************************
-->
<settings>

<!-- 
--------------------------------------
 settings associated with the 
 Levenberg-Marquardt algorithm
-------------------------------------- 
-->
<levmar>
<maxiter> 25 </maxiter>
<chi2min> 1e-3 </chi2min>
<ftol> 1e-3 </ftol>
</levmar>

<!-- 
--------------------------------------
 settings associated with the 
 model computation
-------------------------------------- 
-->
<models>
<dy_dz> 2. </dy_dz>
<yp>0.235</yp>
<zp>0.</zp>
<start>zams</start>
<cf>8e-5</cf>
</models>

</settings>

</config>

The parameters

  • name="X" : name of the free parameter. The allowed parameters are these handled by CESTAM in the .don file. For example 'agemax' for the age, 'mtot' for the mass ... etc

  • value : initial value of the parameter

  • step : the step used for the calculation of the associated derivative (the derivatives are used for the calculation of the Hessian matrix)

  • rate : the maximum rate [in %] at which the parameter is allowed to change

  • bounds : authorized interval (minimal value , maximum value)

The "global" constraints ("targets")

  • name="X" : name of the target. A restricted number of targets are manage by OSM. The targets currently managed by OSM are:
    - effective temperature: teff (in K)
    - radius: r (in solar unit)
    - luminosity: l (in solar unit)
    - decimal logarithm of the luminosity: logl
    - decimal logarithm of teff: log_teff
    - decimal logarithm of the gravity, : logg
    - surface helium abundance: y_z
    - surface metal abundance: z_s
    - ratio (Z/X) at the surface: zsx_s
    - mean density (M/R^3) : mean_density (in solar unit ; Msun = 1.98919e33 ; Rsun = 6.9599e10 )
    - mean large separation from the scaling law sqrt(GM/R^3): deltanuscl (in muHz ; solar reference: deltanuscl = 135.5 muHz)
    - mean large seperation : largesep . This quantity is derived from theoretical eigenfrequencies computed with ADIPLS. This requires to setup the file adipls.in, an example is given in the package (more details are also given below).

  • value : target value

  • sigma : standard uncertainty associated with the target.

General settings

This is the section named 'settings' of the XML file

  • sub-section 'levmar' : Settings associated with the Levenberg-Marquardt algorithm
    - maxiter : maximum number of iteration
    - chi2min : minimal value of the Chi2. The program will stop when the Chi2 is lower than this value
    - ftol : The program will stop when the relative change in Chi2 is lower than this value

  • sub-section 'models': Settings associated with the model computation
    - dy_dz : adopted value of the slope dY/dZ
    - yp : primordial helium abundance
    - zp : rimordial metal abundance
    - start: starting point of the calculation: 'zams' or 'pms'
    - cf: contraction factor used for the PMS

Running OSM

To execute OSM, type:

osm.py mymodel

If you want that OSM runs independently from your shell (so that you can leave your shell session), type: 

nohup osm.py mymodel &

If you want to receive an email once OSM has finished, type:

nohup osm.py -e your_email mymodel

Mean large separation

The mean large separation can be among the targets. Its name is "largesep". An example named test_largesep.xml is provided in the package.
In addition you must include the following lines in the section <setting> of your .xml file:

<modes>
<l>0,1</l>
<nmin>10</nmin>
<nmax>20</nmax>
<dn>1</dn>
<w2min>-1</w2min>
<w2max>-1</w2max>
</modes>

The mean large separation is computed for a given set of l degrees and a given interval in radial order (nmin,nmax):

  • l : set of l degrees

  • nmin : minimal radial order

  • nmax : maximum radial order

  • dn : tolerance. The mean large separation is computed by shifting the interval by -dn, dn-1, ..., 0, 1 , ...,dn-1, dn In total 2n + 1 values of the mean large separation are obtained. The program adopts the closest value to the specified constraint.

The calculation relies on the theoretical eigenvalues obtained with the ADIPLS code. The behaviours of this program is controlled by a specific configuration file, named adipls.in and provided in the OSM package.
For more details refers to the documentation of ADIPLS. It is important to setup ADIPLS such that the theoretical frequencies cover the specified range in radial order (nmin,nmax).

Diffusion

The inclusion of the microscopic diffusion with CESTAM requires the specification of the helium initial abundance (named y0 in the .don file) and the initial value of the ratio (Z/X) (named zsx0 in the .don file).
OSM can manage the inclusion of the diffusion. You have two possibilities: either to consider both y0 and zsx0 as free parameters, or to consider one or the other as a free parameter. In that latter case you must specify as fixed parameters the slope dY/dZ, the primordial helium abundance yp and the primordial metal abundance zp (see below). This is done by adding the following lines to the section <setting> of your XML file:

<models>
<dy_dz> 2. </dy_dz>
<yp>0.235</yp>
<zp>0.</zp>
<start>zams</start>
<cf>8e-5</cf>
</models>

The parameters involved in the sub-section <models> have the following meaning:

  • dy_dz : adopted value of the slope dY/dZ

  • yp : primordial helium abundance

  • zp : rimordial metal abundance

An example of .xml using y0 and zsx0 as free parameters is given in the XML file named test_diff.xml.
The XML file test_diff2.xml shows an example when zsx0 is a free parameter while y0 is obtained from the slope dY/dZ.

Important remark : to enable to OSM to manage microscopic diffusion, x0 must be set to the value -1 in the .don file.

Seismic constraints

OSM can include seismic constraints derived from a set of individual frequencies. The seismic constraints currently implemented are listed below. Note that OSM takes into account the correlated uncertainties between the seismic constraints (but assumes that the uncertainties on the individual frequencies are not correlated).

The individual frequencies must be listed in an ASCII file, as shown in the file named tablefreq.txt.
The first column specifies the radial order (the absolute value does not matter if the matching is done in terms of frequency, see below), the second one the l degree, the third one the frequency (in microHz) and the last one the associated standard uncertainty.

The seismic constraints are setup in the .xml file in a different way than the other "targets". Indeed, the seismic constraints are controlled by the inclusion of a section named <seismic_constraints>. An example is given in the file named test_seismic.xml. The section <seismic_constraints> has the following structure:

<seismic_constraints>
<file>tablefreq.txt</file>
<types>dnu0,d01</types>
<matching>frequency</matching>
</seismic_constraints>

The parameters involved have the following meaning:

  • file: name of the ASCII file containing the individual mode frequencies

  • matching : procedure followed for matching theoretical frequencies with observed ones:
    - frequency : the matching is made in terms of frequency
    - order: the matching is made in terms of radial order

  • types: list of seismic constraints to include. At the moment, the seismic constraints that can be included are:
    - dnu: the large separation (as a function of frequency) for all the l degrees present in the frequency table, dnu(n) = nu_{n,l} - nu_{n-1,l}
    - dnu0: the large separation of the radial modes only, dnu0(n) = nu_{n,0} - nu_{n-1,0}
    - dnu1: the large separation of the dipole (l=1) modes only, dnu1(n) = nu_{n,1} - nu_{n-1,1}
    - dnu2: the large separation of the quadrupole (l=2) modes only, dnu2(n) = nu_{n,2} - nu_{n-1,2}
    - d01: the small separation d01, d01(n) = nu_{n,0} - ( nu_{n-1,1} + nu_{n,1}) / 2
    - d02: the small separation d02, d02(n) = nu_{n,0} - nu_{n-1,2}
    - sd: second difference (Gough 1990, Houdek & Gough 2007), sd(n) = nu_{n-1,l} - 2 nu_{n,l} + nu_{n+1,l}
    - sd01: second difference "01" (as defined in Eq. (4) of Roxburgh & Vorontsov 2003,A&A), sd01(n) = (1/8) ( nu_{n-1,0} - 4 nu_{n-1,1} + 6 nu_{n,0} - 4 nu_{n,1} + nu_{n+1,0})
    - sd10: second difference "10" (as defined in Eq. (5) of Roxburgh & Vorontsov 2003,A&A), sd10(n) = -(1/8) ( nu_{n-1,1} - 4 nu_{n,0} + 6 nu_{n,1} - 4 nu_{n+1,0} + nu_{n+1,1})
    - rd02: ratio d02(n) / dnu1(n) with dnu1(n) = nu_{n,1} - nu_{n-1,1}
    - rsd01: ratio sd01(n) / dnu1(n) with dnu1(n) = nu_{n,1} - nu_{n-1,1}
    - rsd10: ratio sd10(n) / dnu0(n) with dnu0(n+1) = nu_{n+1,0} - nu_{n,0} (note the difference with dnu1(n))

The seismic constraints are compared to the corresponding combinations of the theoretical eigenvalues obtained with the ADIPLS code. The behavior of this program is controlled by a specific configuration file named adipls.in. This file must be present in your working directory and setup according to your needs.
For more details refers to the documentation of ADIPLS. By default, the correspondence between observed and theoretical frequencies is performed in terms of frequency: for each l degree, the program searches the theoretical frequency that is the closest to the first observed frequency (with same l degree).

Important remarks:

  • the calculation of d01 requires an additional dipole mode

  • it is not possible to have a gap in the radial order

  • It is important to setup ADIPLS such that the theoretical frequencies cover the range of observed frequencies

(c) 2012 by Réza SAMADI, Observatoire de Paris.

20 – December - 2013