A BRAMS guide for Beginners (First Time users)
(Version 5.2)

1. Introduction

This page will guide You to install software infrastructure and BRAMS model. BRAMS code is distributed under CC-GPL License. You can download, copy, modify and redistribute the code. Some rights are reserved. We recommend the user to read the license terms on site Creative Commons.

BRAMS works with Linux or Unix operational’s systems. As a first approach, we recommend the Linux distribution UBUNTU.

Please, read carefully each of the steps below in order to install and run the model.

2. Install Fortran & C Compilers

BRAMS has been tested with the compilers: INTEL® compilers, PGI® compilers and GNU Fortran compiler (GPL). Follow the instructions of each site to install the compilers.

3. Install MPI Libraries and Software

BRAMS works only in parallel mode. One can run the model using a single processor/core, but must to do it using MPI with the MPIRUN command. We recommend download and install the last version of MPICH stable release. The last working version is 3.1.4. You may have problems with new versions, such as version 3.2. Also take care to choose the correct version to your OS.

After download the MPICH, please, proceed the installation:

  • Uncompress: ~\> tar -zxvf mpich-3.1.4.tar.gz
  • goto mpich directory: ~\> cd mpich-3.1.4
  • Configure mpich’s makefile: ~\> ./configure -disable-fast CFLAGS=-O2 FFLAGS=-O2 CXXFLAGS=-O2 FCFLAGS=-O2 -prefix=/opt/mpich3 CC=icc FC=ifort F77=ifort
  • make and install: ~\> make; ~\> sudo make install

Notes:

  1. -prefix= directory where mpich will be installed when You make the install command;
  2.  CC= C compiler according You install on step (2) above;
  3. FC= Fortran compiler according You install on step (2) above;
  4. F77= Use the same as FC

4. Install HDF5 libraries and Software

BRAMS uses HDF5 to perform I/O operations. Download HDF5 source from the HDF5 Group Site. After downloading the source code for all plataforms , please, proceed the installation:

  • uncompress: ~\> tar -zxvf hdf5-1.8.16.tar.gz
  • goto hdf5 directory: ~\> cd hdf5-1.8.16/
  • Configure hdf5’s makefile: ~\> ./configure -enable-fortran -enable-parallel -prefix=/opt/hdf5 CC=/opt/mpich3/bin/mpicc FC=/opt/mpich3/bin/mpif90 CXX=/opt/mpich3/bin/mpicxx CFLAGS=-O2 FCFLAGS=-O2 CXXFLAGS=-O2
  • Make and Install: ~\> make; sudo make install

Notes:

  1. -prefix= directory where hdf5 will be installed when You make the install command;
  2.  CC= , FC= and CXX= must have the directory you used to install the mpich at step (3) above;

5. Download and compile the BRAMS Model

To download BRAMS, you must fill a form with your identification. Then You must click on “Send Activation E-mail” at bottom of page. You will receive an e-mail with one alphanumeric activation code number. Enter with the code  in the box and another e-mail with download instructions will be sent You.

BRAMS project uses Subversion version control system. You must have installed the subversion on your machine in order to checkout the code.

Please, click in the box bellow.

Download Requisition Form

After checkout the code, the instalation of BRAMS code is the following:

  • go to build directory: ~\>cd BRAMS-5.2/build/
  • configure the model’s makefile: ~\> ./configure -program-prefix=BRAMS -prefix=/home/xuser -enable-jules -with-chem=RELACS_TUV -with-aer=SIMPLE -with-fpcomp=/opt/hdf5/bin/h5pfc -with-cpcomp=/opt/hdf5/bin/h5pcc -with-fcomp=ifort –with-ccomp=icc
  • make and make install: ~\>make; sudo make install

Notes:

  1. -prefix= directory where BRAMS will be installed when You make the install command;
  2. -with-chem= The chemical to be used (RELACS_TUV, RELACS_MX, CB07_LUT, CB07_TUV, RACM_TUV)

  3. -with-aer= aerosol mechanism (SIMPLE or MATRIX(under test))

  4. -with-fpcomp= and –with-cpcomp= hdf5 parallel compiler installed on step 4 above.

  5. -with-fcomp= and –with-ccomp= compiler installed on step 2 above.

6. Run the BRAMS Model

Before run the model, You must get the input data. There are two packages for initial tests:

a) Small meteorological case for laptops and desktops (722MB)

Click to get it

b) Small chemical case (using RELACS_TUV) for laptops and desktops (945 MB)

Click to get it

Both cases are just for testing and learning processes. To get data for any different runs, visit the Input Data page.

  • After downloading a test case, uncompress it using the command “tar”: ~> tar -zxvf meteo-only.tgz
  • Goto the test directory: ~>cd meteo-only
  • Make a tmp directory (necessary to Jules): ~>mkdir ./tmp
  • Export the tmp directory (especially if you are running NOT locally !): ~>export TMPDIR=./tmp
  • Take care about stack size of your machine. Make it at least 65536 or unlimited : ~>ulimit -s 65536
  • Run the model using mpirun installed on step 3: ~>/opt/mpich3/bin/mpirun -np 4 ./brams-5.2

Notes:

  1. -np= the numbers of cores You will use.
    If You do not know try the command: $ lscpu (see the information about CPU(s))
  2. ./brams-5.2 – The BRAM’s executable code. Please, point to the directory of code.

  3. When the model start a lot of logs will be printed on your screen, Pay attention for errors that will be printed during the run.

  4. If you got an error and needs for help, please, send a e-mail to brams_help@cptec.inpe.br and inform the error. Please, attach the log printed on the screen.

7. Visualize the results with GrADS

BRAMS, by default, writes the output in subdirectory dataout/POSPROCESS. Later you can set others directories and features on namelist file (expert users). The format of the output in POS is in GrADS software (COLA/IGES). You must install GrADS in your computer.

Get the software from OpenGrads and install it on your computer, or, if You use UBUNTU You can get grads using: ~\> sudo apt-get install grads

After install, please:

  • Goto pos directory: ~\> cd dataout/POSPROCESS
  • Run grads software: ~\> grads -l
  • When grads prompt appears on terminal (ga->), you can choose one of the output files, check they by listing: ga-> !ls -latr *.ctl
  • Choose one and open it: ga->open METEO-ONLY-A-2015-08-27-030000-g1.ctl (the name is just an example)
    after the file is open You will see information about the file, LON, LAT, LEV, etc.
  • list all the variables available in output: ga->q file
  • Choose one of them and proceed the plot: ga->d tempc (in this example plotting tempc – temperature)

You can see more information about Grads on Cola: Grads User’s Guide