1.2 Getting started with KROME

In this section we show how to download KROME and how to run the "Hello KROME" test.
Don't forget to check if you have these prerequisites.

1.2.1 Get KROME

The package can be downloaded from the web site http://www.kromepackage.org or directly cloned via git from https://bitbucket.org/tgrassi/krome/

git clone https://bitbucket.org/tgrassi/krome.git

which will make a copy of the last version of KROME on your local computer. More details on bitbucket here.

cd into your new directory and check that is not empty:

home:~/wherever/> cd krome
home:~/wherever/krome> ls
README      clean       kromelib.py patches     tests
alltest.py  data        kromeobj.py solver      tools
argparse.py gpl-3.0.txt networks    src         wizard.py
build       krome       options_example test_list

note that the list of the files could differ.

1.2.2 Running the "Hello KROME!" test

Now you can run the "Hello KROME!" test, a simple two reactions test, based on this. The test file and the chemical network employed here are discussed in detail in Sections 1.2.5 and 1.2.6 below. Type

 ./krome -test=hello

or

 python3 krome -test=hello

The output should show something like

******************************
      WELCOME TO KROME
******************************

This TEST is running with the following arguments:
 -test = hello
 -noSinkCheck = True
 -n = networks/react_hello

that are the information relative to the test, namely the name of the test (hello), a control to avoid sink species, and the network name (networks/react_hello).
These options are stored in tests/hello/options.opt.

ODEs needed: 7
Reactions found: 2
Species found: 3

displays the number of the ODEs found, the number of the reactions, and the species found.

Species list saved in build/species.log
Species index initialization for gnuplot in build/species.gps
Heating cooling index init for gnuplot in build/heatcool.gps
Reactions saved in build/reactions.log

the list of the species and the reactions are saved in build/ in different files (log), including some gnuplot utilities (gps). The details of these files are discussed here.

ODE partition: [3 atom/mols]  + [1 CR] + [1 PHOT] + [1 Tgas] + [1 dummy] = 7 ODEs
ODEs list: FK1, FK2, FK3, CR, g, Tgas, dummy

in this case the partition of the ODE has 3 species + cosmic rays + photons + Tgas + dummy. Note that cosmic rays and photons are included only for retro-compatibility and are no longer used. Dummy ODE is always zero, while dummy species always 1. These last four terms are internally employed by KROME and the user can ignore them. The user should employ a species array of 3 (in general krome_specs), while the internal length of the ODE array is 7 (in general krome_spec+4).

Max number of reactants: 1
Max number of products: 1

in this case the maximum number of reactants and products is 1, since all the reactions are A->B. When reactions are e.g. A+B->C+D both the maximum numbers are 2.

Jacobian non-zero elements: 4 over 49
(8.16% of total elements, sparsity = 91.84%)
solver info:
 MF: 222
 MOSS+METH+MITER: 2+2+2
 LWM: 166 LRW: 249

information on the Jacobian and on the solver: see DLSODES manual for further details. The sparsity is algebraic, hence this is the maximum sparsity allowed.

******************
Reading coolants from data/coolZ.dat...
...
...

then KROME reads the network file and writes the files in the build\ folder.

Everything done, goodbye!


************************************************
31. MOST SOFTWARE TODAY IS VERY MUCH LIKE 
AN EGYPTIAN PYRAMID WITH MILLIONS OF BRICKS 
PILED ON TOP OF EACH OTHER, WITH NO STRUCTURAL   
INTEGRITY, BUT JUST DONE BY BRUTE FORCE AND 
THOUSANDS OF SLAVES.
--- Alan Kay
************************************************

If everything went smooth you should see the "goodbye message", and a random quote. If you don't like chemistry you can use KROME as a random quote generator.
Something went wrong? Check the prerequisites.

1.2.3 Compile and run the test

KROME is a pre-processor, so what you have done in the previous step was to create all the necessary FORTRAN (and non-FORTRAN) files in the build/ directory. Type

cd build
ls

you should see the list of the files (source, makefile, and so on...)

heatcool.gps         krome_ode.f90           krome_user.f90          plot.gps
krome_commons.f90    krome_photo.f90         list_user_functions.py  reactions.log
krome_constants.f90  krome_reduction.f90     Makefile                README
krome_cooling.f90    krome_stars.f90         network.dot             species.gps
krome_dust.f90       krome_subs.f90          opkda1.f                species.log
krome.f90            krome_tabs.f90          opkda2.f                test.f90
krome_heating.f90    krome_user_commons.f90  opkdmain.f

Now if you have ifort type

make
./test

or if you have gfortran type

make gfortran
./test

you should obtain the message

 Test OK!

Well done, the test works! To take a closer look to the test file see Section 1.2.6 below.
Before this, let's take a look at the test results.

Something went wrong? Check the prerequisites.

1.2.4 Plot the test results

To show what the test produced use gnuplot (if you want you can install it with sudo apt-get install gnuplot) typing

gnuplot
load 'plot.gps'

you should obtain the following

Schermata del 2014-08-20 13:50:47.png

which shows the evolution of the three species with time.

Note that all the pre-built tests included in KROME are provided with a gnuplot script plot.gps, so you can easily check the tests results by running it!

1.2.5 Hello chemical network!

In this Section we will look inside the chemical network file employed by the hello KROME test, react_hello. This is

@format:idx,R,P,P,rate
1,FK1,FK2,,1d0
2,FK2,FK3,,0.5d0

This means first that the format of the reaction is index, reactant, product, product, rate coefficient. The two reactions are FK1->FK2 and FK2->FK3, where FK* are some fake reactants. Each reaction has a rate coefficient indicated after the last comma. In this case they are two constants, but they can be any valid FORTRAN expression of the temperature Tgas. Expressions can include other free parameters than temperature and functions, but this will be discussed later in this wiki.

1.2.6 A closer look to the test.f90

This test.f90 file mimics the behaviour of a code that needs to call KROME (as could be RAMSES, FLASH, or any code that needs chemistry and/or microphyiscs).

The hello KROME test is very simple. It calls the solver repeatedly to track the evolution of the three species. Here the details line-by-line:

program test
  use krome_main !use krome (mandatory)
  use krome_user !use utility (for krome_idx_* constants and others)

this include the KROME module (krome_main) and the krome_user module, which contains several utilities to make things easier. The latter is not mandatory.

  implicit none
  real*8::Tgas,dt,x(krome_nmols),t

no need to comment this, except for krome_nmols, which is a common variable contained in krome_user that contains the size of the species array: in this case krome_nmols=3.

  call krome_init() !init krome (mandatory)

a mandatory initialization to KROME. This subroutine must be executed at least once before the main call to KROME.

  x(:) = 0d0 !default abundances (number density)
  x(krome_idx_FK1) = 1.d0 !FK1 initial abundance (number density)

  Tgas = 1d2 !gas temperature, not used (K)
  dt = 1d-5 !time-step (arbitrary)
  t = 0d0 !time (arbitrary)

the initialization of the species is everything to zero, except for the FK1 species. With KROME you don't need to remember the position of the species in the array since indexes are stored in user-friendly variables as krome_idx_FK1. To enable this variables you need to include krome_user. Tgas is not used by this test, but should be initialized, being one of the variable necessary for the main KROME call (see below). The initial time step is dt, and the time is initially set to zero.

  do
     dt = dt * 1.1d0 !increase timestep
     call krome(x(:), Tgas, dt) !call KROME
     write(66,'(99E17.8e3)') t,x(:)
     t = t + dt !increase time
     if(t>5d0) exit !break loop after 5 time units
  end do

Now, to provide a number of evolutionary steps (we want to plot some nice evolving curves), we prepare a loop that increases the length of the time-step dt. Every loop we also increase the time by dt, and we want to break the loop when time is greater than 5 seconds. The most important line is where we call KROME: x(:) is the array that contains the number densities of the species FK*, initialized few lines above. Tgas is the gas temperature that in this case is non-influential, but should be provided. Finally, is the time-step. KROME advances the solution by a dt: then x(:) is the new value of the evolved species. In fact we print the new species on a file (fort.66). This file will contains the evolution of the species during the 5 seconds of our model. Note: if you need the evolution of the species after 5 seconds, but you don't want to display intermediate steps, the loop is useless and you can call directly KROME with dt=5 seconds. This is faster.

  print *,"Test OK!"
  print *,"In gnuplot type"
  print *," load 'plot.gps'"

end program test

Some concluding output.

1.2.7 The gnuplot script plot.gps

In this Section we discuss the simple gnuplot script file that plot the results of the "hello KROME" test. A basic knowledge of gnuplot is required. The file is:

nkrome = 1
load 'species.gps'

This part allows to use the same index of KROME in the plot. In particular the species.gps file contains variables as krome_idx_FK1 and so on. This works as the same variable in the krome_user module discussed in Section 1.2.6 above, and allows to keep the same variable even if the indexes are changing due to modifications to the network. The offset nkrome = 1 indicates that the position of the species in the file is shifted by one column, due to the time variable (in fact it was write(66,'(99E17.8e3)') t,x(:)).

plot './fort.66' u 1:(column(krome_idx_FK1)) w l t "FK1",\
 '' u 1:(column(krome_idx_FK2)) w l t "FK2",\
 '' u 1:(column(krome_idx_FK3)) w l t "FK3"

With the previous variables you can plot the exact species without the need to remember the corresponding index in the species array.

Wiki

KROME / Get_started