Skip to content

Commit 00ba013

Browse files
AdamGohsAdamGohs
authored
Merge pull request #119 from USACE-RMC/docs/minor/breach-v1.1
Breach Toolbox v1.1: correct EBL (2005) equation exponents
2 parents 41122ac + becdb9b commit 00ba013

44 files changed

Lines changed: 1639 additions & 3 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/toolbox-technical-manuals/internal-erosion-suite/breach/v1.1/00-document-info.mdx‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
title: Document Info
3+
reportDate: November 2023
4+
reportType: Computer Program Document
5+
reportTitle: RMC Breach Toolbox
6+
reportSubTitle: RMC Internal Erosion Suite
7+
reportAuthors: ['Damon Amlung, Risk Management Center']
8+
reportAbstract: The spreadsheet tools contained in this toolbox help assess the likelihood of breach due to gross enlargement of a concentrated leak pipe using the excess shear stress equation, unraveling of the downstream slope due to flows through the rockfill, and sinkhole development, in addition to providing general guidance for assessing slope instability.
9+
reportSubjectTerms: ['Internal erosion', 'breach', 'gross enlargement', 'unraveling', 'sinkhole development', 'slope instability']
10+
responsiblePersonName: Tim O'Leary
11+
responsiblePersonNumber: (502) 315-6599
12+
citationGuide: 'D. Amlung, <i>RMC Breach Toolbox Technical Manual</i>, Lakewood, CO: U.S. Army Corps of Engineers, Risk Management Center, 2023. Accessed on <i>{enter current date here}</i>.'
13+
---
14+
15+
import Link from '@docusaurus/Link';
16+
import addBaseUrl from '@docusaurus/useBaseUrl';
17+
import DocumentMetadata from '@site/src/components/DocumentMetadata';
18+
import NavContainer from '@site/src/components/NavContainer';
19+
20+
<NavContainer
21+
link="/toolboxes/internal-erosion-suite"
22+
linkTitle="Internal Erosion Suite"
23+
document="toolbox-technical-manuals/internal-erosion-suite/breach"
24+
/>
25+
26+
# Document Information
27+
28+
<DocumentMetadata metadata={frontMatter} />

‎docs/toolbox-technical-manuals/internal-erosion-suite/breach/v1.1/00-version-history.mdx‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
title: Version History
3+
---
4+
5+
import Link from '@docusaurus/Link';
6+
import NavContainer from '@site/src/components/NavContainer';
7+
import TableVersionHistory from '@site/src/components/TableVersionHistory';
8+
9+
<NavContainer
10+
link="/toolboxes/internal-erosion-suite"
11+
linkTitle="Internal Erosion Suite"
12+
document="toolbox-technical-manuals/internal-erosion-suite/breach"
13+
/>
14+
15+
# Version History
16+
17+
<TableVersionHistory
18+
versions={['1.1', '1.0']}
19+
dates={['May 2026', 'March 2026']}
20+
descriptions={[
21+
'Updated the EBL (2005) method equation to correct the exponents for downstream slope and unit discharge for the calculation of the median rock size needed for stability in the Unraveling chapter.',
22+
'Initial release as an online document. Source is RMC-CPD-2023-09.',
23+
]}
24+
modifiedBy={['Adam Gohs', '-']}
25+
reviewedBy={['Casey Cummins', "Tim O'Leary"]}
26+
approvedBy={['-', 'Nate Snorteland']}
27+
/>

‎docs/toolbox-technical-manuals/internal-erosion-suite/breach/v1.1/01-preface.mdx‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
title: 'Preface'
3+
---
4+
5+
import Link from '@docusaurus/Link';
6+
import addBaseUrl from '@docusaurus/useBaseUrl';
7+
import CitationFootnote from '@site/src/components/CitationFootnote';
8+
import NavContainer from '@site/src/components/NavContainer';
9+
import VersionSelector from '@site/src/components/VersionSelector';
10+
11+
<NavContainer
12+
link="/toolboxes/internal-erosion-suite"
13+
linkTitle="Internal Erosion Suite"
14+
document="toolbox-technical-manuals/internal-erosion-suite/breach"
15+
/>
16+
17+
# Preface
18+
19+
The Risk Management Center (RMC) of the U.S. Army Corps of Engineers (USACE) has developed a suite of Microsoft Excel spreadsheets to support risk
20+
assessments for dam and levee safety. Each analysis suite is composed of multiple toolboxes (Microsoft Excel workbooks), and each toolbox contains
21+
multiple spreadsheet tools or calculation worksheets (Microsoft Excel worksheets). The RMC Breach Toolbox is part of the RMC Internal Erosion Suite.
22+
23+
The information from these spreadsheet tools, along with other pertinent information, informs judgment when developing a list of more and less likely
24+
factors and estimating probabilities. USACE best practice for estimating probabilities is to use the best available and multiple methods, but all
25+
final probabilities are estimated using team elicitation based on the totality and strength of the evidence.
26+
27+
The RMC continuously works to improve the performance of RMC software; report possible bugs directly to the RMC at the address listed below. Ideally,
28+
report suspected errors in written form with a description of the problem and the steps that lead to its occurrence. Suggestions for improvement are
29+
also welcomed.
30+
31+
U.S. Army Corps of Engineers
32+
Institute for Water Resources
33+
Risk Management Center
34+
[RMC.software@usace.army.mil](mailto:RMC.software@usace.army.mil)
35+
36+
<CitationFootnote />

‎docs/toolbox-technical-manuals/internal-erosion-suite/breach/v1.1/02-terms-and-conditions-for-use.mdx‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
title: 'Terms and Conditions for Use'
3+
---
4+
5+
import Link from '@docusaurus/Link';
6+
import addBaseUrl from '@docusaurus/useBaseUrl';
7+
import CitationFootnote from '@site/src/components/CitationFootnote';
8+
import NavContainer from '@site/src/components/NavContainer';
9+
import VersionSelector from '@site/src/components/VersionSelector';
10+
11+
<NavContainer
12+
link="/toolboxes/internal-erosion-suite"
13+
linkTitle="Internal Erosion Suite"
14+
document="toolbox-technical-manuals/internal-erosion-suite/breach"
15+
/>
16+
17+
# Terms and Conditions for Use
18+
19+
By using Institute for Water Resources (IWR) software, users voluntarily accept the following terms and conditions. Users that do not agree to these
20+
terms and conditions should uninstall the IWR software and return any program materials to IWR and its technical centers. If users downloaded the
21+
software and do not have disk media, delete all copies and cease using the software.
22+
23+
## Terms and Conditions for Use of Institute for Water Resources Software
24+
25+
The United States Government, U.S. Army Corps of Engineers, Institute for Water Resources (“IWR”), and IWR’s technical centers including the Risk
26+
Management Center (“RMC”) and Hydrologic Engineering Center (“HEC”) grant to the user the rights to install “IWR Software” (either from a disk copy
27+
obtained from IWR and IWR’s technical centers, a distributor or another user or by downloading it from a network) and to use, copy and/or distribute
28+
copies of the IWR Software to other users, subject to the following Terms and Conditions of Use:
29+
30+
- All copies of the IWR Software received or reproduced by or for user pursuant to the authority of this Terms and Conditions of Use will be and
31+
remain the property of IWR.
32+
33+
- User may reproduce and distribute the IWR Software provided that the recipient agrees to the Terms and Conditions for Use noted herein.
34+
35+
- IWR and IWR’s technical centers are solely responsible for the content of the IWR Software. The IWR Software may not be modified, abridged,
36+
decompiled, disassembled, unobfuscated or reverse engineered. The user is solely responsible for the content, interactions, and effects of any and all
37+
amendments, if present, whether they be extension modules, language resource bundles, scripts, or any other amendment.
38+
39+
- The name of the IWR Software must not be used to endorse or promote products derived from the IWR Software. Products derived from the IWR Software
40+
may not be called the IWR Software nor may any part of the IWR Software name appear within the name of derived products.
41+
42+
- No part of this Terms and Conditions for Use may be modified, deleted or obliterated from the IWR Software.
43+
44+
- No part of the IWR Software may be exported or re-exported in contravention of U.S. export laws or regulations.
45+
46+
## Waiver of Warranty
47+
48+
THE UNITED STATES GOVERNMENT AND ITS AGENCIES, OFFICIALS, REPRESENTATIVES, AND EMPLOYEES, INCLUDING ITS CONTRACTORS AND SUPPLIERS PROVIDE THE IWR
49+
SOFTWARE “AS IS,” WITHOUT ANY WARRANTY OR CONDITION, EXPRESS, IMPLIED OR STATUTORY, AND SPECIFICALLY DISCLAIM ANY IMPLIED WARRANTIES OF TITLE,
50+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. Depending on state law, the foregoing disclaimer may not apply to you, and you
51+
may also have other legal rights that vary from state to state.
52+
53+
## Limitation of Liability
54+
55+
IN NO EVENT SHALL THE UNITED STATES GOVERNMENT AND ITS AGENCIES, OFFICIALS, REPRESENTATIVES, AND EMPLOYEES, INCLUDING ITS CONTRACTORS AND SUPPLIERS,
56+
BE LIABLE FOR LOST PROFITS OR ANY SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF OR IN CONNECTION WITH USE OF THE IWR SOFTWARE REGARDLESS
57+
OF CAUSE, INCLUDING NEGLIGENCE. THE UNITED STATES GOVERNMENT’S LIABILITY, AND THE LIABILITY OF ITS AGENCIES, OFFICIALS, REPRESENTATIVES, AND
58+
EMPLOYEES, INCLUDING ITS CONTRACTORS AND SUPPLIERS, TO YOU OR ANY THIRD PARTIES IN ANY CIRCUMSTANCE IS LIMITED TO THE REPLACEMENT OF CERTIFIED COPIES
59+
OF THE IWR SOFTWARE WITH IDENTIFIED ERRORS CORRECTED. Depending on state law, the above limitation or exclusion may not apply to you.
60+
61+
## Indemnity
62+
63+
As a voluntary user of the IWR Software you agree to indemnify and hold the United States Government, and its agencies, officials, representatives,
64+
and employees, including its contractors and suppliers, harmless from any claim or demand, including reasonable attorneys’ fees, made by any third
65+
party due to or arising out of your use of the IWR Software or breach of this Agreement or your violation of any law or the rights of a third party.
66+
67+
<CitationFootnote />

‎docs/toolbox-technical-manuals/internal-erosion-suite/breach/v1.1/03-general-overview.mdx‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
---
2+
title: 'General Overview'
3+
---
4+
5+
import Link from '@docusaurus/Link';
6+
import addBaseUrl from '@docusaurus/useBaseUrl';
7+
import CitationFootnote from '@site/src/components/CitationFootnote';
8+
import Figure from '@site/src/components/Figure';
9+
import FigureInline from '@site/src/components/FigureInline';
10+
import FigReference from '@site/src/components/FigureReference';
11+
import NavContainer from '@site/src/components/NavContainer';
12+
import VersionSelector from '@site/src/components/VersionSelector';
13+
14+
<NavContainer
15+
link="/toolboxes/internal-erosion-suite"
16+
linkTitle="Internal Erosion Suite"
17+
document="toolbox-technical-manuals/internal-erosion-suite/breach"
18+
/>
19+
20+
# General Overview
21+
22+
## Getting Started
23+
24+
Copy or download the toolbox file to the computer. To open the toolbox file, either:
25+
26+
- Find the file on the computer and double-click it. This opens the file in Microsoft Excel.
27+
28+
- Open Microsoft Excel and use the application to open the file: Once Microsoft Excel is open, go to the File menu at the top of the window and select
29+
Open.
30+
31+
The toolbox is an Excel binary workbook (.xlsb) that uses macros. You may need to enable the macros, either before opening the file or by clicking
32+
“Enable Content” in the yellow Security Warning message bar with a shield icon that appears after the file is opened. The actual message in the
33+
message bar will vary depending on the computer’s settings and installed add-ins. <FigReference figKey="figure-1" /> displays examples of different
34+
wordings that may appear in the message bar.
35+
36+
<Figure
37+
figKey="figure-1"
38+
src="figures\toolbox-technical-manuals\internal-erosion-suite\breach\v1.1\figures\figure1.png"
39+
alt="Security warning message bars with the “Enable Content” option to enable macros."
40+
caption="Security warning message bars with the “Enable Content” option to enable macros."
41+
background="transparent"
42+
/>
43+
44+
## Organization
45+
46+
Although the toolbox does not provide a calculation cover sheet, adding one is strongly recommended. A calculation cover sheet captures project
47+
information, a description and purpose of the calculation, the assumptions for critical input parameters, a summary of the major conclusion and
48+
results, and a revision history.
49+
50+
Each toolbox has a similar appearance and organizational structure:
51+
52+
- The first worksheet, About, summarizes the purpose of the toolbox and gives contact information for the RMC software development team.
53+
54+
- The second worksheet, Terms and Conditions, contains the terms and conditions for use of the toolbox (IWR software).
55+
56+
- The third worksheet, Version History, contains the revision history. Semantic versioning is used in the format of MAJOR.MINOR.PATCH:
57+
- MAJOR – significant worksheet changes not compatible with previous versions.
58+
59+
- MINOR – additional features or enhancements that do not fundamentally change the calculations.
60+
61+
- PATCH – backward-compatible bug fixes.
62+
63+
- The fourth worksheet, References, lists the references cited for each calculation worksheet.
64+
65+
The workbook and worksheets are not protected to prevent unwanted changes. However, because the toolbox has user-defined functions (UDFs) and
66+
subroutines in Visual Basic, you cannot directly copy worksheets to another workbook without potentially losing functionality. A note in a bold red
67+
font at the upper right margin indicates if the selected worksheet includes such features.
68+
69+
At the top of each calculation worksheet, input information for the preparer and checker for quality control (QC) documentation and the calculation
70+
title in case multiple copies of the worksheet are created for different analysis scenarios (<FigReference figKey="figure-2" />). The footer of each
71+
calculation worksheet contains the version number, which can be cross-referenced with the revision history on the third worksheet.
72+
73+
<Figure
74+
figKey="figure-2"
75+
src="figures\toolbox-technical-manuals\internal-erosion-suite\breach\v1.1\figures\figure2.png"
76+
alt="Calculation worksheet heading."
77+
caption="Calculation worksheet heading."
78+
/>
79+
80+
User-specified input includes values and selections from drop-down lists. User input cells are light yellow, and these cells are unprotected. When
81+
cells use drop-down lists, a note in blue font in the right margin of the row alerts the user to use the drop-down list. Conditional formatting
82+
applies a gray background to cells that are not based on a user selection. When a user-specified value or calculated value is outside of acceptable
83+
ranges, the cell is orange to indicate caution to the user.
84+
85+
All units for user-specified input values are clearly labeled. Most user-specified input values use English units. However, values may be in metric
86+
where metric units are more common in practice (e.g., particle size in millimeters or permeability in centimeters per second). The toolbox may convert
87+
English units to metric units to perform some calculations or if required for a specific formula based on the reference material for the equation.
88+
89+
If the calculation worksheet is a function of headwater level, up to seven headwater and tailwater levels may be specified at the top of the
90+
worksheet. Tailwater may be required to calculate the net hydraulic head and hydraulic gradient. Specify the elevation datum by selecting one of three
91+
options from the drop-down list: ft-NAVD88, ft-NGVD29, and Other. The two datum selections include English units of length (feet). If Other is
92+
selected, provide a user-specified datum along with feet (e.g., ft-MSL [Mean Sea Level]). <FigReference figKey="figure-3" /> through
93+
{"\n"}<FigReference figKey="figure-5" /> illustrate the three possible scenarios.
94+
95+
<Figure
96+
figKey="figure-3"
97+
src="figures\toolbox-technical-manuals\internal-erosion-suite\breach\v1.1\figures\figure3.png"
98+
alt="Headwater and tailwater input: NAVD88."
99+
caption="Headwater and tailwater input: NAVD88."
100+
/>
101+
102+
<Figure
103+
figKey="figure-4"
104+
src="figures\toolbox-technical-manuals\internal-erosion-suite\breach\v1.1\figures\figure4.png"
105+
alt="Headwater and tailwater input: NGVD29."
106+
caption="Headwater and tailwater input: NGVD29."
107+
/>
108+
109+
<Figure
110+
figKey="figure-5"
111+
src="figures\toolbox-technical-manuals\internal-erosion-suite\breach\v1.1\figures\figure5.png"
112+
alt="Headwater and tailwater input: User-specified datum."
113+
caption="Headwater and tailwater input: User-specified datum."
114+
/>
115+
116+
Most calculation worksheets break down complex analysis into computational steps following a logical sequence (<FigReference figKey="figure-6" />).
117+
Some simpler worksheets do not have steps. Generally, different methodologies are unique worksheets. Some worksheets may include multiple
118+
methodologies, which are labeled as options (<FigReference figKey="figure-7" />).
119+
120+
<Figure
121+
figKey="figure-6"
122+
src="figures\toolbox-technical-manuals\internal-erosion-suite\breach\v1.1\figures\figure6.png"
123+
alt="Example of step banner."
124+
caption="Example of step banner."
125+
/>
126+
127+
<Figure
128+
figKey="figure-7"
129+
src="figures\toolbox-technical-manuals\internal-erosion-suite\breach\v1.1\figures\figure7.png"
130+
alt="Example of option banner."
131+
caption="Example of option banner."
132+
/>
133+
134+
Some calculation worksheets can perform either a deterministic or probabilistic analysis. Although not required to perform a probabilistic analysis,
135+
Palisade @RISK software (standalone version or as part of the Palisade DecisionTools Suite) can customize the probabilistic analysis. A note appears
136+
in a bold red font at the upper right-hand margin of a calculation worksheet indicating if this feature is included with the toolbox.
137+
138+
User notes generally appear in the right margin of each calculation worksheet. Some notes are in blue or red font for heightened awareness. These
139+
notes include references to source materials for equations, figures, tables, pages, etc. If the RMC modified the source material, the reference
140+
citation says “adapted from” instead of “from.”
141+
142+
Tabular and/or graphical summaries are generally the primary output of the toolbox. The UDFs in the PlotScale module change the minimum and maximum
143+
values of the x-axis and y-axis for charts. If the calculation worksheet is a function of headwater level, you can define up to five headwater levels
144+
of interest and plot them as vertical reference lines. By selecting the chart and then selecting the Filter icon to display the filter pane, you can
145+
choose which data series to display. This is useful when computing the results from multiple methodologies, but not all are applicable or desired to
146+
display.
147+
148+
<CitationFootnote />

0 commit comments

Comments
 (0)