# Water Hammer Simulator - ScriptsManager Edition
## Interactive Hydraulic Transient Analysis for Syrup Pumping Systems

![Python](https://img.shields.io/badge/python-v3.8+-blue.svg)
![Flask](https://img.shields.io/badge/Flask-2.0+-green.svg)
![License](https://img.shields.io/badge/license-MIT-green.svg)
![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)

### 🎯 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:

```bash
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**
```bash
git clone https://github.com/miguefin/colpo_ariete_interattivo.git
cd colpo_ariete_interattivo
```

2. **Crear entorno virtual** (recomendado)
```bash
# 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**
```bash
pip install -r requirements.txt
```

### 🎮 Uso

#### Ejecutar el Simulador Principal
```bash
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](https://github.com/miguefin/colpo_ariete_interattivo)
- **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.