zRFsim - RF Simulation Tool

A modern RF (Radio Frequency) simulation and analysis tool built in Zig, featuring a cross-platform user interface built with DVUI and SDL3, and an advanced Entity Component System (ECS) architecture for flexible RF component management.

Features

Core Functionality

• RF Chain Simulation: Cascaded analysis of RF component chains with industry-standard calculations

  • Gain, noise figure, and intermodulation distortion analysis
  • Support for amplifiers, mixers, filters, attenuators, and other RF components
  • Real-time parameter updates with automatic chain recalculation
  • Comprehensive handling of extreme values and edge cases

• Interactive Component Placement: Drag-and-drop RF component placement with intelligent collision detection

  • Grid-based alignment system for precise component positioning
  • Visual feedback during placement and connection operations
  • Multi-selection support for bulk operations

• Connection Management: Visual connection system for building RF signal chains

  • Automatic connection validation and signal flow analysis
  • Support for multiple input/output ports per component
  • Real-time connection state visualization

• Project Management: Complete save/load functionality with .zrfs file format

  • JSON-based project files with comprehensive metadata
  • Version tracking and compatibility checking
  • Automatic backup and recovery capabilities

• Professional UI: Modern, responsive interface designed for RF engineering workflows

  • Component properties panel with real-time parameter editing
  • Results visualization with detailed performance metrics
  • Comprehensive keyboard shortcuts and context menus

Technical Features

• Entity Component System (ECS): Modular architecture for flexible component management
• Real-time Calculations: Microsecond-level RF parameter updates
• Cross-platform Support: Windows, macOS, and Linux compatibility via SDL3
• Memory Efficient: Optimized data structures with minimal overhead
• Type Safety: Compile-time validation and error prevention

Planned Features

• Configuration Persistence: User preferences and settings management (planned feature)

Quick Start

Prerequisites

• Zig 0.14.1: Download from ziglang.org
• Git: For cloning the repository

Installation

1. Clone the repository:

git clone https://github.com/arancormonk/zrfsim.git zrfsim
cd zrfsim

1. Build and run:

zig build run

Dependencies

• DVUI: Immediate-mode GUI framework with SDL3 backend providing cross-platform interface capabilities and hardware-accelerated rendering

Architecture

zRFsim uses a modern Entity Component System (ECS) architecture that separates data (Components) from behavior (Systems), enabling:

1. Modular Design: Clean separation between RF simulation logic and user interface
2. Performance: Cache-friendly data access patterns with O(1) component lookups
3. Extensibility: Easy addition of new RF component types and analysis features
4. Type Safety: Compile-time validation of component relationships and data flow
5. ECS Update Loop: Efficient component data processing with dirty flag optimization

Performance Considerations

• Real-time Updates: ECS systems provide microsecond-level calculation updates
• Memory Efficiency: Component-based architecture with minimal memory overhead
• Spatial Optimization: Collision detection with spatial partitioning for large layouts
• Numerical Stability: Robust handling of extreme values and edge cases
• Cross-platform: Consistent behavior across operating systems via SDL3

Documentation

Comprehensive documentation is available in the docs/ directory:

Technical Guides

• Build System Documentation: Complete guide to the Zig build system, including:
  • Build commands and configuration options
  • Dependency management and cross-platform compilation
  • CI/CD integration with GitHub Actions
  • Advanced usage, troubleshooting, and development workflows

Architecture Documentation

• ECS Architecture: Entity Component System framework design and implementation
• RF Chain Integration: RF simulation algorithms and ECS integration
• RF Simulation Engine Architecture: Core RF calculation engine design and implementation
• UI Rendering Architecture: DVUI/SDL3 rendering system and interface design
• User Interaction Architecture: Input handling and user interaction systems
• Event System Design: Application-wide event coordination and messaging
• Configuration Architecture: Centralized configuration system design
• Spatial Systems Architecture: Collision detection and component placement systems
• Component Registry Type System: Component management and type system design
• Data Flow: Application data flow patterns and state management
• App State Architecture: Central application state coordination
• System Integration: Inter-system communication and coordination
• Memory Performance Architecture: Memory management and performance optimization strategies

Project Management

• Version Tracking: Guidelines for version management and release processes

Development

Building and Testing

# Standard development build
zig build

# Run with development flags
zig build run

# Execute unit tests
zig build test

# Release build for distribution
zig build -Doptimize=ReleaseSmall

For detailed information about the build system, cross-compilation, dependency management, and CI/CD workflows, see the Build System Documentation.

Code Organization

The codebase follows modern Zig conventions and architectural patterns:

• Naming: camelCase for functions, snake_case for variables, PascalCase for types
• ECS Architecture: Clean separation of data (Components) and behavior (Systems)
• Memory Management: Explicit allocator patterns with proper cleanup
• Error Handling: Comprehensive error types with informative messages
• Configuration: Centralized settings management with validation
• Testing: Integrated unit tests for all calculation modules
• Documentation: Extensive inline documentation with usage examples

Contributing

Contributions are welcome! Please see our contribution guidelines:

• Code Style: Follow existing Zig conventions and architectural patterns
• Testing: Include unit tests for new functionality
• Documentation: Update relevant documentation for changes
• Performance: Maintain real-time performance characteristics

Communication

• Issues: Report bugs and feature requests through GitHub Issues
• Discussions: Technical discussions and usage questions via GitHub Discussions

Roadmap

Version 0.1.0 (Current)

✅ Core RF Simulation: Cascaded analysis with industry-standard calculations
✅ ECS Architecture: Complete Entity Component System implementation
✅ Interactive UI: Component placement, connection management, and property editing
✅ Project Files: Save/load functionality with .zrfs format
✅ Cross-platform: Windows, macOS, and Linux support via SDL3

Version 0.2.0 (Planned)

Configuration persistence (.ini/.cfg config file)
Enhanced component library with additional RF component types
Improved visualization features and performance metrics display
Advanced keyboard shortcuts and workflow optimizations
Enhanced error handling and user feedback systems

Version 0.3.0 (Future)

Advanced plotting and graphing features with data import ability (CSV files)
Component parameter sweeping and optimization tools
Enhanced RF analysis capabilities and measurement tools
Interactive Smith chart for impedance matching with 2-port S-parameter import/export capability (.s2p files)
Advanced simulation features and analysis tools

License

This project is licensed under the GNU General Public License v3.0 - see the COPYING file for details.