garywelz/programming_framework

1# Whole of Mathematics — Interactive Zoomable Chart Design2 3## Vision4 5A single, high-level interactive visualization that shows the **entire landscape of mathematics** as our collection understands it—with the ability to **zoom in** from broad domains down to individual processes, and to **click through** to the actual flowchart or dependency graph for any process.6 7Think of it as a "map of mathematics" that is:8- **Data-driven** — built from `metadata.json` and our hierarchy9- **Zoomable** — pan and zoom like a geographic map or Prezi10- **Drillable** — click a region to focus on it and see its children11- **Linked** — deepest level opens the existing process HTML page12 13---14 15## Domain Grouping: arXiv Math Taxonomy16 17Use the **arXiv Mathematics** taxonomy (math.XX) as the canonical domain structure. arXiv is widely recognized, stable, and aligns with how mathematicians categorize research.18 19### arXiv Math Categories (math.XX)20 21| Code | Name |22|------|------|23| math.AC | Commutative Algebra |24| math.AG | Algebraic Geometry |25| math.AP | Analysis of PDEs |26| math.AT | Algebraic Topology |27| math.CA | Classical Analysis and ODEs |28| math.CO | Combinatorics |29| math.CT | Category Theory |30| math.CV | Complex Variables |31| math.DG | Differential Geometry |32| math.DS | Dynamical Systems |33| math.FA | Functional Analysis |34| math.GM | General Mathematics |35| math.GN | General Topology |36| math.GR | Group Theory |37| math.GT | Geometric Topology |38| math.HO | History and Overview |39| math.IT | Information Theory |40| math.KT | K-Theory and Homology |41| math.LO | Logic |42| math.MG | Metric Geometry |43| math.MP | Mathematical Physics |44| math.NA | Numerical Analysis |45| math.NT | Number Theory |46| math.OA | Operator Algebras |47| math.OC | Optimization and Control |48| math.PR | Probability |49| math.QA | Quantum Algebra |50| math.RA | Rings and Algebras |51| math.RT | Representation Theory |52| math.SG | Symplectic Geometry |53| math.SP | Spectral Theory |54| math.ST | Statistics Theory |55 56### Mapping Our Subcategories → arXiv57 58| Our subcategory | arXiv code(s) |59|-----------------|---------------|60| abstract_algebra | math.GR, math.RA, math.AC |61| linear_algebra | math.RA |62| category_theory | math.CT |63| calculus_analysis | math.CA, math.CV, math.DS |64| geometry_topology | math.GN, math.GT, math.AT, math.DG, math.MG |65| number_theory | math.NT |66| discrete_mathematics | math.CO, math.LO |67| foundations | math.LO |68| bioinformatics | (applied; no direct math.XX; use math.GM or separate) |69 70*Wikipedia* math portal uses a flatter structure (Algebra, Analysis, Geometry, etc.)—can serve as a secondary grouping if we want a simpler top level.71 72---73 74## Hierarchy: What We're Mapping75 76### Level 0 — Whole of Mathematics (root)77The entire collection. One view.78 79### Level 1 — arXiv Math Domains (or grouped)80Either use arXiv codes directly (math.NT, math.AG, …) or group into ~6–8 broader areas for a simpler top level:81 82| Domain | arXiv codes | Our subcategories |83|--------|-------------|-------------------|84| **Algebra** | AC, AG, CT, GR, RA, RT, QA | abstract_algebra, linear_algebra, category_theory |85| **Analysis** | AP, CA, CV, FA, NA, SP | calculus_analysis, complex_analysis |86| **Geometry & Topology** | AT, DG, GN, GT, MG, SG | geometry_topology |87| **Number Theory** | NT | number_theory |88| **Discrete & Logic** | CO, LO | discrete_mathematics, foundations |89| **Dynamical Systems** | DS | (part of calculus_analysis) |90| **Probability & Statistics** | PR, ST | (future) |91| **Applied / Other** | GM, MP, OC, IT | bioinformatics |92 93### Level 2 — Subcategories94e.g., within **Analysis**: Real Analysis, Complex Analysis, Complex Dynamics, Symbolic Dynamics.95 96### Level 3 — Processes97Individual charts. Click → open process page.98 99---100 101## Force-Directed Graph: Deep Dive102 103### Why It Aligns With Our Current Metaphor104 105Our existing process charts are **node–link diagrams**:106- **Axiomatic theories**: nodes = axioms, definitions, theorems; edges = "depends on"107- **Algorithms**: nodes = steps; edges = control flow108 109A force-directed graph is the same visual language at a higher level: **nodes and edges**. It extends the dependency-graph metaphor from *within* a process to *between* processes and domains.110 111### Force-Directed vs. Treemap: Core Difference112 113| Aspect | Treemap | Force-Directed Graph |114|--------|---------|----------------------|115| **Structure** | Containment (parent *contains* children) | Links (nodes *connected* by edges) |116| **Relationships** | Implicit (nesting) | Explicit (edges) |117| **Hierarchy** | Strict tree; one parent per node | Can be tree, DAG, or general graph |118| **Cross-links** | Hard to show (a node lives in one place) | Natural (Galois ↔ Field Theory ↔ Group Theory) |119| **Layout** | Rectangles, area = weight | Organic; forces pull/push nodes |120| **Zoom** | Zoom into a region (geometric) | Pan/zoom canvas; click node to focus |121 122### Force-Directed *Can* Be Hierarchical123 124You can use a force-directed layout with **hierarchical constraints**:125- **Parent–child links**: domain → subcategory → process (tree edges)126- **Cross-links**: `namedCollections` overlap, or explicit "related to" (e.g., Galois Theory ↔ Field Theory)127- **Collision / clustering**: Give nodes of the same domain a "gravity" toward each other so they cluster128- **Level-based y-position**: Fix y by depth (root at top, processes at bottom) for a tree-like flow129 130So you get: **hierarchy + relationships** in one view.131 132### Zoom and Pan133 134Force-directed graphs support zoom and pan the same way as treemaps:135- Wrap the graph in an SVG `<g>` (group)136- Apply `d3.zoom()` to the SVG; transform the group on zoom/pan events137- **Geometric zoom**: scale + translate the whole canvas (simple)138- **Semantic zoom** (optional): at different zoom levels, show different detail (e.g., zoomed out = domains only; zoomed in = subcategories; further in = processes)139 140### Ease of Use With Our Collection141 142**Data we have:**143- `subcategory` per process → gives hierarchy (domain → subcategory → process)144- `processType` (algorithm vs axiomatic_theory) → can style nodes differently145- Process IDs and names → node labels and links146 147**Data we can add:**148- `namedCollections` → cross-links: two processes in "fermat" get an edge149- Optional `dependsOn` or `relatedTo` → explicit edges between processes150 151**Graph structure:**152```153Nodes:  [Mathematics (root)] + [~8 domains] + [~10 subcategories] + [~98 processes]154Edges:  Tree edges (parent→child) + optional cross-edges (namedCollections, relatedTo)155```156 157~120 nodes, ~100+ edges is well within D3 force layout comfort zone. No performance concerns.158 159### Relationship to Other Types160 161- **Treemap**: Force-directed shows *links*; treemap shows *containment*. Different metaphors. Treemap is "zoom into a region"; force-directed is "follow the edges."162- **Sunburst**: Both can show hierarchy. Sunburst is radial containment; force-directed is node-link. Sunburst is more compact; force-directed shows relationships.163- **Map metaphor**: Could use force-directed *for layout* (position nodes), then draw "regions" (Voronoi, convex hulls) around domain clusters—hybrid approach.164 165---166 167## Technical Approaches (Summary)168 169### Option A: D3 Zoomable Treemap170- Containment metaphor; area = count; no explicit edges.171- **Fit**: Pure hierarchy, no cross-links.172 173### Option B: D3 Sunburst174- Radial containment; compact.175- **Fit**: Hierarchy; explore later.176 177### Option C: Force-Directed Graph with Zoom ← **Primary choice**178- Node–link; explicit edges; aligns with our dependency-graph metaphor.179- **Fit**: Hierarchy + cross-links; zoom/pan; works with our collection.180 181### Option D: Map Metaphor182- Geographic feel; Voronoi or custom.183- **Fit**: Explore later.184 185### Option E: Hybrid186- Treemap + graph overlay.187- **Fit**: Explore later.188 189---190 191## Recommended: Force-Directed Graph (Option C) + Zoom + Breadcrumbs192 193**Why**: Aligns with our existing node–link dependency metaphor. Shows both hierarchy (domain → subcategory → process) and cross-links (e.g., via `namedCollections`). Zoom and pan are standard (D3 zoom on SVG group). ~120 nodes is trivial for D3 force. Breadcrumbs solve "where am I?" when zoomed.194 195**Data shape** (nodes + links for force-directed):196 197```json198{199  "nodes": [200    { "id": "root", "name": "Mathematics", "level": 0 },201    { "id": "algebra", "name": "Algebra", "level": 1 },202    { "id": "analysis", "name": "Analysis", "level": 1 },203    { "id": "abstract_algebra", "name": "Abstract Algebra", "level": 2 },204    { "id": "abstract_algebra-group-theory", "name": "Group Theory", "level": 3, "processId": "abstract_algebra-group-theory",205      "subcategory": "abstract_algebra", "url": "processes/abstract_algebra/abstract_algebra-group-theory.html" }206  ],207  "links": [208    { "source": "root", "target": "algebra" },209    { "source": "algebra", "target": "abstract_algebra" },210    { "source": "abstract_algebra", "target": "abstract_algebra-group-theory" },211    { "source": "abstract_algebra-field-theory", "target": "abstract_algebra-group-theory" }212  ]213}214```215 216`level` drives hierarchy. `links` include tree edges (parent→child) and optional cross-edges (e.g., Field Theory → Group Theory). `processId` and `url` at leaves for linking.217 218---219 220## Metadata Extensions for the Chart221 222### 1. Domain Mapping (arXiv-Based)223 224Add to `metadata.json`:225 226```json227{228  "domainHierarchy": {229    "algebra": {230      "name": "Algebra",231      "arxiv": ["math.AC", "math.AG", "math.CT", "math.GR", "math.RA", "math.RT", "math.QA"],232      "subcategories": ["abstract_algebra", "linear_algebra", "category_theory"]233    },234    "analysis": {235      "name": "Analysis",236      "arxiv": ["math.AP", "math.CA", "math.CV", "math.FA", "math.NA", "math.SP"],237      "subcategories": ["calculus_analysis", "complex_analysis"]238    },239    "geometry_topology": {240      "name": "Geometry & Topology",241      "arxiv": ["math.AT", "math.DG", "math.GN", "math.GT", "math.MG", "math.SG"],242      "subcategories": ["geometry_topology"]243    },244    "number_theory": {245      "name": "Number Theory",246      "arxiv": ["math.NT"],247      "subcategories": ["number_theory"]248    },249    "discrete_logic": {250      "name": "Discrete & Logic",251      "arxiv": ["math.CO", "math.LO"],252      "subcategories": ["discrete_mathematics", "foundations"]253    },254    "dynamical_systems": {255      "name": "Dynamical Systems",256      "arxiv": ["math.DS"],257      "subcategories": []258    },259    "applied": {260      "name": "Applied & Other",261      "arxiv": ["math.GM", "math.MP", "math.OC", "math.PR", "math.ST"],262      "subcategories": ["bioinformatics"]263    }264  },265  "subcategoryToArxiv": {266    "abstract_algebra": "math.GR",267    "calculus_analysis": "math.CA",268    "geometry_topology": "math.GT"269  }270}271```272 273### 2. Optional: Process-Level "Domain" Override274 275For processes that span domains (e.g., Category Theory), allow:276 277```json278{ "id": "...", "domain": "algebra", "subcategory": "category_theory" }279```280 281Default: derive domain from subcategory via `domainHierarchy`.282 283---284 285## Interaction Design286 287### Zoom & Pan288- **Scroll** or **pinch**: zoom in/out289- **Drag**: pan290- **Double-click** a region: zoom to fit that region (focus)291- **Breadcrumb click**: jump back to that level292 293### Click Behavior294- **Level 1–2** (domain, subcategory): zoom in to show children295- **Level 3** (process): open process page in new tab (or same tab with back)296 297### Visual Feedback298- **Hover**: highlight region, show tooltip (name + count)299- **Focus**: breadcrumb updates; optional sidebar with list of processes in current view300- **Cross-links**: if we add graph overlay, dim non-adjacent regions when hovering a node with many connections301 302---303 304## Responsive & Accessibility305 306- **Mobile**: Touch pan/zoom; larger hit targets for small regions; consider "list view" fallback when zoomed to a subcategory307- **Keyboard**: Tab through regions, Enter to zoom/select308- **Screen readers**: Breadcrumb + list of current level's items as text309 310---311 312## Implementation Phases313 314### Phase 1: Static Hierarchy + Force-Directed Graph315- Add `domainHierarchy` (arXiv-based) to metadata316- Build nodes + links from processes (domain → subcategory → process)317- Single HTML page with D3 force-directed graph + zoom/pan318- **Deliverable**: Working "Whole of Mathematics" graph with our current 98 processes319 320### Phase 2: Process Links321- Leaf nodes (processes) link to process HTML (using existing URL pattern)322- Breadcrumb navigation323- **Deliverable**: Full drill-down from root to process page324 325### Phase 3: Polish326- Tooltips, legend (colors = domains or arXiv codes)327- Optional "list view" toggle for current level328- **Deliverable**: Production-ready interactive chart329 330### Phase 4: Cross-Links (Optional)331- Use `namedCollections` to draw edges between related processes332- Or: "Related" panel when hovering a process333- **Deliverable**: Relationship-aware exploration334 335---336 337## Growing With the Collection338 339As we add:340- **New subcategories** (complex_analysis, landmark_theorems, formal_verification, ai_mathematics): extend `domainHierarchy` and subcategory→arXiv mapping341- **New processes**: they appear automatically (nodes + links derived from metadata)342- **Named mathematicians** (`namedCollections`): cross-edges between processes in the same collection; or a *second* view—"By Mathematician"—same graph structure but nodes grouped by collection. Toggle: "By Topic" | "By Mathematician"343- **New arXiv codes**: add to `domainHierarchy`; graph reflows344 345The chart is **always generated from metadata**—no manual diagram maintenance.346 347---348 349## Alternative: "Map" Metaphor (Future Enhancement)350 351For a more geographic feel:352- **Continents** = domains (irregular shapes, not rectangles)353- **Countries** = subcategories354- **Cities** = processes (dots or small regions)355- Layout: Voronoi tessellation or force-directed placement with "gravity" to keep siblings near each other356- Could use **MapLibre** or **Leaflet** with a custom "projection" that maps our hierarchy to 2D—playful and memorable357 358---359 360## Summary361 362| Aspect | Choice |363|--------|--------|364| **Visualization** | D3 force-directed graph (primary) |365| **Domain taxonomy** | arXiv math.XX (math.AC, math.NT, etc.) |366| **Data** | Nodes + links derived from metadata + `domainHierarchy` |367| **Levels** | 3: Domain → Subcategory → Process |368| **Edges** | Tree (parent→child) + optional cross-links (`namedCollections`) |369| **Interaction** | Zoom, pan, click-to-focus, breadcrumbs |370| **Leaf action** | Open process HTML page |371| **Growth** | Add to metadata; chart updates automatically |372| **Future** | Sunburst, map metaphor—explore later |373 374The "Whole of Mathematics" chart becomes the **entry point** to the database—a node–link visual index that matches our dependency-graph metaphor and scales with the collection.375