dolfin team mailing list archive

[Joachim B Haga <jobh@xxxxxxxxxxxx>]

I'm just starting finding my way around dolfin, and I think it would be easier
(more discoverable in ipython or your-ide-of-choice) if the dolfin namespace
weren't so cluttered.

At the moment there are 546 attributes in the dolfin namespace (with only
ublas). I don't know dolfin well enough to say which are pointless, but I can
make some educated guesses:

- 113 of the functions in the main namespace are called *_swigregister, and are
  probably not meant to be called by the user.

- A number of functions seem to be "leaked" from c++. Examples: ios, ios_base,
  ios_base_sync_with_stdio, ios_base_xalloc, iostream, istream, istringstream,
  endl_cb_ptr, ends, ends_cb_ptr.

- Some utility functions which are not dolfin-specific. Example: is_empty,
  tokens(?)

- Functions that duplicate native python functions or numpy/math
  functions. Examples: ipow, sqr, rand, DOLFIN_PI, Identity

- Some all-uppercase attributes are constants, other are classes. Are the
  constants used? If so, maybe use a submodule (namespace) for constants?
  Examples: LINE, TRIANGLE vs. ODE, LU.

- 20 other 1-2 character attributes. I know some of them are end-user
  relevant. Are all? D, a, b, cg, dS, ds, dx, f, i, j, k, l, m, n, t0, t1, v,
  v0, v1, v2
  (Side note: the demos use "from dolfin import *". The common pattern of "for
  i in N:" will rebind the variable "i" outside the loop, so this is rather
  fragile in practice. The fully qualified variant "dolfin.i" is of course
  immune to this problem.)

- 11 cpp_* functions. Are they meant to be called by the user?

- A few leaks from other modules. Examples: Set (sets.Set), array (numpy.array)

- Variables that are probably used internally in the library.
  vecs = [array([ 2.,  0.,  0.]), array([ 0.,  2.,  0.])]
  a = (-1.0, -1.0, -1.0)
  b = (1.0, -1.0, -1.0)
  cg = 0
  alpha = 0.0

- Class methods that are also exposed directly. Examples:
  MatrixFactory_computeConvectionMatrix (MatrixFactory.computeConv...)
  MatrixFactory_computeLoadVector (MatrixFactory.computeLoad...)
  MatrixFactory_computeMassMatrix (MatrixFactory.computeMass...)
  MatrixFactory_computeStiffnessMatrix (MatrixFactory.computeStiff...)
  GraphPartition_*

- Some non-obvious names. Examples: dolfin_{add,get,set} which could perhaps be
  called {add,get,set}_parameter. I was actually looking for this functionality
  but didn't find it before compiling this list :)

- The 23 methods called ublas_* or uBlas* are an obvious candidate for a
  submodule, or are they supposed to be used directly instead of through
  GenericMatrix etc? I don't have petsc, but that's probably another candidate.


I could make a patch myself, but I don't know enough about this stuff to feel
comfortable making these decisions (especially since some of the choices are
probably made for c++/python equivalence, and I don't plan to use the c++
part).

-j.