docs: Zensical Documentation Site with Scientific Visualization Suite

[Anselmoo]

Zensical Documentation Site with Scientific Visualization Suite

Summary

Create a modern documentation site using Zensical (the next-gen SSG from the Material for MkDocs team), leveraging its modern design system with Material Design 3 color palette compatibility, featuring state-of-the-art scientific visualization for optimizer benchmark results inspired by COCO/IOHprofiler standards.

Why Zensical? The squidfunk team (creators of Material for MkDocs) launched Zensical in November 2025 as their next-generation static site generator. It addresses MkDocs' architectural limitations and supply chain risks (unmaintained since Aug 2024) while providing 5x faster rebuilds, blazing-fast Disco search, and full mkdocs.yml compatibility.

---

Technology Stack

Core Framework

Component	Technology	Rationale
SSG	Zensical	Next-gen from squidfunk team, Rust+Python, 5x faster rebuilds
Build Engine	ZRX	Differential build engine - backbone of Zensical (Open Source)
Theme	Modern Design	Built-in brandable design, breaks from Material Design aesthetic
Colors	Material Design 3	Built-in deep purple + teal palette with dark/light toggle
Search	Disco	Blazing-fast client-side search with filtering & aggregation
Math	MathJax/KaTeX	Full LaTeX support for optimization equations
Diagrams	Mermaid	Native support inherited from Material for MkDocs
API Docs	mkdocstrings	Tim (@pawamoy) joining Zensical team for API reference

Built-in Color Palette (Zero Custom CSS)

Zensical inherits Material for MkDocs' battle-tested color system:

# zensical.yml (compatible with mkdocs.yml)
theme:
  palette:
    # Light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: deep purple
      accent: teal
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    # Dark mode  
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: deep purple
      accent: teal
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

Deep Purple + Teal Palette:

• deep purple (#673AB7) - Primary: headers, links, navigation accents
• teal (#009688) - Accent: buttons, highlights, interactive elements
• slate - Dark mode background scheme
• Automatic WCAG AA contrast compliance

Zensical-Specific Advantages

Feature	Benefit for useful-optimizer
ZRX Differential Builds	Only rebuild changed pages - critical for 100+ algorithm docs
Disco Search	Filtering by category, aggregation, fuzzy matching for 100+ algorithms
mkdocs.yml Compatibility	Minimal migration effort from existing MkDocs projects
Module System (Early 2026)	Replace plugins with deterministic, parallelizable modules
Component System (2026)	Custom Vue-like components for scientific visualizations
CommonMark Rust Parser	Significant Markdown performance improvements
mkdocstrings Integration	Native Python docstring extraction (Google-style)

---

Scientific Visualization Architecture

Overview

Three-tier visualization system matching academic benchmarking standards (COCO, IOHprofiler, Nevergrad):

┌─────────────────────────────────────────────────────────────────┐
│                    TIER 1: Scientific Standard                   │
│  ┌─────────┐ ┌──────────────┐ ┌────────┐ ┌──────────┐ ┌───────┐ │
│  │  ECDF   │ │ Convergence  │ │ Violin │ │ Friedman │ │Wilcox │ │
│  │  Curve  │ │ w/Confidence │ │  Plot  │ │ Heatmap  │ │Matrix │ │
│  └─────────┘ └──────────────┘ └────────┘ └──────────┘ └───────┘ │
├─────────────────────────────────────────────────────────────────┤
│                    TIER 2: Interactive Exploration               │
│  ┌─────────┐ ┌──────────────┐ ┌──────────┐ ┌─────────┐ ┌──────┐ │
│  │   3D    │ │   Search     │ │ Parallel │ │ Perf.   │ │Radar │ │
│  │Landscape│ │  Trajectory  │ │  Coords  │ │ Profile │ │Chart │ │
│  └─────────┘ └──────────────┘ └──────────┘ └─────────┘ └──────┘ │
├─────────────────────────────────────────────────────────────────┤
│                    TIER 3: Dashboard Integration                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │  Unified Dashboard: Algorithm Selection → Multi-View Panel  │ │
│  │  Statistical Summary: Avg | Std | Best | Worst | Time | FE  │ │
│  └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

---

Tier 1: Scientific Standard Visualizations

1.1 Empirical Cumulative Distribution Function (ECDF)

The gold standard for optimizer comparison (COCO platform standard):

interface ECDFConfig {
  targetPrecisions: number[];  // e.g., [1e-1, 1e-3, 1e-5, 1e-7]
  maxBudget: number;           // Max function evaluations
  logScale: boolean;           // Log-scale x-axis
  confidenceBands: boolean;    // Bootstrap confidence intervals
}

Implementation:

• X-axis: log₁₀(#f-evaluations / dimension)
• Y-axis: Proportion of (function, target) pairs solved
• Multiple line series per algorithm
• Shaded confidence bands (95% CI)

1.2 Convergence Curves with Confidence Bands

interface ConvergenceConfig {
  runs: number;                 // Default: 30 independent runs
  showConfidenceBand: boolean;  // ±1 std or 95% CI
  showMedian: boolean;          // Median line + IQR shading
  logYAxis: boolean;            // Log-scale fitness
  aggregation: 'mean' | 'median' | 'best';
}

Metrics per iteration:

• Mean ± Standard Deviation
• Median with IQR (Q1-Q3) shading
• Best/Worst envelope

1.3 Boxplot / Violin Plot Comparison

Statistical distribution of final fitness values across 30 runs:

interface BoxplotConfig {
  showViolin: boolean;       // Kernel density overlay
  showPoints: boolean;       // Scatter individual runs
  showOutliers: boolean;     // Mark statistical outliers
  sortBy: 'median' | 'mean' | 'name';
}

1.4 Friedman Test Heatmap

Rank-based statistical comparison across multiple functions:

interface FriedmanHeatmapConfig {
  functions: string[];        // Benchmark functions
  algorithms: string[];       // Optimizers to compare
  cellContent: 'rank' | 'avg_rank' | 'p_value';
  colorScale: 'viridis' | 'material';  // Material Design colors
}

Statistical Protocol:

1. Run each algorithm 30 times per function
2. Compute Friedman chi-squared statistic
3. Post-hoc Nemenyi test for pairwise comparison
4. Critical difference diagram

1.5 Wilcoxon Signed-Rank Matrix

Pairwise statistical significance testing:

interface WilcoxonMatrixConfig {
  significanceLevel: number;  // α = 0.05
  correction: 'bonferroni' | 'holm' | 'none';
  cellDisplay: 'p_value' | 'symbol' | 'both';  // ✓✗ or p-values
}

---

Tier 2: Interactive Exploration

2.1 3D Fitness Landscape

Interactive surface plots using JavaScript charting (Plotly.js or ECharts-GL):

interface LandscapeConfig {
  function: string;            // e.g., 'shifted_ackley'
  resolution: number;          // Grid points per axis
  showContour: boolean;        // 2D contour projection
  showSearchPath: boolean;     // Overlay optimization trajectory
  colormap: 'viridis' | 'plasma' | 'material';
}

Features:

• Orbit controls (rotate, zoom, pan)
• Click-to-inspect fitness values
• Animated search trajectory overlay
• Toggle between surface/wireframe/contour

2.2 Search Trajectory Animation

Visualize optimizer population movement:

interface TrajectoryConfig {
  playbackSpeed: number;       // Iterations per second
  showTrails: boolean;         // Ghost positions
  trailLength: number;         // Frames to retain
  colorByFitness: boolean;     // Heatmap coloring
  showBestPath: boolean;       // Highlight global best trajectory
}

2.3 Parallel Coordinates Plot

High-dimensional parameter space exploration:

interface ParallelCoordConfig {
  dimensions: string[];        // Parameters to display
  colorBy: 'fitness' | 'algorithm' | 'iteration';
  brushing: boolean;           // Interactive range selection
  polylineOpacity: number;     // 0.0-1.0
}

2.4 Performance Profile

Dolan-Moré performance profiles:

interface PerformanceProfileConfig {
  metric: 'time' | 'evaluations' | 'iterations';
  tau_max: number;             // Max performance ratio
  logScale: boolean;
}

2.5 Algorithm Radar Chart

Multi-criteria comparison:

interface RadarConfig {
  criteria: Array<{
    name: string;              // e.g., 'Convergence Speed'
    min: number;
    max: number;
    optimal: 'min' | 'max';
  }>;
  normalize: boolean;
}

Default Criteria:

• Convergence Speed
• Final Precision
• Robustness (low std)
• Scalability (dimension performance)
• Computational Cost

---

Tier 3: Dashboard Integration

Unified Benchmark Dashboard

<!-- Conceptual dashboard structure -->
<div class="benchmark-dashboard">
  <!-- Algorithm/Function Selector -->
  <select-panel algorithms="..." functions="..." />
  
  <!-- Multi-View Grid -->
  <grid-layout>
    <ecdf-chart />
    <convergence-chart />
    <violin-plot />
    <friedman-heatmap />
  </grid-layout>
  
  <!-- Statistical Summary Table -->
  <stats-table />
</div>

Statistical Summary Table

Algorithm	Avg	Std	Best	Worst	Median	FE	Time(s)	Rank
PSO	1.23e-5	2.1e-6	8.9e-6	2.1e-5	1.1e-5	10000	0.42	1
DE	2.45e-5	3.2e-6	1.2e-5	4.3e-5	2.3e-5	10000	0.38	2
SGO	3.12e-5	4.5e-6	2.1e-5	5.8e-5	3.0e-5	10000	0.45	3

---

Data Format Specification

IOHprofiler-Compatible JSON Schema

interface OptimizationRun {
  algorithm: string;
  function: string;
  dimension: number;
  run_id: number;
  seed: number;
  trajectory: Array<{
    iteration: number;
    evaluations: number;
    best_fitness: number;
    current_fitness?: number;
    best_position?: number[];
    timestamp_ms?: number;
  }>;
  final_result: {
    best_fitness: number;
    best_position: number[];
    total_evaluations: number;
    wall_time_seconds: number;
    converged: boolean;
  };
  metadata?: {
    hyperparameters: Record<string, any>;
    hardware: string;
    python_version: string;
  };
}

interface BenchmarkSuite {
  name: string;
  description: string;
  created_at: string;
  config: {
    runs_per_instance: number;  // Default: 30
    max_evaluations: number;
    target_precision: number;
  };
  results: OptimizationRun[];
}

Export Format per Algorithm Category

docs/
├── api/
│   ├── swarm_intelligence.json    # mkdocstrings-generated
│   ├── evolutionary.json
│   ├── gradient_based.json
│   ├── classical.json
│   ├── physics_inspired.json
│   ├── social_inspired.json
│   ├── metaheuristic.json
│   ├── probabilistic.json
│   ├── constrained.json
│   └── multi_objective.json
├── benchmarks/
│   ├── sphere_30d.json            # Benchmark results
│   ├── rosenbrock_30d.json
│   ├── shifted_ackley_30d.json
│   └── summary_statistics.json
└── landscapes/
    ├── sphere_2d.json             # For 3D visualization
    ├── rosenbrock_2d.json
    └── ackley_2d.json

---

mkdocstrings Integration for Python Docstrings

Configuration (zensical.yml)

# zensical.yml
plugins:
  - mkdocstrings:
      handlers:
        python:
          options:
            docstring_style: google
            show_source: true
            show_root_heading: true
            members_order: source
            separate_signature: true
            signature_crossrefs: true

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.superfences
  - pymdownx.arithmatex:
      generic: true
  - admonition
  - attr_list
  - md_in_html

API Documentation Page Structure

# Particle Swarm Optimization

::: opt.swarm_intelligence.particle_swarm.ParticleSwarm
    options:
      show_root_heading: true
      heading_level: 2
      members:
        - __init__
        - search
        - _update_velocity
        - _update_position

---

Project Structure

docs/
├── zensical.yml                  # Zensical config (mkdocs.yml compatible)
├── api/
│   ├── index.md                  # API overview
│   ├── swarm-intelligence.md
│   ├── evolutionary.md
│   ├── gradient-based.md
│   ├── classical.md
│   ├── physics-inspired.md
│   ├── social-inspired.md
│   ├── metaheuristic.md
│   ├── probabilistic.md
│   ├── constrained.md
│   └── multi-objective.md
├── benchmarks/
│   ├── index.md                  # Benchmark overview
│   ├── methodology.md            # 30-run protocol
│   ├── results.md                # Interactive dashboard
│   └── functions.md              # Benchmark function docs
├── guide/
│   ├── index.md                  # Getting started
│   ├── installation.md
│   ├── quickstart.md
│   └── advanced.md
├── algorithms/
│   ├── index.md                  # Algorithm overview
│   ├── particle-swarm.md
│   ├── social-group-optimizer.md
│   └── ...
├── assets/
│   ├── stylesheets/
│   │   └── extra.css             # Minimal custom CSS (if needed)
│   └── javascripts/
│       └── charts.js             # Chart initialization
└── overrides/                    # Template overrides (Jinja2/MiniJinja)
    └── main.html

---

Implementation Outlook

Phase 1: Foundation (Immediate - Q1 2026)

Leverages Zensical's current capabilities

• Initialize Zensical project with pip install zensical
• Configure zensical.yml with deep purple + teal palette
• Set up MathJax/KaTeX integration for equations
• Configure mkdocstrings for Python docstrings
• Create basic page structure and navigation
• Benefit: 5x faster rebuilds via ZRX, Disco search out-of-the-box

Phase 2: API Documentation (Q1 2026)

• Set up mkdocstrings with Google-style docstring parsing
• Generate API docs for all 100+ algorithms
• Cross-link related algorithms
• Add type annotations and examples
• Outlook: Zensical's native API documentation system will replace mkdocstrings plugin

Phase 3: Scientific Visualizations (Q1-Q2 2026)

Component System enables custom interactive elements

• Implement Tier 1 charts (ECDF, Convergence, Violin, Heatmaps)
• Outlook - Component System: When Zensical's component system releases (early 2026):
  • Self-contained visualization components
  • SSR-rendered with client-side rehydration (island architecture)
  • Native integration without external runtime
  • Asset compilation built into Zensical

# Future: Zensical Component (conceptual)
# components/ecdf-chart.zen
<script>
  export let algorithms: string[];
  export let data: BenchmarkResult[];
</script>

<template>
  <div class="ecdf-chart">
    <canvas ref="chart"></canvas>
  </div>
</template>

<style scoped>
  .ecdf-chart { /* component-scoped styles */ }
</style>

Phase 4: Benchmark Integration (Q2 2026)

Module System enables custom data pipelines

• Design benchmark data collection script
• Run 30-run benchmark suite for all algorithms
• Build unified dashboard
• Implement statistical tests (Friedman, Wilcoxon)
• Outlook - Module System: When released:
  • Custom module for benchmark data processing
  • Automatic dependency tracking in task graph
  • Intelligent build caching for benchmark results
  • Python API via PyO3 bindings

# Future: Zensical Module (conceptual)
from zensical import Module, artifact

class BenchmarkModule(Module):
    """Process benchmark results for visualization."""
    
    @artifact("benchmarks/*.json")
    def process_benchmarks(self, data):
        # Transform benchmark data
        return processed_data

Phase 5: Polish & Deploy (Q2 2026)

• Responsive design optimization
• Accessibility audit (WCAG AA)
• Performance optimization (lazy loading)
• GitHub Pages deployment
• CI/CD pipeline for auto-rebuild
• Benefit: Disco standalone OSS release (early 2026) for advanced search customization

---

Technical Requirements

Dependencies (pyproject.toml)

[project.optional-dependencies]
docs = [
    "zensical>=0.0.14",           # Core SSG
    "mkdocstrings[python]>=0.27", # API documentation
    "mkdocs-material>=9.6",       # Fallback compatibility
]

Build Scripts

{
  "scripts": {
    "docs:dev": "zensical serve",
    "docs:build": "zensical build",
    "docs:preview": "zensical serve --build"
  }
}

uv Integration

# Install docs dependencies
uv sync --extra docs

# Serve documentation locally
uv run zensical serve

# Build for production
uv run zensical build

---

Zensical Roadmap Alignment

Zensical Feature	Timeline	Impact on useful-optimizer Docs
Current	Now	5x faster rebuilds, Disco search, mkdocs.yml compatibility
Module System	Early 2026	Custom benchmark processing, deterministic builds
Component System	Early 2026	Interactive visualization components (ECDF, 3D landscapes)
CommonMark Parser	2026	Faster Markdown processing for 100+ algorithm pages
Disco Standalone	Early 2026	Advanced search customization (filtering by category)
API Documentation	2026	Native multi-language API docs (replaces mkdocstrings)
Subprojects	2026	Separate benchmark suite as interconnected subproject

---

Success Criteria

1. Documentation Coverage: All 100+ algorithms documented with examples
2. Visualization Quality: Research-grade charts matching IOHprofiler standards
3. Performance: Lighthouse score > 90 on all metrics
4. Accessibility: WCAG AA compliance
5. Search: Sub-100ms search results via Disco
6. Build Time: < 60 seconds for full site generation (via ZRX differential builds)
7. Migration: Zero content changes required from existing MkDocs setup

---

References

Zensical Ecosystem

• Zensical - Next-gen SSG from squidfunk team
• ZRX - Differential build engine (Open Source)
• Zensical Roadmap - Module system, component system timeline
• Zensical Announcement

Scientific Benchmarking

• COCO Platform - Comparing Continuous Optimizers
• IOHprofiler - Iterative Optimization Heuristics Profiler
• IOHanalyzer - Interactive performance analysis
• Nevergrad - Gradient-free optimization platform

Documentation Tools

• mkdocstrings - Python API documentation
• Material for MkDocs - Color palette reference

---

Related Issues

• epic: VitePress Documentation Site with Scientific Visualization Suite #52 - VitePress documentation (alternative approach with Catppuccin Mocha)
• docs: MkDocs Material Documentation with Built-in Color Palette & Scientific Visualization #54 - MkDocs Material with built-in colors (fallback if Zensical is too new)
• Enhance SocialGroupOptimizer with convergence tracking and adaptive parameters #49 - SocialGroupOptimizer enhancements (example use case for visualization)