CAP is a program that can be used to develop stage-discharge relationships for culverts and to determine peak discharge through culverts from high-water marks.
This file describes a Windows version of CAP that has source code that can be compiled with a Visual Studio solution that is generated by CMake. The Windows version of CAP runs in a command window and does not have a graphical user interface (GUI).
CAP (version 2021) will be included as a pre-compiled solver beginning in version 4 of the International River Interface Cooperative (iRIC) numerical simulation platform available at https://i-ric.org/. The iRIC platform provides a front-end GUI to facilitate creating the inputs for CAP.
A. Documentation
B. Compiling the Windows standalone version of CAP
C. Running CAP
D. Test files
E. Suggested citation
F. Acknowledgements
G. Contacts
The following user guide is available in electronic format. A Portable Document Format (PDF) file is included in the doc subdirectory of the CAP program distribution.
Fulford, J.M., 1998, User's guide to the U.S. Geological Survey Culvert Analysis Program, Version 97-08: U.S. Geological Survey Water-Resources Investigations Report 98-4166, 70 p. (https://doi.org/10.3133/wri984166)
Notes about CAP version 2021 and a summary of errors resolved in this version (including notes on capabilities added in version 2021) are also included in the doc subdirectory of the CAP program distribution.
The following report provides details on the methods used in the CAP program.
Bodhaine, G.L., 1968, Measurement of peak discharges at culverts by indirect methods: U.S. Geological Survey Techniques of Water-Resources Investigations, book 3, chap. A3, 60 p., (https://pubs.usgs.gov/twri/twri3-a3/)
In general, to compile CAP, you will need:
- CMake (build process manager)
- a FORTRAN compiler,
- familiarity with the compiler and the Windows operating system.
CMake can be downloaded from https://www.cmake.org/. If you download the binary distribution installer, CMake is installed when you execute it.
The directory cap-2021.0.0 is created when the files are extracted; if this directory already exists, you may want to delete or rename it before extracting the files.
The following directory structure is created (the contents of each directory are shown to the right):
cap-develop
--data Sample input and output data files
--doc Documentation files
--solverdef PNG files used when compling for iRIC
--src Source code
CMake has many options other than Visual Studio, but here we assume that you are using some version of Visual Studio. On the first use of CMake, it may be necessary to close all Visual Studio instances.
Open CMake. Fill in the top two lines:
- Where is the source code: The top level directory (ie cap-2021.0.0).
- Where to build the binaries: A directory of your choosing.
Click Configure. From the pulldown menu of the cmake-gui popup, select the 64-bit version of Visual Studio installed on your computer. There typically is no need to change the default configuration.
Click Generate. You should now have a Visual Studio solution file (.sln) in the directory chosen for the binaries (second line of CMake screen). At any point, you can delete the contents of the directory and start over. You can make solutions for different versions of Visual Studio, or different options in other directories.
Open the Visual Studio solution in the build directory defined in CMake.
The default configuration is "Debug". If you want to create a standalone (executable, change the configuration to "Release".
Build ALL_BUILD.
CAP is compiled.
If CAP has been installed in a directory included in the users' PATH, the program can be executed from a command line as follows:
CAP.exe
The program will query for each of the needed inputs.
If CAP is not located in a directory in PATH, the executable may be copied to the current directory. In addition, it is usually most convenient to copy the input file(s) into the same directory as the CAP executable. That way, path names will not be required when specifying the input file name(s).
The tests are described in the table below, where 'test' is the test number and the 'usage' column indicates how a file is used, with 'i' for input and 'o' for output.
test description of test and files file name & usage
---- ----------------------------------------- -----------------
1 Mercer Creek culvert example
CAP input data mercer.dat i
Program output mercer.out o
2 Pigeon House Creek culvert example
CAP input data pigeon.dat i
Program output pigeon.out o
3 TWRI creek culvert example based on examples 3 and 5 in USGS Techniques
of Water-Resources Investigations (TWRI), book 3, chapter A3
CAP input data cultwri.dat i
Program output cultwri.out o
4 TWRI concrete pipe culvert example based on TWRI example 8; metric units
and *C records used for culvert computations
CAP input data twri8.dat i
Program output twri8.out o
5 Vertical elliptical culvert section example
CAP input data vellip.dat i
Program output vellip.out o
6 Vertical elliptical culvert section example using *CS records
CAP input data vellipcs.dat i
Program output vellipcs.out o
Fulford, J.M. and Koltun, G.F., 2022, Culvert Analysis Program - Version 2021, U.S. Geological Survey software release, https://doi.org/10.5066/P9DW3XXX
Mark Smith (U.S. Geological Survey Scientist Emeritus) spearheaded the effort to update CAP, including organizing and overseeing the effort to identify known errors/issues with the previous version of CAP and providing valuable input on and review of revisions. Scott Charlton (U.S. Geological Survey) and Keisuke Inoue (Mizuho Instrumentation and Research) contributed some code used in CAP, primarily to provide the interface between CAP and the iRIC numerical simulation platform.
Inquiries about this software distribution should be directed to:
e-mail: [email protected] or [email protected]