[petsc-dev] questions on new include organization

[Barry Smith]

  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. ;-)