Define and implement a framework for component quantity unit handling

[zsarnoczay]

Problem

• Mismatched units between CMP_QNT and downstream expectations can distort damage and repair metrics. Pelicun allows a wide range of units and outputs damage quantities in whatever the user specifies. ATC 138 code cannot handle arbitrary units and might be based on the blocks defined in FEMA P-58 acting as units (e.g., 100LF).

Proposed solution

• Discuss the requirements for ATC 138 simulation. Document these explicitly and include Unit checks in the Pelicun output converter that warn users if they do not have the right units. Additionally, consider including more flexibility by converting units in the main code; or enhancing the pelicun conversion method to support multiple units at least from Pelicun.

[zsarnoczay]

This has been addressed in PR #20 .

What was done

Root cause: The convert_pelicun function in input_builder.py stripped Pelicun's unit metadata and passed raw physical quantities (SF, LF, EA) directly as qnt_damaged, num_comps, and comp_population. The ATC-138 engine expects these as P-58 component unit counts (physical quantity ÷ unit_qty), so the area calculations in the functionality assessment were inflated by unit_qty (often 30–1000×).

Fix — unit conversion:

1. Added a _UNIT_TO_SI conversion table and a _pelicun_to_p58_factor helper that computes the combined conversion factor for each component using its Pelicun unit (from CMP_QNT.csv) and its P-58 block size (unit_qty from component_attributes.csv).
2. The conversion handles imperial↔metric automatically (e.g., m² → sf) and correctly skips components with specialized units (EA → amp/ton/cfm) where the Pelicun value already represents a P-58 unit count.
3. The factor is applied to qnt_damaged, qnt_damaged_dir_*, num_comps, and comp_population — all quantities that are multiplied by unit_qty downstream.

Additional fix — replacement time: Pelicun's repair_time-parallel (worker-days) was also being used directly as calendar days for replacement time. Added a conversion that divides by a realistic crew size, consistent with the REDi-based formula used by the repair scheduler.

Repair times in worker-days and repair costs are left unconverted as they are decision variables not scaled by unit_qty downstream.