cppyyy/TopoBox-3D

TopoBox-3D

Paper (arXiv:2609.05860) | Code (GitHub)

TopoBox-3D is the dataset accompanying Beyond Arbitrary Geometry: Topology Generalization in Neural PDE Operators. It is a controlled three-dimensional benchmark for separating fixed-topology geometry shift from generalization to unseen homological support.

The benchmark contains 5,280 connected box-minus-void geometries and 63,360 fixed-time Hodge-heat instances. Through-tunnels and enclosed cavities control the first and second Betti numbers. Every geometry is represented by a tetrahedral mesh, geometry features, a regular-grid signed-distance field, and an oriented simplicial complex. Hodge-heat data are provided for vertex, edge, and face cochains (k = 0, 1, 2) under four initial-condition configurations.

Scope

Each protocol has 800 training, 120 validation, 200 Test-IID, and 200 Test-OOD geometries. Geometry IDs are the atomic split unit.

Directory layout

TopoBox-3D/
├── DATASET.md                 detailed geometry schema
├── dataset_config.json        generation and protocol configuration
├── manifest.csv               one row per geometry
├── packed/                    training-ready geometry HDF5 shards
│   ├── index.csv
│   ├── index.json
│   └── protocol_{A,B,C,D}/...
└── protocol_{A,B,C,D}/...     raw per-geometry mesh data

TopoBox-3D-HodgeHeat/
├── manifest.json              equation and generation configuration
├── index.csv
├── index.json                 geometry-to-shard lookup
├── COMPLETION.json            completion and adapter checks
├── audit_report.json          deep numerical audit
└── protocol_{A,B,C,D}/...     Hodge-heat HDF5 shards

examples/
└── TopoBox-3D-HodgeHeat-representatives/
                                lightweight topology and field previews

RELEASE.json                   release-level counts and provenance
SHA256SUMS.txt                 checksums for all published files

The raw geometry layer contains mesh.npz, mesh.msh, mesh.vtu, and metadata.json for every geometry. The packed layer stores the same numerical content in HDF5 shards optimized for training. Both layers are included so the release supports efficient experiments, per-sample inspection, and independent repacking. The small TopoBox-3D-mini development subset is not duplicated in this repository because it is derived from the complete release. The examples/ directory contains only lightweight previews referenced by the saved completion record; it is not an additional data split.

Hodge-heat task

The supervised target is the fixed-time solution of

partial_t omega + kappa Delta_k omega = 0,
k in {0,1,2}, kappa = 1, T = 0.1.

Targets use homogeneous absolute boundary conditions and 100 Crank--Nicolson steps. The four initial-condition configurations are non_harmonic, weak_harmonic, balanced, and strong_harmonic. Geometry and PDE records are joined by geometry_id.

Loading with the accompanying code

After placing this dataset under the code repository's data/ directory, the expected roots are:

data/TopoBox-3D/packed/
data/TopoBox-3D-HodgeHeat/

from topobox3d.pde_dataset import TopoBoxPDEDataset

dataset = TopoBoxPDEDataset(
    geometry_packed_root="data/TopoBox-3D/packed",
    solution_root="data/TopoBox-3D-HodgeHeat",
    protocol="B",
    split="train",
    degrees=(1,),
    configs=("balanced",),
)

sample = dataset[0]
print(sample.geometry_id, sample.w0.shape, sample.wT.shape)
dataset.close()

The accompanying code repository contains the generators, validators, model adapters, training entry points, and complete schema documentation. See the paper for the benchmark and reported results.

Integrity and validation

The geometry manifest and both HDF5 indices contain 5,280 unique geometry IDs. The Hodge-heat release contains 212 shards and 63,360 PDE instances. The saved deep audit reports zero errors. SHA256SUMS.txt can be used to verify the local copy after download.

License and citation

Dataset license metadata has not yet been specified.

For the paper, see Beyond Arbitrary Geometry: Topology Generalization in Neural PDE Operators (arXiv:2609.05860).