visum_network_analysis

Analyze Visum network performance with detailed statistics and metrics to evaluate transportation system efficiency and identify improvement areas.

Instructions

Analyze the loaded Visum network with detailed statistics and performance metrics

Input Schema

TableJSON Schema

Name	Required	Description	Default
`includeGeometry`	No	Include geometric analysis of network elements
`sampleSize`	No	Number of sample elements to analyze (default: 50)

Implementation Reference

src/index-backup.ts:421-588 (handler)

Complete tool definition including registration, input schema, and handler logic. The handler constructs and executes a comprehensive Python script for Visum network analysis (nodes, links, zones, geometry, samples) using PersistentVisumController.executeCustomCode, then formats and returns detailed statistics and performance metrics.

server.tool(
  "visum_network_analysis",
  "Analyze the loaded Visum network with detailed statistics and performance metrics",
  {
    includeGeometry: z.boolean().optional().default(false).describe("Include geometric analysis of network elements"),
    sampleSize: z.number().optional().default(50).describe("Number of sample elements to analyze (default: 50)")
  },
  async ({ includeGeometry, sampleSize }) => {
    try {
      let analysisCode = `
# Comprehensive network analysis
import time
try:
    start_time = time.time()
    
    # Basic network statistics
    num_nodes = visum.Net.Nodes.Count
    num_links = visum.Net.Links.Count
    num_zones = visum.Net.Zones.Count
    num_stops = visum.Net.Stops.Count if hasattr(visum.Net, 'Stops') else 0
    num_lines = visum.Net.Lines.Count if hasattr(visum.Net, 'Lines') else 0
    
    # Sample node analysis
    sample_nodes = []
    if num_nodes > 0:
        node_iter = visum.Net.Nodes.Iterator
        count = 0
        while node_iter.Valid and count < ${sampleSize}:
            node = node_iter.Item
            sample_nodes.append({
                'id': node.AttValue('No'),
                'x': node.AttValue('XCoord') if hasattr(node, 'AttValue') else None,
                'y': node.AttValue('YCoord') if hasattr(node, 'AttValue') else None
            })
            node_iter.Next()
            count += 1
    
    # Sample link analysis  
    sample_links = []
    if num_links > 0:
        link_iter = visum.Net.Links.Iterator
        count = 0
        while link_iter.Valid and count < ${sampleSize}:
            link = link_iter.Item
            sample_links.append({
                'from_node': link.AttValue('FromNodeNo'),
                'to_node': link.AttValue('ToNodeNo'),
                'length': link.AttValue('Length') if hasattr(link, 'AttValue') else None
            })
            link_iter.Next()
            count += 1
    `;

      if (includeGeometry) {
        analysisCode += `
    # Geometric analysis
    total_length = 0.0
    if num_links > 0:
        link_iter = visum.Net.Links.Iterator
        while link_iter.Valid:
            try:
                length = link_iter.Item.AttValue('Length')
                if length:
                    total_length += length
            except:
                pass
            link_iter.Next()
    `;
      }

      analysisCode += `
    analysis_time = time.time() - start_time
    
    result = {
        'network_statistics': {
            'nodes': num_nodes,
            'links': num_links,
            'zones': num_zones,
            'stops': num_stops,
            'lines': num_lines
        },
        'sample_analysis': {
            'nodes': sample_nodes[:10],  # Limit output
            'links': sample_links[:10]   # Limit output
        },${includeGeometry ? `
        'geometric_analysis': {
            'total_network_length_km': round(total_length / 1000, 2) if 'total_length' in locals() else None
        },` : ''}
        'performance': {
            'analysis_time_seconds': round(analysis_time, 3)
        },
        'analysis_successful': True
    }
    
except Exception as e:
    result = {
        'analysis_successful': False,
        'error': str(e)
    }`;

      const result = await visumController.executeCustomCode(
        analysisCode,
        "Analisi completa della rete Visum"
      );

      if (result.success && result.result?.analysis_successful) {
        const analysis = result.result;
        const stats = analysis.network_statistics;
        
        let geometryInfo = '';
        if (includeGeometry && analysis.geometric_analysis) {
          geometryInfo = `**Analisi Geometrica:**\n` +
                        `• **Lunghezza Totale Rete:** ${analysis.geometric_analysis.total_network_length_km || 'N/A'} km\n\n`;
        }

        let sampleInfo = '';
        if (analysis.sample_analysis) {
          const sampleNodes = analysis.sample_analysis.nodes?.length || 0;
          const sampleLinks = analysis.sample_analysis.links?.length || 0;
          sampleInfo = `**Analisi Campionaria:**\n` +
                      `• **Nodi Analizzati:** ${sampleNodes}\n` +
                      `• **Link Analizzati:** ${sampleLinks}\n\n`;
        }

        return {
          content: [
            {
              type: "text", 
              text: `✅ **Analisi Rete Completata**\n\n` +
                    `**Statistiche Rete:**\n` +
                    `• **Nodi:** ${stats.nodes?.toLocaleString() || 'N/A'}\n` +
                    `• **Link:** ${stats.links?.toLocaleString() || 'N/A'}\n` +
                    `• **Zone:** ${stats.zones?.toLocaleString() || 'N/A'}\n` +
                    `• **Fermate:** ${stats.stops?.toLocaleString() || 'N/A'}\n` +
                    `• **Linee:** ${stats.lines?.toLocaleString() || 'N/A'}\n\n` +
                    sampleInfo +
                    geometryInfo +
                    `**Performance:**\n` +
                    `• **Tempo Analisi:** ${analysis.performance?.analysis_time_seconds || 'N/A'}s\n` +
                    `• **Tempo Esecuzione Tool:** ${result.executionTimeMs?.toFixed(3) || 'N/A'}ms\n\n` +
                    `*Analisi della rete completata con successo*`
            }
          ]
        };
      } else {
        return {
          content: [
            {
              type: "text",
              text: `❌ **Errore Analisi Rete**\n\n` +
                    `**Errore:** ${result.result?.error || result.error || 'Errore sconosciuto'}\n\n` +
                    `*Assicurarsi che un progetto Visum sia caricato correttamente*`
            }
          ]
        };
      }
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `❌ **Errore durante l'analisi:**\n\n${error instanceof Error ? error.message : String(error)}`
          }
        ]
      };
    }
  }
);

src/index-backup.ts:424-427 (schema)

Zod schema defining optional parameters for the visum_network_analysis tool: includeGeometry (boolean, default false) and sampleSize (number, default 50).

{
  includeGeometry: z.boolean().optional().default(false).describe("Include geometric analysis of network elements"),
  sampleSize: z.number().optional().default(50).describe("Number of sample elements to analyze (default: 50)")
},

src/index-backup.ts:421-588 (registration)

MCP server tool registration call for 'visum_network_analysis' using server.tool(name, description, schema, handler).

server.tool(
  "visum_network_analysis",
  "Analyze the loaded Visum network with detailed statistics and performance metrics",
  {
    includeGeometry: z.boolean().optional().default(false).describe("Include geometric analysis of network elements"),
    sampleSize: z.number().optional().default(50).describe("Number of sample elements to analyze (default: 50)")
  },
  async ({ includeGeometry, sampleSize }) => {
    try {
      let analysisCode = `
# Comprehensive network analysis
import time
try:
    start_time = time.time()
    
    # Basic network statistics
    num_nodes = visum.Net.Nodes.Count
    num_links = visum.Net.Links.Count
    num_zones = visum.Net.Zones.Count
    num_stops = visum.Net.Stops.Count if hasattr(visum.Net, 'Stops') else 0
    num_lines = visum.Net.Lines.Count if hasattr(visum.Net, 'Lines') else 0
    
    # Sample node analysis
    sample_nodes = []
    if num_nodes > 0:
        node_iter = visum.Net.Nodes.Iterator
        count = 0
        while node_iter.Valid and count < ${sampleSize}:
            node = node_iter.Item
            sample_nodes.append({
                'id': node.AttValue('No'),
                'x': node.AttValue('XCoord') if hasattr(node, 'AttValue') else None,
                'y': node.AttValue('YCoord') if hasattr(node, 'AttValue') else None
            })
            node_iter.Next()
            count += 1
    
    # Sample link analysis  
    sample_links = []
    if num_links > 0:
        link_iter = visum.Net.Links.Iterator
        count = 0
        while link_iter.Valid and count < ${sampleSize}:
            link = link_iter.Item
            sample_links.append({
                'from_node': link.AttValue('FromNodeNo'),
                'to_node': link.AttValue('ToNodeNo'),
                'length': link.AttValue('Length') if hasattr(link, 'AttValue') else None
            })
            link_iter.Next()
            count += 1
    `;

      if (includeGeometry) {
        analysisCode += `
    # Geometric analysis
    total_length = 0.0
    if num_links > 0:
        link_iter = visum.Net.Links.Iterator
        while link_iter.Valid:
            try:
                length = link_iter.Item.AttValue('Length')
                if length:
                    total_length += length
            except:
                pass
            link_iter.Next()
    `;
      }

      analysisCode += `
    analysis_time = time.time() - start_time
    
    result = {
        'network_statistics': {
            'nodes': num_nodes,
            'links': num_links,
            'zones': num_zones,
            'stops': num_stops,
            'lines': num_lines
        },
        'sample_analysis': {
            'nodes': sample_nodes[:10],  # Limit output
            'links': sample_links[:10]   # Limit output
        },${includeGeometry ? `
        'geometric_analysis': {
            'total_network_length_km': round(total_length / 1000, 2) if 'total_length' in locals() else None
        },` : ''}
        'performance': {
            'analysis_time_seconds': round(analysis_time, 3)
        },
        'analysis_successful': True
    }
    
except Exception as e:
    result = {
        'analysis_successful': False,
        'error': str(e)
    }`;

      const result = await visumController.executeCustomCode(
        analysisCode,
        "Analisi completa della rete Visum"
      );

      if (result.success && result.result?.analysis_successful) {
        const analysis = result.result;
        const stats = analysis.network_statistics;
        
        let geometryInfo = '';
        if (includeGeometry && analysis.geometric_analysis) {
          geometryInfo = `**Analisi Geometrica:**\n` +
                        `• **Lunghezza Totale Rete:** ${analysis.geometric_analysis.total_network_length_km || 'N/A'} km\n\n`;
        }

        let sampleInfo = '';
        if (analysis.sample_analysis) {
          const sampleNodes = analysis.sample_analysis.nodes?.length || 0;
          const sampleLinks = analysis.sample_analysis.links?.length || 0;
          sampleInfo = `**Analisi Campionaria:**\n` +
                      `• **Nodi Analizzati:** ${sampleNodes}\n` +
                      `• **Link Analizzati:** ${sampleLinks}\n\n`;
        }

        return {
          content: [
            {
              type: "text", 
              text: `✅ **Analisi Rete Completata**\n\n` +
                    `**Statistiche Rete:**\n` +
                    `• **Nodi:** ${stats.nodes?.toLocaleString() || 'N/A'}\n` +
                    `• **Link:** ${stats.links?.toLocaleString() || 'N/A'}\n` +
                    `• **Zone:** ${stats.zones?.toLocaleString() || 'N/A'}\n` +
                    `• **Fermate:** ${stats.stops?.toLocaleString() || 'N/A'}\n` +
                    `• **Linee:** ${stats.lines?.toLocaleString() || 'N/A'}\n\n` +
                    sampleInfo +
                    geometryInfo +
                    `**Performance:**\n` +
                    `• **Tempo Analisi:** ${analysis.performance?.analysis_time_seconds || 'N/A'}s\n` +
                    `• **Tempo Esecuzione Tool:** ${result.executionTimeMs?.toFixed(3) || 'N/A'}ms\n\n` +
                    `*Analisi della rete completata con successo*`
            }
          ]
        };
      } else {
        return {
          content: [
            {
              type: "text",
              text: `❌ **Errore Analisi Rete**\n\n` +
                    `**Errore:** ${result.result?.error || result.error || 'Errore sconosciuto'}\n\n` +
                    `*Assicurarsi che un progetto Visum sia caricato correttamente*`
            }
          ]
        };
      }
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `❌ **Errore durante l'analisi:**\n\n${error instanceof Error ? error.message : String(error)}`
          }
        ]
      };
    }
  }
);

Visum Thinker MCP Server