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:

docs/06_cantera_combustion.md

Este documento es deliberadamente operativo.

2. Entorno validado¶

Python   3.12.13
Cantera  3.2.0
Mecanismo gri30.yaml
Especies 53
Reacciones 325

Activación:

conda activate fenicsx-cantera
cd ~/Documents/Prodisys/ProdisysApps/Calculador

Verificación rápida:

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:

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:

python -m pytest -q \
  tests/thermo/test_laminar_flame_speed.py \
  -m "not slow"

Estado verificado durante la preparación de este manual:

pruebas principales aprobadas
pruebas rápidas de velocidad de llama aprobadas
pruebas lentas excluidas

4. Estructura funcional¶

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:

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:

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¶

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:

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¶

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:

Cp
Cv
gamma
viscosidad
temperatura adiabática
composición empleada por Cantera
especies excluidas

9. Estequiometría¶

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:

phi = stoich.equivalence_ratio_from_excess_air(20.0)

10. Balance de combustión¶

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:

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:

scripts/run_fb1602_cantera.py

y ejecutar:

conda activate fenicsx-cantera
cd ~/Documents/Prodisys/ProdisysApps/Calculador

python scripts/run_fb1602_cantera.py

Salidas:

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:

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:

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:

density_kg_per_m3_cantera
viscosity_pa_s
gamma_cp_cv

Para CFD reaccionante:

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:

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:

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:

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:

.. 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¶

python scripts/run_fb1602_cantera.py

17.2 Velocidad laminar¶

python scripts/run_fb1602_flame_speed.py

17.3 Refinamiento numérico¶

python scripts/run_fb1602_flame_refinement.py

Criterio:

variación media-fina < 2 %
SL adoptada = 0.363259 m/s

17.4 Predimensionamiento de puertos¶

python scripts/run_fb1602_stage_port_design.py

Resultado esperado:

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:

Stage 1: 27.26 mm
Stage 2: 33.38 mm
Stage 3: 43.10 mm

17.5 Pruebas¶

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:

el sustituto conserva los balances elementales;
no hay especies excluidas;
las llamas convergen;
la diferencia media-fina es menor de 2 %;
las pruebas pasan;
la geometría es 14/20/34 puertos de 12 mm;
cada toro queda dividido en dos ramas simétricas.

Manual de usuario — módulo Cantera de Calculador¶

1. Propósito¶

2. Entorno validado¶

3. Verificación del módulo¶

4. Estructura funcional¶

5. Regla fundamental de trazabilidad¶

6. Preparar una composición¶

7. Propiedades de ingeniería¶

8. Interfaz API 537 y Cantera¶

9. Estequiometría¶

10. Balance de combustión¶

11. Ejecutar el caso FB-1602¶

12. Interpretación de FB-1602¶

13. Datos para CFD¶

14. Errores frecuentes¶

`ImportError`¶

Especies excluidas¶

Error de balance de masa¶

Composición que no suma 100 %¶

15. Incorporación a Sphinx¶

16. Alcance y limitaciones¶

17. Flujo completo del caso FB-1602¶

17.1 Cálculo termoquímico¶

17.2 Velocidad laminar¶

17.3 Refinamiento numérico¶

17.4 Predimensionamiento de puertos¶

17.5 Pruebas¶

17.6 Reglas de interpretación¶

17.7 Criterio de aceptación¶

index

Navegación

Related Topics

Manual de usuario — módulo Cantera de Calculador¶

1. Propósito¶

2. Entorno validado¶

3. Verificación del módulo¶

4. Estructura funcional¶

5. Regla fundamental de trazabilidad¶

6. Preparar una composición¶

7. Propiedades de ingeniería¶

8. Interfaz API 537 y Cantera¶

9. Estequiometría¶

10. Balance de combustión¶

11. Ejecutar el caso FB-1602¶

12. Interpretación de FB-1602¶

13. Datos para CFD¶

14. Errores frecuentes¶

ImportError¶

Especies excluidas¶

Error de balance de masa¶

Composición que no suma 100 %¶

15. Incorporación a Sphinx¶

16. Alcance y limitaciones¶

17. Flujo completo del caso FB-1602¶

17.1 Cálculo termoquímico¶

17.2 Velocidad laminar¶

17.3 Refinamiento numérico¶

17.4 Predimensionamiento de puertos¶

17.5 Pruebas¶

17.6 Reglas de interpretación¶

17.7 Criterio de aceptación¶

`ImportError`¶