Skip to content

Behavior report: faces and edges with identical boundaries are accepted (expected?) #13

Open

Description

@mzargham

Behavior report, not a feature request. This documents what 0.2.0 does so it can be marked as expected or unexpected.

Observed behavior

add_face accepts any number of faces with the same three boundary edges, provided each has its own ID. add_edge likewise accepts any number of edges with the same two vertices. Neither the write-time SHACL checks nor audit() report anything. The boundary is also accepted in any order.

Why this looks unexpected

In a simplicial complex a simplex is determined by its vertices: there is one edge between two vertices and one triangle on three edges. kc describes itself as a library for typed simplicial complexes, and ARCHITECTURE.md lists the topological rules it enforces (boundary vertices distinct, closed triangle, boundary closure). Uniqueness of a simplex given its boundary is not among them, and I could not find it stated or ruled out in the README, ARCHITECTURE.md or docs/.

Orientation does not explain it either. The data model is unordered: add_edge takes vertices as a set, and add_face takes boundary as an unordered collection of edges (an edge cannot be told apart from its reverse). Orientation appears only as an internal sign convention in knowledgecomplex/analysis.py (boundary_matrices and _orient_face pick signs from vertex index order). So two simplices with the same boundary are not distinguishable as oppositely oriented ones. Allowing them would be a different structure (a multigraph or a Δ-complex), and then betti_numbers would be answering for that structure.

Minimal reproduction (kc only)

from knowledgecomplex import (
    SchemaBuilder, KnowledgeComplex, betti_numbers, euler_characteristic,
)

sb = SchemaBuilder(namespace="ex")
sb.add_vertex_type("node")
sb.add_edge_type("link")
sb.add_face_type("tri")
kc = KnowledgeComplex(schema=sb)

for v in ("a", "b", "c"):
    kc.add_vertex(v, type="node")
kc.add_edge("ab", type="link", vertices={"a", "b"})
kc.add_edge("bc", type="link", vertices={"b", "c"})
kc.add_edge("ca", type="link", vertices={"c", "a"})

kc.add_face("f1", type="tri", boundary=["ab", "bc", "ca"])
print("one face:    betti", betti_numbers(kc), "euler", euler_characteristic(kc))

kc.add_face("f2", type="tri", boundary=["ab", "bc", "ca"])   # different id, same edges
print("f2 accepted. coboundary of 'ab':", sorted(kc.coboundary("ab")))
kc.add_face("f3", type="tri", boundary=["ca", "ab", "bc"])   # same edges, other order
print("f3 accepted. coboundary of 'ab':", sorted(kc.coboundary("ab")))
print("three faces: betti", betti_numbers(kc), "euler", euler_characteristic(kc))
print("audit conforms:", kc.audit().conforms)

Output (knowledgecomplex 0.2.0, Python 3.14.3, analysis extra installed):

one face:    betti [1, 0, 0] euler 1
f2 accepted. coboundary of 'ab': ['f1', 'f2']
f3 accepted. coboundary of 'ab': ['f1', 'f2', 'f3']
three faces: betti [1, 0, 2] euler 3
audit conforms: True

The same for edges:

sb = SchemaBuilder(namespace="ex"); sb.add_vertex_type("node"); sb.add_edge_type("link")
kc = KnowledgeComplex(schema=sb)
for v in ("a", "b"): kc.add_vertex(v, type="node")
kc.add_edge("e1", type="link", vertices={"a", "b"})
kc.add_edge("e2", type="link", vertices={"a", "b"})
print(betti_numbers(kc), euler_characteristic(kc), kc.audit().conforms)
# [1, 1, 0] 0 True

Related cases I checked

  • Adding a face again with the same ID and the same boundary is a no-op.
  • Adding a face again with the same ID and a different boundary merges the two boundaries (six edges on one face) and fails the SHACL face shape. This one is caught.

Not checked

Duplicates introduced through load, the file codecs, or infer_faces.

The question

Is accepting these intended? If it is, a line in the documentation would help people who read "simplicial complex" literally. If it is not, this is the behavior to track.

Workaround in use

Derive each element's ID from its boundary and check coboundary for an existing element on the same boundary before adding.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions