current version: 1.0

What is PopRatio? The paper describing it. The code and description of files.
Building the code. Modification history. Contact.

PopRatio is a Fortran 90 code designed to calculate population ratios of atomic levels.

The program solves the equations of statistical equilibrium considering all possible bound-bound processes: spontaneous decay, collisional or radiation induced (the later either directly or by fluorescence). The code is very flexible, allowing an arbitrary number of levels or processes to be accounted for.

It may find a wide range of applicability in astronomical problems, such as interpreting fine-structure absorption lines or collisionally excited emission lines (such as coronal emission lines) in the spectra of several objects, and also in calculating the cooling rates due to collisional excitation.

Papers describing the code in details, and results obtained from it:

"PopRatio: A program to calculate atomic level populations in astrophysical plasmas"
A. I. Silva and S. M. Viegas
Comp. Phys. Comm. 136 (2001) 319-333
Abstract at CPC

"Physical conditions in quasi-stellar object absorbers from fine-structure absorption lines."
A. I. Silva e S. M. Viegas
MNRAS 329, 135 (2002)
Abstract at ADS

PopRatio uses several routines from the BLAS, LAPACK, LAPACK90 and PPPACK libraries. For your convenience all the necessary routines are distributed together with PopRatio.

get the code (compressed .tar.gz file - 204 kB)
Alternate sites: CPC Program Library and ASCL.net

Here is a brief description of the distributed files (please refer to the paper above for details):

Precision.f90: Module that sets the accuracy to which the floating-point operations are to be done throughout the entire package.

PhysMath.f90: Module that collects a few useful physical constants and mathematical routines.

PopRatio.f90: This is the key module that contains the routines that actually compute the populations ratios.

FieldInt.f90: Module with routines that return the radiation field intensities of some models from the literature. If you don't intend to use any of them, you may exclude this file from the package (make sure to comment the "use FieldIntensities" statement in module PopRatio.f90). This module is required to run the testcases 1-3 below.

These are the BLAS routines used by PopRatio:
dasum.f, daxpy.f, dcopy.f, ddot.f, dgemm.f, dgemv.f, dger.f, dscal.f, dswap.f, dtrsm.f, dtrsv.f, idamax.f, isamax.f, lsame.f, sasum.f, saxpy.f, scopy.f, sdot.f, sgemm.f, sgemv.f, sger.f, sscal.f, sswap.f, strsm.f, strsv.f, xerbla.f .

These are the LAPACK routines used by PopRatio:
dgecon.f, dgeequ.f, dgerfs.f, dgesvx.f, dgetf2.f, dgetrf.f, dgetrs.f, dlabad.f, dlacon.f, dlacpy.f, dlamch.f, dlange.f, dlantr.f, dlaqge.f, dlassq.f, dlaswp.f, drscl.f, ieeeck.f, ilaenv.f, sgecon.f, sgeequ.f, sgerfs.f, sgesvx.f, sgetf2.f, sgetrf.f, sgetrs.f, slabad.f, slacon.f, slacpy.f, slamch.f, slange.f, slantr.f, slaqge.f, slassq.f, slaswp.f, slatrs.f, srscl.f .

These are the LAPACK90 interface routines used by PopRatio:
f77_lapack.f90, f90_lapack.f90, la_auxmod.f90, la_dgesvx.f90, la_dgesvx1.f90, la_erinfo.f90, la_sgesvx.f90, la_sgesvx1.f90 .

These are the PPPACK routines used by PopRatio:
dcubspl.f, dinterv.f, dppvalu.f, scubspl.f, sinterv.f, sppvalu.f .
The original code underwent slight modifications in order to support both single and double precision data types. (therefore you can't use the original one)

spline.f90: This is a Fortran 90 interface we have written to the PPPACK routines.

CI.dat, CII.dat, OI.dat, SiII.dat, FeII.dat: These are sample input files with atomic data to calculate atomic level populations of C0, C+, O0, Si+ and Fe+. (We are submitting a paper describing the atomic data employed within a few days.) You'll need CI.dat, CII.dat and FeII.dat to run the testcases below.

main1.f90, main2.f90, main3.f90, main4.f90, main5.f90: These are sample main programs that illustrate how to use PopRatio. You should run each one of them once, and then compare the outputs with the files provided below in order to make sure everything is working fine.

output1.dat, output2.dat, output3.dat, output4.dat, output5.dat: The outputs of the testcases above.

Building the code:

You must compile and link together the following files: the blas, lapack, lapack90 and pppack routines, spline.f90, Precision.f90, PhysMath.f90, FieldInt.f90 (in case you'll need this), PopRatio.f90 and also a main program you should write to drive the calculations you're interested in.

When running the code for the first time you should pick up the main programs supplied with PopRatio and compare their outputs against the files above.

We also supply a makefile to assist building the code in a Unix-like platform. In this case, one would typically proceed as follows:

1) Extract all the files to a common directory:

gunzip popratio.tar.gz
tar -xvf popratio.tar
rm popratio.tar

2) Move the testcases' files to a separate directory:

mkdir testcases
mv main?.f90 testcases
mv output?.dat testcases

3) Next fire:

make all

This will compile all the files and build the executable.

4) Execute PopRatio in order to run the first testcase (in the distributed files the main program is the same as main1.f90):


5) Compare output1.dat with the corresponding file in the testcases' directory. All the results should agree down to the last significant digit.

6) In order to run the remaining testcases one should move one of the main programs to the working directory and rename it to main.f90. Then you should make sure the function URAD in PopRatio.f90 corresponds to the desired radiation field (check the header of the main?.f90 files). Here's an example:

cp testcases/main2.f90 main.f90
rm main.o

(if you modified PopRatio.f90 then do an additional "rm PopRatio.o" to force make to recompile it)

make all

....... and so on!

Modification history:

17-Aug-2001: If you experience problems running PopRatio with the CI.dat atomic data file on a Sun workstation you should split some of its lines so that they do not exceed 132 characters. Simply typing an "Enter" in between will solve the problem.

Last updated 27-May-2002.

Comments, questions or (even!) bug reports are welcome:

Please manually type in the address above, so that I can make sure you're not a robot!