174 lines
6.3 KiB
Markdown
174 lines
6.3 KiB
Markdown
# Research Notes
|
|
|
|
This crate is moving toward a staged graph anatomy pipeline:
|
|
|
|
```text
|
|
graph -> analysis -> coarse bodies -> constraints -> 3D relaxation -> fold groups
|
|
```
|
|
|
|
The useful lesson from the literature is blunt: do not ask one force soup to
|
|
discover every structure at once. Extract graph structure first, then make the
|
|
solver express it.
|
|
|
|
## Landed
|
|
|
|
These features are implemented in the crate now:
|
|
|
|
- Persistent `Layout3dSolver` for realtime frame-by-frame iteration.
|
|
- Warm-start positions for graph edits and interaction.
|
|
- Barnes-Hut octree repulsion for the 3D solver.
|
|
- Spatial-grid approximate repulsion as a simpler fallback.
|
|
- Repulsion accuracy sweeps against exact all-pairs ground truth.
|
|
- SCC detection for cyclic bodies.
|
|
- weak components for broad spatial islands.
|
|
- articulation points and bridges for hinge-like connectors.
|
|
- biconnected components for blocks that should fold as more durable bodies.
|
|
- k-core numbers and shells for dense nucleus/periphery structure.
|
|
- local clustering coefficients for triangle-rich neighborhoods.
|
|
- deterministic label-propagation communities.
|
|
- fold groups for weak components, SCCs, biconnected blocks, communities,
|
|
core shells, and cycles.
|
|
|
|
## Paper-Derived Design Moves
|
|
|
|
### Constrained Stress
|
|
|
|
Dwyer, Koren, and Marriott show that stress majorization can be augmented with
|
|
linear ordering/separation constraints. That gives us a more principled future
|
|
solver than hand-added forces when rank, spacing, or no-overlap constraints need
|
|
to become harder.
|
|
|
|
Implementation direction:
|
|
|
|
- Add a `StressConfig`.
|
|
- Convert Sugiyama ranks, ordering, and component separation into weighted
|
|
constraints.
|
|
- Use force relaxation as the interactive fast path and constrained stress as
|
|
the higher-quality settle pass.
|
|
|
|
Source:
|
|
https://doi.org/10.1016/j.disc.2007.12.103
|
|
|
|
### Multilevel Layout
|
|
|
|
Walshaw's multilevel force-directed method repeatedly coarsens the graph, lays
|
|
out the coarse graph, then expands and refines. This is exactly the missing
|
|
piece for large graphs and foldable bodies: layout the anatomy before the cells.
|
|
|
|
Implementation direction:
|
|
|
|
- Coarsen by SCC, community, biconnected block, or k-core shell.
|
|
- Lay out coarse bodies first.
|
|
- Expand each body into local coordinates.
|
|
- Relax with cross-body hinge and boundary forces.
|
|
|
|
Source:
|
|
https://doi.org/10.7155/jgaa.00070
|
|
|
|
### Continuous Layout Ergonomics
|
|
|
|
ForceAtlas2 is not magic; it is a practical assembly of force choices, adaptive
|
|
speed, Barnes-Hut approximation, and usability knobs. The useful part for this
|
|
crate is adaptive step control and Barnes-Hut for large interactive layouts.
|
|
|
|
Implementation direction:
|
|
|
|
- Replace fixed cooling with adaptive speed.
|
|
- Tune Barnes-Hut and add benchmarks against exact/grid modes.
|
|
- Expose live-tick APIs for Bevy interaction instead of only batch layout.
|
|
|
|
Current state:
|
|
|
|
- `Layout3dSolver` exists.
|
|
- `RepulsionMode::BarnesHut` is the default realtime path.
|
|
- `RepulsionMode::SpatialGrid` remains available as a simpler local approximation.
|
|
- `RepulsionMode::Exact` remains available for small graphs and comparisons.
|
|
- `repulsion_accuracy_sweep` and `solver_repulsion_accuracy_sweep` report
|
|
absolute/relative error and elapsed time for tuning passes.
|
|
- `TUNING_DOCTRINE.md` records preliminary supervised sweeps and the current
|
|
policy for exact, Barnes-Hut, grid, and future multilevel force categories.
|
|
- Local/global repulsion knobs now expose Barnes-Hut near radius, local pair
|
|
scale, and aggregate far-field scale.
|
|
- `organ_battleground` evaluates raw and body-aware force candidates on
|
|
synthetic fixtures plus SNAP email/Gnutella datasets.
|
|
|
|
Source:
|
|
https://doi.org/10.1371/journal.pone.0098679
|
|
|
|
### Communities
|
|
|
|
Louvain and Leiden are the serious modularity route. Leiden improves Louvain by
|
|
guaranteeing better-connected communities. The crate currently uses deterministic
|
|
label propagation because it is small, fast, dependency-free, and good enough as
|
|
a first structural signal. It is not the final boss.
|
|
|
|
Implementation direction:
|
|
|
|
- Keep label propagation as the cheap default.
|
|
- Add optional Louvain/Leiden-style modularity optimization later.
|
|
- Use community stability across multiple passes as a visual confidence score.
|
|
|
|
Sources:
|
|
https://arxiv.org/abs/0803.0476
|
|
https://www.nature.com/articles/s41598-019-41695-z
|
|
https://doi.org/10.1103/PhysRevE.76.036106
|
|
|
|
### Core/Periphery
|
|
|
|
k-core decomposition is cheap and useful for visualization. Dense cores should
|
|
read as nuclei; low-core leaves should read as peripheral atmosphere, not equal
|
|
citizens in the same spatial argument.
|
|
|
|
Implementation direction:
|
|
|
|
- Use core number to scale anchoring, node mass, and opacity hints.
|
|
- Add `FoldGroupKind::CoreShell` interactions in Bevy.
|
|
- Give high-core regions their own collision shell.
|
|
|
|
Sources:
|
|
https://arxiv.org/abs/cs/0504107
|
|
https://www.nature.com/articles/30918
|
|
|
|
### Edge Bundling
|
|
|
|
Edge bundling is powerful but dangerous. It can reduce clutter while also making
|
|
the underlying graph harder to recover. The right version here is structural and
|
|
inspectable: bundles should be generated from known bodies, edge roles, and
|
|
hierarchy paths, not vague visual mush.
|
|
|
|
Implementation direction:
|
|
|
|
- Add edge control points derived from fold groups.
|
|
- Bundle bridge/cross/back edges differently.
|
|
- Preserve unbundled edge identity for picking and inspection.
|
|
- Treat bundling as renderer geometry, not graph truth.
|
|
|
|
Sources:
|
|
https://www.microsoft.com/en-us/research/publication/improving-layered-graph-layouts-with-edgebundling/
|
|
https://arxiv.org/abs/2108.05467
|
|
|
|
### Dynamic Mental Map
|
|
|
|
Mental-map preservation is more task-dependent than the usual folklore admits.
|
|
The useful move is not "never move nodes"; it is preserving stable landmarks
|
|
when the user needs orientation, while allowing meaningful rearrangement when
|
|
new structure appears.
|
|
|
|
Implementation direction:
|
|
|
|
- Add stable node anchors from previous layouts.
|
|
- Preserve fold group centers more strongly than individual leaf nodes.
|
|
- Expose a `LayoutMemory` object for incremental Bevy updates.
|
|
|
|
Source:
|
|
https://doi.org/10.1016/j.ijhcs.2013.08.004
|
|
|
|
## Next High-Value Crate Work
|
|
|
|
1. Add multilevel coarsening and expansion.
|
|
2. Add a live iterative solver API for Bevy.
|
|
3. Add Barnes-Hut/grid repulsion.
|
|
4. Add edge routing and structural bundling output.
|
|
5. Add optional constrained-stress settling.
|
|
|
|
That is the machine with teeth. Everything else is decoration wearing a badge.
|