PUNC Programmer's Guide


Table of Contents

NOTE: This documentation provides information about the programming interface provided by the PUNC software and a general guide to linking to the PUNC libraries. Information about installation, configuration, and general usage can be found in the User's Guide.


PUNC (Portable Understructure for Numerical Computing) was written by Michael Holst at Caltech and UC San Diego, primarily as a portability layer for FEtk (the Finite Element TookKit).

Clean OO C Formalism

PUNC was written in Clean OO C, which is a self-imposed disciplined coding formalism for producing object-oriented ANSI/Standard C which can be compiled with either a C or C++ compiler. We will briefly describe the formalism here (borrowing from N. Baker's nice description in the APBS documentation).

Clean OO C formalism requires that all public data is enclosed in structures which resemble C++ classes. These structures and member functions are then declared in a public header file which provides a concise description of the interface (or API) for the class. Private functions and data are included in private header files (or simply the source code files themselves) which are not visible generally visible (data encapsulation). When using the library, the user only sees the public header file and the compiled library and is therefore (hopefully) oblivious to the private members and functions. Each class is also equipped with a constructor and destructor function which is responsible for allocating and freeing any memory required by the instatiated objects.

Public data members are enclosed in C structures which are visible to the library user. Public member functions are generated by mangling the class and function names and passing a pointer to the object on which the member function is supposed to act. For example, a public member function with the C++ declaration

   public double Foo::bar(int i, double d)
would be declared as
   double Foo_bar(Foo *thee, int i, double d)
where VEXTERNC is a compiler-dependent macro, the underscore _ replaces the C++ double-colon ::, and thee replaces the this variable implicit in all C++ classes. Since they do not appear in public header files, private functions could be declared in any format pleasing to the user, however, the above declaration convention should generally be used for both public and private functions. Within the source code, the public and private function declarations/definitions are prefaced by the macros VPUBLIC and VPRIVATE, respectively. These are macros which reduce global name pollution, similar to encapsulating private data withing C++ classes.

The only C++ functions not explicitly covered by the above declaration scheme are the constructors (used to allocate and initialize class data members) and destructors (used to free allocated memory). These are declared in the following fashion: a constructor with the C++ declaration

    public void Foo::Foo(int i, double d)
would be declared as
     Foo* Foo_ctor(int i, double d)
which returns a pointer to the newly constructed Foo object. Likewise, a destructor declared as
     public void Foo::~Foo()
in C++ would be
     void Foo_dtor(Foo **thee)
in Clean OO C.

Finally, inline functions in C++ are simply treated as macros in Clean OO C and declared/defined using "#define" statements in the public header file. See any of the PUNC header files for more examples on the Clean OO C formalism.

Coding Style

The best (and most entertaining) description of a C coding style that is very close to what I use in PUNC is that described by Linus Torvalds in his "CodingStyle" file in the Linux kernel sources (usually found in the file "/usr/src/linux/Documentation/CodingStyle" on any Linux box). He describes a coding style that is modular, completely documented (but in a spartan way), and very practical.

Below are some additional notes on the coding style I use in PUNC beyond what Torvalds describes. These additional guidelines are mostly concerned with being compatible with the Clean OO C dialect, giving an object-oriented look and feel to PUNC.

Application programming interface documentation

The API documentation for this code was generated by doxygen. You can either view the API documentation by using the links at the top of this page, or the slight re-worded/re-interpreted list below:


    PUNC = < Portable Understructure for Numerical Computing >
    Copyright (C) 1994--2006  Michael Holst <mholst@math.ucsd.edu>
    This program is free software; you can redistribute it and/or modify it
    under the terms of the GNU General Public License as published by the
    Free Software Foundation; either version 2 of the License, or (at your
    option) any later version.
    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    See the GNU General Public License for more details.
    You should have received a copy of the GNU General Public License along
    with this program; if not, write to the Free Software Foundation, Inc.,
    675 Mass Ave, Cambridge, MA 02139, USA.

Generated on Mon Aug 9 11:13:09 2010 for PUNC by  doxygen 1.5.6