Clone wiki

KROME / Get_started

[back to index](https://bitbucket.org/tgrassi/krome/wiki/Home)

# 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

The package can be downloaded from the web site [http://www.kromepackage.org](http://www.kromepackage.org) or directly cloned via git from [https://bitbucket.org/tgrassi/krome/](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](https://www.atlassian.com/git).

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](http://en.wikipedia.org/wiki/Steady_state_%28chemistry%29#Steady_state_approximation_in_chemical_kinetics). 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
```
 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](https://bitbucket.org/tgrassi/krome/wiki/GPS).

```
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
```
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.

## 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](https://bitbucket.org/repo/r8Lbgz/images/1127563845-Schermata%20del%202014-08-20%2013%3A50%3A47.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](https://bitbucket.org/tgrassi/krome/wiki/quick1). 

## 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.

Updated