# Manual de usuario — módulo Cantera de Calculador ## 1. Propósito Este manual explica cómo ejecutar un caso de gas combustible con el módulo termoquímico de `Calculador`, verificar la instalación, interpretar resultados y preparar bases para CFD. La referencia técnica de arquitectura continúa siendo: ```text docs/06_cantera_combustion.md ``` Este documento es deliberadamente operativo. ## 2. Entorno validado ```text Python 3.12.13 Cantera 3.2.0 Mecanismo gri30.yaml Especies 53 Reacciones 325 ``` Activación: ```bash conda activate fenicsx-cantera cd ~/Documents/Prodisys/ProdisysApps/Calculador ``` Verificación rápida: ```bash python - <<'PY' import cantera as ct gas = ct.Solution("gri30.yaml") print("Cantera:", ct.__version__) print("Mecanismo:", gas.source) print("Especies:", gas.n_species) print("Reacciones:", gas.n_reactions) PY ``` ## 3. Verificación del módulo Suite rápida: ```bash python -m pytest -q \ tests/thermo/test_cantera_service.py \ tests/thermo/test_stoichiometry.py \ tests/thermo/test_combustion_flow_balance.py \ tests/thermo/test_burner_port_hydraulics.py \ tests/thermo/test_burner_port_sensitivity.py \ tests/thermo/test_burner_staging.py ``` Velocidad laminar sin pruebas lentas: ```bash python -m pytest -q \ tests/thermo/test_laminar_flame_speed.py \ -m "not slow" ``` Estado verificado durante la preparación de este manual: ```text 23 pruebas principales aprobadas 3 pruebas rápidas de velocidad de llama aprobadas 2 pruebas lentas excluidas ``` ## 4. Estructura funcional ```text Cromatografía ↓ GasComposition ↓ engineering_summary + API537GasProperties ↓ Stoichiometry ↓ CombustionFlowBalance ↓ Hidráulica y staging ↓ Condiciones de entrada para CFD ``` ## 5. Regla fundamental de trazabilidad Las propiedades no se calculan todas con la misma composición efectiva: - **Propiedades de ingeniería:** usan la cromatografía completa. - **Cantera:** usa solamente especies presentes en el mecanismo. - **Estequiometría:** usa la composición completa soportada por las tablas elementales del módulo. - **Velocidad de llama:** usa la composición compatible con el mecanismo. Siempre deben reportarse: ```text cantera_used_mol_percent cantera_excluded_mol_percent cantera_excluded_species ``` Una temperatura adiabática o una velocidad de llama sin esta trazabilidad no debe presentarse como propiedad de la cromatografía completa. ## 6. Preparar una composición Ejemplo: ```python from src.logic.thermo.cantera.gas_composition import GasComposition composition = GasComposition.from_mol_percent({ "CH4": 80.0, "C2H6": 10.0, "CO2": 8.0, "N2": 2.0, }) composition.validate_total() print(composition.as_mol_percent()) ``` Los valores de entrada no necesitan estar normalizados; la clase normaliza y consolida nombres equivalentes. ## 7. Propiedades de ingeniería ```python from src.logic.thermo.cantera.engineering_properties import engineering_summary results = engineering_summary({ "CH4": 80.0, "C2H6": 10.0, "CO2": 8.0, "N2": 2.0, }) for key, value in results.items(): print(key, value) ``` Resultados principales: ```text molecular_weight_g_per_mol density_kg_per_n_m3 relative_density_air lhv_kj_per_n_m3 hhv_kj_per_n_m3 wobbe_lhv_kj_per_n_m3 ``` ## 8. Interfaz API 537 y Cantera ```python from src.logic.thermo.cantera.api537_properties import ( API537GasInput, API537GasProperties, ) gas_input = API537GasInput( composition_mol_percent={ "CH4": 80.0, "C2H6": 10.0, "CO2": 8.0, "N2": 2.0, }, temperature_k=298.15, pressure_pa=101325.0, mechanism="gri30.yaml", ) results = API537GasProperties(gas_input).calculate() ``` La interfaz combina propiedades de ingeniería con: ```text Cp Cv gamma viscosidad temperatura adiabática composición empleada por Cantera especies excluidas ``` ## 9. Estequiometría ```python from src.logic.thermo.cantera.gas_composition import GasComposition from src.logic.thermo.cantera.stoichiometry import Stoichiometry composition = GasComposition.from_mol_percent({ "CH4": 80.0, "C2H6": 10.0, "CO2": 8.0, "N2": 2.0, }) stoich = Stoichiometry(composition) print(stoich.summary(excess_air_percent=20.0)) ``` La relación de equivalencia asociada al exceso de aire es: ```python phi = stoich.equivalence_ratio_from_excess_air(20.0) ``` ## 10. Balance de combustión ```python from src.logic.thermo.cantera.combustion_flow_balance import ( CombustionFlowBalance, FuelFlowInput, ) balance = CombustionFlowBalance( composition=composition, fuel_flow=FuelFlowInput(mass_flow_kg_h=200.0), excess_air_percent=20.0, ) print(balance.actual_air_mass_flow_kg_h()) print(balance.lhv_heat_release_kw()) print(balance.mass_balance_relative_error()) ``` Revisar siempre: ```text actual_air_mass_flow_kg_h actual_air_normal_volume_flow_nm3_h wet_product_flows dry_product_flows lhv_heat_release_kw mass_balance_relative_error ``` ## 11. Ejecutar el caso FB-1602 Instalar el archivo: ```text scripts/run_fb1602_cantera.py ``` y ejecutar: ```bash conda activate fenicsx-cantera cd ~/Documents/Prodisys/ProdisysApps/Calculador python scripts/run_fb1602_cantera.py ``` Salidas: ```text outputs/fb1602/fb1602_cantera_results.json outputs/fb1602/fb1602_cantera_summary.csv outputs/fb1602/fb1602_cantera_report.rst ``` ## 12. Interpretación de FB-1602 El script evalúa: ```text Caudal de gas 200 kg/h Exceso de aire 20 % Temperaturas 25 y 40 °C Elevación 172 m Presión manométrica entrada 430.92 Pa Mecanismo gri30.yaml ``` El archivo JSON es la fuente completa para automatización. El CSV permite revisión tabular rápida. El RST se puede incorporar al informe Sphinx. ## 13. Datos para CFD Las variables mínimas exportadas son: ```text fuel_inlet_mass_flow_kg_s air_inlet_mass_flow_kg_s total_inlet_mass_flow_kg_s reference_pressure_absolute_pa fuel_temperature_range_k equivalence_ratio ``` Para CFD frío deben emplearse además: ```text density_kg_per_m3_cantera viscosity_pa_s gamma_cp_cv ``` Para CFD reaccionante: ```text composition_cantera_mole_fraction equivalence_ratio adiabatic_flame_temperature wet_products ``` La composición compatible con Cantera no sustituye la composición completa en los cálculos de potencia y balance global. ## 14. Errores frecuentes ### `ImportError` No suponga nombres de clases. La implementación actual usa funciones en `engineering_properties.py`, principalmente: ```text engineering_summary molecular_weight_g_per_mol lhv_kj_per_n_m3 hhv_kj_per_n_m3 ``` ### Especies excluidas No es necesariamente un error. `gri30.yaml` no contiene todos los hidrocarburos pesados. Revise: ```text cantera_excluded_species cantera_excluded_mol_percent ``` Una fracción excluida importante exige un mecanismo ampliado o una representación sustituta documentada. ### Error de balance de masa El valor: ```text mass_balance_relative_error ``` debe ser próximo a cero. Una discrepancia significativa exige revisar datos moleculares, especies y normalización. ### Composición que no suma 100 % `GasComposition` normaliza automáticamente, pero en casos de ingeniería debe conservarse y reportarse el total original para detectar errores de digitación. ## 15. Incorporación a Sphinx Agregar el informe generado al `toctree` correspondiente: ```rst .. toctree:: :maxdepth: 2 ../outputs/fb1602/fb1602_cantera_report ``` También puede copiarse a la carpeta documental del proyecto antes de compilar. ## 16. Alcance y limitaciones El módulo actual sirve para: - propiedades de ingeniería; - propiedades termoquímicas y de transporte; - estequiometría; - balances de aire y productos; - potencia térmica; - predimensionamiento hidráulico; - staging preliminar. No sustituye todavía: - simulación CFD reaccionante; - radiación; - formación de CO y NOx; - hollín; - blowoff y flashback tridimensionales; - validación experimental; - integridad térmica del quemador. ## 17. Flujo completo del caso FB-1602 ### 17.1 Cálculo termoquímico ```bash python scripts/run_fb1602_cantera.py ``` ### 17.2 Velocidad laminar ```bash python scripts/run_fb1602_flame_speed.py ``` ### 17.3 Refinamiento numérico ```bash python scripts/run_fb1602_flame_refinement.py ``` Criterio: ```text variación media-fina < 2 % SL adoptada = 0.363259 m/s ``` ### 17.4 Predimensionamiento de puertos ```bash python scripts/run_fb1602_stage_port_design.py ``` Resultado esperado: ```text Stage 1: 14 x 12 mm, 2 ramas x 7 puertos Stage 2: 20 x 12 mm, 2 ramas x 10 puertos Stage 3: 34 x 12 mm, 2 ramas x 17 puertos ``` Diámetros internos hidráulicos mínimos: ```text Stage 1: 27.26 mm Stage 2: 33.38 mm Stage 3: 43.10 mm ``` ### 17.5 Pruebas ```bash python -m pytest -q tests/thermo/test_fb1602_cantera_script.py tests/thermo/test_fb1602_flame_speed_script.py tests/thermo/test_fb1602_flame_refinement.py tests/thermo/test_fb1602_stage_port_design.py ``` ### 17.6 Reglas de interpretación - usar composición real para hidráulica, densidad, balance y potencia; - usar sustituto GRI30 para química y velocidad de llama; - no usar `SL` como criterio único de estabilidad; - separar pérdida de puertos de pérdidas en líneas y accesorios; - separar diámetro hidráulico mínimo de tamaño comercial. ### 17.7 Criterio de aceptación La corrida es consistente cuando: 1. el sustituto conserva los balances elementales; 2. no hay especies excluidas; 3. las llamas convergen; 4. la diferencia media-fina es menor de 2 %; 5. las pruebas pasan; 6. la geometría es 14/20/34 puertos de 12 mm; 7. cada toro queda dividido en dos ramas simétricas.