Currently PETSc has the following "organization"
There are eight "packages" (each which can be in its own static/dynamic
library (libpetscPACKAGENAME.something) and has its own include file
petscPACKAGENAME.h*)
sys
vec
mat
dm
characteristic
ksp
snes
ts
Each of these packages (except sys) has a "main" class with the same name as
the package (KSP in ksp, TS in ts example).
Each package also contains a bunch of "related" classes (for example the ksp
package has the PC class, the ts package has the TSAdapt class etc etc).
Each class (except a couple) is implemented as an abstract base class with
several implementations (Mat -> Mat_SeqAIJ etc)
Occasionally there are "almost" subclasses of subclasses (KSPGMRES ->
KSPLGMRES, KSPFGMRES stored in subdirectory of gmres)
The naming of subclasses for names and methods is suppose to be readable
from left to right (for example KSPGMRES, KSPGMRESSetRestart())**
We don't always/usually directly incorporate the names of packages in the
names of the various classes in that package (for example we have PC, we don't
call PC KSPPC, we have PetscViewer we don't have SysViewer) but sometimes we
seem to (TSAdapt is a class in the ts package, or is it a subclass of TS?). We
also have strange names like ISLocalToGlobalMapping which is not a subclass of
IS, nor is it in the is package (there is no is package).
We sometimes namespace with Petsc but usually don't.
Much of the specific naming is historical and happenstance.
I believe that the more we can systematize the naming conventions and
hierarchy the easier we make PETSc to use and maintain/write. At the same time
we have to be somewhat sensitive to what people are used to and probably
shouldn't change 80% of the names every six months. If I were to start PETSc
today I would give packages different names from classes and always name space
everything with Petsc_Packagename_Classname[_Subclassname[_Subsubclass]]
(without the _ of course). For example, PetscLinearKrylov[GMRES[L]],
PetscLinearPreconditionerFieldsplit. Don't worry this is not going to happen.
I guess this is one of the reasons I pick on PetscSection so much; I don't
know where it belongs, it begins with Petsc which (informally) is mostly sys
stuff but it is not like sys stuff, it is implemented in the Vec class part of
the vec package but it is definitely not a Vec.
Note there are no action items in this email, just me thinking out loud.
Barry
* There are other petscxxx.h include files, but generally the user need only
include petscPACKAGENAME.h though Jed seems to have broken this model with some
subclasses like petscdmda.h petscpcmg.h etc not being included by petscdm.h and
petscpc.h (hmm this is both good and bad) not including a bunch of stuff the
user doesn't need or specifically request is good but on the other hand the
user has to specifically include it (increased learning curve). So to use PCMG
functionality directly one must include petscpcmg.h directly but to use field
split they don't need petscpcfieldsplit.h this can lead to user exasperation
(and mine)!
** Note we don't do this for sub sub classes, KSPLGMRES should be KSPGMRESL
etc. pity we should have done it right.
On Feb 13, 2013, at 7:50 AM, Jed Brown <jedbrown at mcs.anl.gov> wrote:
>
> On Wed, Feb 13, 2013 at 7:40 AM, Barry Smith <bsmith at mcs.anl.gov> wrote:
> Regardless of exactly how this shakes out I think you both have to agree
> that PetscSection is a bit of an oddball and it should be more "integrated"
> with the "IS stuff" in that we have a single source code location (directory)
> and set of concepts related to indexing things. And don't have some in the
> Vec directory.
> So, for now, I won't change names or functionality but would like
> permission to move source around. Who knows, maybe in the end the is
> directory will get a more suitable name.
>
> That's fine with me, but note that vsection.c depends on Vec, but IS does not
> depend on Vec. vsection.c depends on Vec so it can't simply be moved to
> src/vec/is.
>
>
> Barry
>
> As you know I really really like having names that convey connections left to
> right, KSPGMRES, PC_ILU etc. I think this helps make the learning and
> understanding curve lower. Now people see IS and PetscSection and they are
> two completely unrelated things to their eyes but in fact they are not
> unrelated and I would like to convey that somehow in the future.
>
> BTW: I consider it a terrible tragedy that in (for example C++ and Java) one
> can define a subclass of a class and just use a completely arbitrary ASCII
> name for the subclass completely unrelated to the class it is derived from,
> talk about losing information.
>
> Just be glad not too many projects chose the German way, using a three-term
> recurrence to compute the designation order, and always withholding the verb
> until the end. ;-)
