##2.1 How to prepare your chemical network ##

To include the microphysics in your simulation by employing KROME you need to start with a chemical network which contains the chemical processes and the species which you want to evolve within your code. KROME generates the FORTRAN files from a network_file by typing the following command:

./krome -n network_file

where network_file is the file containing the chemical reactions in KROME's format, i.e. a Comma-Separated Values (CSV) with the following default format:

idx,R,R,R,P,P,P,P,Tmin,Tmax,rate

where idx is the reaction index (integer), R is a reactant (string), P a product (string), Tmin and Tmax the temperature limits of the reaction (double), and rate the rate coefficient written in FORTRAN style (string). For example the reaction O + C3O -> CCO + CO has:

3489,O,C3O,,CCO,CO,,,1.d1,1d4,5.d-12*exp(-9.d2/Tgas)

The rate coefficients are always expressed in units of :math:cm^{3(n-1)}s^{-1} where n is the number of reactants or in 1/s for photo-processes.

KROME already employs pre-built networks that can be used for different applications but the user is free to prepare its own network_file which better fits with a specific astrophysical application. To create a network_file KROME provides a series of useful token that start with the symbol @. Here following the main token and some example.

2.1.1 Tokens

To increase the flexibility of KROME there are some tokens that can be added to the network file. They are listed here and discussed in the next subsections.

@format

@var

@common

@noTabNext, @noTab_start and @noTab_end

@CR_start and @CR_stop

@Xray_start and @Xray_stop

@photo_start and @photo_stop

@ghost

@tabvar

@reactionModifier_start and @reactionModifier_stop

@ODEModifier_start and @ODEModifier_stop

@cooling_start and @cooling_stop

@heating_start and @heating_stop

@next_solomon

- format

@format is very flexible and can be easily used in many ways. As stated above the default format is

idx,R,R,R,P,P,P,P,Tmin,Tmax,rate

that can be used even if a reaction involves less than three/four reactants/products. In the latter case the user should leave blank the field. For instance

65,HOC+,H2,,HCO+,H2,,,NONE,NONE,3d-10

However, the user can change it if the number of reactants/products are less or if the rate is temperature-independent. For instance, instead of three reactants and three products you can specify two reactants and two products as the following, just before the reaction:

@format:idx,R,R,P,P,Tmin,Tmax,rate
65,HOC+,H2,HCO+,H2,NONE,NONE,3d-10

which simplify the preparation of the network_file.

Often reactions involve a photon (in KROME this is not considered as a species): in this case it is possible to write simplified format for a reaction like H + g --> H+ + E:

@format:idx,R,P,P,rate
223,H,H+,E,2.19e-12*exp(-1.14e4*user_Av)

Note that if you don't want to specify the temperature range you can use the NONE keyword, as shown before.

The format is enabled until a new @format token is found, e.g. in the case

@format:idx,R,P,P,rate
227,H3+,H2,H+,4.9d-13*exp(-1.8*user_Av)
228,H3+,H2+,H,4.9d-13*exp(-2.3*user_Av)
229,C,C+,E,3.1d-10*exp(-3.*user_Av)
230,C-,C,E,2.4d-7*exp(-.9*user_Av)

all the reactions share format specified at the beginning with @format.

- var

Some reaction rates have tricky/ugly mathematical expressions. The token @var can be used to define variables involved in the rate expression. For example:

@var:u1 = 11.26d0*invTe
46,C,E,,C+,E,E,,2.73d0,1d8,6.85d-8*u1**0.25*exp(-u1)/(0.193d0+u1)

where ul is defined with an in-line statement. This token becomes very useful for rates which depend on complex functions, e.g. self-shielding, or which involve an external function. For example a rate which depends on the self-shielding can be expressed as:

@var: user_H2self = fselfH2(1.87d21*(n(idx_H2)*1d-3)**(2./3.), 1d5)
226,H2,H,H,5.6d-11*exp(-3.74*user_Av)*user_H2self

where fselfH2(args) will be a function defined by the user.

Note that all the variables included as @var will be automatically defined as double (real*8) in the FORTRAN routine krome_subs that contains the rates. In the current version of KROME only double are permitted.

- common

A very useful feature of KROME is the definition of common variables into the network_file. Rates which depend on very common physical quantities like redshift, extinction coefficient, cosmic ray rate, and so on, need to get the corresponding value from the main code (e.g. RAMSES, Enzo, FLASH...). Introducing these variables by using the token @common allow to automatically define them as double in KROME.

@common: user_crate,user_Av,user_Tdust

Note that all the common should start with user_ to avoid internal conflicts. A value can be subsequently assigned from the framework code by using the user functions provided by KROME. For example user_crate can be defined using

call krome_set_user_crate(1.3d-17)

or returned with

mycr = krome_get_user_crate()

Do not forget to include the module

use krome_user

- noTabNext, noTab_start, and noTab_end

KROME has the capability to tabulate rates to speed-up the calculations, especially in 3D runs. To allow the creation of tables the user should activate the option -useTabs

./krome -n network_file -useTabs

KROME creates tables only for rates which depend on the gas temperature, i.e. k(Tgas). However, there are many rates which are density-dependent or which in general depend on other variables than temperature (e.g. rate coefficients that depend on partial pressure, like some reactions in planet atmosphere). In these specific cases the rates can't be tabulated and the user should specify that in the network_file to avoid error at the runtime. To do this the user can employ the @noTabNext token. For instance

@noTabNext
17,H2,H,,H,H,H,,NONE,NONE,dissH2_Martin96(n,Tgas)

where dissH2_Martin96(n,Tgas) is a function which evaluates the collisional induced dissociation rates of H2 which depends on density and can't be tabulated. In a similar way the user can define a block of reactions that should not be tabulated by using the token @noTab_start and @noTab_end

@noTab_start
1,REACTION
2,REACTION
3,REACTION
@noTab_end

- CR_start and CR_stop

Reactions which involves cosmic-rays are often employed in standard databases as for example in KIDA. You can define set of reactions which depends on the cosmic rays rate by using the token @CR_start and @CR_stop. These two token are mostly needed to build the heating routine coming from cosmic rays. Here following a typical example that is also available with the network react_photobin in the folder networks of the KROME package.

@CR_start
@common:user_crate
@format:idx,R,P,P,rate
8,H,H+,E,4.6d-1*user_crate
9,C,C+,E,1.02d3*user_crate
@CR_stop

Here above three token are used at the same time. user_crate is the cosmic rays rate in 1/s that can be easily defined in your framework code by using one of the user functions provided by KROME. For instance

call krome_set_user_crate(1.3d-17)

will set the cosmic rays rate to 1.3d-17 1/s.

- Xray_start and Xray_stop

Radiation from different sources is very important for different astrophysical applications. High energy components of the radiation spectrum include X-rays. Photons coming from these bands can easily photo-ionise hydrogen and helium and also induce secondary ionisation. The X-rays physics and its implementation in KROME are discussed in "X-rays in KROME". The two tokens here discussed are needed to KROME to set the photo-heating and the photo-rates due to X-rays photons.

@XRAY_start
@format:idx,R,P,P,Tmin,Tmax,rate
24,H,H+,E,NONE,NONE,auto
25,He,He+,E,NONE,NONE,auto
@XRAY_stop

where auto self-consistently set the photo-rates due to this process.

- photo_start and photo_stop

Photo-reactions that requires a cross section should be recognized by KROME. For this reason you can embed them with the tokens

@photo_start
@format:idx,R,P,P,Tmin,Tmax,rate
24,H,H+,E,NONE,NONE,xsec_H(energy_eV)
25,He,He+,E,NONE,NONE,xsec_He(energy_eV)
@photo_stop

where xsec_* are two functions that represent the cross section of the photoionization process. Note that the cross sections can be any F90 expression (as the ordinary rates) that uses the energy in eV (energy_eV) as independent variable (instead of the rate Tgas). When this token is present you must use the -photoBins option.

- ghost

When you need to include some species that are not present in the network (e.g. some coolant that is constant during the evolution, but does not participate to the chemical network) you can specify it by using ghost token as e.g.

@ghost:H2,OH

if you want to include H2 and OH. This is when H2 and OH are not present in any of the reactions of the chemical network, but you need for some other reason (e.g. cooling).

- tabvar

A useful token if the user has any quantities already tabulated. With this token KROME is able to matches/reads the tables provided by the users.

@tabvar:user_xray=data/ratexH.dat,n(idx_H),n(idx_He)

in this example the file ratexH.dat contains the data, which are tabulated in function of the hydrogen and helium abundance n(idx_H) and n(idx_He), respectively. The file indicated here is a row-first table as row,column,value file where each block is separated by a blank line. Moreover, the first line after comments must be the number of rows and the number of columns. For example a 3x2 table is represented as

#some comments
3,2
0.5 5.0 1.24244
0.5 10.0 7.83483

1.0 5.0 6.732849
1.0 10.0 8.30982

1.5 5.0 9.89322
1.5 10.0 9.38923

- ODEmodifier and reactionModifier

Sometimes can be useful to modify one/more of the ODE you have in your system, or re-scale one/more rate coefficient. To allow the users to easily modify the network file and take care about these changes KROME include two token, @ODEmodifier_start, @ODEmodifier_stop, and @reactionModifier_start, @reactionModifier_stop.

Here following you can find a couple of examples on how to use the above tokens:

@reactionModifier_start
 k(:) = k(:) / N_avogadro
@reactionModifier_stop

which rescale all the rates by the Avogadro number, and

@ODEmodifier_start
 !differential equations for non-He species are set to zero
 ! before redhisft 2.243d3.
 ! phys_zredshit is the internal name for redshift
 ! dn(:) is the ODE array, where the index are self-explanatory
 if(phys_zredshift>2.243d3) then
         dn(idx_E) = 0d0
         dn(idx_H) = 0d0
         dn(idx_H2) = 0d0
         dn(idx_Hj) = 0d0
         dn(idx_H2j) = 0d0
         dn(idx_Hk) = 0d0
         dn(idx_D) = 0d0
         dn(idx_Dj) = 0d0
         dn(idx_HD) = 0d0
         dn(idx_HDj) = 0d0
         dn(idx_H2Dj) = 0d0
         dn(idx_H3j) = 0d0
 end if
@ODEmodifier_stop

which sets some of the ODEs to zero. To see a direct application of these token see the networks/react_stars and networks/react_earlyUniverse, and the tests stars and earlyUniverse, respectively.

- next_solomon

This token specifies that the reaction which follows is the H2 indirect photodissociation, so called Solomon process. It automatically enables the corresponding heating term in krome_heating, known as H2 UV pumping heating.

- cooling_start and cooling_stop

To include a custom cooling function (in erg/cm3/s) without modifying the machinery in KROME, we provide a quick way to add any desired function in the network file. For example it could be

@cooling_start
 @cooling:1d-26 * n(idx_C)
@cooling_stop

Note that the index of carbon is idx_C and not krome_idx_C, because in this case this is an internal procedure. Inside the block you can add custom variables using @var token: it doesn't interfere with the @var tokens outside this block. For example is allowed

@var:myvar=Tgas/1d4
@cooling_start
 @var:myvar=1d-26
 @cooling:myvar * n(idx_C)
@cooling_stop

An example with the test customCooling that uses the network file networks/customCool. See

./krome -test=customCOoling

heating_start and heating_stop

Same as for the custom cooling here above.

2.1.2 Including automatic rates in the network file

As briefly mentioned above, KROME contains databases of cross-sections and rates that can be automatically read when the user run the package to create the physical modules. These data are located in data/database. This folder contains

collisional_ionization.dat  photoioniziation.dat    radiative_rec.dat   radiative_rec_lowT.dat

which are the collisional ionisation (atom + electron), radiative recombination (ion + electron), the radiative recombination at low temperatures, and the photoionisation (atom + photon) cross-sections, respectively. The data are from Verner+ 1996. The motivation for this is to have a sort of database with state-of-the-art reaction rates. With this the user can prepare its reaction network without indicating the rates. The test auto (based on the network networks/react_auto) is specifically designed to run without explicitly indicating any reaction rate:

@photo_start
@format:idx,R,P,P,rate
1,C,C+,E,auto
@photo_stop

@format:idx,R,R,P,rate
2,C+,E,C,auto

@format:idx,R,R,P,P,P,rate
3,C,E,C+,E,E,auto

The first reaction is a photoionization, where the cross section is automatically found by KROME, as well as for the other two reactions (recombination and collisional ionization). When an automatic reaction is not found KROME raises and error and stop the execution. In this case you should provide the explicit reaction rate, or add it to the database.

WARNING; the update of the database depends on the requests of the different users, so there might be some reactions that are not state-of-the-art.

2.1.3 Automatic generation of networks (experimental feature)

KROME allows to generate automatic networks using simple rules. You can find an example in custom.dat, which contains self-explanatory comments for the different tokens. In order to use custom.dat just type

./krome -n custom.dat -useAutoNetwork

and the other options you want to use as usual.

In this way KROME uses the rules in the custom.dat file to generate the chemical network.

The generated network is stored in the file cstmnetwork.tmp and the file is then read by KROME to create everything in the build/ folder as usual.

The network can be extended and/or modified by the user and employed as a standard KROME network.

Note also that during this procedure KROME analyses all the possible reactions and prepares the file cstmnetwork_all.tmp, which contains information about the enthalpy of any reaction, alongside its availability in the database.

2.1.4 Availability of the reverse reactions

Furthermore, using the option -checkReverse KROME creates a report for the availability of the reverse reactions including the difference in energy (temperature) between the reactants and the products based on their enthalpy of formation. These information are stored in the file krome_reverse.log in the build/ folder. This file allows to determine if a reverse reaction rate should be included or not. Reactions that could be possible candidate to have a missing reverse are indicated with the symbol *, so for example the two lines below indicate two reactions that don't have the reverse, but the first reverse (292) requires an activation energy of approximately 1e5 K, while the second (294) is energetically favourable (negative enthalpy).

292  H2O + NH2+ -> NH4+ + O                            NO REVERSE FOUND   104132.361062
293  HCN+ + O -> HCN + O+                              NO REVERSE FOUND * -209.583869315

In the second case you should consider to check the literature to understand if the reactions is available, or if the activation barrier is very high and the reverse is not needed (or other caveats). It is worth noticing here that this tool represents a rough way to estimate the availability of the reverse reactions and the data contained in the file should be taken as guidance.

2.2 Hints

Photons, Cosmic Rays and Cosmic Ray Particles (secondary photons) do not need to be specified in the network file. For example:

H2O + CRP -> H + OH

is written

@format:idx,R,R,P,P,rate
10,H2O,,H,OH,auto

in the network file.

2.2.1 Special pre-built functions

Krome already includes a series of useful (special) functions which should be used in the network file, among these the recombination of different ions on dust and the Solomon photodissociation rate for H2. If you want to include these processes in your network here following an example:

@next_solomon
@format:idx,R,P,P,rate
44,H2,H,H,H2_solomonLW(user_myfluxUV)

and

@format:idx,R,R,P,rate
45,H+,E,H,H_recombination_on_dust(n,Tgas)
46,He+,E,He,He_recombination_on_dust(n,Tgas)
47,O+,E,O,O_recombination_on_dust(n,Tgas)
48,Si+,E,Si,Si_recombination_on_dust(n,Tgas)
49,C+,E,C,C_recombination_on_dust(n,Tgas)

In addition Krome also includes the direct H2 photodissociation following the prescription by Abel+ 1997:

@photo_start
@format:idx,R,P,P,Tmin,Tmax,rate
43,H2,H,H,>14.159d0,<17.7d0,H2_sigmaLW(energy_eV)
@photo_stop

2.2.2 Custom rate coefficient functions

The users can add specific functions to evaluate a rate coefficient of a given reaction. This implies two steps

Write the specific FORTRAN function in the krome_user_commons.f90 module, located in krome/src
Include the reaction in the network file

The krome_user_commons.f90 is a specific module for the user, it can be modified and overwritten in the krome/src dir. To include the reaction in the network file is straightforward, it works exactly as for the pre-built functions, which indeed call a function instead to use a FORTRAN style formula. For instance it could be

function fionpol1(Tgas,a,b,c)
    implicit none
    real*8::Tgas,a,b,c,fionpol1

    fionpol1 = a*b*(0.62+0.4767*c*sqrt(3d2/Tgas))
end function fionpol1

and in the network file

8,H2O,H3+,H2,H3O+,fionpol1(Tgas,1d0, 1.73d-9, 5.41d0)

Wiki

KROME / quick1