eos module InterfaceΒΆ

The primary entry point to the eos module is through the routine eosDT_get. Broadly, one provides the density, temperature and full composition information. Then the EOS returns its main set of results, their temperature and density derivatives, and the composition derivatives of a small subset of the results.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
      subroutine eosDT_get( &
               handle, species, chem_id, net_iso, xa, &
               Rho, logRho, T, logT, &
               res, d_dlnd, d_dlnT, d_dxa, ierr)
         use eos_def
         use eosDT_eval, only: Get_eosDT_Results
         use chem_lib, only: basic_composition_info
         integer, intent(in) :: handle ! eos handle; from star, pass s% eos_handle
         integer, intent(in) :: species ! number of species
         integer, pointer :: chem_id(:) ! maps species to chem id
         integer, pointer :: net_iso(:) ! maps chem id to species number
         real(dp), intent(in) :: xa(:) ! mass fractions         
         real(dp), intent(in) :: Rho, logRho ! the density
         real(dp), intent(in) :: T, logT ! the temperature         
         real(dp), intent(inout) :: res(:) ! (num_eos_basic_results)         
         real(dp), intent(inout) :: d_dlnd(:) ! (num_eos_basic_results) 
         real(dp), intent(inout) :: d_dlnT(:) ! (num_eos_basic_results)
         real(dp), intent(inout) :: d_dxa(:,:) ! (num_eos_d_dxa_results,species)
         integer, intent(out) :: ierr ! 0 means AOK.
         real(dp), allocatable :: d_dxa_eos(:,:) ! eos internally returns derivs of all quantities
         type (EoS_General_Info), pointer :: rq
         real(dp) :: X, Y, Z, abar, zbar, z2bar, z53bar, ye, mass_correction, sumx
         call get_eos_ptr(handle,rq,ierr)
         if (ierr /= 0) then
            write(*,*) 'invalid handle for eos_get -- did you call alloc_eos_handle?'
            return
         end if
         call basic_composition_info( &
            species, chem_id, xa, X, Y, Z, &
            abar, zbar, z2bar, z53bar, ye, mass_correction, sumx)
         allocate(d_dxa_eos(num_eos_basic_results, species))
         call Get_eosDT_Results( &
            rq, Z, X, abar, zbar, &
            species, chem_id, net_iso, xa, &
            Rho, logRho, T, logT, &
            res, d_dlnd, d_dlnT, d_dxa_eos, ierr)
         ! only return 1st two d_dxa results (lnE and lnPgas) to star
         d_dxa(1:num_eos_d_dxa_results,1:species) = d_dxa_eos(1:num_eos_d_dxa_results, 1:species)
      end subroutine eosDT_get

The underlying EOS is in a density-temperature basis, but if one has only density or temperature, there are search interfaces (eosDT_get_Rho and eosDT_get_T) for searching for the other, given some another known EOS quantity (e.g., lnE).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
      subroutine eosDT_get_T( &
               handle, &
               species, chem_id, net_iso, xa, &
               logRho, which_other, other_value, &
               logT_tol, other_tol, max_iter, logT_guess, &
               logT_bnd1, logT_bnd2, other_at_bnd1, other_at_bnd2, &
               logT_result, res, d_dlnRho_const_T, d_dlnT_const_Rho, &
               d_dxa_const_TRho, eos_calls, ierr)

         ! finds log10 T given values for density and 'other', and initial guess for temperature.
         ! does up to max_iter attempts until logT changes by less than tol.

         ! 'other' can be any of the basic result variables for the eos
         ! specify 'which_other' by means of the definitions in eos_def (e.g., i_lnE)

         use chem_lib, only: basic_composition_info
         use eos_def
         use eosDT_eval, only : get_T

         integer, intent(in) :: handle ! eos handle; from star, pass s% eos_handle

         integer, intent(in) :: species ! number of species
         integer, pointer :: chem_id(:) ! maps species to chem id
            ! index from 1 to species
            ! value is between 1 and num_chem_isos
         integer, pointer :: net_iso(:) ! maps chem id to species number
            ! index from 1 to num_chem_isos (defined in chem_def)
            ! value is 0 if the iso is not in the current net
            ! else is value between 1 and number of species in current net
         real(dp), intent(in) :: xa(:) ! mass fractions

         real(dp), intent(in) :: logRho ! log10 of density
         integer, intent(in) :: which_other ! from eos_def.  e.g., i_lnE
         real(dp), intent(in) :: other_value ! desired value for the other variable
         real(dp), intent(in) :: other_tol

         real(dp), intent(in) :: logT_tol
         integer, intent(in) :: max_iter ! max number of iterations

         real(dp), intent(in) :: logT_guess ! log10 of temperature
         real(dp), intent(in) :: logT_bnd1, logT_bnd2 ! bounds for logT
            ! if don't know bounds, just set to arg_not_provided (defined in const_def)
         real(dp), intent(in) :: other_at_bnd1, other_at_bnd2 ! values at bounds
            ! if don't know these values, just set to arg_not_provided (defined in const_def)

         real(dp), intent(inout) :: logT_result ! log10 of temperature
         real(dp), intent(inout) :: res(:) ! (num_eos_basic_results)
         real(dp), intent(inout) :: d_dlnRho_const_T(:) ! (num_eos_basic_results)
         real(dp), intent(inout) :: d_dlnT_const_Rho(:) ! (num_eos_basic_results)
         real(dp), intent(inout) :: d_dxa_const_TRho(:,:) ! (num_eos_d_dxa_results, species)
         real(dp), allocatable :: d_dxa_eos(:,:) ! eos internally returns derivs of all quantities

         integer, intent(out) :: eos_calls
         integer, intent(out) :: ierr ! 0 means AOK.

         ! compute composition info
         real(dp) :: Y, Z, X, abar, zbar, z2bar, z53bar, ye, mass_correction, sumx

         call basic_composition_info( &
            species, chem_id, xa, X, Y, Z, &
            abar, zbar, z2bar, z53bar, ye, mass_correction, sumx)

         allocate(d_dxa_eos(num_eos_basic_results, species))

         call get_T( &
               handle, Z, X, abar, zbar, &
               species, chem_id, net_iso, xa, &
               logRho, which_other, other_value, &
               logT_tol, other_tol, max_iter, logT_guess, &
               logT_bnd1, logT_bnd2,  other_at_bnd1, other_at_bnd2, &
               logT_result, res, d_dlnRho_const_T, d_dlnT_const_Rho, &
               d_dxa_eos, eos_calls, ierr)
         ! only return 1st two d_dxa results (lnE and lnPgas) to star
         d_dxa_const_TRho(1:num_eos_d_dxa_results,1:species) = d_dxa_eos(1:num_eos_d_dxa_results, 1:species)

         deallocate(d_dxa_eos)

      end subroutine eosDT_get_T

For legacy reasons, there is also an eosPT_get entry point. (The same result could ultimately be achieved via eosDT_get_Rho.) Internally, this is also implemented as a root-find using the standard density-temperature EOS.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
      subroutine eosPT_get( &
               handle, &
               species, chem_id, net_iso, xa, &
               Pgas, log10Pgas, T, log10T, &
               Rho, log10Rho, dlnRho_dlnPgas_const_T, dlnRho_dlnT_const_Pgas, &
               res, d_dlnRho_const_T, d_dlnT_const_Rho, &
               d_dxa_const_TRho, ierr)

         use chem_lib, only: basic_composition_info
         use eos_def
         use eosPT_eval, only: Get_eosPT_Results

         ! INPUT

         integer, intent(in) :: handle ! eos handle; from star, pass s% eos_handle

         integer, intent(in) :: species ! number of species
         integer, pointer :: chem_id(:) ! maps species to chem id
            ! index from 1 to species
            ! value is between 1 and num_chem_isos
         integer, pointer :: net_iso(:) ! maps chem id to species number
            ! index from 1 to num_chem_isos (defined in chem_def)
            ! value is 0 if the iso is not in the current net
            ! else is value between 1 and number of species in current net
         real(dp), intent(in) :: xa(:) ! mass fractions

         real(dp), intent(in) :: Pgas, log10Pgas ! the gas pressure
            ! provide both if you have them.  else pass one and set the other to arg_not_provided
            ! "arg_not_provided" is defined in mesa const_def

         real(dp), intent(in) :: T, log10T ! the temperature
            ! provide both if you have them.  else pass one and set the other to arg_not_provided

         ! OUTPUT

         real(dp), intent(out) :: Rho, log10Rho ! density
         real(dp), intent(out) :: dlnRho_dlnPgas_const_T
         real(dp), intent(out) :: dlnRho_dlnT_const_Pgas

         real(dp), intent(inout) :: res(:) ! (num_eos_basic_results)

         ! partial derivatives of the basic results

         real(dp), intent(inout) :: d_dlnRho_const_T(:) ! (num_eos_basic_results)
         ! d_dlnRho_const_T(i) = d(res(i))/dlnd|T,X where X = composition
         real(dp), intent(inout) :: d_dlnT_const_Rho(:) ! (num_eos_basic_results)
         ! d_dlnT_const_Rho(i) = d(res(i))/dlnT|Rho,X where X = composition
         real(dp), intent(inout) :: d_dxa_const_TRho(:,:) ! (num_eos_d_dxa_results, species)
         ! d_dxa_const_TRho(i) = d(res(i))/X|T,Rho,X where X = composition

         real(dp), allocatable :: d_dxa_eos(:,:) ! eos internally returns derivs of all quantities

         integer, intent(out) :: ierr ! 0 means AOK.

         type (EoS_General_Info), pointer :: rq

         real(dp) :: X, Y, Z, abar, zbar, z2bar, z53bar, ye, mass_correction, sumx

         call get_eos_ptr(handle,rq,ierr)
         if (ierr /= 0) then
            write(*,*) 'invalid handle for eos -- did you call alloc_eos_handle?'
            return
         end if

         call basic_composition_info( &
            species, chem_id, xa, X, Y, Z, &
            abar, zbar, z2bar, z53bar, ye, mass_correction, sumx)

         allocate(d_dxa_eos(num_eos_basic_results, species))

         call Get_eosPT_Results( &
                  rq, Z, X, abar, zbar, &
                  species, chem_id, net_iso, xa, &
                  Pgas, log10Pgas, T, log10T, &
                  Rho, log10Rho, dlnRho_dlnPgas_const_T, dlnRho_dlnT_const_Pgas, &
                  res, d_dlnRho_const_T, d_dlnT_const_Rho, d_dxa_eos, &
                  ierr)
         ! only return 1st two d_dxa results (lnE and lnPgas) to star
         d_dxa_const_TRho(1:num_eos_d_dxa_results,1:species) = d_dxa_eos(1:num_eos_d_dxa_results, 1:species)

      end subroutine eosPT_get