EPANETConsoleCore C Migration Plan

Overview

This document outlines a plan to migrate the EPANETConsoleCore application from C# to C while maintaining all existing functionality. The goal is to achieve better performance while keeping the robust features of the current implementation.

Current Architecture

The current C# implementation includes:

• EPANET simulation engine integration
• PostgreSQL database connectivity
• SCADA system integration
• Configuration management
• Logging system
• Result collection and storage
• Quality analysis (single and multi-species)

Proposed C Architecture

Core Components

1. Main Application (epanetconsolecore.c)

   • Entry point and main control flow
   • Configuration parsing
   • Simulation orchestration
   • Error handling

2. Database Layer (db_interface.c/h)

   • PostgreSQL connectivity using libpq
   • Query execution and result handling
   • Connection pooling
   • Transaction management

3. SCADA Integration (scada_interface.c/h)

   • SCADA system communication
   • Tag value retrieval
   • Data synchronization

4. Configuration Management (config_parser.c/h)

   • JSON parsing using cJSON
   • Configuration validation
   • Runtime configuration updates

5. Logging System (logger.c/h)

   • Log file management
   • Console output
   • Windows Event Log integration

6. Result Collection (results_collector.c/h)

   • EPANET result processing
   • Data transformation
   • Batch processing

Required Libraries

1. Database

   • libpq: PostgreSQL C client library
   • libpqxx: C++ wrapper for libpq (optional, for easier C++ integration)

2. Configuration

   • cJSON: Lightweight JSON parser for C
   • libconfig: Alternative configuration library

3. Logging

   • Custom implementation using standard C I/O
   • Windows Event Log API for Windows integration

4. Networking

   • libcurl: For HTTP/HTTPS communication
   • openssl: For secure connections

5. Utilities

   • pthreads: For multi-threading support
   • libuuid: For UUID generation
   • libiconv: For character encoding

Migration Steps

Phase 1: Core EPANET Integration

1. Port basic EPANET simulation functionality
2. Implement configuration parsing
3. Set up basic logging
4. Create test harness

Phase 2: Database Integration

1. Implement PostgreSQL connectivity
2. Port database schema and queries
3. Add connection pooling
4. Implement transaction management

Phase 3: SCADA Integration

1. Port SCADA communication layer
2. Implement tag management
3. Add data synchronization
4. Create error handling

Phase 4: Result Collection

1. Port result processing logic
2. Implement batch processing
3. Add data transformation
4. Create validation system

Phase 5: Quality Analysis

1. Port quality analysis logic
2. Implement MSX integration
3. Add result storage
4. Create validation system

Performance Optimizations

1. Memory Management

   • Use memory pools for frequent allocations
   • Implement custom allocators for specific data types
   • Minimize memory copies

2. Database Operations

   • Use prepared statements
   • Implement connection pooling
   • Batch database operations
   • Use asynchronous operations where possible

3. SCADA Integration

   • Implement efficient tag caching
   • Use asynchronous updates
   • Optimize data structures

4. Result Processing

   • Use efficient data structures
   • Implement parallel processing
   • Optimize memory usage

Code Structure

// Example structure for main application
typedef struct {
    Config* config;
    Database* db;
    ScadaSystem* scada;
    Logger* logger;
    ResultsCollector* collector;
} ApplicationContext;

// Example database interface
typedef struct {
    PGconn* connection;
    ConnectionPool* pool;
    // ... other members
} Database;

// Example configuration structure
typedef struct {
    char* input_file;
    char* report_file;
    bool do_quality;
    bool do_msx;
    // ... other settings
} Config;

Build System

1. CMake Configuration

   • Platform-independent build system
   • Dependency management
   • Test integration
   • Installation targets

2. Dependencies

   • Package management using vcpkg or Conan
   • Local dependency builds
   • Version control

Testing Strategy

1. Unit Tests

   • CUnit or Unity framework
   • Component-level testing
   • Mock implementations

2. Integration Tests

   • End-to-end testing
   • Database integration
   • SCADA simulation

3. Performance Tests

   • Benchmark comparisons
   • Memory usage monitoring
   • CPU profiling

Migration Challenges

1. Memory Management

   • Manual memory management in C
   • Resource cleanup
   • Error handling

2. Error Handling

   • Consistent error reporting
   • Resource cleanup
   • Error propagation

3. Thread Safety

   • Multi-threading considerations
   • Resource sharing
   • Synchronization

4. Platform Compatibility

   • Windows/Linux support
   • Compiler differences
   • Library availability

Performance Targets

1. Simulation Speed

   • Target: 2x faster than C# implementation
   • Measurement: Time per simulation step
   • Benchmark: Large network simulations

2. Memory Usage

   • Target: 50% of C# implementation
   • Measurement: Peak memory usage
   • Tools: Valgrind, Windows Performance Monitor

3. Database Operations

   • Target: 3x faster than C# implementation
   • Measurement: Query execution time
   • Benchmark: Bulk operations

Implementation Timeline

1. Phase 1 (2 weeks)

   • Core EPANET integration
   • Basic testing

2. Phase 2 (3 weeks)

   • Database integration
   • Performance optimization

3. Phase 3 (2 weeks)

   • SCADA integration
   • Testing and validation

4. Phase 4 (2 weeks)

   • Result collection
   • Performance optimization

5. Phase 5 (2 weeks)

   • Quality analysis
   • Final testing

Total estimated time: 11 weeks

Maintenance Plan

1. Documentation

   • Code documentation using Doxygen
   • API documentation
   • Usage examples

2. Version Control

   • Git workflow
   • Branch management
   • Release process

3. Monitoring

   • Performance metrics
   • Error tracking
   • Usage statistics

Conclusion

This migration plan outlines a comprehensive approach to moving from C# to C while maintaining and potentially improving the performance of the EPANETConsoleCore application. The plan focuses on maintaining all existing functionality while leveraging C's performance advantages and modern C libraries for required functionality.

The migration should be done in phases to ensure stability and allow for testing at each stage. Performance optimization should be a continuous focus throughout the migration process.