Read Me

GRIN


A flexible program to compute Green's function integrals in two dimensions


Partial elliptic equation problems can often be reduced to a set of integral 
equations using Green's functions. The advantage of the Green's function 
formalism compared to a finite element approach for instance, is that one is 
left with a lower dimensional problem, namely one of computing line 
integral in two-dimensions or surface integrals in three dimensions. Because 
the Green's functions can be chosen so as to vanish at infinity, this 
formalism is particularly applicable to problems where the domain is 
large or extends to infinity. Another typical application of the Green's 
function formalism is when one is only interested in determining the field 
on selected surfaces (or contours in 2-D).

One potential source of inaccuracy of the Green's function approach is the 
singular nature of the Green's functions; G ~ log x in two dimensions or 
G ~ 1/x in three dimensions. Thus, the integrals must be evaluated carefully. 
It is hence not surprising that most Green's function programs have been 
tailored for specific Green's functions, using semi-analytic rules to 
estimate the integral contribution in the neighbourhood of a singularity 
[1]. In GRIN [2],  the Green's function can be specified by the user 
although a selection of Green's function is also provided. The only 
assumption used in GRIN is that G ~ log (x - x').

In the presence of several contours, the Green problem is analogous to the one
of determining an inductance matrix coupling the source contributions from 
all contours.  It is up to the user to determine what is a physically relevant
source term in his/her problem, the Green's function formalism providing a 
response matrix to prescribed sources.  Typically, the response and the 
sources can either be the solution or its normal derivative at the contours. 
In this sense, the Green's function formalism can be used to determine the 
impedance of the system. 

In addition to GRIN there is the VACUUM code by Morrell Chance which the 
potential user may well consider to use. Both codes are very similar as 
they both perform Green's function integrals in two dimensions. 
Indeed GRIN owes much to VACUUM, which has pioneered many aspects of such 
computation. The differences are that GRIN is much flexible in its
problem prescription, both in terms of geometry and elliptic operator, while 
VACUUM is faster by an order of magnitude. If you want to compute the energy
contribution of the vacuum in linear toroidal stability codes, you are well 
advised to stick with VACUUM. If speed is not an issue and flexibility and ease
of use is required then you may consider using GRIN.
 
Caveats:

* doubleGradShafranov has not been tested. We recommend using the 
doubleLaplaceN driver as a model for computing the toroidal n > 0
mode. doubleLaplaceN has been verified against a finite element code
(ellitp2d). 

* The response matrices computed by doubleLaplaceN can be suitably 
transformed to yield the response matrices of the Grad-Shafranov 
problem. This would provide a verification for doubleGradShafranov.

* doubleLaplaceN computes the response of sources, which are 
functions of the angle-like coordinate used to parametrize 
contours. It does not matter whether the angle goes clockwise or
counter clockwise (when the contour is closed). However, this 
will determine the direction of the normal: n = t x e_z.

* doubleLaplaceN: the observer points are located in the center
of segments. Often the observer points would need to match the
nodes of a grid, and thus, segments should be laid accordingly. 


$Id$

Author: Alexander Pletzer (pletzer@txcorp.com) and Ireneusz Szczesniak
(2001 summer student who implemented most of the vector, matrix 
classes).

Language: 

C++ and fortran 77

Precision: double (64-bit)

Platforms: 

tested on multiple Unix platforms

Installation: 

see INSTALL file

Documentation:

GRIN is not a program but a collection of classes, methods and procedures which
are provided as building blocks. The most important classes, defined as header
under the include directory, are:

* "MvVector" for a dense (templated) vector representation 
* "MvMatrix" for a dense matrix representation
* "GrSegment" for the parametric representation of a line in two dimensions
* "GrGaussQuadrature" for the generic integration of a function using 
   Gauss' method
* "GrGreenFunctions" for a selected number of Green's functions and
   function integral methods (greenIntegral and twoGreenIntegral).

The tests/ directory contains a number of unit tests. 

References:

[1] Chance, Phys Plasmas 4, 2167 (1997)
[2] A. Pletzer, H. R. Strauss, Computer Physics Communications, Volume 182, Issue 10, p. 2077-2083 (2011)