elkrb 1.0.0

data/Rakefile

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec
+
+namespace :benchmark do
+  desc "Generate test graphs for benchmarking"
+  task :generate_graphs do
+    ruby "benchmarks/generate_test_graphs.rb"
+  end
+
+  desc "Run ElkRb benchmarks"
+  task elkrb: :generate_graphs do
+    ruby "benchmarks/elkrb_benchmark.rb"
+  end
+
+  desc "Run elkjs benchmarks (requires Node.js and elkjs)"
+  task elkjs: :generate_graphs do
+    sh "node benchmarks/elkjs_benchmark.js"
+  end
+
+  desc "Generate performance report"
+  task :report do
+    ruby "benchmarks/generate_report.rb"
+  end
+
+  desc "Run all benchmarks and generate report"
+  task all: %i[elkrb report] do
+    puts "\nAll benchmarks completed!"
+    puts "Note: Run 'rake benchmark:elkjs' separately if elkjs is installed"
+  end
+end
+
+namespace :validate do
+  desc "Import test cases from elkjs"
+  task :import_elkjs do
+    ruby "spec/cross_validation/elkjs_test_importer.rb"
+  end
+
+  desc "Import test cases from Java ELK"
+  task :import_java_elk do
+    ruby "spec/cross_validation/java_elk_test_importer.rb"
+  end
+
+  desc "Import all test cases from elkjs and Java ELK"
+  task import_all: %i[import_elkjs import_java_elk]
+
+  desc "Run cross-validation tests"
+  task :run do
+    ruby "spec/cross_validation/validation_runner.rb"
+  end
+
+  desc "Import and run cross-validation (full pipeline)"
+  task all: %i[import_all run]
+
+  desc "Generate validation report (AsciiDoc)"
+  task :report do
+    ruby "spec/cross_validation/generate_validation_report.rb"
+  end
+end

data/benchmarks/README.md

@@ -0,0 +1,172 @@
+# ElkRb Performance Benchmarks
+
+This directory contains the performance benchmarking suite for ElkRb, comparing it against elkjs and potentially Java ELK.
+
+## Directory Structure
+
+```
+benchmarks/
+├── fixtures/
+│   └── graphs.json           # Test graphs in JSON format
+├── results/
+│   ├── elkrb_results.json    # Raw ElkRb benchmark results
+│   ├── elkrb_summary.json    # ElkRb summary with metadata
+│   ├── elkjs_results.json    # Raw elkjs benchmark results (if run)
+│   └── elkjs_summary.json    # elkjs summary with metadata (if run)
+├── generate_test_graphs.rb   # Generates test graphs
+├── elkrb_benchmark.rb         # ElkRb benchmark runner
+├── elkjs_benchmark.js         # elkjs benchmark runner (requires Node.js)
+├── generate_report.rb         # Generates performance report
+└── README.md                  # This file
+```
+
+## Running Benchmarks
+
+### Prerequisites
+
+* Ruby 3.0+ with ElkRb installed
+* Node.js 14+ (optional, for elkjs comparison)
+* elkjs npm package (optional, install with `npm install elkjs`)
+
+### Quick Start
+
+Run all ElkRb benchmarks and generate report:
+
+```bash
+rake benchmark:all
+```
+
+### Individual Commands
+
+**Generate test graphs:**
+```bash
+rake benchmark:generate_graphs
+# or
+ruby benchmarks/generate_test_graphs.rb
+```
+
+**Run ElkRb benchmarks:**
+```bash
+rake benchmark:elkrb
+# or
+ruby benchmarks/elkrb_benchmark.rb
+```
+
+**Run elkjs benchmarks** (requires Node.js and elkjs):
+```bash
+rake benchmark:elkjs
+# or
+node benchmarks/elkjs_benchmark.js
+```
+
+**Generate performance report:**
+```bash
+rake benchmark:report
+# or
+ruby benchmarks/generate_report.rb
+```
+
+## Test Graphs
+
+The benchmark suite uses four test graphs of varying complexity:
+
+1. **Small Simple** (10 nodes, 15 edges)
+   - Simple graph for basic performance testing
+   - Fast execution, ideal for algorithm correctness verification
+
+2. **Medium Hierarchical** (50 nodes, 75 edges, 3 levels)
+   - Hierarchical structure with nested containers
+   - Tests handling of parent-child relationships
+
+3. **Large Complex** (200 nodes, 400 edges)
+   - Large flat graph with many nodes
+   - Tests scalability of algorithms
+
+4. **Dense Network** (100 nodes, 500 edges)
+   - Dense connectivity between nodes
+   - Stresses edge routing and overlap prevention
+
+## Benchmark Methodology
+
+* **Iterations**: Each algorithm runs 10 times with a warm-up run
+* **Timing**: Average execution time in milliseconds
+* **Timeout**: 5 seconds per algorithm to prevent hangs
+* **Error Handling**: Algorithms that fail are marked with error messages
+* **Consistency**: Same test graphs used across all implementations
+
+## Performance Metrics
+
+The benchmarks collect:
+
+* **Average Time**: Mean execution time across 10 runs
+* **Min/Max Time**: Best and worst execution times
+* **Memory Usage**: Memory delta during execution (ElkRb only)
+* **Errors**: Stack overflows, timeouts, or other failures
+
+## Algorithms Benchmarked
+
+* `layered` - Hierarchical layered layout
+* `force` - Force-directed layout
+* `stress` - Stress minimization
+* `box` - Simple box layout
+* `random` - Random positioning
+* `fixed` - Fixed node positions
+* `mrtree` - Tree layout
+* `radial` - Radial/circular layout
+* `rectpacking` - Rectangle packing
+* `disco` - Disconnected graph handling
+* `topdownpacking` - Top-down packing
+* `libavoid` - Orthogonal routing (libavoid-inspired)
+* `vertiflex` - Vertical flex layout
+
+Note: `sporeOverlap` and `sporeCompaction` are not yet implemented in ElkRb.
+
+## Performance Report
+
+The generated performance report (`docs/PERFORMANCE.adoc`) includes:
+
+* Benchmark environment details
+* Methodology description
+* Performance comparison tables
+* Algorithm performance analysis
+* Recommendations for different use cases
+* Future optimization opportunities
+
+## Known Issues
+
+* **Cyclic Graphs**: Some algorithms (e.g., MRTree) don't handle cyclic graphs well
+* **Hierarchical Graphs**: Nested container support varies by algorithm
+* **Timeouts**: Complex algorithms may timeout on very large graphs
+* **Memory**: Ruby uses more memory than JavaScript due to interpreter overhead
+
+## Tips for Running Benchmarks
+
+1. **Close other applications** to ensure consistent performance
+2. **Run multiple times** if you need statistical significance
+3. **Adjust timeout** in `elkrb_benchmark.rb` if needed (default: 5s)
+4. **Check logs** in `benchmarks/results/` for detailed data
+5. **Compare carefully** - different environments may have different results
+
+## Interpreting Results
+
+* **< 10ms**: Fast, suitable for real-time/interactive use
+* **10-50ms**: Medium speed, good for most applications
+* **50-200ms**: Slower, suitable for batch processing
+* **> 200ms**: Slow, consider simpler algorithms or optimization
+* **Timeout**: Algorithm doesn't scale well for this graph size
+
+## Contributing
+
+To add new benchmark graphs:
+
+1. Edit `generate_test_graphs.rb`
+2. Add a new graph generation method
+3. Include it in `generate_all`
+4. Re-run benchmarks
+
+To benchmark against Java ELK:
+
+1. Create `java_elk_benchmark.java` or `.sh` script
+2. Output results in same JSON format
+3. Update `generate_report.rb` to include Java results
+4. Add rake task for Java benchmarks

data/benchmarks/elkjs_benchmark.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+// elkjs Performance Benchmark
+
+const fs = require('fs');
+
+// Import elkjs - we'll check if it's available
+let ELK;
+try {
+  ELK = require('elkjs');
+} catch (e) {
+  console.error('ERROR: elkjs not installed. Install it with: npm install elkjs');
+  process.exit(1);
+}
+
+class ElkjsBenchmark {
+  constructor() {
+    this.elk = new ELK();
+    this.graphs = this.loadGraphs();
+    this.results = {};
+  }
+
+  loadGraphs() {
+    const data = fs.readFileSync('benchmarks/fixtures/graphs.json', 'utf8');
+    return JSON.parse(data);
+  }
+
+  async run() {
+    console.log('elkjs Performance Benchmark');
+    console.log('='.repeat(60));
+    console.log(`Node Version: ${process.version}`);
+
+    try {
+      const pkg = require('elkjs/package.json');
+      console.log(`elkjs Version: ${pkg.version}`);
+    } catch (e) {
+      console.log('elkjs Version: unknown');
+    }
+
+    console.log();
+
+    for (const [name, data] of Object.entries(this.graphs)) {
+      console.log(`Graph: ${name} - ${data.description}`);
+      await this.benchmarkGraph(name, data.graph);
+      console.log();
+    }
+
+    this.saveResults();
+  }
+
+  async benchmarkGraph(name, graphData) {
+    this.results[name] = {};
+
+    const algorithms = [
+      'layered', 'force', 'stress', 'box', 'random', 'fixed',
+      'mrtree', 'radial', 'disco'
+    ];
+
+    for (const algorithm of algorithms) {
+      try {
+        const times = [];
+
+        // Clone graph data for each test
+        const testGraph = JSON.parse(JSON.stringify(graphData));
+        testGraph.layoutOptions = { 'elk.algorithm': algorithm };
+
+        // Warm-up run
+        await this.elk.layout(testGraph);
+
+        // Benchmark runs (10 iterations)
+        for (let i = 0; i < 10; i++) {
+          const testGraphCopy = JSON.parse(JSON.stringify(graphData));
+          testGraphCopy.layoutOptions = { 'elk.algorithm': algorithm };
+
+          const start = process.hrtime.bigint();
+          await this.elk.layout(testGraphCopy);
+          const end = process.hrtime.bigint();
+
+          times.push(Number(end - start) / 1_000_000); // Convert to ms
+        }
+
+        const avg = times.reduce((a, b) => a + b) / times.length;
+        const min = Math.min(...times);
+        const max = Math.max(...times);
+
+        this.results[name][algorithm] = { avg, min, max };
+
+        console.log(`  ${algorithm.padEnd(20)}: ${this.formatTime(avg)}`);
+      } catch (error) {
+        console.log(`  ${algorithm.padEnd(20)}: ERROR - ${error.message}`);
+        this.results[name][algorithm] = { error: error.message };
+      }
+    }
+  }
+
+  formatTime(ms) {
+    if (ms < 1) return `${(ms * 1000).toFixed(2)}µs`;
+    if (ms < 1000) return `${ms.toFixed(2)}ms`;
+    return `${(ms / 1000).toFixed(2)}s`;
+  }
+
+  saveResults() {
+    const summary = {
+      timestamp: new Date().toISOString(),
+      node_version: process.version,
+      elkjs_version: this.getElkjsVersion(),
+      results: this.results
+    };
+
+    fs.writeFileSync(
+      'benchmarks/results/elkjs_results.json',
+      JSON.stringify(this.results, null, 2)
+    );
+
+    fs.writeFileSync(
+      'benchmarks/results/elkjs_summary.json',
+      JSON.stringify(summary, null, 2)
+    );
+
+    console.log('='.repeat(60));
+    console.log('Results saved to:');
+    console.log('  - benchmarks/results/elkjs_results.json');
+    console.log('  - benchmarks/results/elkjs_summary.json');
+  }
+
+  getElkjsVersion() {
+    try {
+      const pkg = require('elkjs/package.json');
+      return pkg.version;
+    } catch (e) {
+      return 'unknown';
+    }
+  }
+}
+
+// Run benchmark
+if (require.main === module) {
+  new ElkjsBenchmark().run().catch(console.error);
+}
+
+module.exports = ElkjsBenchmark;

data/benchmarks/elkrb_benchmark.rb

@@ -0,0 +1,145 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "elkrb"
+require "json"
+require "benchmark"
+
+# ElkRb Performance Benchmark
+class ElkrbBenchmark
+  ALGORITHMS = %w[
+    layered force stress box random fixed
+    mrtree radial rectpacking disco
+    sporeOverlap sporeCompaction
+    topdownpacking libavoid vertiflex
+  ].freeze
+
+  def initialize
+    @graphs = load_graphs
+    @results = {}
+  end
+
+  def run
+    puts "ElkRb Performance Benchmark"
+    puts "=" * 60
+    puts "Ruby Version: #{RUBY_VERSION}"
+    puts "ElkRb Version: #{Elkrb::VERSION}"
+    puts
+
+    @graphs.each do |name, data|
+      puts "Graph: #{name} - #{data['description']}"
+      benchmark_graph(name, data["graph"])
+      puts
+    end
+
+    save_results
+    generate_report
+  end
+
+  private
+
+  def load_graphs
+    JSON.parse(File.read("benchmarks/fixtures/graphs.json"))
+  end
+
+  def benchmark_graph(name, graph_data)
+    @results[name] = {}
+
+    ALGORITHMS.each do |algorithm|
+      times = []
+      memory_before = get_memory_usage
+
+      # Warm-up run with timeout
+      result = run_with_timeout(5) do
+        Elkrb.layout(graph_data, algorithm: algorithm)
+      end
+
+      if result.nil?
+        puts "  #{algorithm.ljust(20)}: TIMEOUT (> 5s)"
+        @results[name][algorithm] = { error: "Timeout" }
+        next
+      end
+
+      # Benchmark runs (10 iterations)
+      10.times do
+        time = Benchmark.realtime do
+          Elkrb.layout(graph_data, algorithm: algorithm)
+        end
+        times << time
+      end
+
+      memory_after = get_memory_usage
+      memory_delta = memory_after - memory_before
+
+      avg_time = times.sum / times.size
+      min_time = times.min
+      max_time = times.max
+
+      @results[name][algorithm] = {
+        avg: avg_time * 1000, # Convert to ms
+        min: min_time * 1000,
+        max: max_time * 1000,
+        memory: memory_delta,
+      }
+
+      puts "  #{algorithm.ljust(20)}: #{format_time(avg_time * 1000)}"
+    rescue StandardError, SystemStackError => e
+      error_msg = e.is_a?(SystemStackError) ? "Stack overflow (graph has cycles)" : e.message
+      puts "  #{algorithm.ljust(20)}: ERROR - #{error_msg}"
+      @results[name][algorithm] = { error: error_msg }
+    end
+  end
+
+  def run_with_timeout(seconds, &)
+    require "timeout"
+    Timeout.timeout(seconds, &)
+  rescue Timeout::Error
+    nil
+  end
+
+  def get_memory_usage
+    `ps -o rss= -p #{Process.pid}`.to_i
+  end
+
+  def format_time(ms)
+    if ms < 1
+      "#{(ms * 1000).round(2)}µs"
+    elsif ms < 1000
+      "#{ms.round(2)}ms"
+    else
+      "#{(ms / 1000).round(2)}s"
+    end
+  end
+
+  def save_results
+    File.write(
+      "benchmarks/results/elkrb_results.json",
+      JSON.pretty_generate(@results),
+    )
+  end
+
+  def generate_report
+    summary = {
+      timestamp: Time.now.iso8601,
+      ruby_version: RUBY_VERSION,
+      elkrb_version: Elkrb::VERSION,
+      results: @results,
+    }
+
+    File.write(
+      "benchmarks/results/elkrb_summary.json",
+      JSON.pretty_generate(summary),
+    )
+
+    puts "=" * 60
+    puts "Results saved to:"
+    puts "  - benchmarks/results/elkrb_results.json"
+    puts "  - benchmarks/results/elkrb_summary.json"
+  end
+end
+
+# Run benchmark when executed directly
+if __FILE__ == $PROGRAM_NAME
+  ElkrbBenchmark.new.run
+end