f2cl

# Welcome to f2cl - a Fortran to Common Lisp Translator

Contained in this directory are source code files and some documentation.
The translator is written in Common Lisp making installation simple.

# Installation


If this has been extracted as a part of CLOCC, the way to build f2cl
is to simply run "make system" from a shell, as is usual with CLOCC
packages.

A second method is to use defsystem from CLOCC.  Then load
`f2cl.system`, and then finally run `(mk:oos "f2cl" :compile)`.  

A third method is to use asdf.  You can load `f2cl.asd` and run
`(asdf:oos 'asdf:load-op :f2cl)`.

Finally, a fourth method, if you have none of the above, is to
manually run everything as follows:

1. Start your favorite Common Lisp implementation use the function
   `compile-file` to compile each of the source files:

		f2cl0.l
		f2cl1.l
		f2cl2.l
		f2cl3.l
		f2cl4.l
		f2cl5.l
		f2cl6.l
		f2cl7.l
		macros.l

2. Load up all of the files

        (load "f2cl0.l")
        (load "f2cl1.l")
        (load "f2cl2.l")
        (load "f2cl3.l")
        (load "f2cl4.l")
        (load "f2cl5.l")
        (load "f2cl6.l")
        (load "f2cl7.l")
	    (load "macros.l")

   to load all the compiled files.


# Usage


## Converting Fortran Code

To use f2cl:
```
(f2cl:f2cl "<path>/fortran.f")
```
will convert the file `<path>/fortran.f` to Lisp code and places the
result in the file `<path>/fortran.lisp`.

Alternatively,
```
(f2cl:f2cl-compile "<path>/fortran.f")
```
will also run `compile-file` on the Lisp file so you can load it
directly into your lisp.


For those anxious to use the translator without studying the documentation
here is a short list of restrictions that may result in obscure errors:
 - input code is assumed to be valid Fortran 77
 - no tabs are permitted in the source,
 - $comments should only be turned on if the Fortran code has comments
   exclusively within subroutines,
 - linebreaks must occur within whitespace,
 - spaces are required to separate symbols.

Note also that an intermediate file called "prep.tmp" is produced by the
preprocessing stage of the translation.

### Options

These are the options available to `f2cl:f2cl` and `f2cl:f2cl-compile`

* `:OUTPUT-FILE`             
	File to contain Lisp code

* `:VERBOSE`                
	Verbose output. Default = NIL.  Mostly for debugging.

* `:PRUNE-LABELS`           
	Prune unused labels. Default = NIL.

* `:INCLUDE-COMMENTS`       
	Include Fortran comments in the Lisp output.
        Default = NIL

* `:AUTO-SAVE`              
	Variables in DATA statements are automatically SAVE'd. Default
	= T.

* `:RELAXED-ARRAY-DECLS`      
	Declarations of array sizes are relaxed in formal
        parameters to functions. That is, any array
        length declarations (except lower limits) are
        ignored if possible, like old Fortran used
        to. Default = T.

* `:COERCE-ASSIGNS`  
	If `T` or `:ALWAYS`, all assignment statements automatically
        coerce the RHS to the appropriate type for the assignment.  If
        `NIL` or `:NEVER`, coercion never happens.  If `:AS-NEEDED`, f2cl
        applies coercion if it thinks it is needed.  Default =
        `:AS-NEEDED`.

* `:EXTENSION`                 
	The extension to use for the output file, if needed.  Defaults
        to `*DEFAULT-LISP-EXTENSION*` or "lisp".

* `:KEEP-TEMP-FILE`
	If `T`, the temporary file is not deleted.  This is mostly for
	debugging f2cl. Default = `NIL`.

* `:ARRAY-TYPE`  
	The type of array f2cl should use.  Should be `:simple-array` or
        `:array`.  For some compilers, there can be significant speed up
        if the array can be declared as simple-arrays.  But this is
        incompatible with array-slicing, so care must be used if you
        choose `:simple-array`. Default = `:array.`

* `:ARRAY-SLICING`  
	When non-`NIL`, f2cl assumes that, whenever we do an array
        reference in a call to a subroutine or function, we are really
        passing a subarray to the routine instead of just the single
        value, unless f2cl knows the function takes a scalar arg that
        is not modified.  Default = `T`.

* `:PACKAGE`  
	A string or symbol specifying what package the resulting code
        should be in. (Basically puts a `(in-package <p>)` at the top.)
        Default is "COMMON-LISP-USER".

* `:DECLAIM` 
	Declaim compilation options (Basically puts a `(declaim <declaim>)` at the top.)  Default is none.

* `:DECLARE-COMMON`  
	When non-`NIL`, any structures definitions for common blocks are
        defined when converting this file. Otherwise, the structures
        for the common blocks are expected to be defined elsewhere.
        This should be used only once for one subprogram that will be
        used to define the common block.  See below for more
        information. Default is `NIL`.

* `:FLOAT-FORMAT`              
	Float format to use when printing the result.  Default is
        `*READ-DEFAULT-FLOAT-FORMAT*`

* `:COMMON-AS-ARRAY`  
	Instead of defining a common block as a structure with the
	same slot names as variables in the common block, the common
	block is defined as a set of arrays.  The actual common block
	variables are defined as offsets into these arrays.  For more
	information see below.  This mimics the memory layout of how
	Fortran treats common blocks.  Default = `NIL`.

# Using Converted Code

Once you've converted the code, you do not need to load up all of f2cl
to use the converted code.  In fact, you only need f2cl0.l and
macros.l to define the necessary packages and functions used by the
converted code.  Actually, you really only need the defpackage for
f2cl-lib in f2cl0.l.

# Issues

For a more detailed list of issues and notes, see src/NOTES.

We highlight just a few issues here.

## Block data statements

In Fortran, block data statments are used to initialize common
blocks.  Since Fortran executables are loaded and run just once,
this is not a problem.  However, in Lisp, this might not be true,
and you may want to run the main program many times.  Thus, it is
up to you to run the block data initializer at the right time, as
needed.  f2cl cannot know when and where to call the initializer.

## Common blocks  
F2cl converts common blocks to structures.  However, common blocks
may be referenced in several different files, so the user must
tell f2cl when to define the structure.  Use the :declare-common
parameter to tell f2cl to define the structure. This should be
done exactly once for each common block that is defined.  This
should also be done for the first file that is compiled and
loaded, so that subsequent files know about the definition.

In addition, there is another option, :common-as-array.  This
changes how f2cl handles common blocks.   A rather common use of
common blocks has the same common block using different variable
names.  For example, one routine might have
```
        COMMON /foo/ a(10), b, i(4)
```

and another might say

```
        COMMON /foo/ b(9), c, d, j(2), k(2)
```

In Fortran, this is perfectly acceptable.  Normally, f2cl expects
all common blocks to use the same variable names, and then f2cl
creates a structure for the common block using the variable names
as the names of the slots.  However, for a case like the above,
f2cl gets confused.  Hence, :common-as-array.  We treat the common
block as an array of memory.  So this gets converted into a
structure somewhat like
```
        (defstruct foo
          (part-0 (make-array 11 :element-type 'real))
          (part-1 (make-array 4 :element-type 'integer4)))
```
(In a more general case, we group all contiguous variables of the
same type into one array.  f2cl and Lisp cannot handle the case
where a real and integer value are allocated to the same piece of
memory.)

Then in the individual routines, symbol-macrolets are used to
create accessors for the various definitions.  Hence, for the
second version, we would do something like
```
          (symbol-macrolet 
            (b (make-array 9 :displaced-to 
                           (foo-part-0 *foo*)
                           :diplaced-offset 0))
            (c (aref (foo-part-0 *foo*) 9))
            (d (aref (foo-part-0 *foo*) 10))
            (j (make-array 2 :displaced-to
                           (foo-part-1 *foo*)
                           :displaced-offset 0))
            (k (make-array 2 :displaced-to
                           (foo-part-1 *foo*)
                           :displaced-offset 2))
            ...)
```
Thus, we access the right parts of the common block, independent
of the name.  Note that this has a performance impact since we
used displaced arrays.
  


## Conversion order
While not necessary, f2cl can do a significantly better job in
generating code if the functions are compiled in the correct
order.  This means any function, F, that is called by another
function, G,  should compiled first.  In this way, f2cl can
determine the calling conventions for F, and generate the
appropriate call for F in G.  This is important if F takes an
array argument and G passes a slice of an array to F, or
conversely if F takes a simple variable, and G calls F with an
array reference.  

If this is not done, the user may have to modify either the
Fortran code or the resulting Lisp code to pass arguments
correctly.  

F2cl cannot always determine whether a slice of an array should be
used or just the single element.

See also the file src/NOTES which contains a change log.  But there
are also various notes about about restrictions and enhancements on
various features supported by f2cl.


# Acknowledgments

The translator was written by Kevin Broughan and Diane Koorey Willcock
at the University of Waikato. Reports should be sent to
kab@waikato.ac.nz and should include examples of Fortran code which
fails to translate or which translates incorrectly.

Major changes have be written by Raymond Toy and the entire translator
is now part of CLOCC, with permission from Kevin Broughan.  Send bug
reports and other comments to http://clocc.sourceforge.net.

The code is also placed under the GPL, by permission of Kevin
Broughan.  The exception is macros.l which is released under the LGPL
so that it can be incorporated into other packages.


blas-complex

blas-package

blas-real

BLAS (Basic Linear Algebra Subprograms) for double-float matrices.

blas

BLAS routines for complex double-float  matrices

blas-hompack

BLAS routines for real double-float matrices

F2CL conversion of COLNEW: Solution of boundary-value problems for ODEs

colnew

colnew/test-1

colnew/test-2

colnew/test-3

f2cl-asdf

fftpack5

fftpack5-double

F2CL conversion of FISHPACK: Solution of separable elliptic PDEs

fishpack

fishpack/test-hstcrt

fishpack/test-hstcsp

fishpack/test-hstcyl

fishpack/test-hstplr

fishpack/test-hstssp

fishpack/test-hwscrt

fishpack/test-hwscsp

fishpack/test-hwscyl

fishpack/test-hwsplr

fishpack/test-hwsssp

fishpack/test-sepx4

F2CL conversion of HOMPACK: Solution of non-linear systems of equations by homotopy methods.

hompack

hompack/test-mainf

hompack/test-mainp

hompack/test-mains

lapack/complex

lapack/package

lapack/real

LAPACK - Linear Algebra PACKage for double-float matrices

lapack

LAPACK routines for complex double-float matrices

LAPACK routines for real double-float matrices

lapack/tests

F2CL conversion of MINPACK: Solutions to non-linear equations and least-squares problems

minpack

minpack/test-hybrd

minpack/test-lmdif

F2CL conversion of ODEPACK: Initial value solver for ODEs

odepack

odepack/package

odepack/blas-util

odepack/lsoda

odepack/lsoda-demo

odepack/lsodar

odepack/lsodar-demo

odepack/lsode

odepack/lsode-demo

odepack/lsodi-demo

odepack/lsodkr-demo

odepack/lsodpk-demo

odepack/lsoibt-demo

quadpack/mach-par

F2CL conversion of QUADPACK: Adaptive numerical integration

quadpack

quadpack/tests

F2CL conversion of TOMS 419: Zeroes of a complex polynomial

toms419

toms419/test

F2CL conversion of TOMS 715:  Numerical Evaluation of Special Functions

toms715

toms715/tests

F2CL conversion of TOMS 717: Max- and quasi-likelihood estimation in non-linear regression

f2cl

Upstream URL

License

blas

Dependencies:

blas-complex

Dependencies:

blas-hompack

Dependencies:

blas-package

Dependencies:

blas-real

Dependencies:

colnew

Dependencies:

colnew/test-1

Dependencies:

colnew/test-2

Dependencies:

colnew/test-3

Dependencies:

f2cl

Defsystem Dependencies:

Dependencies:

f2cl-asdf

Dependencies:

fftpack5

Dependencies:

fftpack5-double

Dependencies:

fishpack

Dependencies:

fishpack/test-hstcrt

Dependencies:

fishpack/test-hstcsp

Dependencies:

fishpack/test-hstcyl

Dependencies:

fishpack/test-hstplr

Dependencies:

fishpack/test-hstssp

Dependencies:

fishpack/test-hwscrt

Dependencies:

fishpack/test-hwscsp

Dependencies:

fishpack/test-hwscyl

Dependencies:

fishpack/test-hwsplr

Dependencies:

fishpack/test-hwsssp

Dependencies:

fishpack/test-sepx4

Dependencies:

hompack

Dependencies:

hompack/test-mainf

Dependencies:

hompack/test-mainp

Dependencies:

hompack/test-mains

Dependencies:

lapack

Dependencies:

lapack/complex

Dependencies:

lapack/package

Dependencies:

lapack/real

Dependencies:

lapack/tests

Dependencies:

minpack

Dependencies:

minpack/test-hybrd

Dependencies:

minpack/test-lmdif

Dependencies:

odepack

Dependencies: