dolfin team mailing list archive

[Anders Logg <logg@xxxxxxxxx>]

On Sat, Mar 29, 2008 at 06:17:00PM +0100, Ola Skavhaug wrote:
> Garth N. Wells skrev den 29/03-2008 følgende:
> > 
> > 
> > Johan Hake wrote:
> > > On Saturday 29 March 2008 15:56:29 Anders Logg wrote:
> > >> On Sat, Mar 29, 2008 at 02:42:24PM +0100, Joachim B Haga wrote:
> > >>> 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 :)
> > >> Good suggestion.
> > >>
> > >>> - 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.
> > >> You are right, there are too many things being imported. This is
> > >> because we've been lazy and done import * in many places.
> > >>
> > >> If you want to make a patch (hg export) or bundle, that would be
> > >> excellent. Remove as much as you can, as long as it's possible to
> > >> run the demos.
> > > 
> > > I agree with Joachim and Anders that the namespace is too cluttered. Some are 
> > > probably easy to remove, eg. all swig_ names and the polutions from other 
> > > packages that is internally used. 
> > > 
> > > But some of the pointed out names are imported from FFC, should we eg. place 
> > > this in dolfin.ffc? In a demo or program you could then from dolfin.ffc 
> > > import *. I would also suggest to modularize the actuall dolfin namespace 
> > > too, a la the c++ modules, eg. put all mesh related things in dolfin.mesh 
> > > aso.
> > > 
> > > How close is the python interface ment to be to the c++ interface? 
> > 
> > I would like to keep them similar.

Yes, definitely. The two interfaces should be as equal as possible.
There are some exceptions:

1. Cases where we need to adapt to how things are done differently in
C++ and Python, for example iterators:

  for (CellIterator c(mesh); !c.end(); ++c)
      ...

  for c in cells(mesh):
      ...

2. Cases where we can do things easier/better in Python, for example

  u = Function(...)
  ...
  print norm(u)

which is not possible in C++.

> > I have a
> > > feeling that modularization of namespaces is good practice in python. Doing 
> > > this in a more extensive manner would ofcourse diverge the two interfaces 
> > > with regard to namespaces.
> > > 
> > 
> > If we refine the C++ namespace, how hard would it be to reflect this in 
> > the Python code (i.e. can Swig deal with it automatically)? It would be 
> > nice to have dolfin::mesh and dolfin.mesh, dolfin::la and dolfin.la, etc.
> 
> We're in the lucky situation where the dolfin.py and _dolfin.so files are not
> imported directly, but through the __init__.py file in site-packages/dolfin.
> Hence, we can make the modularization exactly the way we want. The question is
> how we want it.

I'm not sure we need to modularize the namespace, so let's keep it
flat until it's really necessary. My reason for wanting to keep it
flat is:

1. There aren't (or shouldn't be) that many things in the namespace
anyway. Basically, we have a few classes:

    Vector, Matrix, Mesh, FiniteElement, Function, DirichletBC

and a few free functions:

    assemble, solve, plot

2. If you just want the mesh, then do

    from dolfin import Mesh

-- 
Anders