Metadata-Version: 2.4
Name: pycfast
Version: 0.1.0
Summary: Python interface for building, running, and analyzing CFAST fire simulation models
Author-email: WYGAS Benoît <benoit.wgs@protonmail.com>
Maintainer-email: WYGAS Benoît <benoit.wgs@protonmail.com>
License: MIT License
        
        Copyright (c) 2025 Benoît WYGAS — Orano.
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/bewygs/pycfast
Project-URL: Documentation, https://bewygs.github.io/pycfast
Project-URL: Repository, https://github.com/bewygs/pycfast
Project-URL: Issues, https://github.com/bewygs/pycfast/issues
Project-URL: Changelog, https://github.com/bewygs/pycfast/blob/main/CHANGELOG.md
Keywords: fire,simulation,cfast,modeling,fire-safety,engineering
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: License :: OSI Approved :: MIT License
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: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: f90nml>=1.4.5
Requires-Dist: pandas>=2.0.0
Provides-Extra: docs
Requires-Dist: pycfast[examples]; extra == "docs"
Requires-Dist: ipython; extra == "docs"
Requires-Dist: sphinx>=5.0; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Requires-Dist: nbsphinx; extra == "docs"
Requires-Dist: sphinx-gallery>=0.16; extra == "docs"
Requires-Dist: linkify-it-py; extra == "docs"
Requires-Dist: numpydoc>=1.9.0; extra == "docs"
Requires-Dist: sphinx-copybutton>=0.5.2; extra == "docs"
Requires-Dist: pydata-sphinx-theme>=0.16.1; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=3.0.1; extra == "docs"
Provides-Extra: dev
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: coverage; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pandas-stubs; extra == "dev"
Provides-Extra: examples
Requires-Dist: salib>=1.5.1; extra == "examples"
Requires-Dist: scipy>=1.15.3; extra == "examples"
Requires-Dist: matplotlib>=3.10.5; extra == "examples"
Requires-Dist: jupyter>=1.1.1; extra == "examples"
Requires-Dist: seaborn>=0.13.2; extra == "examples"
Requires-Dist: scikit-learn>=1.7.1; extra == "examples"
Requires-Dist: dask>=2025.7.0; extra == "examples"
Requires-Dist: distributed>=2025.7.0; extra == "examples"
Requires-Dist: bokeh>=3.8.0; extra == "examples"
Requires-Dist: torch>=2.8.0; extra == "examples"
Dynamic: license-file

# PyCFAST

[![CI Status](https://github.com/bewygs/pycfast/actions/workflows/test.yml/badge.svg)](https://github.com/bewygs/pycfast/actions/workflows/test.yml)
[![Docs](https://github.com/bewygs/pycfast/actions/workflows/docs.yml/badge.svg)](https://bewygs.github.io/pycfast)
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![MyPy Checked](https://img.shields.io/badge/mypy-checked-blue)](https://github.com/python/mypy)
[![codecov](https://codecov.io/gh/bewygs/pycfast/graph/badge.svg?token=B39Q5PHMU3)](https://codecov.io/gh/bewygs/pycfast)
[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](https://github.com/bewygs/pycfast/blob/main/LICENSE)

**PyCFAST** is a Python interface for the [**Consolidated Fire and Smoke Transport (CFAST)**](https://pages.nist.gov/cfast/)
fire simulation software. Its primary goal is to **automate CFAST calculations at scale**,
run parametric studies, sensitivity analyses, data generation, or optimization loops that would be
impractical through the graphical interface. It also provides a convenient way to
create CFAST input files, execute simulations, and analyze results using the versatility
and extensive ecosystem of Python.

## From CEdit GUI to Python

PyCFAST can be seen as an alternative to the CEdit graphical interface. It exposes Python objects with **rich interactive representations** that integrate naturally into your Python workflow. Instead of relying on static input files, you define and manipulate CFAST models programmatically.

<table>
<tr>
<td align="center"><strong>CEdit (GUI)</strong></td>
<td align="center"><strong>PyCFAST (Python)</strong></td>
</tr>
<tr>
<td><img src="docs/source/_static/images/cedit-compartments-tab.png" alt="CEdit Compartments Tab" width="400"></td>
<td>

```python
from pycfast import Compartments

room = Compartments(
    id="Comp 1",
    width=10.0, depth=10.0, height=10.0,
    ceiling_mat_id="Gypboard",
    wall_mat_id="Gypboard",
    floor_mat_id="Gypboard",
)
room  # displays interactive HTML card
```

</td>
</tr>
</table>

Every PyCFAST object such as compartments, fires, vents, devices, materials can render as an interactive HTML card when displayed in Jupyter notebooks or VS Code notebooks. These cards provide a visual summary of the component's properties and can be expanded to show more details.:

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/source/_static/images/pycfast-all-cards-dark.png">
    <img src="docs/source/_static/images/pycfast-all-cards-light.png" alt="PyCFAST component cards" width="700">
  </picture>
</p>

The complete model overview displays all components at a glance with expandable details:

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/source/_static/images/pycfast-model-card-dark.png">
    <img src="docs/source/_static/images/pycfast-model-card-light.png" alt="PyCFAST model card" width="400">
  </picture>
</p>


## Example Usage

You can define your own CFAST model directly in python by importing the required classes.

```python
from pycfast import (
    CeilingFloorVents,
    CFASTModel,
    Compartments,
    Fires,
    MaterialProperties,
    MechanicalVents,
    SimulationEnvironment,
    WallVents,
)

simulation_environment = SimulationEnvironment(...)
material_properties = [MaterialProperties(...)]
compartments = [Compartments(...)]
wall_vents = [WallVents(...)]
ceiling_floor_vents = [CeilingFloorVents(...)]
mechanical_vents = [MechanicalVents(...)]
fires = [Fires(...)]

model = CFASTModel(
    simulation_environment=simulation_environment,
    material_properties=material_properties,
    compartments=compartments,
    wall_vents=wall_vents,
    ceiling_floor_vents=ceiling_floor_vents,
    mechanical_vents=mechanical_vents,
    fires=fires,
    file_name="test_simulation.in",
    cfast_exe="/path/to/cfast_executable",
    extra_arguments=["-f"],
)

results = model.run()
# results is a dict of pandas DataFrames for each output CSV file
```

Or you can import your existing model from a CFAST input file:

```python
from pycfast.parsers import parse_cfast_file

model = parse_cfast_file("existing_model.in")
```

**Note:** When importing an existing model, ensure that all component names (such as TITLE, MATERIAL, ID, etc.) use **only alphanumeric characters**. Avoid **special characters** like quotes and slashes, as these may cause parsing issues and will be automatically sanitized where possible.

You can inspect any model interactively (displays the HTML card shown above), or use text-based methods:

```python
model             # interactive HTML card in Jupyter/VS Code
model.summary()   # text summary to stdout
model.save()      # writes the CFAST input file to disk
model.view_cfast_input_file()  # view the generated input file
```

With this library you can easily obtain a similar data generation workflow as below:

https://github.com/user-attachments/assets/9ae23493-9440-4850-a371-0079fbd61975

Check out the [examples](https://pycfast.org/examples/) for more usage scenarios.

## Installation

PyCFAST requires **Python 3.10 or later**. It is fully tested with **CFAST 7.7.5** and is expected to be compatible with all **CFAST 7.7.x** versions.

### Pip or Conda

PyCFAST can be installed from [PyPI](https://pypi.org/project/pycfast) or [conda-forge](https://anaconda.org/conda-forge/pycfast):

```bash
pip install pycfast
```

```bash
conda install -c conda-forge pycfast
```

### Source

To install PyCFAST from source, clone the repository and install the required dependencies:

```bash
git clone https://github.com/bewygs/pycfast.git
cd pycfast
python -m pip install .
```

### CFAST Installation

Download and install CFAST from the [NIST CFAST website](https://pages.nist.gov/cfast/) or the [CFAST GitHub repository](https://github.com/firemodels/cfast). Follow the installation instructions for your operating system and ensure `cfast` is available in your PATH. If CFAST is installed in a non-standard location, you can manually specify the path with these methods :

- From an environment variable ``CFAST``:

    ```bash
    export CFAST="/path/to/your/cfast/executable"  # Linux/MacOS
    set CFAST="C:\path\to\your\cfast\executable"  # Windows (cmd)
    $env:CFAST="C:\path\to\your\cfast\executable"  # Windows (PowerShell)
    ```

- From Python code when defining the ``CFASTModel``:

    ```python
    import pycfast

    # set custom CFAST executable path via environment variable
    import os
    os.environ['CFAST'] = "/path/to/your/cfast/executable"

    # Or directly when defining CFASTModel
    model = pycfast.CFASTModel(cfast_path="/path/to/your/cfast/executable")
    ```

## Documentation

Full documentation, including the API reference and examples, is available online: [PyCFAST Documentation](https://pycfast.org/stable/)

## Examples

Some examples on how to use PyCFAST with various python libraries (Numpy, SciPy, SAlib, etc.) can be found in the [examples](https://pycfast.org/stable/examples/).

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for more information.

## References

If you use PyCFAST in your projects, please consider citing the following:

```bib
@misc{pycfast-zenodo-2025,
    title        = {PyCFAST},
    author       = {{Benoit Wygas}},
    year         = {2025},
    publisher    = {Zenodo},
    version      = {0.1.0},
    doi          = {},
    url          = {},
    note         = {Software release}
}
```

## Acknowledgments

This Python package was developed with the support of [**Orano**](https://www.orano.group/).

<a href="https://www.orano.group/">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/source/_static/orano-logo-dark.svg">
    <img src="docs/source/_static/orano-logo.svg" alt="Orano logo" width="150" >
  </picture>
</a>

PyCFAST is built on top of the work of the CFAST development team at the 
[National Institute of Standards and Technology (NIST)](https://www.nist.gov/). 
We acknowledge their ongoing efforts in maintaining and improving the CFAST fire 
modeling software.
