PELICUN Loss Assessment - Technical Guide

POST /assess-property
Content-Type: application/json

{
  property: {
    lat: number;              // Latitude (WGS84)
    lng: number;              // Longitude (WGS84)
    building_type: string;    // HAZUS type (W1, S1L, C2M, etc.)
    occupancy: string;        // HAZUS occupancy (RES1, COM1, etc.)
    stories: number;          // Number of stories
    year_built: number;       // Year of construction
    square_feet: number;      // Building area
    replacement_value: number; // USD
    design_level?: string;    // 'Pre' | 'Low' | 'Moderate' | 'High'
  },
  hazard: {
    earthquake?: {
      pga: number;            // Peak Ground Acceleration (g)
      sa_03?: number;         // Spectral Acceleration at 0.3s
      sa_10?: number;         // Spectral Acceleration at 1.0s
    }
  },
  options?: {
    num_realizations?: number; // Default: 1000
    include_components?: boolean;
    include_injuries?: boolean;
  }
}

{
  assessment_id: string;
  property_id: string;
  timestamp: string;
  
  loss_estimate: {
    structural: {
      mean: number;           // Mean loss (USD)
      median: number;
      std: number;
      cov: number;            // Coefficient of variation
      percentiles: {
        P10: number;
        P50: number;
        P90: number;
        P95: number;
        P99: number;
      }
    },
    non_structural_drift: { /* same structure */ },
    non_structural_acceleration: { /* same structure */ },
    contents: { /* same structure */ },
    total_loss: { /* same structure */ }
  },
  
  damage_states: {
    DS0_no_damage: number;    // Percentage (0-100)
    DS1_slight: number;
    DS2_moderate: number;
    DS3_extensive: number;
    DS4_complete: number;
  },
  
  collapse: {
    probability: number;      // 0-1
    injuries_given_collapse: number;
    fatalities_given_collapse: number;
  },
  
  metadata: {
    pelicun_version: string;
    num_realizations: number;
    computation_time_seconds: number;
  }
}

curl -X POST \
  https://publicrisk--publicrisk-pelicun-service.modal.run/assess-property \
  -H "Content-Type: application/json" \
  -d '{
    "property": {
      "lat": 37.7749,
      "lng": -122.4194,
      "building_type": "W1",
      "occupancy": "RES1",
      "stories": 2,
      "year_built": 1965,
      "square_feet": 2400,
      "replacement_value": 850000,
      "design_level": "Low"
    },
    "hazard": {
      "earthquake": {
        "pga": 0.52,
        "sa_03": 0.73,
        "sa_10": 0.41
      }
    },
    "options": {
      "num_realizations": 5000,
      "include_components": true
    }
  }'

POST /assess-multi-hazard
Content-Type: application/json

{
  property: PropertyCharacteristics, // Same as above
  
  hazards: {
    earthquake?: EarthquakeHazard,
    flood?: {
      inundation_depth_ft: number;
      velocity_fps?: number;
      duration_hours?: number;
      water_type?: 'fresh' | 'salt';
    },
    wind?: {
      wind_speed_mph: number;
      exposure?: 'B' | 'C' | 'D';
      storm_surge_ft?: number;
    },
    wildfire?: {
      flame_intensity_kw_m2: number;
      ember_exposure?: 'low' | 'medium' | 'high';
    }
  },
  
  analysis_options?: {
    num_realizations?: number;
    consider_cascading?: boolean;
    spatial_correlation?: number; // 0-1
  }
}

{
  assessment_id: string;
  multi_hazard_results: {
    combined_loss: LossStatistics,
    
    loss_by_hazard: {
      earthquake?: LossStatistics,
      flood?: LossStatistics,
      wind?: LossStatistics,
      wildfire?: LossStatistics
    },
    
    cascading_failures?: {
      primary_hazard: string;
      triggered_hazards: string[];
      amplification_factor: number;
      description: string;
    }[],
    
    loss_correlation_matrix: number[][],
    
    combined_damage_states: {
      DS0_no_damage: number,
      DS1_slight: number,
      DS2_moderate: number,
      DS3_extensive: number,
      DS4_complete: number
    }
  }
}

POST /component-damage
Content-Type: application/json

{
  assessment_id: string;      // From property assessment
  detail_level: 'summary' | 'full';
  filters?: {
    category?: string[];      // ['structural', 'non-structural', 'contents']
    min_contribution?: number; // Minimum % contribution to show
    damage_state?: string[];  // ['DS1', 'DS2', 'DS3', 'DS4']
  },
  sort?: {
    by: 'expected_loss' | 'repair_cost' | 'damage_probability';
    order: 'asc' | 'desc';
  }
}

{
  assessment_id: string;
  total_components: number;
  
  components_by_category: {
    structural: ComponentDamage[],
    non_structural_drift: ComponentDamage[],
    non_structural_acceleration: ComponentDamage[],
    contents: ComponentDamage[]
  },
  
  top_contributors: ComponentDamage[], // Top 10 by expected loss
  
  component_summary: {
    total_expected_loss: number;
    total_repair_cost: number;
    components_damaged: number;
    components_total: number;
  }
}

// ComponentDamage structure:
{
  component_id: string;       // "B.10.41.001a"
  description: string;        // "Reinforced Concrete Shear Wall"
  category: string;
  quantity: number;
  unit: string;
  
  damage_states: {
    DS0: { probability: number, cost: 0 },
    DS1: { probability: number, cost: number },
    DS2: { probability: number, cost: number },
    DS3: { probability: number, cost: number },
    DS4: { probability: number, cost: number }
  },
  
  expected_loss: ProbabilisticValue, // { mean, median, std, P10, P50, P90 }
  repair_cost: ProbabilisticValue,
  repair_time_days: ProbabilisticValue,
  contribution_pct: number    // % of total loss
}

POST /repair-timeline
Content-Type: application/json

{
  assessment_id: string;
  timeline_options?: {
    crew_size?: number;       // Default: 5
    working_hours_per_day?: number; // Default: 8
    consider_dependencies?: boolean; // Default: true
    parallel_work?: boolean;  // Default: true
  }
}

{
  assessment_id: string;
  
  repair_phases: RepairPhase[], // Chronological phases
  
  critical_path: CriticalPathItem[], // Components on critical path
  
  cost_breakdown: {
    labor_cost: number;
    material_cost: number;
    equipment_cost: number;
    total_cost: number;
  },
  
  summary: {
    total_duration_days: number;
    earliest_completion: string; // ISO date
    latest_completion: string;   // With delays
    parallel_efficiency: number; // 0-1
  }
}

// RepairPhase structure:
{
  phase_number: number;
  phase_name: string;           // "Foundation Repair", "Frame Retrofit"
  start_day: number;
  duration_days: number;
  end_day: number;
  
  components: string[];         // Component IDs in this phase
  prerequisites: number[];      // Phase numbers that must complete first
  
  cost_estimate: number;
  labor_hours: number;
  critical_path_item: boolean;
}

POST /casualty-estimate
Content-Type: application/json

{
  assessment_id: string;
  
  scenario?: {
    time_of_day: 'daytime' | 'nighttime' | 'custom';
    occupancy_rate?: number;  // 0-1, overrides time_of_day
    population?: number;      // Override default occupancy
  },
  
  casualty_options?: {
    include_severity_breakdown?: boolean; // Default: true
    include_injury_types?: boolean;
  }
}

{
  assessment_id: string;
  scenario: {
    time_of_day: string;
    occupancy_rate: number;
    population: number;
  },
  
  casualties_by_severity: {
    severity_1: CasualtyLevel, // Minor injuries
    severity_2: CasualtyLevel, // Moderate injuries (hospitalization)
    severity_3: CasualtyLevel, // Life-threatening injuries (ICU)
    severity_4: CasualtyLevel  // Fatalities
  },
  
  total_casualties: {
    injuries: number;         // Severity 1-3
    fatalities: number;       // Severity 4
    total: number;
  },
  
  contributing_factors: [
    {
      factor: string;         // "Structural collapse", "Non-structural falling"
      contribution_pct: number;
      severity_distribution: {
        severity_1: number,
        severity_2: number,
        severity_3: number,
        severity_4: number
      }
    }
  ]
}

// CasualtyLevel structure:
{
  count: number;              // Expected casualties
  probability: number;        // 0-1
  percentage: number;         // % of total casualties
  confidence_interval: {
    P10: number,
    P50: number,
    P90: number
  }
}

GET /loss-distribution?assessment_id={id}&distribution_type={type}

{
  assessment_id: string;
  distribution_type: string;
  
  distribution: {
    type: 'metalog',
    quantiles: {
      q01: number,  // 1st percentile
      q25: number,  // 25th percentile
      q50: number,  // Median
      q75: number,  // 75th percentile
      q99: number   // 99th percentile
    },
    metalog_coefficients: number[] // For reconstruction
  },
  
  statistics: {
    mean: number,
    median: number,
    mode: number,
    std: number,
    skewness: number,
    kurtosis: number,
    cv: number,           // Coefficient of variation
    percentiles: {
      P01: number, P05: number, P10: number,
      P25: number, P50: number, P75: number,
      P90: number, P95: number, P99: number
    }
  },
  
  compression_metrics: {
    original_samples: number;    // e.g., 10000
    compressed_quantiles: number; // 5
    compression_ratio: number;    // 0.9995 (99.95%)
    monte_carlo_size_bytes: number;
    metalog_size_bytes: number;
    space_savings_pct: number;
  },
  
  slurp_export?: {
    var_name: string;      // "TotalLoss_W1_PGA052"
    trials: number[];      // 10,000 Monte Carlo samples
    format: 'slurp'
  }
}