pyFDS-Evac Roadmap With JuPedSim API Placement

[chraibi]

<proposed_plan>

pyFDS-Evac Roadmap With JuPedSim API Placement

Summary

• Build pyFDS-Evac as a standalone Python package that owns fire-aware evacuation behavior.
• Use FDS+Evac as the primary behavioral reference, especially:
  • smoke-speed reduction in evac.f90
  • fire-condition/FED field generation in evac.f90
  • route/door decision logic in evac.f90
• Put the JuPedSim API inside the runtime/integration layer of pyFDS-Evac, not inside the web backend.
• The web backend becomes a thin adapter over pyFDS-Evac.

Package Structure

• pyfdsevac/io
  • responsibility: load FDS outputs, load/export scenario data, persist results
• pyfdsevac/fields
  • responsibility: generic fire fields, coordinate alignment, field sampling, door/path summaries
• pyfdsevac/behavior
  • responsibility: speed model, route-decision logic, FED accumulation, future detection logic
• pyfdsevac/runtime
  • responsibility: JuPedSim API integration, step loop orchestration, scripted runs, CLI
• pyfdsevac/interfaces
  • responsibility: stable Python API for external callers
• pyfdsevac/cli
  • responsibility: batch/script commands

Where JuPedSim API Goes

• JuPedSim belongs in pyfdsevac/runtime, because it is the simulation engine dependency, not the fire-model definition.
• Concretely:
  • pyfdsevac/runtime/jupedsim_adapter.py
    • create/load simulation from scenario geometry and agent definitions
    • manage JuPedSim stepping
    • expose hooks for applying fire-aware speed and route updates
  • pyfdsevac/runtime/session.py
    • own one fire-aware simulation run
    • coordinate fields -> behavior -> JuPedSim step -> outputs
  • pyfdsevac/runtime/runner.py
    • high-level batch/programmatic entrypoint
• The app backend should call pyfdsevac.interfaces.run_simulation(...), which internally uses the JuPedSim adapter.

Core Internal Modules

pyfdsevac/io

• fds_source.py
  • wrap fdsvismap
  • load FDS slice-based data and metadata
  • expose quantity/time/height availability
• scenario_loader.py
  • load app-exported scenarios
  • normalize geometry, exits, routing graph inputs
• result_writer.py
  • save trajectories, route changes, FED histories, diagnostics
• fixtures.py
  • deterministic fixture builders for tests

pyfdsevac/fields

• models.py
  • FireFieldFrame
  • FireFieldSeries
  • FieldBounds
  • DoorFieldSummary
  • PathFieldSummary
• sampler.py
  • unified API:
    • sample_field(quantity, x, y, z, t)
    • sample_agent_conditions(agent_state, t)
    • summarize_path(path_geometry, t)
• alignment.py
  • map FDS coordinates to scenario/JuPedSim geometry space
  • validate overlap, resolution, height assumptions
• door_metrics.py
  • compute:
    • average extinction / visibility along a door path
    • max FED along a door path
    • visible vs non-visible route state

pyfdsevac/behavior

• speed.py
  • default FDS+Evac smoke-speed model from evac.f90
  • future optional compatibility modes:
    • Fridolf2018
    • Jin1978
• routing.py
  • implement FDS+Evac-style target-door selection from evac.f90
  • maintain:
    • known door state
    • visible door state
    • smoke rejection state
• fed.py
  • cumulative FED tracking using FDS+Evac semantics from evac.f90
• detection.py
  • smoke detection state hooks from evac.f90
• engine.py
  • fire-behavior orchestration for one update tick

pyfdsevac/runtime

• jupedsim_adapter.py
  • convert normalized scenario into JuPedSim API objects
  • expose agent state reads and update hooks
  • apply speed changes to desired speed / model parameters
  • apply route changes to current targets or routing state
• session.py
  • own one simulation session:
    • initialize JuPedSim
    • load fire fields
    • run periodic fire updates
    • collect outputs
• runner.py
  • public orchestration entrypoints for scripted use
• outputs.py
  • structured result objects for trajectories, FED, route switches, fire diagnostics

pyfdsevac/interfaces

• api.py

  • stable programmatic API for both backend and scripts
  • main entrypoints:

  run_simulation(
      scenario,
      simulation_config,
      fire_config,
      fds_results_path,
  ) -> SimulationResult

  load_fire_fields(
      fds_results_path,
      fire_config,
  ) -> FireFieldSeries

  replay_with_fire(
      scenario,
      base_trajectory=None,
      ...
  ) -> SimulationResult

pyfdsevac/cli

• main.py
  • command structure:

  pyfdsevac run --scenario scenario.json --fds-results /path/to/fds --fire-config fire.json
  pyfdsevac inspect-fds --fds-results /path/to/fds
  pyfdsevac validate --case fed-basic

Public Data Contracts

• FireConfig
  • enabled
  • time_step_s
  • z_slice_m
  • speed_model
  • routing_model
  • fed_model
  • fallback_policy
• SimulationConfig
  • JuPedSim runtime settings and stepping controls
• SimulationResult
  • trajectories
  • per-agent FED history
  • per-agent speed factor history
  • route switch events
  • fire diagnostics and warnings
• AgentFireState
  • speed_factor
  • fed_cumulative
  • smoke_detected
  • current_target_id
  • last_update_s

Step-by-Step Implementation Tasks

Phase 1: Package Foundation

1. Create pyFDS-Evac package skeleton in its own backend-reusable location.
2. Write the design/reference doc:
   • FDS+Evac as primary reference
   • JuPedSim placement in runtime layer
   • fdsvismap as low-level data dependency
3. Define internal models and public API contracts.

Phase 2: FDS Ingestion and Generic Fire Fields

1. Implement fds_source.py on top of fdsvismap.
2. Implement generic field objects:
   • frame-based
   • quantity-agnostic
   • sampleable by (x, y, z, t)
3. Implement geometry alignment against scenario/JuPedSim coordinates.
4. Add failure rules for:
   • missing slices
   • unsupported heights
   • non-overlapping coordinates

Phase 3: JuPedSim Runtime Integration

1. Build jupedsim_adapter.py.
2. Define exactly where fire updates happen in the JuPedSim stepping loop.
3. Expose reads for:
   • agent position
   • agent current target
   • agent desired speed/base speed
4. Expose writes for:
   • updated desired speed factor
   • updated route target / routing preference
5. Keep this adapter isolated so future JuPedSim API changes stay localized.

Phase 4: Speed Model

1. Implement the default smoke-speed model from evac.f90.
2. Add minimum speed clamping and configuration.
3. Integrate speed updates into the JuPedSim runtime loop.
4. Add tests for:
   • extinction/visibility conversion assumptions
   • factor bounds
   • repeated update stability

Phase 5: Route-Decision Logic

1. Model door candidates from scenario exits/routing graph.
2. Implement door/path fire summaries:
   • K_ave_Door
   • FED_max_Door
   • visible/non-visible classification
3. Implement FDS+Evac-style target selection ordering from evac.f90.
4. Add route-switch events and diagnostics.
5. Add deterministic tests covering:
   • smoke-free preferred path
   • reroute under smoke
   • candidate rejection under excessive smoke
   • fallback behavior when all candidates are poor

Phase 6: FED Tracking

1. Implement FED accumulation from sampled field values using evac.f90.
2. Store cumulative FED per agent over time.
3. Expose FED in outputs and diagnostics.
4. Do not yet add incapacitation unless explicitly enabled later.

Phase 7: Script and Batch Interface

1. Implement stable Python API in interfaces/api.py.
2. Implement CLI commands in cli/main.py.
3. Support scenario files exported/downloaded from the app.
4. Ensure script mode and backend mode call the exact same runtime path.

Phase 8: Backend Integration

1. Add a thin backend adapter layer in the current web backend.
2. Backend routes:
   • load scenario
   • call pyfdsevac.interfaces.api.run_simulation
   • return structured result
3. Do not implement fire logic in route handlers.

Phase 9: Validation

1. Add unit tests for:
   • field sampling
   • alignment
   • speed model
   • routing scoring
   • FED accumulation
2. Add integration tests for:
   • JuPedSim + fire runtime session
   • scripted run path
   • backend API path
3. Add behavior validation against:
   • Pathfinder FED cases
   • Pathfinder walk-speed-smoke cases
   • source-derived FDS+Evac spot checks

Deliverables

• pyFDS-Evac package with reusable API
• JuPedSim integration inside runtime
• backend adapter using that package
• CLI for batch/scenario runs
• validation tests and reference documentation

Assumptions and Defaults

• FDS results are consumed offline only.
• fdsvismap remains the low-level FDS reader dependency.
• JuPedSim remains the simulation engine used by pyFDS-Evac.
• App/backend scenario geometry remains authoritative.
• v1 scope is:
  • speed change
  • route change
  • FED tracking
• Future richer human behavior should extend behavior/ without changing the outer API.
  </proposed_plan>