EllBase

Gerd Lanfermann

Date

Abstract

Infrastructure for standard elliptic solvers

1 Introduction

Following a brief introduction to the elliptic solver interfaces provided by EllBase, we explain how to add a new class of elliptic equations and how to implement a particular solver for any class. We do not discuss the individual elliptic solvers here since these are documented in their own thorns.

1.1 Purpose of Thorn

Thorn EllBase provides the basic functionality for

The solvers are called by the user through a unique interface, which calls the required elliptic solver for a class using the name under which the solver routine is registered.

EllBase itself defines the elliptic classes

  1. flat: Ell_LinFlat
    solves a linear elliptic equation in flat space: ϕ + Mϕ + N = 0
  2. metric: Ell_LinMetric
    solves a linear elliptic equation for a given metric: gϕ + Mϕ + N = 0
  3. conformal metric: Ell_LinConfMetric
    solves a linear elliptic equation for a given metric and a conformal factor: cgϕ + Mϕ + N = 0
  4. generic: solves a linear elliptic equation by passing the stencil functions. There is support for a maximum of 27 stencil functions (33). This is not implemented, yet.

2 Technical Specification

3 ToDo

4 Solving an elliptic equation

EllBase provides a calling interface for each of the elliptic classes implemented. As a user you must provide all information needed for a particular elliptic class. In general this will include

Motivation: At a later stage you might want to compile with a different solver for this elliptic class: just change the name of the solver in your elliptic interface call. If somebody improves a solver you have been using, there is no need for you to change any code on your side: the interface will hide all of that. Another advantage is that your code will compile and run, even though certain solvers are not compiled in. In this case, you will have to do some return value checking to offer alternatives.

4.1 Ell_LinFlat

To call this interface from Fortran:

 call Ell_LinFlatSolver(ierr, cctkGH, phi_gfi, M_gfi, N_gfi,  
.                       AbsTol, RelTol, "solvername")

To call this interface from C:

 
 ierr = Ell_LinFlatSolver(GH, phi_gfi, M_gfi, N_gfi,  
                          AbsTol, RelTol, "solvername");

Argument List:

Example use in Fortran, as used in the WaveToy arrangement: CactusWave/IDScalarWave:

 
c     We derive the grid function indicies from the names of the  
c     grid functions:  
      call CCTK_VarIndex (Mcoeff_gfi, "idscalarwaveelliptic::Mcoeff")  
      call CCTK_VarIndex (Ncoeff_gfi, "idscalarwaveelliptic::Ncoeff")  
      call CCTK_VarIndex (phi_gfi,    "wavetoy::phi")  
 
c     Load the Absolute Tolerance Arrays  
      AbsTol(1)=1.0d-5  
      AbsTol(2)=1.0d-5  
      AbsTol(3)=1.0d-5  
 
c     Load the Relative Tolerance Arrays, they are not  
c     used here: -1  
      RelTol(1)=-1  
      RelTol(2)=-1  
      RelTol(3)=-1  
 
c     Call to elliptic solver, named ‘‘sor’’  
      call Ell_LinFlatSolver(ierr, cctkGH,  
     .     phi_gfi, Mcoeff_gfi, Ncoeff_gfi, AbsTol, RelTol,  
     .     "sor")  
 
c     Do some error checking, a call to another solver  
c     could be coded here  
      if (ierr.ne.0) then  
         call CCTK_WARN(0,"Requested solver not found / solve failed");  
      endif

4.2 Ell_LinMetric

To call this interface from Fortran:

 call Ell_LinMetricSolver(ierr, cctkGH, Metric_gfi,  
.             phi_gfi, M_gfi, N_gfi,  
.                         AbsTol, RelTol, "solvername")

To call this interface from C:

 ierr = Ell_LinMetricSolver(GH, Metric_gfi,  
              phi_gfi, M_gfi, N_gfi,  
                            AbsTol, RelTol, "solvername");

Argument List:

4.3 Ell_LinConfMetric

To call this interface from Fortran:

 call Ell_LinMetricSolver(ierr, cctkGH, MetricPsi_gfi,  
.             phi_gfi, M_gfi, N_gfi,  
.                         AbsTol, RelTol, "solvername")

To call this interface from C:

 ierr = Ell_LinMetricSolver(GH, MetricPsi_gfi,  
              phi_gfi, M_gfi, N_gfi,  
                            AbsTol, RelTol, "solvername");

Argument List:

5 Extending the elliptic solver class

EllBase by itself does not provide any elliptic solving capabilities. It merely provides the registration structure and calling interface.

The idea of a unified calling interface can be motivated as follows: assume you a have elliptic problem which conforms to one of the elliptic classes defined in EllBase.

5.1 Registration Mechanism

Before a user can successfully apply a elliptic solver to one of his problems, two things need to be done by the author who programs the solver.

The registration process is part of the authors thorn, not part of EllBase. There is no need to change code in EllBase. Usually, a author of solver routines will register the routines that register an elliptic equation class and/or an elliptic solver in the STARTUP timebin. If a author registers both, class and solver, you must make sure, that the elliptic class is registered before the solver registration takes place.

5.2 EllBase Programming Guide

Here we give a step by step guide on how to implement an new elliptic solver class, its interface and provide a solver for this class. Since some of the functionality needed in the registration code can only be achieved in C, a basic knowledge of C is helpful.

6 Norms

7 Parameters




elliptic_verbose
Scope: restricted  KEYWORD



Description: elliptic verbosity



Range   Default: no
yes
be verbose in elliptic
no
silence in elliptic
debug
even more verbose in elliptic



8 Interfaces

General

Implements:

ellbase

Adds header:

EllBase.h

Ell_DBstructure.h

9 Schedule

This section lists all the variables which are assigned storage by thorn CactusElliptic/EllBase. Storage can either last for the duration of the run (Always means that if this thorn is activated storage will be assigned, Conditional means that if this thorn is activated storage will be assigned for the duration of the run if some condition is met), or can be turned on for the duration of a schedule function.

Storage

NONE

Scheduled Functions

CCTK_STARTUP

  ell_registerbaseeqtypes

  register the standard elliptic classes

 

 Language:c
 Type: function