SIDEL_ScriptsManager/app/backend/script_groups/hammer/README.md

Water Hammer Simulator - ScriptsManager Edition

Interactive Hydraulic Transient Analysis for Syrup Pumping Systems

🎯 Overview

Interactive web-based water hammer simulator for analyzing hydraulic transients in syrup pumping systems. Built for ScriptsManager framework with multi-language support, real-time parameter adjustment, and Chart.js visualizations.

🏭 System Features

• Fluid: Syrup (density 1100-1300 kg/m³, temperature-dependent properties)
• Pipeline: Stainless steel, configurable diameter and length
• Pump: Variable pressure and flow rate
• Valve: Controllable closure time (0.1 - 20s)
• Protection: Optional hydropneumatic damper analysis
• Analysis: Joukowsky equations with reduction factors

🌐 Multi-Language Support

• English - Complete interface and documentation
• Español - Interfaz y documentación completa
• Italiano - Interfaccia e documentazione completa
• Français - Interface et documentation complète

🚀 ScriptsManager Integration

This simulator follows ScriptsManager specifications:

python hammer_simulator.py --data-dir /path/to/data --user-level operator --port 5200 --project-id project_name

Features:

• Project-specific data persistence
• User-level access control
• Automatic port management
• Session-based configuration storage
• Multi-project support

✨ Funcionalidades Principales

🖥️ Interfaz Gráfica Interactiva

• Modificación de parámetros en tiempo real
• Visualización inmediata de resultados
• Gráficos profesionales con Matplotlib
• Análisis de seguridad automático

🔧 Parámetros Configurables

• Sistema hidráulico: longitud, diámetro, rugosidad
• Propiedades del fluido: densidad, temperatura, módulo bulk
• Operación: caudal, presión, tiempo de cierre
• Protección: damper con volumen y presión ajustable

📊 Análisis y Resultados

• Cálculo de sobrepresión máxima
• Velocidad de onda de presión
• Tiempo crítico de cierre
• Análisis de seguridad automático
• Recomendaciones de protección

💾 Exportación

• Gráficos en alta resolución (PNG)
• Reportes detallados
• Configuraciones guardables

🚀 Instalación

Requisitos del Sistema

• Python 3.12 o superior
• Sistema operativo: Windows, Linux o macOS
• Memoria RAM: 4GB mínimo (8GB recomendado)

Instalación Paso a Paso

1. Clonar el repositorio

git clone https://github.com/miguefin/colpo_ariete_interattivo.git
cd colpo_ariete_interattivo

2. Crear entorno virtual (recomendado)

# Con conda
conda create -n tsnet python=3.12
conda activate tsnet

# O con venv
python -m venv tsnet_env
# Windows
tsnet_env\Scripts\activate
# Linux/macOS
source tsnet_env/bin/activate

3. Instalar dependencias

pip install -r requirements.txt

🎮 Uso

Ejecutar el Simulador Principal

python simulador_hammer_interactivo.py

Interfaz Gráfica

1. Panel de Parámetros: Ajusta las características del sistema
2. Panel de Control: Ejecuta simulaciones y análisis
3. Panel de Resultados: Visualiza gráficos y resultados
4. Panel de Protección: Configura dampers y sistemas de protección

Flujo de Trabajo Típico

1. Configurar parámetros del sistema
2. Ejecutar simulación base
3. Analizar resultados de seguridad
4. Ajustar protecciones si es necesario
5. Exportar resultados y reportes

📁 Estructura del Proyecto

colpo_ariete_interattivo/
├── simulador_hammer_interactivo.py    # 🎯 Aplicación principal
├── conceptos_golpe_ariete.md          # 📚 Documentación técnica
├── requirements.txt                   # 📦 Dependencias
├── README.md                         # 📖 Este archivo
├── doc/                              # 📁 Documentación adicional
│   ├── configurador_hammer.py        # 🧮 Calculadora rápida
│   ├── simulador_hammer_simple.py    # 🔧 Versión simplificada
│   ├── simulador_jarabe_final.py     # 🏭 Versión específica jarabe
│   └── *.png                         # 📊 Ejemplos de resultados
└── test/                             # 🧪 Scripts de prueba
    ├── test_tsnet_*.py               # ✅ Tests unitarios
    └── debug_*.py                    # 🔍 Scripts de depuración

🔬 Fundamentos Técnicos

Ecuación de Joukowsky

ΔP = ρ × c × ΔV

• ΔP: Sobrepresión (Pa)
• ρ: Densidad del fluido (kg/m³)
• c: Velocidad de onda (m/s)
• ΔV: Cambio de velocidad (m/s)

Velocidad de Onda de Presión

c = √(K/ρ) / √(1 + (K/E) × (D/e))

• K: Módulo bulk del fluido (Pa)
• E: Módulo de Young del material (Pa)
• D: Diámetro interno (m)
• e: Espesor de pared (m)

⚠️ Criterios de Seguridad

• Presión máxima: No superar 1.5 × presión nominal
• Tiempo crítico: Tc = 2L/c (tiempo mínimo seguro)
• Factor de seguridad: Mínimo 2.0 para aplicaciones críticas

🛡️ Sistemas de Protección

Damper Hidropneumático

• Volumen ajustable (10-200 litros)
• Presión de precarga configurable
• Posición optimizable en la línea
• Análisis automático de efectividad

📈 Ejemplos de Resultados

El simulador genera automáticamente:

• Gráficos de presión vs tiempo
• Análisis de velocidad de flujo
• Mapas de riesgo por tiempo de cierre
• Recomendaciones de protección

🔧 Desarrollo y Contribución

Tecnologías Utilizadas

• Python 3.12: Lenguaje base
• Tkinter: Interfaz gráfica
• Matplotlib: Visualización avanzada
• NumPy: Cálculos numéricos
• TSNet: Simulación de transitorios

Estructura del Código

• Programación orientada a objetos
• Interfaz modular y extensible
• Documentación completa en código
• Tests unitarios incluidos

📞 Soporte y Contacto

• Repositorio: GitHub
• Issues: Reportar bugs y solicitar funcionalidades
• Documentación: Wiki del proyecto
• Autor: Generado con GitHub Copilot (Septiembre 2025)

📄 Licencia

Este proyecto está bajo la Licencia MIT. Ver archivo LICENSE para más detalles.

🙏 Agradecimientos

• Comunidad TSNet por las herramientas de simulación
• GitHub Copilot por asistencia en desarrollo
• Comunidad Python por las excelentes librerías

---

¡Contribuciones bienvenidas! 🚀

Si encuentras bugs, tienes ideas de mejora o quieres contribuir al proyecto, no dudes en abrir un issue o pull request.