Orientation of simplicial complexes

[ffl096]

The Problem

Simplicial complexes are often used with an arbitrary reference orientation in mind, e.g., when considering edge flows. Consider this simple example:

from toponetx.classes import SimplicialComplex

SC = SimplicialComplex()
SC.add_simplex((2, 1), flow=10)

The user should expect that the edge (2, 1) is added with exactly this orientation, i.e., with an edge flow of 10 from node 2 to node 1. However, TopoNetX does not handle orientation, it transforms the edge into canonical form (1, 2) without any thought about associated data that might be orientation-aware.

Possible Actions

• Full-fledged orientation support. This is a big undertaking, especially for when already existing simplices are re-added with a different orientation. A priori it is not clear how to deal with already existing data, as we cannot infer whether arbitrary user-data is relative to the orientation or not. For data that is relative to orientation, we might have to change the sign, for other data (with may also be numeric), we must not alter them.
• Offload the cannocalization and appropriate sign-changes of data to the user. SimplicialComplex.add_simplex calls are only allowed for pre-sorted tuples.

[ffl096]

A priori it is not clear how to deal with already existing data, as we cannot infer whether arbitrary user-data is relative to the orientation or not. For data that is relative to orientation, we might have to change the sign, for other data (with may also be numeric), we must not alter them.

We can work around this issue by replacing the attributes of existing simplices instead of updating/extending them. If we go that round, we should make this change consistently across all complexes though.