1.2 Getting started with KROME
In this section we show how to download KROME and how to run the "Hello KROME" test.
1.2.1 Get 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.
We strongly suggest to clone the git repository, but if you prefer you can just download KROME from the website and get a tar file. The first thing to do is to untar the archive wherever you want
gunzip KROME.tar.gz | tar xvf
cd into your new directory and check the contents:
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
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
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.
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
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
or if you have gfortran type
make gfortran ./test
you should obtain the message
Well done, the test works! To take a closer look to the test file see Section 1.2.6 below.
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
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
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
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.