The Dxtr library in broad strokes

Following Dieter Rams principles for good Design (the 4th & 10th especially), and drawing inspiration from the FEniCS library, we tried to make our implementation of DEC as close as possible to the underlying mathematical concepts.

In the following we will detail a bit the architecture of the library and present its main modules, classes and functions.

Architecture

src/dxtr
    ├── cochains #(2)
    │   ├── cochain
    │   ├── example_cochains
    │   └── whitneymap
    ├── complexes #(1)
    │   ├── abstractsimplicialcomplex
    │   ├── example_complexes
    │   ├── simplex
    │   ├── simplicialcomplex
    │   ├── simplicialmanifold
    │   └── Module
    ├── io
    │   ├── read
    │   └── write
    ├── math
    │   ├── geometry
    │   └── topology
    ├── operators #(3)
    │   ├── differential
    │   ├── curvature
    │   ├── hodge
    │   └── musical
    ├── utils
    │   ├── logging
    │   ├── quality_control
    │   ├── typecheck
    │   └── wrappers
    └── visu
        ├── visu_plotly
        ├── visu_pyvista
        └── visualize

Let's review quickly the organization of the three main modules.

• Complexes

  The complexes module encapsulates classes needed to implement geometrical entities such as simplices (Simplex) or simplicial complexes (SimplicialComplex). These classes are related through inheritance and aggregation as depicted through the dependency graph below.

  Basics use-case examples of SimplicialComplex manipulations can be found in the dedicated notebook.

  Fig.2: Complexes Module hierarchy graph.

  flowchart BT
  
  subgraph *math* Module
      Top
      Geo
      end
  
  Asc -...-> Top[[*math.topology*]]
  Sm & Sc -....-> Geo[[*math.geometry*]]
  
  Asc(AbstractSimplicalComplex) --o mdl(Module) --o Splx(Simplex)
  Sc(SimplicialComplex) --> Asc
  Sm(SimplicialManifold) --> Sc

  The main classes & their relationships. plain arrows signal inheritance, dotted arrows dependency and plain lines ended with dots composition.

• Cochains

  The cochains module is dedicated to the implementation of discrete differential forms, aka cochains.

  Beside the Cochain sub-module, which contains the eponymous class, this module also features a WhitneyMap class. Given a SimplicialManifold instance, this class enables the computation of Whitney k-maps on it, i.e. the interpolation of k-cochains on top-level simplices. Such interpolation maps are central in our implementation of the sharp() operator, see musical isomorphisms. This is also worth noticing that Whitney maps are central in the defintion of a a proper Finite Element Method adapted to differential form. Such a FEM is for now not available within the current version (1.0.0) of the Dxtr library, but the basic ingredients are here.

  Check the dedicated notebook for some examples of cochain basic manipulations.

• Operators

  The operators module gathered functions acting on cochains. It is subdivied into various thematics:

  differentialhodgemusicalwedgecurvature

  The differential sub-module contains the implementation of the exterior derivative(exterior_derivative) and all the subsequent differential operators, e.g. the Laplacian (laplacian()) or divergence (divergence())

  The hodge sub-module hosts the hodge star (hodge_star()) operator this enables to transform a primal cochain into a dual one and vice-versa.

  The musical sub-module gathers the flat (flat()) & sharp (sharp()) musical isomorphisms. These operators purpose is to convert (discrete) vector fields into cochains (flat()) and conversly cochains into vector fields (sharp()).

  This sub-module encompasses the implementation of the wedge product (wedge()) that enables to generate a (k+l)-cochain from two cochains of degrees k and l (1).

  1. In the current version (V 1.0.0), only primal cochains can be "wedged" together. The extension toward dual cochains is currently being developped.

  Implementations of the Gaussian & mean curvatures (resp. gaussian_curvature() & mean_curvature()) can be found in the curvature submodule(1).

  1. This curvature module is currently (V 1.0.0) a work in progress.

  Some examples of operators acting on cochain can be seen in the dedicated notebook.

  Fig.3: Differential operator dependency graph

  flowchart BT
  
      subgraph *differential*
          ED(Exterior derivative)
          CD(Codifferential)
          Lpc(Laplacian)
          Div(Divergence)
          Lie(Lie derivative):::Soon
          end
  
      subgraph *musical*
          Flt(Flat)
          Shp(Sharp)
          end
      subgraph *hodge*
          HS(Hodge star)
          end
  
      subgraph *wedge*
          Wdg(Wedge product):::Soon
          Ctr(Contraction):::Soon
          end
  
  CD --> ED & HS  
  Lpc ---> ED & CD
  Div ---> CD & HS
  Ctr ---> HS & Flt & Wdg 
  Lie ----> ED & Ctr
  
  
  classDef Soon stroke-dasharray: 5 5

  The gray boxes corresponds to various sub-modules. The boxes with dashed contour correspond to operators that are not yet fully implemented. The arrows points from an operator toward the ones its definition relies on.

• Additional modules

  To support and complement these three core modules, you will also find:

  mathiovisuutils

  This module that contains functions & algorithms to perform all the needed computations required by the various data structures & methods.

  This module enables the user to read & write files on disk, mostly in the .ply & .vtk format.

  This module contains functions to visualize simplicial complexes & cochains. It relies on two visualization libraries: plotly and pyvista (optional).

  This is where housekeeping data structures, methods and decorators are centralized.

  Fig.4: Dxtr submodule dependency graph

  
  flowchart RL
  
  Op(operators) --> Cp(complexes) & Co(cochains) & Mat(math)
  Vis[visu] --> Cp(complexes) & Co(cochains) --> Mat(math) & Io(io) 
  Uti(utils)

  The arrows show the dependency relationship between the various modules of the library.
  Note: No arrow points toward utils for clarity reason, but all other modules rely on it however.

External dependencies

The biggest external dependencies of the library come from its algebraic nature. We implemented a lot of attributes as array to gain in computing time and therefore lie heavily on the numpy library. Likewise, a lot of matrices, used to implement the chain complex notably, have been implemented in a sparse format, making use of the sparse module from the scipy library. Note that in order to efficiently implemented the exterior product (wedge() operator) we needed a sparse implementation of putatively large 3rd order tensors. To that end, we made use of the COO class from the sparse library, adding it to the list of external dependencies.

• numpy: Used ubiquitously throughout the whole library.
• scipy: Mainly the sparse module to implement big matrices such as the ones encountered in the chain complex implementation.
• sparse: Only needed in the wedge() operator to efficiently handle putatively large 3rd order tensors.
• plotly: A visualization library used to draw simplicial complexes.
• pyvista: A visualization library specialized in mesh representation. Used to visualize Cochain instances. We also make use of its UGrid data structure & .vtk file format to save on disk SimplicialComplex and Cochain instances.

Coding style

Throughout the Dxtr library, we manipulate a limited number of objects and concepts. In order to ligthen the code, we chose to use abreviations and aliases to refer to the most commonly used ones. To keep the code as self-explanable as possible we tried to say consistant and always used the same abreviation for a given concept.

In the next sections, we briefly introduce the main modules and classes of the library. For technical details on specific methods or attributes, please refer to the API Reference guide.