c
c     this is an example program to compute the Boltzman ratio for
c     neutral hydrogen from the n=2 to the n=1 excitation level and the
c     n=3 to n=1 level
c
c     after setting up the variables, the code uses a subroutine called
c     BOLTZMAN to compute the ratio
c
c     for illustration purposes, some variables are passed via a COMMON
c     block from this maan routine to the subroutine
c

c     begin main routine with a PROGRAM statement

      PROGRAM example

c     Variable declarations: Fortran implicitly assigns variables that
c     begin with "a"-"h" and "p"-"z" as real (floating) and those that
c     begin with "i"-"o" as integers (case insensitive).  It is best
c     practice to turn this off with the statement "implicit none" and
c     then declare each variable explicitly (which is now forced when
c     this command is used).  For greater precision, use "double
c     precision" for reals instead of "real*4"
      
c     turn off implied variable assingments

      implicit none

c     declare needed integer and double precision variables

      integer           i
      double precision  m,ratio

c     include the file called example.com, which is a common block; this
c     common block is used to pass some variables to the subroutine;
c     note that this common block is also included in the subroutine!

      include           'example.com'


c     main body of program starts here


c     pick an arbirary temperature

      temp   = 1.e4

c     for the three n levels; compute the statistical weights, g;
c     compute the excitation protentials, chi; store them in arrays,
c     which are declared in the file example.com because these arrays
c     are passed in the common block to the subroutine

c     DO loops and WHILE loops can be used for stepping variables; the
c     format of a DO loop is provided below.  Note that the end of the
c     loop is a CONTINUE statement with a line number.  That line number
c     appears in the DO statement; The write statement is to the screen;
c     the WRITE statement is "WRITE(unit,format)" where "unit"=6 writes
c     to the screen and other units are reserved for files (see below).
c     "format" is a line number that has the format statement.

      DO 11 i=1,3
        m      =  float(i)    ! convert i to a real for computations
        g(i)   = 2.0*m**2
        chi(i) = 13.6*(1.0-1.0/m**2)
        WRITE(6,600) i,g(i),chi(i)
 11   CONTINUE

c     loop over n=2 and n=3 to obtain 2/1 and 3/1 ratios; subroutine
c     BOLTZMAN makes the calculation; passed to the subroutine are "i",
c     the excitation level (actually n), and upon return from the
c     subroutine, the variable "ratio" has our answer.  see comments in
c     subroutine BOLTZMAN; write the results to file called
c     "example.dat"; note that WRITE unit=1, which is defined in the
c     OPEN statement for the file

      OPEN(unit=1,file='example.dat')

c     write a header for the file (see FORMAT statement 601)

      WRITE(1,601)

      DO 15 i=2,3
        CALL boltzman(i,ratio)
        WRITE(1,602) temp,i,ratio
 15   CONTINUE

c     always close your files!

      CLOSE(unit=1)
  
c FORMAT statements are referenced as line numbers in WRITE statements
c spaces are Nx, where N is an integer, (1x is one space)
c integers are iN, where N is an integer, (i3 give integers with 3 places)
c reals are fL.R, where L is number of total places including the decimal,
c       and R is number of places to the right of the decimal
c exponential notation is 1peL.R, where the 1p puts one significant digit
c       to the left of the decimal place

 600  FORMAT(1x,i3,1x,f8.2,1x,f7.3)
 601  FORMAT(4x,'Temp, K',3x,'i',3x,'n(i)/n(1)')
 602  FORMAT(1x,f10.1,1x,i3,1x,1pe11.3)

c     in the main routine, the program is ended with a STOP followed by
c     and END statement

      STOP
      END

c     ...........................................................

c     this is the subroutine that computes the boltzman equation
c     on return, R has the desired value

      SUBROUTINE boltzman(i,r)

      implicit none
      integer            i
      double precision   r,theta

      include         'example.com'


c     temp, g, and chi are passed in the common block


      theta =  5040./temp 
      r     = (g(i)/g(1)) * 10**(-theta*chi(i))
      
c     in a subroutine, the last lines are RETURN followed by an END

      RETURN
      END

c     ...........................................................