pycfast 0.2.0__tar.gz → 0.2.2__tar.gz

pycfast-0.2.2/.dockerignore

@@ -0,0 +1,18 @@
+# Keep .git — hatch-vcs needs it to resolve the package version during the
+# Docker build (see the sdist-builder stage in the Dockerfile).
+
+.venv
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+__pycache__/
+*.py[codz]
+htmlcov/
+.coverage
+docs/build/
+docs/_build/
+tests/verification_tests/verification_data_local/
+tests/validation_tests/validation_data_local/
+dist/
+build/
+*.egg-info/

pycfast-0.2.2/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,51 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: 'BUG: <Please write a comprehensive title after the ''BUG: '' prefix>'
+labels: bug
+assignees: bewygs
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Create a model with '...'
+2. Run simulation with '...'
+3. Parse results using '...'
+4. See error
+
+**Minimal Code Example**
+Please provide a minimal code example that reproduces the issue:
+
+```python
+# Your code here
+```
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Error message**
+If applicable, paste the full error message/traceback:
+
+```
+Error traceback here
+```
+
+**Environment (please complete the following information):**
+ - OS: [e.g., Ubuntu 22.04, Windows 11]
+ - Python version: [e.g., 3.10, 3.11, 3.12, 3.13]
+ - PyCFAST version: [e.g., 0.1.0]
+ - CFAST version: [e.g., 7.7.7]
+ - Installation method: [e.g., pip, uv, from source]
+
+**CFAST Input File**
+If the issue is related to a specific CFAST model, please attach or include the `.in` file:
+```
+Attach or paste file content here
+```
+
+**Additional context**
+Add any other context about the problem here (e.g., specific building configuration, fire scenario details, convergence issues, etc.).

pycfast-0.2.2/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea or enhancement for PyCFAST
+title: 'FEAT: <Please write a comprehensive title after the FEAT: prefix>'
+labels: enhancement
+assignees: bewygs
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

pycfast-0.2.2/.github/copilot-commit-message-instructions.md

@@ -0,0 +1,44 @@
+# Commit Message Instructions for PyCFAST
+
+Follow conventional commit format: `<type>: <description>`
+
+## Types
+- **DEV**: development tool or utility
+- **FIX**: Bug fix  
+- **DOC**: Documentation changes
+- **BLD**: Dependencies/build system (Makefile, pyproject.toml, ...)
+- **STY**: Code formatting
+- **TST**: addition or modification of tests
+- **MAINT**: maintenance commit (refactoring, typos, etc.)
+- **FEAT**: new feature or enhancement
+- **CI**: CI/CD workflows
+- **REL**: release commit (version bump, changelog update, etc.)
+- **chore**: Other maintenance
+
+## Rules
+- Use imperative mood ("Add" not "Added")
+- Start with capital letter
+- No period at end
+- Keep under 50 characters
+- Reference issues when relevant
+
+## Examples
+```
+FEAT: add CFAST 7.8 ventilation support
+FIX: handle missing executable gracefully
+DOC: update installation guide for uv  
+TST: add compartment validation tests
+CI: migrate workflows to use uv
+BLD: bump pandas minimum to 2.1.0
+DEV: add mypy type checking to Makefile
+MAINT: refactor simulation environment module
+STY: apply ruff formatting rules
+```
+
+## Breaking Changes
+Add `!` and footer:
+```
+FEAT!: redesign Model class interface
+
+BREAKING CHANGE: Model.run() returns SimulationResult object
+```

pycfast-0.2.2/.github/copilot-instructions.md

@@ -0,0 +1,29 @@
+# PyCFAST Overview
+
+PyCFAST is a Python interface for building, running, and analyzing CFAST fire simulation models. It allows you to programmatically create CFAST input files, execute simulations, and process results directly in Python. It's a pure Python library that does not require any CFAST-specific dependencies.
+
+CFAST is a computer program that fire investigators, safety officials, researchers, and engineers can use to simulate the impact of past or potential fires and smoke in a specific building environment. CFAST is a two-zone fire model used to calculate the evolving distribution of smoke, fire gases and temperature throughout compartments of a building during a fire.
+
+ ## Folder Structure
+
+- `/src/pycfast`: Contains the source code for the library.
+- `/examples`: Contains examples scripts showing how to use the library.
+- `/docs`: Contains documentation for the project, a user guides and some script to keep the documentation up to date with CFAST official documentation.
+- `/tests`: Contains tests that validate the functionality of the library.
+
+## Libraries and Frameworks
+ - python
+ - pandas
+ - f90nml
+
+## Coding Standards
+
+- Use ruff coding standard including formatting, linting, and best practices.
+- Follow mypy for type checking.
+- Use numpy docstring style for documentation.
+- Stay Pythonic
+- Follow SOLID and DRY principles where applicable.
+
+## Environment Setup
+
+When running command you can use the makefile commands to have the right environment with the right dependencies installed.

pycfast-0.2.2/.github/dependabot.yml

@@ -0,0 +1,27 @@
+version: 2
+
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    groups:
+      python-minor-patch:
+        patterns:
+          - "*"
+        update-types:
+          - "minor"
+          - "patch"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      github-actions-minor-patch:
+        patterns:
+          - "*"
+        update-types:
+          - "minor"
+          - "patch"

pycfast-0.2.2/.github/workflows/docker-image.yml

@@ -0,0 +1,110 @@
+name: Docker Image CI
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [ "main" ]
+    paths:
+      - 'Dockerfile'
+      - 'src/**'
+      - 'pyproject.toml'
+      - 'README.md'
+      - '.github/workflows/docker-image.yml'
+
+  pull_request:
+    branches: [ "main" ]
+    paths:
+      - 'Dockerfile'
+      - 'src/**'
+      - 'pyproject.toml'
+      - 'README.md'
+      - '.github/workflows/docker-image.yml'
+
+  # Triggers the `publish` job below once the PyPI release is available
+  workflow_run:
+    workflows: ["Upload Python Package"]
+    types: [completed]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    if: github.event_name != 'workflow_run'
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # hatch-vcs needs the full history and tags to resolve the package
+          # version in the sdist-builder stage (see Dockerfile).
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Build image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          target: local
+          load: true
+          tags: pycfast:ci
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: test image
+        run: |
+          docker run --rm pycfast:ci python -c "import pycfast; print(pycfast.__version__)"
+          output=$(docker run --rm pycfast:ci sh -c "cfast 2>&1 || true")
+          echo "$output"
+          echo "$output" | grep -qi "cfast"
+
+  publish:
+    if: github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'success'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # workflow_run defaults to the default branch; check out the exact
+          # commit that python-publish.yml actually released instead.
+          ref: ${{ github.event.workflow_run.head_sha }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract image metadata
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ghcr.io/${{ github.repository }}
+          # workflow_run doesn't carry the triggering tag in `github.ref`, so
+          # the tag/version has to be given explicitly. `head_branch` holds
+          # the tag name here despite the field name (GitHub Actions quirk).
+          tags: |
+            type=semver,pattern={{version}},value=${{ github.event.workflow_run.head_branch }}
+            type=semver,pattern={{major}}.{{minor}},value=${{ github.event.workflow_run.head_branch }}
+
+      - name: Push image to GitHub Container Registry
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          target: pypi
+          build-args: |
+            PYCFAST_VERSION=${{ steps.meta.outputs.version }}
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha

pycfast-0.2.2/.github/workflows/docs.yml

@@ -0,0 +1,115 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'src/**'
+      - 'docs/**'
+      - 'examples/**'
+      - 'CONTRIBUTING.md'
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - '.github/workflows/docs.yml'
+
+  pull_request:
+    branches: [main]
+    paths:
+      - 'src/**'
+      - 'docs/**'
+      - 'examples/**'
+      - 'CONTRIBUTING.md'
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - '.github/workflows/docs.yml'
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      CFAST_VERSION: "7.7.7"
+      CFAST_TAG: "CFAST-7.7.7"
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+          
+      - name: Set up Python
+        run: uv python install 3.10
+        
+      - name: Install pandoc
+        run: sudo apt-get update && sudo apt-get install -y pandoc
+
+      - name: Cache CFAST binary
+        id: cache-cfast
+        uses: actions/cache@v6
+        with:
+          path: ~/cfast-cache/cfast-${{ env.CFAST_VERSION }}-ubuntu-latest
+          key: cfast-binary-${{ env.CFAST_VERSION }}-Linux-X64-${{ hashFiles('.github/workflows/docs.yml') }}
+          restore-keys: |
+            cfast-binary-${{ env.CFAST_VERSION }}-Linux-X64-
+
+      - name: Install build dependencies for CFAST
+        if: steps.cache-cfast.outputs.cache-hit != 'true'
+        run: sudo apt-get update && sudo apt-get install -y gfortran make
+
+      - name: Download and build CFAST ${{ env.CFAST_VERSION }}
+        if: steps.cache-cfast.outputs.cache-hit != 'true'
+        run: |
+          git clone --depth 1 --branch ${{ env.CFAST_TAG }} https://github.com/firemodels/cfast.git cfast-${{ env.CFAST_VERSION }}
+          cd cfast-${{ env.CFAST_VERSION }}/Build/CFAST/gnu_linux
+          chmod +x make_cfast.sh
+          ./make_cfast.sh
+          mkdir -p ~/cfast-cache
+          cp cfast7_linux ~/cfast-cache/cfast-${{ env.CFAST_VERSION }}-ubuntu-latest
+          chmod +x ~/cfast-cache/cfast-${{ env.CFAST_VERSION }}-ubuntu-latest
+
+      - name: Install CFAST to system path
+        run: |
+          sudo cp ~/cfast-cache/cfast-${{ env.CFAST_VERSION }}-ubuntu-latest /usr/bin/cfast
+          sudo chmod +x /usr/bin/cfast
+
+      - name: Verify CFAST installation
+        run: |
+          which cfast
+          cfast
+        
+      - name: Install dependencies
+        run: uv sync --extra docs
+        
+      - name: Build documentation
+        run: |
+          cd docs
+          uv run sphinx-build -b html source build/html -W --keep-going
+          echo "pycfast.org" > build/html/CNAME
+          
+      - name: Upload pages artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: docs/build/html
+
+  deploy:
+    if: github.ref == 'refs/heads/main'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

pycfast-0.2.2/.github/workflows/joss.yml

@@ -0,0 +1,38 @@
+name: JOSS Paper
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    paths:
+      - .github/workflows/joss.yml
+      - 'paper/paper.md'
+      - 'paper/paper.bib'
+  pull_request:
+    paths:
+      - .github/workflows/joss.yml
+      - 'paper/paper.md'
+      - 'paper/paper.bib'
+
+jobs:
+  paper:
+    runs-on: ubuntu-latest
+    name: Paper Draft
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+      - name: Build draft PDF
+        uses: openjournals/openjournals-draft-action@master
+        with:
+          journal: joss
+          # This should be the path to the paper within your repo.
+          paper-path: paper/paper.md
+      - name: Upload
+        uses: actions/upload-artifact@v7
+        with:
+          name: paper
+          # This is the output path where Pandoc will write the compiled
+          # PDF. Note, this should be the same directory as the input
+          # paper.md
+          path: paper/paper.pdf

pycfast-0.2.2/.github/workflows/python-publish.yml

@@ -0,0 +1,67 @@
+# This workflow will upload a Python Package to PyPI when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # hatch-vcs needs the full history and tags to resolve the package
+          # version from the release tag.
+          fetch-depth: 0
+          fetch-tags: true
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.x"
+
+      - name: Build release distributions
+        run: |
+          # NOTE: put your own distribution build steps here.
+          python -m pip install build
+          python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      id-token: write
+
+    environment:
+      name: pypi
+      url: https://pypi.org/project/pycfast/
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

pycfast-0.2.2/.github/workflows/sync-cfast-inputs.yml

@@ -0,0 +1,100 @@
+name: Sync CFAST Input Files
+
+on:
+  schedule:
+    # Run every Sunday at 2 AM UTC
+    - cron: '0 2 * * 0'
+  workflow_dispatch:
+    inputs:
+      suite:
+        description: 'Which suite to sync'
+        required: false
+        default: 'all'
+        type: choice
+        options: [all, verification, validation]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  sync-input-files:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+        token: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Configure Git
+      run: |
+        git config --global user.name 'github-actions[bot]'
+        git config --global user.email 'github-actions[bot]@users.noreply.github.com'
+
+    - name: Install required tools
+      run: sudo apt-get update && sudo apt-get install -y rsync curl
+
+    - name: Sync CFAST input files
+      id: sync
+      run: |
+        SUITE="${{ github.event.inputs.suite || 'all' }}"
+        chmod +x tests/sync_cfast_inputs.sh
+        tests/sync_cfast_inputs.sh --suite "$SUITE"
+
+        if git diff --quiet && git diff --cached --quiet; then
+          echo "changes_detected=false" >> $GITHUB_OUTPUT
+        else
+          echo "changes_detected=true" >> $GITHUB_OUTPUT
+          changed=$(git diff --name-only | wc -l)
+          new=$(git ls-files --others --exclude-standard tests/verification_tests/Verification/ tests/validation_tests/Validation/ | wc -l)
+          echo "changed_files=$changed" >> $GITHUB_OUTPUT
+          echo "new_files=$new" >> $GITHUB_OUTPUT
+          echo "total_changes=$((changed + new))" >> $GITHUB_OUTPUT
+          echo "suite=$SUITE" >> $GITHUB_OUTPUT
+        fi
+
+    - name: Create Pull Request
+      if: steps.sync.outputs.changes_detected == 'true'
+      uses: peter-evans/create-pull-request@v8
+      with:
+        token: ${{ secrets.GITHUB_TOKEN }}
+        commit-message: |
+          chore: sync CFAST ${{ steps.sync.outputs.suite }} input files
+
+          - Modified: ${{ steps.sync.outputs.changed_files }} files
+          - Added: ${{ steps.sync.outputs.new_files }} files
+          - Total: ${{ steps.sync.outputs.total_changes }} files
+
+          Auto-generated by sync-cfast-inputs workflow
+        title: 'chore: sync CFAST ${{ steps.sync.outputs.suite }} input files'
+        body: |
+          ## Automated CFAST Input Files Sync
+
+          **Suite:** `${{ steps.sync.outputs.suite }}`
+
+          | | Count |
+          |---|---|
+          | Modified files | ${{ steps.sync.outputs.changed_files }} |
+          | New files | ${{ steps.sync.outputs.new_files }} |
+          | Total | ${{ steps.sync.outputs.total_changes }} |
+
+          Please review the changes and merge if everything looks correct.
+        branch: sync-cfast-input-files
+        delete-branch: true
+        labels: |
+          automated
+          maintenance
+
+    - name: Summary
+      run: |
+        if [ "${{ steps.sync.outputs.changes_detected }}" == "true" ]; then
+          echo "Changes detected — PR created"
+          echo "  Suite:    ${{ steps.sync.outputs.suite }}"
+          echo "  Modified: ${{ steps.sync.outputs.changed_files }}"
+          echo "  New:      ${{ steps.sync.outputs.new_files }}"
+          echo "  Total:    ${{ steps.sync.outputs.total_changes }}"
+        else
+          echo "No changes — input files are up to date"
+        fi