cs-element/docs/17-graph-algorithms.md

Advanced reactive data management library with state machines, blueprints, persistence, compression, networking, and multithreading support

# Графовые алгоритмы - Анализ и обход структур данных

Система графовых алгоритмов CSElement предоставляет мощный набор инструментов для анализа и обхода сложных структур данных с оптимизацией производительности и кэшированием результатов.

## 🎯 Основные возможности

### Алгоритмы поиска пути
- **BFS (Breadth-First Search)** - поиск в ширину
- **DFS (Depth-First Search)** - поиск в глубину  
- **Dijkstra** - кратчайший путь с весами
- **A*** - эвристический поиск пути

### Анализ структуры
- **Обнаружение циклов** - поиск циклических зависимостей
- **Компоненты связности** - анализ связанных групп
- **Топологическая сортировка** - упорядочивание по зависимостям
- **Минимальное остовное дерево** - оптимальные связи

### Метрики централизации
- **Betweenness Centrality** - важность как посредника
- **Closeness Centrality** - близость к другим узлам
- **Degree Centrality** - количество связей
- **PageRank** - алгоритм ранжирования

## 🚀 Быстрый старт

### Базовая настройка

```typescript
import { CSElement } from 'cs-element';

// Настройка графовых алгоритмов
CSElement.configureGraphAlgorithms({
  defaultTimeout: 5000,
  enableCaching: true,
  enableEvents: true,
  maxDepth: 100
});

// Создание структуры для анализа
const root = CSElement.create('network');
const server1 = root.createChild('server1');
const server2 = root.createChild('server2');
const database = root.createChild('database');

// Создание связей
server1.connectTo(database, { weight: 1, type: 'read' });
server2.connectTo(database, { weight: 2, type: 'write' });
server1.connectTo(server2, { weight: 0.5, type: 'sync' });
```

### Поиск пути

```typescript
// Поиск кратчайшего пути
const path = await CSElement.findShortestPath(server1, database, {
  algorithm: 'dijkstra',
  weightFunction: (from, to, edge) => edge.weight || 1,
  maxDepth: 10
});

if (path.found) {
  console.log('Путь найден:', path.path.map(node => node.name));
  console.log('Общий вес:', path.totalWeight);
  console.log('Количество шагов:', path.steps);
} else {
  console.log('Путь не найден');
}
```

### Обнаружение циклов

```typescript
// Поиск циклов в структуре
const cycleResult = await CSElement.detectCycles(root, {
  algorithm: 'dfs',
  includeVisualization: true,
  maxCycles: 10
});

if (cycleResult.hasCycles) {
  console.log(`Найдено циклов: ${cycleResult.cycles.length}`);
  
  cycleResult.cycles.forEach((cycle, index) => {
    console.log(`Цикл ${index + 1}:`, cycle.path.join(' -> '));
    console.log(`Длина цикла: ${cycle.length}`);
    console.log(`Тип цикла: ${cycle.type}`); // 'simple', 'complex'
  });
}
```

## 📚 Подробное руководство

### Алгоритмы поиска пути

#### BFS - Поиск в ширину

```typescript
// BFS для поиска кратчайшего пути (по количеству шагов)
const bfsPath = await CSElement.findShortestPath(start, target, {
  algorithm: 'bfs',
  maxDepth: 15,
  visitedTracker: true, // Отслеживание посещенных узлов
  pathReconstruction: true // Восстановление полного пути
});

console.log('BFS результат:', {
  path: bfsPath.path,
  steps: bfsPath.steps,
  visitedNodes: bfsPath.visitedCount,
  executionTime: bfsPath.executionTime
});
```

#### DFS - Поиск в глубину

```typescript
// DFS для обхода всех возможных путей
const dfsResult = await CSElement.traverseDepthFirst(root, {
  visitCallback: (node, depth, path) => {
    console.log(`Посещение: ${node.name} на глубине ${depth}`);
    return { continue: true, data: node.extractData() };
  },
  maxDepth: 20,
  avoidCycles: true,
  collectPaths: true
});

console.log('DFS обход завершен:', {
  totalNodes: dfsResult.visitedCount,
  maxDepthReached: dfsResult.maxDepth,
  paths: dfsResult.allPaths
});
```

#### Dijkstra - Кратчайший путь с весами

```typescript
// Dijkstra для взвешенных графов
const dijkstraPath = await CSElement.findShortestPath(source, destination, {
  algorithm: 'dijkstra',
  weightFunction: (from, to, edge) => {
    // Пользовательская функция веса
    const baseWeight = edge.weight || 1;
    const latencyPenalty = edge.latency ? edge.latency * 0.1 : 0;
    const reliabilityBonus = edge.reliability ? (1 - edge.reliability) : 0;
    
    return baseWeight + latencyPenalty + reliabilityBonus;
  },
  heuristic: null, // Не используется в Dijkstra
  maxNodes: 1000
});

console.log('Dijkstra путь:', {
  path: dijkstraPath.path,
  totalWeight: dijkstraPath.totalWeight,
  efficiency: dijkstraPath.efficiency
});
```

#### A* - Эвристический поиск

```typescript
// A* с пользовательской эвристикой
const astarPath = await CSElement.findShortestPath(start, goal, {
  algorithm: 'astar',
  weightFunction: (from, to, edge) => edge.distance || 1,
  heuristic: (node, goal) => {
    // Эвристическая функция (например, манхэттенское расстояние)
    const dx = Math.abs(node.x - goal.x);
    const dy = Math.abs(node.y - goal.y);
    return dx + dy;
  },
  maxNodes: 5000,
  optimistic: true // Оптимистичная эвристика
});

console.log('A* путь:', {
  path: astarPath.path,
  cost: astarPath.totalCost,
  heuristicEfficiency: astarPath.heuristicEfficiency
});
```

### Анализ структуры графа

#### Компоненты связности

```typescript
// Поиск связанных компонентов
const components = await CSElement.findConnectedComponents(root, {
  algorithm: 'union-find', // 'union-find', 'dfs', 'bfs'
  includeIsolated: true,
  minComponentSize: 2
});

console.log(`Найдено компонентов: ${components.componentCount}`);

components.components.forEach((component, index) => {
  console.log(`Компонент ${index + 1}:`);
  console.log(`- Узлов: ${component.nodes.length}`);
  console.log(`- Связей: ${component.edges.length}`);
  console.log(`- Плотность: ${component.density.toFixed(3)}`);
  console.log(`- Диаметр: ${component.diameter}`);
});

// Анализ самого большого компонента
const largestComponent = components.largestComponent;
console.log('Самый большой компонент:', {
  size: largestComponent.size,
  coverage: largestComponent.coverage, // % от общего графа
  centralNode: largestComponent.centralNode
});
```

#### Топологическая сортировка

```typescript
// Топологическая сортировка для DAG
const topoSort = await CSElement.topologicalSort(root, {
  algorithm: 'kahn', // 'kahn', 'dfs'
  detectCycles: true,
  includeMetadata: true
});

if (topoSort.isDAG) {
  console.log('Топологический порядок:');
  topoSort.order.forEach((node, index) => {
    console.log(`${index + 1}. ${node.name} (уровень: ${node.level})`);
  });
  
  console.log('Статистика:', {
    levels: topoSort.levelCount,
    parallelizable: topoSort.parallelGroups,
    criticalPath: topoSort.criticalPath
  });
} else {
  console.log('Граф содержит циклы:', topoSort.cycles);
}
```

#### Минимальное остовное дерево

```typescript
// Построение MST
const mst = await CSElement.minimumSpanningTree(root, {
  algorithm: 'kruskal', // 'kruskal', 'prim'
  weightFunction: (from, to, edge) => edge.cost || edge.weight || 1,
  includeVisualization: true
});

console.log('Минимальное остовное дерево:', {
  totalWeight: mst.totalWeight,
  edgeCount: mst.edges.length,
  savings: mst.savings, // Экономия по сравнению с полным графом
  efficiency: mst.efficiency
});

// Визуализация MST
if (mst.visualization) {
  console.log('ASCII представление MST:');
  console.log(mst.visualization.ascii);
}
```

### Метрики централизации

#### Centrality анализ

```typescript
// Вычисление различных метрик централизации
const centrality = await CSElement.calculateCentrality(root, {
  metrics: ['betweenness', 'closeness', 'degree', 'pagerank'],
  normalize: true,
  includeStatistics: true
});

// Betweenness Centrality - важность как посредника
const betweenness = centrality.betweenness;
console.log('Топ узлов по betweenness:');
Object.entries(betweenness)
  .sort(([,a], [,b]) => b - a)
  .slice(0, 5)
  .forEach(([nodeId, score]) => {
    console.log(`${nodeId}: ${score.toFixed(3)}`);
  });

// Closeness Centrality - близость к другим узлам
const closeness = centrality.closeness;
console.log('Топ узлов по closeness:');
Object.entries(closeness)
  .sort(([,a], [,b]) => b - a)
  .slice(0, 5)
  .forEach(([nodeId, score]) => {
    console.log(`${nodeId}: ${score.toFixed(3)}`);
  });

// PageRank
const pagerank = centrality.pagerank;
console.log('Топ узлов по PageRank:');
Object.entries(pagerank)
  .sort(([,a], [,b]) => b - a)
  .slice(0, 5)
  .forEach(([nodeId, score]) => {
    console.log(`${nodeId}: ${score.toFixed(3)}`);
  });
```

#### Продвинутый анализ централизации

```typescript
// Детальный анализ централизации
const advancedCentrality = await CSElement.calculateAdvancedCentrality(root, {
  algorithms: {
    eigenvector: { iterations: 100, tolerance: 1e-6 },
    katz: { alpha: 0.1, beta: 1.0 },
    bonacich: { alpha: 0.5, beta: 0.5 }
  },
  compareMetrics: true,
  clustering: true
});

console.log('Продвинутые метрики:', {
  eigenvector: advancedCentrality.eigenvector,
  katz: advancedCentrality.katz,
  bonacich: advancedCentrality.bonacich
});

// Корреляция между метриками
console.log('Корреляция метрик:', advancedCentrality.correlations);

// Кластеризация по централизации
console.log('Кластеры по централизации:', {
  clusters: advancedCentrality.clusters,
  silhouetteScore: advancedCentrality.clusteringQuality
});
```

## ⚙️ Конфигурация и оптимизация

### Глобальные настройки

```typescript
// Конфигурация графовых алгоритмов
CSElement.configureGraphAlgorithms({
  // Производительность
  defaultTimeout: 10000,
  maxNodes: 10000,
  maxDepth: 50,
  
  // Кэширование
  enableCaching: true,
  cacheSize: 1000,
  cacheTTL: 300000, // 5 минут
  
  // Параллелизм
  useWorkers: true,
  workerPoolSize: 4,
  
  // События и логирование
  enableEvents: true,
  logLevel: 'info', // 'debug', 'info', 'warn', 'error'
  
  // Оптимизации
  enableHeuristics: true,
  enablePruning: true,
  enableMemoization: true
});
```

### Кастомные алгоритмы

```typescript
// Регистрация пользовательского алгоритма
CSElement.registerGraphAlgorithm('custom-pathfinding', {
  name: 'Custom Pathfinding',
  type: 'pathfinding',
  
  execute: async (graph, start, end, options) => {
    // Пользовательская логика поиска пути
    const visited = new Set();
    const queue = [{ node: start, path: [start], cost: 0 }];
    
    while (queue.length > 0) {
      const current = queue.shift();
      
      if (current.node === end) {
        return {
          found: true,
          path: current.path,
          cost: current.cost,
          algorithm: 'custom-pathfinding'
        };
      }
      
      if (visited.has(current.node.id)) continue;
      visited.add(current.node.id);
      
      for (const neighbor of current.node.getNeighbors()) {
        if (!visited.has(neighbor.id)) {
          queue.push({
            node: neighbor,
            path: [...current.path, neighbor],
            cost: current.cost + this.calculateCost(current.node, neighbor)
          });
        }
      }
    }
    
    return { found: false, path: [], cost: Infinity };
  },
  
  calculateCost: (from, to) => {
    // Пользовательская функция стоимости
    return 1;
  }
});

// Использование пользовательского алгоритма
const customPath = await CSElement.findShortestPath(start, end, {
  algorithm: 'custom-pathfinding',
  customOptions: { /* параметры алгоритма */ }
});
```

## 🔍 Продвинутые возможности

### Динамический анализ

```typescript
// Анализ изменений в реальном времени
const dynamicAnalyzer = CSElement.createDynamicGraphAnalyzer(root, {
  trackChanges: true,
  updateInterval: 1000,
  metrics: ['centrality', 'connectivity', 'clustering']
});

// Подписка на изменения
dynamicAnalyzer.onMetricsUpdate((newMetrics, changes) => {
  console.log('Обновление метрик:', {
    timestamp: new Date(),
    changes: changes.summary,
    topChanges: changes.significant
  });
  
  // Реакция на значительные изменения
  if (changes.significant.length > 0) {
    console.log('Значительные изменения обнаружены!');
    changes.significant.forEach(change => {
      console.log(`- ${change.type}: ${change.description}`);
    });
  }
});

// Запуск мониторинга
dynamicAnalyzer.start();
```

### Сравнительный анализ

```typescript
// Сравнение двух графов
const comparison = await CSElement.compareGraphs(graph1, graph2, {
  metrics: ['structure', 'centrality', 'connectivity'],
  alignment: 'name', // 'name', 'id', 'custom'
  includeVisualization: true
});

console.log('Сравнение графов:', {
  structuralSimilarity: comparison.structuralSimilarity,
  centralitySimilarity: comparison.centralitySimilarity,
  differences: comparison.differences
});

// Различия в структуре
comparison.differences.structural.forEach(diff => {
  console.log(`Структурное различие: ${diff.type} - ${diff.description}`);
});

// Различия в централизации
comparison.differences.centrality.forEach(diff => {
  console.log(`Различие в централизации: ${diff.node} - ${diff.change}`);
});
```

### Анализ сообществ

```typescript
// Обнаружение сообществ в графе
const communities = await CSElement.detectCommunities(root, {
  algorithm: 'louvain', // 'louvain', 'leiden', 'infomap'
  resolution: 1.0,
  iterations: 100,
  includeHierarchy: true
});

console.log('Обнаруженные сообщества:', {
  count: communities.communityCount,
  modularity: communities.modularity,
  coverage: communities.coverage
});

communities.communities.forEach((community, index) => {
  console.log(`Сообщество ${index + 1}:`);
  console.log(`- Размер: ${community.size}`);
  console.log(`- Плотность: ${community.density.toFixed(3)}`);
  console.log(`- Центральные узлы: ${community.centralNodes.join(', ')}`);
});

// Иерархическая структура сообществ
if (communities.hierarchy) {
  console.log('Иерархия сообществ:');
  communities.hierarchy.levels.forEach((level, index) => {
    console.log(`Уровень ${index}: ${level.communityCount} сообществ`);
  });
}
```

## 📊 Производительность и мониторинг

### Профилирование алгоритмов

```typescript
// Включение профилирования
CSElement.enableGraphProfiling(true);

// Выполнение алгоритма с профилированием
const profilingResult = await CSElement.findShortestPathWithProfiling(start, end, {
  algorithm: 'dijkstra',
  profileMemory: true,
  profileTime: true,
  profileOperations: true
});

console.log('Профилирование:', {
  executionTime: profilingResult.timing.total,
  memoryUsage: profilingResult.memory.peak,
  operationCounts: profilingResult.operations,
  bottlenecks: profilingResult.bottlenecks
});

// Рекомендации по оптимизации
console.log('Рекомендации:', profilingResult.recommendations);
```

### Бенчмарки

```typescript
// Сравнение производительности алгоритмов
const benchmark = await CSElement.benchmarkGraphAlgorithms(root, {
  algorithms: ['bfs', 'dfs', 'dijkstra', 'astar'],
  iterations: 10,
  scenarios: [
    { start: 'node1', end: 'node10' },
    { start: 'node5', end: 'node20' },
    { start: 'node1', end: 'node50' }
  ]
});

console.log('Результаты бенчмарка:');
benchmark.results.forEach(result => {
  console.log(`${result.algorithm}:`);
  console.log(`- Среднее время: ${result.averageTime}ms`);
  console.log(`- Среднее потребление памяти: ${result.averageMemory}KB`);
  console.log(`- Успешность: ${result.successRate}%`);
});

console.log('Лучший алгоритм:', benchmark.winner);
```

## 🔧 Интеграция и расширения

### React интеграция

```typescript
import React, { useEffect, useState } from 'react';

function GraphAnalysisComponent({ element }) {
  const [analysis, setAnalysis] = useState(null);
  const [loading, setLoading] = useState(false);
  
  const analyzeGraph = async () => {
    setLoading(true);
    try {
      const result = await CSElement.analyzeGraph(element, {
        metrics: ['centrality', 'connectivity', 'communities'],
        includeVisualization: true
      });
      setAnalysis(result);
    } catch (error) {
      console.error('Ошибка анализа графа:', error);
    } finally {
      setLoading(false);
    }
  };
  
  useEffect(() => {
    if (element) {
      analyzeGraph();
    }
  }, [element]);
  
  if (loading) return <div>Анализ графа...</div>;
  if (!analysis) return <div>Нет данных для анализа</div>;
  
  return (
    <div className="graph-analysis">
      <h3>Анализ графа</h3>
      
      <div className="metrics">
        <h4>Метрики централизации</h4>
        {Object.entries(analysis.centrality).map(([metric, values]) => (
          <div key={metric}>
            <strong>{metric}:</strong>
            <ul>
              {Object.entries(values)
                .sort(([,a], [,b]) => b - a)
                .slice(0, 3)
                .map(([node, score]) => (
                  <li key={node}>{node}: {score.toFixed(3)}</li>
                ))}
            </ul>
          </div>
        ))}
      </div>
      
      <div className="communities">
        <h4>Сообщества</h4>
        <p>Найдено сообществ: {analysis.communities.count}</p>
        <p>Модулярность: {analysis.communities.modularity.toFixed(3)}</p>
      </div>
    </div>
  );
}
```

### API интеграция

```typescript
// Создание REST API для графового анализа
class GraphAnalysisAPI {
  async analyzeNetwork(req, res) {
    try {
      const { graphData, options } = req.body;
      
      // Построение графа из данных
      const graph = CSElement.fromJSON(graphData);
      
      // Выполнение анализа
      const analysis = await CSElement.analyzeGraph(graph, {
        ...options,
        timeout: 30000 // Ограничение по времени для API
      });
      
      res.json({
        success: true,
        analysis: {
          centrality: analysis.centrality,
          communities: analysis.communities,
          connectivity: analysis.connectivity,
          metadata: analysis.metadata
        }
      });
    } catch (error) {
      res.status(500).json({
        success: false,
        error: error.message
      });
    }
  }
  
  async findPath(req, res) {
    try {
      const { graphData, start, end, algorithm = 'dijkstra' } = req.body;
      
      const graph = CSElement.fromJSON(graphData);
      const startNode = graph.findNode(start);
      const endNode = graph.findNode(end);
      
      const path = await CSElement.findShortestPath(startNode, endNode, {
        algorithm,
        timeout: 10000
      });
      
      res.json({
        success: true,
        path: {
          found: path.found,
          route: path.path?.map(node => node.id),
          cost: path.totalWeight,
          steps: path.steps
        }
      });
    } catch (error) {
      res.status(500).json({
        success: false,
        error: error.message
      });
    }
  }
}
```

## 🚨 Устранение неполадок

### Общие проблемы

**Проблема:** Алгоритм работает слишком медленно
```typescript
// ❌ Неправильно - без ограничений
const result = await CSElement.findShortestPath(start, end, {
  algorithm: 'dijkstra'
  // Нет ограничений по времени или узлам
});

// ✅ Правильно - с оптимизациями
const result = await CSElement.findShortestPath(start, end, {
  algorithm: 'dijkstra',
  timeout: 5000,
  maxNodes: 1000,
  enablePruning: true,
  useHeuristics: true
});
```

**Проблема:** Превышение памяти на больших графах
```typescript
// ❌ Неправильно - загрузка всего графа в память
const analysis = await CSElement.analyzeGraph(hugeGraph, {
  metrics: ['all']
});

// ✅ Правильно - поэтапный анализ
const analysis = await CSElement.analyzeGraph(hugeGraph, {
  metrics: ['centrality'],
  batchSize: 100,
  streaming: true,
  memoryLimit: '512MB'
});
```

### Диагностика

```typescript
// Диагностика производительности графовых алгоритмов
const diagnostics = await CSElement.diagnoseGraphPerformance(graph, {
  testAlgorithms: ['bfs', 'dfs', 'dijkstra'],
  samplePaths: 10,
  includeRecommendations: true
});

console.log('Диагностика графа:', {
  complexity: diagnostics.complexity,
  density: diagnostics.density,
  recommendations: diagnostics.recommendations,
  optimalAlgorithms: diagnostics.optimalAlgorithms
});
```

Система графовых алгоритмов CSElement предоставляет полный набор инструментов для анализа и обработки сложных сетевых структур с высокой производительностью и гибкостью настройки.