Metadata-Version: 2.4
Name: pifira
Version: 0.2.0
Summary: Pressure-based inverse fire analysis with evidence-gated LH2 ortho-para and nozzle utilities
Author: Ugwiyeon Lee
Maintainer: Ugwiyeon Lee
License-Expression: MIT
Project-URL: Homepage, https://github.com/lyullee/pifira
Project-URL: Repository, https://github.com/lyullee/pifira
Project-URL: Issues, https://github.com/lyullee/pifira/issues
Project-URL: Changelog, https://github.com/lyullee/pifira/blob/main/CHANGELOG.md
Project-URL: Validation sources, https://github.com/lyullee/pifira/blob/main/VALIDATION_SOURCES.md
Project-URL: DOI, https://doi.org/10.5281/zenodo.22162092
Keywords: LPG,liquid hydrogen,fire safety,heat flux,pressure relief valve,ortho-para hydrogen,closed-vessel,pressure-rise method,BLEVE,process safety,thermal engineering,inverse method
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Requires-Dist: scipy>=1.9
Requires-Dist: pandas>=1.5
Requires-Dist: CoolProp>=6.6
Provides-Extra: plot
Requires-Dist: matplotlib>=3.7; extra == "plot"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: matplotlib>=3.7; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: twine>=6.0; extra == "dev"
Dynamic: license-file

# pifira

[![PyPI](https://img.shields.io/pypi/v/pifira)](https://pypi.org/project/pifira/)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22162092.svg)](https://doi.org/10.5281/zenodo.22162092)
[![tests](https://github.com/lyullee/pifira/actions/workflows/tests.yml/badge.svg)](https://github.com/lyullee/pifira/actions/workflows/tests.yml)

**P**ressure-based **I**nverse **F**ire-heat-flux and **R**adiative-**A**rea
analysis, with evidence-gated liquid-hydrogen utilities.

`pifira` is a research toolkit for two related process-safety workflows:

1. estimating heat input and effective flame-contact area from pressure and
   wall-temperature histories of pressurized LPG tanks; and
2. evaluating traceable liquid-hydrogen (LH2) ortho-para thermodynamics,
   published Milenko/Petitpas kinetics, and a CoolProp HEOS nozzle closure.

> **No experimental or validation data are distributed in the repository,
> source archive, or wheel.** The validation material belongs to its original
> publishers and depositors. [`VALIDATION_SOURCES.md`](https://github.com/lyullee/pifira/blob/main/VALIDATION_SOURCES.md)
> identifies the original DOI or official download page, the evidence used,
> and the limits of each comparison.

## Installation

```bash
python -m pip install pifira
```

Python 3.10 or newer is required. Plotting support is optional:

```bash
python -m pip install "pifira[plot]"
```

## LPG inverse-analysis example

```python
import pifira

tank = pifira.TankSpec(
    volume=0.619,
    fluid="HEOS::Propane[0.95]&n-Butane[0.05]",
    fill=0.70,
)

heat_W = pifira.heat_input(
    P1_bar=10.83,
    P2_bar=16.30,
    dt=544.5,
    tank=tank,
)

arc = pifira.effective_arc(
    angles_deg=[0, 90, 180, -90],
    T_wall_C=[271, 49, 39, 46],
    T_amb_C=35.0,
)["arc_deg"]

height = pifira.effective_height(flame_height_m=0.767, liquid_height_m=0.885)
area = pifira.effective_area(diameter_m=0.75, arc_deg=arc, height_m=height)
print(pifira.heat_flux(heat_W, area), "kW/m2")
```

The pressure-rise calculation uses a closed-vessel interval before relief
venting. The internal energy is evaluated with CoolProp while total mass and
vessel volume remain fixed. The effective circumferential width is obtained
from a Gaussian fit to the radiative driving force
`T_wall^4 - T_ambient^4`.

## LH2 evidence-gated example

```python
from pifira.lh2 import MilenkoCorrelation, RigidRotorSpinThermo

thermo = RigidRotorSpinThermo()
print(thermo.equilibrium_ortho(20.3))
print(thermo.conversion_energy_J_per_kg(20.3))

kinetics = MilenkoCorrelation()
k = kinetics.forward_rate_per_s(
    temperature_K=20.3,
    density_kg_m3=70.0,
    phase="liquid",
)
print(k, "1/s")
```

The LH2 functions enforce the reported temperature, density, phase and
composition domains by default. They do not constitute a certified relief
valve sizing method. In particular, the package does not infer a discharge
coefficient, effective area, lift law or two-phase capacity for a commercial
PSV from pressure cycling alone.

## Public API

| Area | Public objects |
|---|---|
| LPG pressure rise | `TankSpec`, `internal_energy`, `liquid_height`, `heat_input`, `heat_input_series` |
| Effective area | `radiative_driving_force`, `effective_arc`, `effective_height`, `effective_area`, `heat_flux` |
| Representative values | `heat_input_weighted_mean`, `simple_mean`, `coverage_fraction`, `normalized_flux`, `pressurization_number`, `orientation_factor` |
| File input | `load_pressure_csv`, `load_temperature_csv` |
| LH2 spin thermodynamics | `pifira.lh2.RigidRotorSpinThermo` |
| LH2 published kinetics | `pifira.lh2.MilenkoCorrelation`, `pifira.lh2.CorrelationDomainError` |
| LH2 nozzle utility | `pifira.lh2.HEOSNozzleLookup`, `pifira.lh2.heos_nozzle_lookup` |

## Validation-data policy

Only source metadata and acquisition instructions are versioned. The project
does not redistribute source PDFs, spreadsheets, presentation files, figure
rasters, digitized traces, or derived validation tables. Users who reproduce a
comparison must obtain the material from the original source, comply with its
terms, and keep it outside version control. See
[`VALIDATION_SOURCES.md`](https://github.com/lyullee/pifira/blob/main/VALIDATION_SOURCES.md).

Package releases are checked automatically for common third-party data and
document formats before PyPI publication.

## Scope and safety

`pifira` is research software. It is not an ISO 21013, API 520/521, ASME or
KGS design implementation, and it must not replace certified sizing,
manufacturer capacity data, or engineering review. A successful numerical
reproduction means that the code regenerated a reported result; it does not by
itself establish physical validation or fitness for safety-critical use.

## Citation and release history

Use [`CITATION.cff`](https://github.com/lyullee/pifira/blob/main/CITATION.cff)
and cite the archived Zenodo release. The
badge above uses the concept DOI, which resolves to the newest archived
version. Changes are listed in
[`CHANGELOG.md`](https://github.com/lyullee/pifira/blob/main/CHANGELOG.md).

## License

The software is released under the
[MIT License](https://github.com/lyullee/pifira/blob/main/LICENSE). Third-party source
material is not covered by that license and is not included.
