Subject: [UFC-dev] comments on the manual

From: [email-masked]
Date: Tue, 5 Jun 2007 22:54:28 +0200 (CEST)

Hi, I feel that (much of) the UFC manual now is more like a UFC
reference than a user manual. Is that the way we want it ?
I think we can generate
a reference from the header file once it is properly documented,
except for the conventions on the polygon entities which need
to be drawn.

First of all, I would like to
put in more examples. For instance, on page 15 we could
put in several examples on forms with different arity, coefficients
finite elements etc.
Examples may be:

1:
Arity 2, with no coefficients: div matrix:
  (div u, p)

2:
Arity 2, with two coefficients: nonlinear convection
  (rho u\cdot\nabla u, v )

3:
Arity 1: right hand side:
   (f, v)

4:
Arity 0: H1 error norm
   (\nabla (u - u_h), \nabla (u - u_h)

These examples will demonstrate the notation on page 15.

Additionally, we can have

5:
Boundary facet integral:
   (g, v)   on boundary

6.
Interior facet integral:
   (nabla u, nabla v), discont. Galerkin.

This examples demonstrate most of the features in the notation on
page 14 and 15.

Some of these examples will then need to be repeated in the section
concerning the discrete operator, and some of the generated
code for these forms can be shown in Section 3.

It might also be that a finite element, a dof map, and a
degree of freedom have to be defined abstractly in order
to be able to explain their software counterparts, I
am not sure.

Finally, I also think we should say something about the design
which I don't think is necessarily obvious.
The UFC classes are organized as classes that should work with
flat C-arrays or pointers. It does not contain functionality for
creating or
checking arrays. The users need to do that. Instead there are:
1) functions that can be used to compute the proper size of the
   arrays such that the user may allocate such an array
   (or reuse an existing one)
2) functions for filling the arrays, e.g. computing the
   element tensor.

There are many alternative ways we could have designed this,
so I feel we should clarify this point. We have of course choosen
this path for maximal portabillity between Fortran/C/C++/Python.

I can put in most of the examples here and write something about
design issues. I just wanted to ask for your opinions first
in case someone have a clear view of what this document should
look like.

Kent

---

From: Anders Logg <[email-masked]>
Date: Tue, 5 Jun 2007 23:05:39 +0200

> reference than a user manual. Is that the way we want it ?

Since UFC is a specification for a low-level code interface, it may be
natural that the "manual" becomes more of a reference than a manual.
UFC will only be used directly by experts I guess.

> except for the conventions on the polygon entities which need

I think we shouldn't touch the ufc.h any more, keep the comments in
there to a minimum (a single line for each function) and then say what
we need to say in the reference.

> put in several examples on forms with different arity, coefficients

Yes, more examples would be good, but I didn't think we had time to
add them.

> Arity 2, with no coefficients: div matrix:

Is p a test function? I would use q instead.

> Arity 1: right hand side:

In these examples, the test function v needs to be first. Maybe we
should say this also explicitly. (It corresponds to the first
dimension in the matrix.)

> code for these forms can be shown in Section 3.

All these examples would be very good to have!

> to be able to explain their software counterparts, I

Would also be very good.

> 2) functions for filling the arrays, e.g. computing the

Would also be very good to explain.

> in case someone have a clear view of what this document should

I have no objections.

/Anders

---

From: "Martin Sandve Alnæs" <[email-masked]>
Date: Wed, 6 Jun 2007 09:26:31 +0200

> UFC will only be used directly by experts I guess.

It should have a reference-like part; it must be very easy to go
quickly to the description of function foo in class bar. But
descriptive examples are very good to have too.

Should we include the complete source in the manual? F.ex. we could
start each class section of the interface chapter with a figure of the
class in question, instead of spreading code snippets around. This
could also reduce the "reference feeling" a bit.

> > this path for maximal portabillity between Fortran/C/C++/Python.

Nah... I wouldn't press that language argument. The interface does not
translate easily to either fortran or C, and python is probably not
very interesting at this level. Even ignoring the obvious about using
abstract classes and factory functions, we still have some "double **"
function arguments that don't translate well.

We rather chose this path because, although we need the flexiblity of
virtual functions, this is still low level code which needs a minimal
overhead. Pointers allow the assembly implementer to either copy data
or pass pointers into existing structures.

> > in case someone have a clear view of what this document should

I'm all for that.

martin