Docs/applications guide

docs/desktop-applications/lifesim/applications-guide/v1.0/00-document-info.mdx

@@ -1,16 +1,16 @@
 ---
 title: Document Info
-reportDate: March 2026
+reportDate: April 2026
 reportType: Computer Program Document
 reportTitle: LifeSim
 reportSubTitle: Applications Guide
 reportAuthors: ['Susie Byrd, Risk Management Center']
 reportAbstract:
 reportAcknowledgments: A special thank you to Jordan McMaster, Kurt Buchanan, Woodrow Fields, and Karen Mai for their contributions and support to make the LifeSim Applications Guide a reality.
 reportSubjectTerms:
-responsiblePersonName: xx
+responsiblePersonName: Susie Byrd
 responsiblePersonNumber: ###-###-####
-citationGuide: "S. E. Byrd and xx, <i>LifeSim Applications Guide</i>, Davis, CA: U.S. Army Corps of Engineers, Risk Management Center, 2026. Accessed on <i>{enter current date here}</i>."
+citationGuide: "S. E. Byrd et al., <i>LifeSim Applications Guide</i>, Davis, CA: U.S. Army Corps of Engineers, Risk Management Center, 2026. Accessed on <i>{enter current date here}</i>."
 ---
 
 import Link from "@docusaurus/Link";

docs/desktop-applications/lifesim/applications-guide/v1.0/00-version-history.mdx

@@ -16,9 +16,9 @@ import TableVersionHistory from "@site/src/components/TableVersionHistory";
 
 <TableVersionHistory
   versions={['1.0']}
-  dates={['March 2026']}
-  descriptions={["Initial release of LifeSim Applications Guide"]}
+  dates={['April 2026']}
+  descriptions={["Official release of LifeSim Applications Guide"]}
   modifiedBy={['Susie Byrd']}
-  reviewedBy={['xx']}
-  approvedBy={['xx']}
+  reviewedBy={['Sarah Mattingly; Ariel Feldman']}
+  approvedBy={['Woodrow Fields']}
 />

docs/desktop-applications/lifesim/applications-guide/v1.0/01-preface.mdx

@@ -6,7 +6,13 @@ import Link from "@docusaurus/Link";
 import addBaseUrl from "@docusaurus/useBaseUrl";
 import Citation from "@site/src/components/Citation";
 import CitationFootnote from "@site/src/components/CitationFootnote";
+import Figure from "@site/src/components/Figure";
+import FigureInline from "@site/src/components/FigureInline";
+import FigReference from "@site/src/components/FigureReference";
 import NavContainer from "@site/src/components/NavContainer";
+import ProcessList from "@site/src/components/ProcessList";
+import TableReference from "@site/src/components/TableReference";
+import TableVertical from "@site/src/components/TableVertical";
 import VersionSelector from "@site/src/components/VersionSelector";
 
 <NavContainer 
@@ -17,9 +23,9 @@ import VersionSelector from "@site/src/components/VersionSelector";
 
 # Preface
 
-LifeSim is the life loss and direct damage estimation software used by the U.S. Army Corps of Engineers. LifeSim is designed to simulate the entire
-warning and evacuation process for estimating potential life loss and direct economic damages resulting from floods. The following is a description of
- the major capabilities of LifeSim:
+<a href="https://www.rmc.usace.army.mil/Software/LifeSim/" target="_blank" rel="noopener noreferrer">LifeSim</a> is the life loss and direct damage estimation 
+software used by the U.S. Army Corps of Engineers. LifeSim is designed to simulate the entire warning and evacuation process for estimating potential life loss
+and direct economic damages resulting from floods. The following is a description of the major capabilities of LifeSim:
 
 - Graphical User Interface
 - Agent Based Modeling
@@ -30,20 +36,21 @@ The user interacts with LifeSim through a graphical user interface (GUI). The in
 maintaining a high level of efficiency for the user.
 
 LifeSim uses an agent-based approach to track individuals throughout the warning and evacuation process. During an evacuation, agents are interacting
-with the roads, other vehicles, and the incoming hazard. After the warning and evacuation process has been simulated, LifeSim calculates lethality for
- those people who are exposed to the hazard and the associated direct damages. By tracking individual people and their movements, LifeSim can help
+with the roads, other vehicles, and the incoming hazard (e.g., floodwaters). After the warning and evacuation process has been simulated, LifeSim calculates 
+lethality for those people who are exposed to the hazard and the associated direct damages. By tracking individual people and their movements, LifeSim can help
 identify where people are most at risk of losing their lives, whether it is on roads or in structures.
 
 Three modes of evacuation are included in LifeSim: cars, sports utility vehicles (SUVs), and pedestrians. For vehicular evacuation, a dual regime
 modified Greenshields model (USDOT) in conjunction with spillback enforcement is used for traffic propagation to represent the effects of traffic
 density and road capacity on vehicle speed. Each road is assigned default values for the number of lanes, free flow speed, traffic jam densities, and
-minimum stop-and-go speeds based on the Highway Capacity Manual (HCM) (TRB 2000).
+minimum stop-and-go speeds based on the Highway Capacity Manual (HCM) <Citation citationKey="HCM2000"/>.
 
 To define the routes people use to evacuate, a road network is provided where each segment of the network contains information such as road category,
 directionality, ground offset (for bridges), and interconnectivity. The road network can be imported from an existing GIS polyline shapefile or from
-OpenStreetMap. OpenStreetMap is a collaborative project to create a free editable map of the world. During each timestep at the user defined interval
-Δt, evacuating groups (PAR evacuating from a structure in a single vehicle) move as far as the model allows until the group reaches a destination
-point, gets caught, or becomes stranded. More information on the evacuation simulation can be found in the  (RMC 2021).
+OpenStreetMap <Citation citationKey="OSM"/>. OpenStreetMap is a collaborative project to create a free editable map of the world. During each timestep at the user 
+defined interval Δt, evacuating groups (PAR evacuating from a structure in a single vehicle) move as far as the model allows until the group reaches a destination
+point, gets caught, or becomes stranded. More information on the evacuation simulation can be found in the LifeSim 2.0 Technical Reference Manual 
+<Citation citationKey="LifeSimTech2021"/>.
 
 LifeSim applies both natural variability and knowledge uncertainty through Monte Carlo analysis. Multiple parameters can be entered with uncertainty
 including those that influence the warning and evacuation timeline. Each iteration in a simulation represents a scenario that could occur given the

docs/desktop-applications/lifesim/applications-guide/v1.0/02-introduction.mdx

@@ -23,42 +23,49 @@ import VersionSelector from "@site/src/components/VersionSelector";
 
 # Introduction
 
-Welcome to the U.S. Army Corps of Engineers LifeSim Applications Guide. LifeSim uses an agent-based methodology for estimating life loss with the
-fundamental intent to simulate population redistribution during an evacuation. Direct life loss, direct economic damages, and direct agriculture
-damages are then determined by the hazard (e.g., flooding). Direct consequences, the primary focus of LifeSim, are those incurred when people,
+Welcome to the LifeSim Applications Guide developed by the Risk Management Center, U.S. Army Corps of Engineers. LifeSim uses an agent-based methodology 
+for estimating life loss with the fundamental intent to simulate population redistribution during an evacuation. Direct life loss, direct economic damages, 
+and direct agriculture damages are then determined by the hazard (e.g., flooding). Direct consequences, the primary focus of LifeSim, are those incurred when people,
 structures, or agricultural resources interact with the hazard.
 
-LifeSim is designed to simulate the entire warning and evacuation process for estimating potential life loss and direct economic damages resulting from
- catastrophic floods (e.g., riverine flooding, coastal flooding, dam breach, and levee breach). LifeSim applies both natural variability and knowledge
- uncertainty (i.e., naturally occurring change in models’ parameters and outputs and gaps in what can be known by the modelers at the time) through
-Monte Carlo simulation. Many parameters can be entered with uncertainty including those that influence the warning and evacuation timeline (see the ,
-Warning and Evacuation Timeline Section for a more detailed overview). LifeSim is a multifaceted consequence estimation tool that can be utilized for various
- types of studies and analyses, including dam safety, levee safety, coastal storm risk management, flood risk management, risk communication, and
-more.
+LifeSim is designed to simulate the entire warning and evacuation process (see <FigReference figKey="figure-0"/>) for estimating potential life loss and direct economic damages resulting from
+catastrophic floods (e.g., riverine flooding, coastal flooding, dam failures, and levee failures). LifeSim applies both natural variability and knowledge
+uncertainty (i.e., naturally occurring change in models’ parameters and outputs and gaps in what can be known by the modelers at the time) through
+Monte Carlo simulation. Many parameters can be entered with uncertainty including those that influence the warning and evacuation timeline (see the LifeSim 2.0
+Technical Reference Manual <Citation citationKey="LifeSimTech2021"/> Warning and Evacuation Timeline Section for a more detailed overview). LifeSim is 
+a multifaceted consequence estimation tool that can be utilized for various types of studies and analyses, including dam safety, levee safety, coastal 
+storm risk management, flood risk management, risk communication, and more.
+
+<Figure
+  figKey="figure-0"
+  src="figures/desktop-applications/lifesim/applications-guide/v1.0/figures/figure0.png"
+  alt="Warning and evacuation timeline in LifeSim"
+  caption="Warning and evacuation timeline in LifeSim"
+/>
 
 ## Overview of this Guide
 
-The LifeSim Applications Guide contains written descriptions of seven examples that demonstrate the main features of the LifeSim software. The
-discussions in this manual contain detailed descriptions for the data inputs and analysis of the output for each example. The examples show and
-describe various input and output screens used to enter the data and view the output. The examples are intended as a guide for performing similar
-analyses in LifeSim. The manual is organized as follows:
+The LifeSim Applications Guide contains written descriptions of eight examples that highlight the main ways to utilize the LifeSim software, which is 
+focused on estimating direct life loss and direct economic damages to structures, contents, and vehicles. The examples in this manual contain detailed descriptions 
+for the data inputs and analysis of the output for each example. Each example describes various inputs, different features of LifeSim, and how best to view and analyze
+your results. The examples are intended as a guide for performing similar analyses in LifeSim. The manual is organized as follows:
 
 <ProcessList
   items={[
     { // STEP 1
       title: (
         <>
-          <strong>Summary of LifeSim Inputs</strong>, details the required inputs for all LifeSim studies. This section also defines and explains the inputs.
-          Finally, some recommended data pre-processing is discussed. Reference back to this section for additional information on Hydraulic Data, emergency
-          planning zones, Structure Inventories, Alternatives, and Simulations.
+          <strong>Summary of LifeSim Inputs</strong>, defines and explains the required inputs for all LifeSim studies. Finally, some recommended 
+          data pre-processing is discussed. Reference back to this section for additional information on Hydraulic Data, Emergency Planning Zones (EPZ), 
+          Structure Inventories, Alternatives, and Simulations.
         </>
       ),
     },
     { // STEP 2
       title: (
         <>
-          <strong>Estimating Consequence for Levees and Floodwalls</strong>,<strong> </strong>demonstrates the data required to estimate consequences
-          (life loss and direct economic damages) for a levee or floodwall breach. The example details required inputs, ways to acquire emergency preparedness
+          <strong>Estimating Consequence for Levees and Floodwalls</strong>, demonstrates the data required to estimate consequences
+          (life loss and direct economic damages) for a levee or floodwall failure. The example describes the required inputs, ways to acquire emergency preparedness
           information for populations at risk (PAR) and emergency management agencies (EMAs), how to simulate evacuation, and how to analyze your modeling
           results.
         </>
@@ -67,17 +74,17 @@ analyses in LifeSim. The manual is organized as follows:
     { // STEP 3
       title: (
         <>
-          <strong>Estimating Consequences for Dams</strong>, demonstrates the data required to estimate consequences for a dam breach model. The
+          <strong>Estimating Consequences for Dams</strong>, demonstrates the data required to estimate consequences for a dam failure model. The
           example details potential Geospatial Information System (GIS) pre-processing needed for data inputs, editing your structure inventory for accuracy,
-          and inputting warning and evacuation data specific to dams.
+          and inputting warning and evacuation data specific to dams. It also demonstrates how to conduct a quality check review of your structure inventory.
         </>
     ),
     },
     { // STEP 4
       title: (
         <>
-          <strong>Estimating Consequences for Cascading Dam Breaches</strong>, demonstrates various ways to model cascading dam breaches. The example
-          highlights the modeling differences if there is a downstream dam that breaches due to an upstream dam breaching. This example primarily focuses on
+          <strong>Estimating Consequences for Cascading Dam Failures</strong>, demonstrates various ways to model cascading dam failures. The example
+          highlights the modeling differences if there is a downstream dam that fails due to an upstream dam failure. This example primarily focuses on
           differences in (1) selecting the hazard occurrence time (i.e., the date and time breach or overtopping occurs in the study area) and (2) the
           delineation and parameter selection of the emergency planning zones (i.e., zones in LifeSim that can uniquely sample uncertainty parameters).
         </>
@@ -86,27 +93,27 @@ analyses in LifeSim. The manual is organized as follows:
     { // STEP 5
       title: (
         <>
-          <strong>Estimating Consequences for Coastal Infrastructure</strong>,<strong> </strong>illustrates how LifeSim modeling differs for coastal
-          structures (e.g., floodwalls, seawalls, dunes, and levees) compared to riverine infrastructure (e.g., floodwalls and levees), including differences in
-          hydraulic data, warning times, and other consequence nuances specific to coastal infrastructure.
+          <strong>Estimating Consequences for Coastal Infrastructure</strong>, illustrates how LifeSim modeling differs for coastal
+          structures (e.g., floodwalls, seawalls, and dunes) compared to typical riverine infrastructure (e.g., dams, floodwalls, and levees), including differences in
+          hydraulic data, warning times, and other considerations specific to coastal infrastructure.
         </>
       ),
     },
     { // STEP 6
       title: (
         <>
           <strong>Estimating Life Loss in Flood Risk Management Planning</strong>, details how to compare life loss across an array of Planning
-          alternatives in LifeSim. This example shows how to use typical Planning hydraulic outputs (e.g., eight flow-frequency events typically used in
-          Hydrologic Engineering Center’s Flood Damage Reduction Analysis [ HEC-FDA]) in LifeSim to estimate expected annual life loss and how to utilize these
-          results in the Planning process.
+          alternatives in LifeSim. This example shows how to use the typical hydraulic outputs provided in a Planning study (e.g., eight flow-frequency events often 
+          used in Hydrologic Engineering Center’s Flood Damage Reduction Analysis [HEC-FDA] <Citation citationKey="FDA"/>) in LifeSim to estimate expected annual 
+          life loss and how to utilize these results in the Planning process.
         </>
       ),
     },
     { // STEP 7
       title: (
         <>
          <strong>Estimating Direct Economic Damages for Flood Risk Management Planning</strong>, focuses solely on generating accurate direct
-          economic damages with more uncertainty than the default parameters. The chapter details how to edit and create structure occupancy types, adjust
+          economic damages by updating various uncertainty parameters in LifeSim. The chapter details how to edit and create structure occupancy types, adjust
           stage-damage curve uncertainty, adjust foundation height uncertainty, and adjust structure value uncertainty.
         </>
       ),
@@ -116,7 +123,7 @@ analyses in LifeSim. The manual is organized as follows:
         <>
           <strong>Estimating Consequences Using Summary Grids</strong>,<strong> </strong>demonstrates how to estimate life loss and economic damages
           using summary grid output which differs from using Hierarchical Data Format (HDF) files from Hydrologic Engineering Center’s River Analysis System
-          (HEC-RAS). This example will be helpful for individuals attempting to estimate consequences for a smaller Planning study, a study that did not utilize
+          (HEC-RAS) <Citation citationKey="HECRAS2024"/>. This example will be helpful for individuals attempting to estimate consequences for a smaller Planning study, a study that did not utilize
           unsteady flow in HEC-RAS, or a study with limited output or information from the hydraulic model.
         </>
       ),