cppyyy/TopoBox-3D

1---2pretty_name: TopoBox-3D3language:4  - en5tags:6  - neural-operators7  - partial-differential-equations8  - scientific-machine-learning9  - topology10  - hodge-laplacian11---12 13# TopoBox-3D14 15[Paper (arXiv:2609.05860)](https://arxiv.org/abs/2609.05860) | [Code (GitHub)](https://github.com/asmld/TopoBox-3D)16 17TopoBox-3D is the dataset accompanying **Beyond Arbitrary Geometry: Topology18Generalization in Neural PDE Operators**. It is a controlled three-dimensional19benchmark for separating fixed-topology geometry shift from generalization to20unseen homological support.21 22The benchmark contains 5,280 connected box-minus-void geometries and 63,36023fixed-time Hodge-heat instances. Through-tunnels and enclosed cavities control24the first and second Betti numbers. Every geometry is represented by a25tetrahedral mesh, geometry features, a regular-grid signed-distance field, and26an oriented simplicial complex. Hodge-heat data are provided for vertex, edge,27and face cochains (`k = 0, 1, 2`) under four initial-condition configurations.28 29## Scope30 31| Item | Count |32|---|---:|33| Protocols | 4 |34| Geometries per protocol | 1,320 |35| Geometries in total | 5,280 |36| Degrees per geometry | 3 |37| Initial conditions per degree | 4 |38| PDE instances in total | 63,360 |39| Geometry HDF5 shards | 108 |40| Hodge-heat HDF5 shards | 212 |41 42Each protocol has 800 training, 120 validation, 200 Test-IID, and 200 Test-OOD43geometries. Geometry IDs are the atomic split unit.44 45| Protocol | In-support topology | Test-OOD topology | Shift |46|---|---|---|---|47| A | `(beta1, beta2) = (1, 1)`, family A | `(1, 1)`, family B | fixed-topology geometry |48| B | `beta1 in {0,1,2}, beta2 = 0` | `(3, 0)` | unseen tunnel support |49| C | `beta1 = 0, beta2 in {0,1,2}` | `(0, 3)` | unseen cavity support |50| D | `(beta1, beta2) in {0,1,2}^2` | `(3, 3)` | mixed topology |51 52## Directory layout53 54```text55TopoBox-3D/56├── DATASET.md                 detailed geometry schema57├── dataset_config.json        generation and protocol configuration58├── manifest.csv               one row per geometry59├── packed/                    training-ready geometry HDF5 shards60│   ├── index.csv61│   ├── index.json62│   └── protocol_{A,B,C,D}/...63└── protocol_{A,B,C,D}/...     raw per-geometry mesh data64 65TopoBox-3D-HodgeHeat/66├── manifest.json              equation and generation configuration67├── index.csv68├── index.json                 geometry-to-shard lookup69├── COMPLETION.json            completion and adapter checks70├── audit_report.json          deep numerical audit71└── protocol_{A,B,C,D}/...     Hodge-heat HDF5 shards72 73examples/74└── TopoBox-3D-HodgeHeat-representatives/75                                lightweight topology and field previews76 77RELEASE.json                   release-level counts and provenance78SHA256SUMS.txt                 checksums for all published files79```80 81The raw geometry layer contains `mesh.npz`, `mesh.msh`, `mesh.vtu`, and82`metadata.json` for every geometry. The packed layer stores the same numerical83content in HDF5 shards optimized for training. Both layers are included so the84release supports efficient experiments, per-sample inspection, and independent85repacking. The small `TopoBox-3D-mini` development subset is not duplicated in86this repository because it is derived from the complete release. The87`examples/` directory contains only lightweight previews referenced by the88saved completion record; it is not an additional data split.89 90## Hodge-heat task91 92The supervised target is the fixed-time solution of93 94```text95partial_t omega + kappa Delta_k omega = 0,96k in {0,1,2}, kappa = 1, T = 0.1.97```98 99Targets use homogeneous absolute boundary conditions and 100100Crank--Nicolson steps. The four initial-condition configurations are101`non_harmonic`, `weak_harmonic`, `balanced`, and `strong_harmonic`. Geometry and102PDE records are joined by `geometry_id`.103 104## Loading with the accompanying code105 106After placing this dataset under the code repository's `data/` directory, the107expected roots are:108 109```text110data/TopoBox-3D/packed/111data/TopoBox-3D-HodgeHeat/112```113 114```python115from topobox3d.pde_dataset import TopoBoxPDEDataset116 117dataset = TopoBoxPDEDataset(118    geometry_packed_root="data/TopoBox-3D/packed",119    solution_root="data/TopoBox-3D-HodgeHeat",120    protocol="B",121    split="train",122    degrees=(1,),123    configs=("balanced",),124)125 126sample = dataset[0]127print(sample.geometry_id, sample.w0.shape, sample.wT.shape)128dataset.close()129```130 131The accompanying [code repository](https://github.com/asmld/TopoBox-3D)132contains the generators, validators, model adapters, training entry points,133and complete schema documentation. See the134[paper](https://arxiv.org/abs/2609.05860) for the benchmark and reported results.135 136## Integrity and validation137 138The geometry manifest and both HDF5 indices contain 5,280 unique geometry IDs.139The Hodge-heat release contains 212 shards and 63,360 PDE instances. The saved140deep audit reports zero errors. `SHA256SUMS.txt` can be used to verify the local141copy after download.142 143## License and citation144 145Dataset license metadata has not yet been specified.146 147For the paper, see [Beyond Arbitrary Geometry: Topology Generalization in Neural PDE Operators (arXiv:2609.05860)](https://arxiv.org/abs/2609.05860).148