A step by step user's guide to cossam

cossam_ff :	codice per la sintesi spettrale nelle atmosfere magnetiche
	code pour la synthèse spectrale dans les atmosphères magnétiques

Contents of the step by step user's guide to cossam_ff
(cossam version for co-rotating grid and force-free field geometries)

Step 1   : Downloading and installing the compiler
Step 2   : Downloading the code
Step 3   : Splitting (chopping) the code
Step 4   : Compiling the code
Step 5   : Establishing the line data files
Step 6A : Calculating stellar Stokes spectra : generalised dipole
Step 6B : Calculating stellar Stokes spectra : spherical harmonics
Step 7   : Understanding the output and visualising the magnetic geometry

A step by step user's guide to cossam_ff and lines (version 2022-08-25)

Step 1 : Downloading and installing the compiler

A recent free 32-bit or 64-bit GNAT compiler may be obtained from the AdaCore site
or any of the numerous Linux distributions.
Step 2 : Downloading the code and the data files
The following files are required for the calculation of a sample Stokes spectrum
- colin_2022-08-25.ada
- lines.inp
- cossam_dipo.inp (for a generalised dipole)
- cossam_igrf.inp (for spherical harmonics)
- grev_sau.abund.orig (abundance file)
- HD326_lines.list (line list taken from Kurucz)
- t12000_400_1000G_0d.fil (atmospheric file provided by atlas12_ada)
Step 3 : Splitting (chopping) the code

The file colin_2022-08-25.ada contains many packages, procedure and functions.
GNAT users have to split (gnatchop) this file, because GNAT requires different
compilation units to be in different files.

The following command will split the file: gnatchop -w colin_2022-08-25.ada

Note: The -w option overwrites existing files.
Step 4 : Compiling the code

After splitting (gnat-chopping) colin_2022-08-25.ada you have to create the executables
lines and cossam by issuing the following 2 commands:

     gnatmake -O3 -gnatfvp lines
     gnatmake -O3 -gnatfvp cossam_ff

Note: In order to be able to execute lines or cossam_ff, make sure that your system

       provides unlimited stacksize. With the tcsh shell for example set

       "limit stacksize unlimited"

Step 5 : Establishing the line data files

One has now to create the auxiliary files containing the atomic line data; this is done by invoking

./lines lines.inp

lines_run.2062167039	log file
sysom_ess.2062167039	essential model and abundance data
sysom_line.2062167039	data for all the selected lines
sysom_stream.2062167039	binary line data

would be line data and log files created by lines on 2022-06-21 18:37

What you have to specify in the input file lines.inp

Number of processors
Atmospheric model file
Atomic transition list file

Zeeman splitting option

'-'

Lande factors as given in the line file; set to unity if unknown (=99.00)

Hydrogen option

'h' or 'H'	Hydrogen line profiles according to the analytical formula of Hubeny
'-'	No hydrogen lines considered

Lower-upper level limit

'0.6667'

leave unchanged

Stark option

'a', 'A'	Stark broadening according to Gonzalez et al. 1995, A&A, 297, 223
'v', 'V'	Stark broadening as given in the atomic transition list file; zero if not listed
'n', 'N'	Stark broadening set zo zero and Unsoeld van der Waals broadening

Line strength option

'-'

Oscillator strengths log gf as given in the line file

Partition functions (4-character string)

'KCIB'

cossam uses the Kurucz partition functions from Atlas, leave unchanged

Lower limit in lambda (in Angstroms)
Upper limit in lambda (in Angstroms)
Rel. line opacity contr. limit (typically 0.001 or 0.0005) :
a line is only considered if the ratio (central line opacity) / (cont. opacity)
exceeds this limit at any one optical depth
Microturbulence (in km/s)
Abundance file name
The input file has to end with FIN

Step 6A : Calculating stellar Stokes spectra with cossam_ff (generalised dipole)

Step a : The generalised dipole option (with co-rotating grid) of the code is invoked by

./cossam_ff input_file sysom_ess_extension

input_file	sysom_ess_extension
Any arbitrary name is permitted, e.g. cossam_dipo.inp	the 10-digit extension of the line data files created with lines

Step b : What you have to specify in the input file cossam_dipo.inp

Number of processors (cores)
Sub-Interval size
Atmospheric model file

Polarised formal solver option

'Z'	Zeeman Feautrier solver (default)
'z'	Zeeman Feautrier solver without magneto-optical terms

Hydrogen option (must agree with the values given in 'lines.inp')
cossam_ff checks for contradictions. You may only exchange 'h' for 'H' and vice versa

'h' or 'H'	Hydrogen line profiles according to the analytical formula of Hubeny
'-'	No hydrogen lines considered

Lower limit in lambda (in Angstroms)
Upper limit in lambda (in Angstroms)
Step size in lambda (in Angstroms) or in velocity (in km/s)
Abundance file name

Line selection file name

'file_name'	The spectrum is synthesised only over intervals of +- 1.50 Angstroem centred on each line listed in this file, located between the lower and the upper limit in lambda.
'-'	no such selection, the spectrum is synthesised for the whole spectral region located between the lower and the upper limit in lambda.

Finally there is the keyword DIPOLE (dipole), followed by the Oblique Rotator Model data - for their definition see

Stift, MNRAS 172, 133 (1975) - and the grid data

The inclination i    (in degrees)
The 3 Eulerian angles alpha, beta, gamma    (in degrees)
The decentring parameters y_2 and y_3   [-1 < y_2 < 1, -1 < y_3 < 1]

The dipole moment - half the polar field strength for a centred dipole (in Gauss)
The projected rotational velocity v sin i (in km/s)
The number of rings
(permitted values are : 6, 8, 9, 10, 12, 15, 18, 20, 24, 25, 30, 36, 40, 45, 50, 60, 72, 75, 90)

No. of rings	No. of surface elements
8	80
15	284
24	732
40	2034
90	10310

The number of rotational phases
The rotational phases [0 <= Phase_rot < 1]
(there can be only 10 phases per line; 25 phases for example have to be specified on 3 lines)

Step 6B : Calculating stellar Stokes spectra with cossam_ff (spherical harmonics)

Step a : The spherical harmonics option (with co-rotating grid) of the code is invoked by

./cossam_ff input_file sysom_ess_extension

input_file	sysom_ess_extension
Any arbitrary name is permitted, e.g. cossam_igrf.inp	the 10-digit extension of the line data files created with lines

Step b : What you have to specify in the input file cossam_igrf.inp

Number of processors (cores)
Sub-Interval size
Atmospheric model file

Polarised formal solver option

'Z'	Zeeman Feautrier solver (default)
'z'	Zeeman Feautrier solver without magneto-optical terms

Hydrogen option (must agree with the values given in 'lines.inp')
cossam_ff checks for contradictions. You may only exchange 'h' for 'H' and vice versa

'h' or 'H'	Hydrogen line profiles according to the analytical formula of Hubeny
'-'	No hydrogen lines considered

Lower limit in lambda (in Angstroms)
Upper limit in lambda (in Angstroms)
Step size in lambda (in Angstroms) or in velocity (in km/s)
Abundance file name

Line selection file name

'file_name'	The spectrum is synthesised only over intervals of +- 1.50 Angstroem centred on each line listed in this file, located between the lower and the upper limit in lambda.
'-'	no such selection, the spectrum is synthesised for the whole spectral region located between the lower and the upper limit in lambda.

Finally there is the keyword IGRF (igrf), followed by the grid data and the Gauss coefficients -
for their definition see "International Geomagnetic Reference Field: the thirteenth generation".
cossam_ff uses Schmidt semi-normalised associated Legendre functions of degree L and order M.

The inclination i (in degrees)
The projected rotational velocity v sin i (in km/s)
The number of rings
(permitted values are : 6, 8, 9, 10, 12, 15, 18, 20, 24, 25, 30, 36, 40, 45, 50, 60, 72, 75, 90)

No. of rings	No. of surface elements
8	80
15	284
24	732
40	2034
90	10310

The number of modes

The modes

glm hlm L M

Gauss coeff. degree order

The number of rotational phases
The rotational phases [0 <= Phase_rot < 1]
(there can be only 10 phases per line; 25 phases for example have to be specified on 3 lines)

Step 7 : Understanding the output and visualising the magnetic geometry

The results of the calculations are written into the file(s)
: cosdipo_pprof.[phase-number][10-digits-extension] for the generalised dipole case
cosigrf_pprof.[phase-number][10-digits-extension] for the spherical harmonics case
: There are 6 columns:
:       wavelength (in Angstroms)
      Stokes I
      Stokes Q
      Stokes U
      Stokes V
Continuum; cossam_ff writes a log file with a copy of the input file and the abundance file. You also
           find the values of the "effective field" H_e and "surface field" H_s for each phase.

     ./cossam_ff cossam_dipo.inp sysom_ess_extension   => cossam_run.[10-digits-extension]
     ./cossam_ff cossam_igrf.inp sysom_ess_extension   => cossam_run.[10-digits-extension]

cossam_ff also creates a file containing the data required for visualisation

cossam_dipo_eps.2062167053 for the generalised dipole case
cossam_igrf_eps.2062167078 for the spherical harmonics case

hammer_field_orient_contour visualises the magnetic geometry by providing an
equal area Hammer projection of magnetic field strength and field direction.

Please make sure that the files libpghelp.a and libpgplot.a have been downloaded
before proceeding to compile the code with

gnatmake -O3 -gnatfvp hammer_field_orient_contour

The command ./hammer_field_orient_contour gives instructions how to use the code

  Hammer
                        projection of magnetic field and of orientation
                        
                         No arguments : 4 

                             Argument(1) :
                        [ext] of cossam_dipo_eps or 

                               [ext] of
                        cossam_igrf_eps 

                             Argument(2) :
                        inclination 

                        (to avoid plotting invisible parts) 

                             Argument(3) :
                        half-width of smoothing window 

                             Argument(4) :
                        number of contours 

                         creates file 'field_angle.[ext].c.eps'
                        when number /= 0 

                         creates file
                        'field_angle.[ext].eps'   when
                        number  = 0

Try for example ./hammer_field_orient_contour 2010351930 80 8 10
or ./hammer_field_orient_contour 2010351918 80 1 0

Contents of the file lines.inp

Contents of the file lines_run.2062167039

Data start at line 4, col 35    : !
=== Comment :
--------------------------------:
No. of processors               : 1
Atmospheric model               : t12000_400_1000G_0d.fil
List of spectral lines          : HD326_lines.list
Zeeman splitting option         : -
Hydrogen option                 : -
lower-upper level limit         : 0.6666667
Stark option                    : A
Line strength option            : -
Partition function preferences : KCIB
Lower limit in lambda [A]       : 4250.0
Upper limit in lambda [A]       : 5200.0
Rel. line opacity contr. limit : 0.001
Microturbulence [km/s]          : 0.0
Element file                    : grev_sau.abund.orig
                                : FIN

Lines version                  : 20-06-2022
version produced by this run    : 2062167039
date                            : 21-06-2022 18:37:19

1 H   12.00    1.008 2   : -
2 He 10.93    4.00 3   : -
3 Li   1.10    6.94 4   : -
4 Be   1.40    9.02 4   : -
5 B    2.55   10.82 4   : -
6 C    8.52   12.01 6   : -
7 N    7.92   14.01 6   : -
8 O    8.83   16.00 6   : -
....
20 Ca   6.36   40.08 5   : -
21 Sc   3.17   45.10 5   : -
22 Ti   5.02   47.90 5   : -
23 V    4.00   50.95 5   : -
24 Cr   5.67   52.01 5   : -
25 Mn   5.39   54.93 5   : -
26 Fe   7.50   55.85 5   : + 7.50
27 Co   4.92   58.94 5   : -
....
91 Pa   0.01 231.00 3   : -
92 U    0.01 238.10 3   : -
------------------------------

Contents of the file sysom_ess.2062167039

ZS A KCIB
t12000_400_1000G_0d.fil
HD326_lines.list
2062167039
12000.0 4.000 0.07833 0.00
9 44 45 102 514 90 4250.000 5200.000
12.000 12.000 12.000 12.000 12.000 12.000 12.000 12.000 12.000 12.000 12.000 12.000 ....
....

Contents of the file sysom_line.2062167039

   Teff        Log g       He/H
12000.0       4.000       0.078
Microturb. = 0.00 (km/sec)
4290.219 Ti 2 5.020 -0.930 1.165 1.5 2.5 1.74 1.37 1.09   2.891 15.478 31.300 2.262E+01
4563.761 Ti 2 5.020 -0.790 1.221 0.5 1.5 0.66 0.92 0.99   1.648 15.551 31.415 2.976E+01
4558.650 Cr 2 5.670 -0.449 4.073 4.5 3.5 1.33 1.43 1.16   2.570 15.438 31.420 1.319E+02
4588.199 Cr 2 5.670 -0.627 4.071 3.5 2.5 1.24 1.38 1.06   2.570 15.465 31.420 8.806E+01
4824.127 Cr 2 5.670 -0.970 3.871 4.5 4.5 1.34 1.34 1.34   2.553 15.428 31.348 5.460E+01
4583.837 Fe 2 7.500 -1.860 2.807 4.5 3.5 1.31 1.40 1.15   4.121 15.480 31.378 6.693E+02
4923.927 Fe 2 7.500 -1.320 2.891 2.5 1.5 2.00 2.40 1.70   3.083 15.355 31.297 2.129E+03
5018.440 Fe 2 7.500 -1.220 2.891 2.5 2.5 2.00 1.87 1.93   3.062 15.359 31.297 2.705E+03
5169.033 Fe 2 7.500 -1.303 2.891 2.5 3.5 2.00 1.70 1.33   3.048 15.363 31.297 2.267E+03

Contents of the file cossam_dipo.inp

Contents of the file cossam_igrf.inp

Data start at line 4, col 35    : !
=== Comment :
--------------------------------:
No. of processors               : 6
Interval size in [A]            : 0.100
Atmospheric model               : t12000_400_1000G_0d.fil
Formal solver option            : Z
Hydrogen option                 : -
Lower limit in lambda [A]       : 5018.140
Upper limit in lambda [A]       : 5018.740
Step size in lambda   [A]       : 0.010
Abundance file                  : grev_sau.abund.orig
Line selection file             : -
                                : IGRF
Incl Vrot No_rings            : 80.0   5.0   75
No. of modes                    : 20
glm hlm phi_0 L M           :   2417.0         0.0      1 0
glm hlm phi_0 L M           :   1236.0      1277.0      1 1
glm hlm phi_0 L M           :    641.6         0.0      2 0
glm hlm phi_0 L M           :    224.8      -207.2      2 1
glm hlm phi_0 L M           :    232.3      -224.8      2 2
glm hlm phi_0 L M           :     80.1         0.0      3 0
glm hlm phi_0 L M           :     24.84     -122.1      3 1
glm hlm phi_0 L M           :      2.94      -52.8      3 2
glm hlm phi_0 L M           :    -32.34      -33.42     3 3
glm hlm phi_0 L M           :      0.24        0.0      4 0
glm hlm phi_0 L M           :      1.08      -25.74     4 1
glm hlm phi_0 L M           :    -12.18       -7.98     4 2
glm hlm phi_0 L M           :     -9.00       -3.42     4 3
glm hlm phi_0 L M           :     -4.38        4.26     4 4
glm hlm phi_0 L M           :     -3.78        0.0      5 0
glm hlm phi_0 L M           :     -0.24       -2.76     5 1
glm hlm phi_0 L M           :     -3.78       -0.78     5 2
glm hlm phi_0 L M           :     -1.62        0.90     5 3
glm hlm phi_0 L M           :     -0.72        1.32     5 4
glm hlm phi_0 L M           :      0.54        0.54     5 5
No. of rotational phases       : 10
Rotational phases [0<=phi<=1] : 0.0 0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9
                                : FIN

Profile files obtained with options "dipole" or "igrf"

cosdipo_pprof_r07.2062167053 (created 2022-06-21 18:37)
cosigrf_pprof_r03.2062167078 (created 2022-06-21 18:38)
Sub-interval size

A good choice for the sub-interval size is <= 1.000 Angstroms. The total interval size must be a multiple of the sub-interval size.

When synthesising a spectrum over a large interval, using a large number of processors, a sub-interval size of 1.000 Angstroms tends to ensure good load balance. Narrow intervals and many processors may require 0.500 Angstroms or less. In any case you have to make sure that every processor calculates at least 1 sub-interval.

The abundance file

The abundances in the abundance file are logarithmic with the abundance of hydrogen = 12.00).

1 H   12.00    1.008 2   : -
2 He 10.93    4.00 3   : -
,,,,
11 Na   6.33   23.00 6   : -
12 Mg   7.58   24.32 6   : -
13 Al   6.47   26.97 6   : -
14 Si   7.55   28.06 6   : -
15 P    5.45   30.98 6   : -
....
19 K    5.12   39.10 5   : -
20 Ca   6.36   40.08 5   : -
21 Sc   3.17   45.10 5   : -
22 Ti   5.02   47.90 5   : -
23 V    4.00   50.95 5   : -
24 Cr   5.67   52.01 5   : - Cr.noc
25 Mn   5.39   54.93 5   : -
26 Fe   7.50   55.85 5   : - 7.50
27 Co   4.92   58.94 5   : -
....

All elements are listed with:
atomic number, element symbol, solar abundance, atomic weight,
number of ionisation stages considered.

To specify a different constant abundance over optical depth,
enter the new value after the '-' (preceded by a blank).

To specify a different non-constant abundance over optical depth,
enter the name of a file after the '-' (preceded by a blank).
The file must contain an abundance value for each optical depth.

There must be no blanks following the '-' or the new abundances

The atmospheric model file

The atmospheric input file for a Kurucz model (provided by atlas12_ada) with T_eff = 12000 K, log_g = 4.00,
solar abundances, and 90 depth points look as follows:

90
12000.0     4.000    0.07833
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
1.017E-05 2.8840E-06 0.6839 -1.3282 -0.9954   24.2253 ....
1.232E-05 3.5043E-06 0.6814 -1.2464 -0.9123   24.2255 ....
1.498E-05 4.2581E-06 0.6783 -1.1628 -0.8274   24.2250 ....
1.820E-05 5.1739E-06 0.6747 -1.0794 -0.7430   24.2238 ....
2.209E-05 6.2868E-06 0.6707 -0.9962 -0.6589   24.2217 ....
2.679E-05 7.6390E-06 0.6664 -0.9132 -0.5750   24.2188 ....
3.246E-05 9.2820E-06 0.6619 -0.8305 -0.4917   24.2151 ....
3.929E-05 1.1278E-05 0.6573 -0.7482 -0.4089   24.2105 ....
4.749E-05 1.3704E-05 0.6526 -0.6664 -0.3266   24.2049 ....
5.731E-05 1.6652E-05 0.6480 -0.5853 -0.2450   24.1984 ....
6.905E-05 2.0233E-05 0.6432 -0.5047 -0.1641   24.1909 ....
  .....

M_dep
T_eff, log_g, He

rho_x, tau, theta,
log_pe, log_pg,
log_k

M_dep

T_eff
log_g
He
rho_x
tau
theta
log_pe
log_pg
log_k

Number of depth points
M_dep must be negative if there are no columns with H and He number densities
M_dep must be positive if there are these columns
effective temperature
logarithm of gravity
He abundance (by number)
column mass
optical depth at 5000 A
reciprocal temperature 5040 / T
logarithm of electron pressure
logarithm of gas pressure
scaled logarithm of continuous opacity at 5000 A

The atomic transition list file

The atomic transitions are taken from the VALD database (or from the Kurucz CD).
The file must have the following format:

4290.219 22.01 -0.930   1.165 1.5   4.054 2.5 1.74 1.37 1.09 8.461 -6.665 -7.915 d3 a4P    (3F)4p z4D
4563.761 22.01 -0.790   1.221 0.5   3.937 1.5 0.66 0.92 0.99 8.217 -6.713 -7.961 d3 a2P    (3F)4p z2D
4558.650 24.01 -0.449   4.073 4.5   6.792 3.5 1.33 1.43 1.16 8.410 -6.638 -7.963         1|4F3)       1
4588.199 24.01 -0.627   4.071 3.5   6.773 2.5 1.24 1.38 1.06 8.410 -6.656 -7.963         1|4F3)       1
4824.127 24.01 -0.970   3.871 4.5   6.440 4.5 1.34 1.34 1.34 8.407 -6.631 -7.934       2|3F4)4F       1
4583.837 26.01 -1.860   2.807 4.5   5.511 3.5 1.31 1.40 1.14 8.615 -6.666 -7.946       2|3F4)4F       1
4923.927 26.01 -1.320   2.891 2.5   5.408 1.5 2.00 2.40 1.69 8.489 -6.583 -7.914       3|6S5)6S       1
5018.440 26.01 -1.220   2.891 2.5   5.361 2.5 2.00 1.87 1.93 8.486 -6.585 -7.914       3|6S5)6S       1
5169.033 26.01 -1.303   2.891 2.5   5.289 3.5 2.00 1.70 1.33 8.484 -6.588 -7.914       3|6S5)6S       1
....

Alam0 Isym Algf Chi_low J_low Chi_up J_up g_low g_up g_eff Rad Alc4 Alc6 Dummy_string

  Alam0  

                    Isym  

                    Algf  

                    Chi_low  

                    J_low  

                    Chi_up  

                    J_up  

                    g_low  

                    g_up  

                    g_eff  

                    Rad  

                    Alc4  

                    Alc6  

                    Dummy_string

 
                  wavelength  

                    element symbol  

                    oscillator strength log_gf  

                    excitation potential of lower level  

                    J value of lower level  

                    excitation potential of upper level  

                    J value of upper level  

                    Lande factor of lower
                  level          
                  (99.00 means unknown) 

                    Lande factor of upper
                  level          
                  (99.00 means unknown) 

                    "effective" Lande
                  factor        
                       (99.00 means unknown)
                  

                    radiation damping constant   
                          (0.000
                    means unknown) 

                    constant for Stark effect   
                           (0.000 means
                    unknown) 

                    constant for van der Waals broadening (0.000
                    means unknown) 

                    extra information on transition 

                

Line selection file

It is recommended to use part of the output contained in sysom_line.[10-digit-extension]
for line selection, e.g.

4563.761 Ti 2 5.020 -0.790 1.221 0.5 1.5 0.66 0.92 0.99   1.648 15.551 31.415 2.976E+01
4558.650 Cr 2 5.670 -0.449 4.073 4.5 3.5 1.33 1.43 1.16   2.570 15.438 31.420 1.319E+02
4923.927 Fe 2 7.500 -1.320 2.891 2.5 1.5 2.00 2.40 1.70   3.083 15.355 31.297 2.129E+03

but any list containing just the wavelengths of the lines to be synthesised will do it.

Back to the cossam_ff page