Repository navigation
Description
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 TrueRelated 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