tm14-a1_ReadMeScoops3D_1.3.01.txt U.S. Geological Survey Software Scoops3D and Scoops3D-i version 1.3.01 Software to Analyze Three-Dimensional Slope Stability Throughout a Digital Landscape Last updated: March 2023 Scoops3D analyzes 3D slope stability throughout a digital landscape. It determines the minimum factor of safety associated with potential 3D failure masses encompassing each cell in a digital elevation model (DEM). Scoops3D-i is a graphical user interface for creation and modification of complete and internally consistent Scoops3D main parameter input files. Scoops3D-i can also be used to implement tasks such as running or stopping Scoops3D. Details of version enhancements are contained in the file: Whatsnew_Scoops3D_v1.3, which is accessible from the help pulldown menu in Scoops3D-i and summarized below. ENHANCEMENTS FOR VERSION 1.3.01 Bug fix • Corrected error in calculations used to issue warnings for adequate DEM resolution. ENHANCEMENTS FOR VERSION 1.3 Version 1.3 contains several major changes which improve accuracy and efficiency. Our test runs show that version 1.3 computation times are 2.5 to 4 times faster than version 1.1.2. Note that model results using version 1.3 may differ slightly from earlier versions because of the changes listed below, such as the inclusion of single-node columns and a more accurate method for calculating volumes. Although the global critical surface may differ between versions the regional factor-of-safety maps should generally look the same, with factors of safety of critical surfaces within a few percent of results from prior versions. Individual DEM cells near the borders of critical surfaces may have larger differences in factor of safety as a result of small differences in the areal extent of associated critical surfaces. Version 1.3 has implemented several features that became available with Fortran 95 and Fortran 2003. Therefore, the user should be aware that self-compilation of the provided Fortran code requires use of a compiler that supports Fortran 2003. Changes to Input: • A user can now specify the input file name on the same line when calling the executable in a command window (using Get_Command_Argument available in Fortran 2003). For example, the user can type the following command on a single line: Scoops3D_1.3win64.exe InputFilename.scp • If a user chooses to analyze multiple slip directions for each trial surface (in addition to the ground-surface overall fall direction) the method has changed to an automated search for the sliding direction which identifies the lowest factor of safety for each trial surface. Earlier versions used the parameters deginc, degmax, and numdir, which were specified in the .scp input file with the following line pair: LINE ID: dr deginc degmax numdir or by setting the number of slip directions and maximum deviation angle in the Search Configuration box of Scoops3D-i. The parameters deginc, degmax, and numdir are no longer used directly. In the current version, a new input parameter (islipdirflag), added as a new line pair in the .scp input file, can be used to trigger the slip direction search. LINE ID: islipdirflag islipdirflag flag to enable multiple flip direction search (1 to enable or 0 to disable the search) If an input file contains the older parameters with deginc >= degmax > 0 (numdir is not required), then the automated search flag will be set to one. This feature enables backward compatibility with pre-exiting input files which specify a search of multiple slip directions. If valid older slip parameters are present the user will see the following screen message during run time to explain: 'Incremental slip direction search is specified using obsolete parameters: new automated slip direction search will be implemented'. For all cases, the initial slip direction is calculated by summing the volume-weighted components of land surface slope of each column included in the current failure mass, representing the overall fall direction. Note that this method of computing the overall fall direction using volume weighting is a slight change from the prior Scoops3D versions in which ground slope alone determined slide direction. Our empirical testing has shown that slip directions derived using volume weighting can produce slightly lower factors of safety. When islipdirflag is set to one, a search for the slip direction with the lowest factor of safety is implemented. This search first computes factors of safety for slip directions one degree on either side of the overall fall direction. If a new trial direction results in a lower factor of safety, additional directions will be calculated using a secant method until either the change in factor of safety falls below a preset tolerance, the change in slip angle is less than 0.001 degrees, or the number of angles tried is greater than 10. Note that the factor of safety calculated using the initial overall fall direction is typically very close (within a small fraction of a percent) to the minimum value obtained from other slip directions except in cases where the slip surface exhibits a significant amount of asymmetry of weight distribution or pore pressures. Sampling additional slip directions can require significantly more computational effort. We suggest initial testing with and without implementation of the multiple slip direction search to determine if this option produces different results. • fostol is a now an optional parameter and set to a default of 0.001 percent difference in factor of safety. Computational Enhancements: • Factor-of-safety calculations now include single-node partial columns on the boundary of a potential failure mass, enabling more accurate results using coarser DEM resolutions and thereby potentially reducing computer memory requirements. Prior versions included partial columns with two and three nodes, but not one node. • Volumes of full columns are calculated using the prismoidal formula with three parallel planes as before. However, the area of the central parallel plane is now calculated using the elevation of the sphere at the center of the column to better approximate the volume of a column truncated by a sphere. Prior versions of Scoops3D used only the sphere elevations at each column corner which slightly underestimates volume and tends to result in a slightly higher factor of safety. The new method provides a better volume approximation and retains computational efficiency. • Calculation of the location of the midpoint of partial columns projected on the x-y plane has been revised to use the centroid formula for the polynomial representing the projected area. This method provides a more accurate estimate of slip surface elevation and slope at the column center and associated moment arms. • Slip surfaces with land elevations above the rotational center are now allowed if these columns do not intersect the boundary of the slip surface to form a partial column. This approach avoids situations where a spherical surface wraps around on top of itself at the edge of the slide, which is not physically feasible. • Subsets are now identified using a flood-fill routine to reduce computation time. • Several large arrays used to process three-dimensional subsurface data have been eliminated, reducing memory requirements for this category of problems. • Many other enhancements have been completed to reduce memory usage and improve computational efficiency. Changes in Output: • Elapsed run time is written at the end of the main output file, calculated by calling the Fortran 95 intrinsic function cpu_time at the start and end of each run. Bug fixes: • Corrected bug where piezometric surface was not identified and moisture level parameter was not set prior to processing unit weight data when using the combination of 3D pore-pressure or pressure-head files with layer files. • Revised input check to issue warning instead of terminating program when minimum volume or area of primary size constraint is likely to not include enough columns to provide an accurate factor-of-safety result. • Corrected and optimized array handling, character strings, and other variables and eliminated obsolete Fortran syntax. ENHANCEMENTS FOR VERSION 1.1.2 Minor changes to formatting of output were implemented. Additional warning messages are provided for potential failure size criteria that are smaller than recommended. Improvements to error traps in the case of memory allocation errors when insufficient computer memory is available. This version also contains important bug fixes. ENHANCEMENTS FOR VERSION 1.1.1 Improved handling of error/warning messages related to memory allocation and subsets. Allows 25 subsets within a defined sphere before issuing a warning (Scoops3D 1.0 and 1.1 allowed 10 subsets). ENHANCEMENTS FOR VERSION 1.1 Added option to specify 3D groundwater conditions in units of pore pressure. More information on the theoretical basis of the program, program operation, practical considerations, and testing of Scoop3D can be found in the Scoops3D manual: Reid, M.E., Christian, S.B., Brien, D.L., and Henderson, S.T., 2015, Scoops3D--Software to analyze three-dimensional slope stability throughout a digital landscape: U.S. Geological Survey Techniques and Methods, book 14, chapter A1 [http://pubs.usgs.gov/tm/14/a01]. Scoops3D and Scoops3D-i support is provided for correcting bugs. Only limited assistance can be provided for applying Scoops3D to specific problems by contacting scoops3D@usgs.gov. Although this software program has been used by the U.S. Geological Survey (USGS), no warranty, expressed or implied, is made by the authors, the USGS or the U.S. Government as to the accuracy and functioning of the program and related program material nor shall the fact of distribution constitute any such warranty, and no responsibility is assumed by the USGS in connection therewith. The software is provided on an "as is" basis. The user assumes all risk for any damages arising in connection with the access, use, quality, or performance of this software and related materials. Any use of trade, firm, or product names is for descriptive purposes only and does not imply endorsement by the U.S. Government. TABLE OF CONTENTS A. CONTENTS OF DOWNLOADS DIRECTORY B. INSTALLATION b1. WINDOWS INSTALLATION b2. MACINTOSH INSTALLATION b3. LINUX C. UNINSTALLATION c1. WINDOWS INSTALLATION c2. MACINTOSH INSTALLATION D. EXAMPLES E. CODE COMPILATION F. VERSION HISTORY G. ADDITIONAL REFERENCES A. CONTENTS OF DOWNLOADS DIRECTORY tm14-a1_ReadMeScoops3D_1.x.txt - explanatory file, describing contents of downloads directory, installation and uninstallation instructions, and additional information regarding Scoops3D and Scoops3D-i. tm14-a1_Scoops3Dexamples_1.0.zip - compressed file containing Scoops3D examples described in Chapter 7 of the Scoops3D manual (Reid and others, 2014). tm14-a1_Scoops3D_1.1mac.dmg - disk image for Mac OSX. Includes Scoops3D, Scoops3D-i, and Scoops3D manual (Reid and others, 2014). tm14-a1_Scoops3D_1.3win_installer.exe - Scoops3D and Scoops3D-i installation package for Windows. Includes Scoops3D, Scoops3D-i, and Scoops3D manual (Reid and others, 2014). B. INSTALLATION System-specific files are available for Microsoft Windows, Apple Macintosh, and Linux operating systems. The installation packages for Windows and Macintosh operating systems include executable versions of Scoops3D, Scoops3D-i, Scoops3D manual, and associated icons. Files containing examples of Scoops3D input and output are provided separately and can be downloaded to the user's directory of choice. Installation of Scoops3D and Scoops3D-i on a Windows or Macintosh computer will require administrative user privileges. Note that the software is not copyrighted and the license agreement is for informational purposes only. b1. WINDOWS INSTALLATION To install Scoops3D and Scoops3D-i on a Windows operating system, the user should download the installer file and launch the installer. The user may receive a User Control Account screen with the message "Do you want to allow the following program from an unknown publisher to make changes to this computer?" To continue the installation, answer yes and proceed through the subsequent screens (clicking Next). The installer will ask for a directory destination for the programs and a name for the start menu folder. The user can accept the defaults or modify these locations. The user should proceed through all the additional installer screens, selecting any desired options (such as adding a desktop icon for Scoops3D-i), until the installation is complete. The installer can subsequently launch Scoops3D-i if that option is chosen. The Windows installation package has been tested on Windows 7, Windows 8.1, and Windows 10. The Windows installer will automatically query the user's operating system and install either a 32-bit or 64-bit version of Scoops3D compiled code. The user interface (Scoops3D-i) is a 32-bit application. b2. MACINTOSH INSTALLATION We currently do not provide a mac OS installer for Scoops3D verion 1.3. The fortran source code for Scoops3D is available for download at http://landslides.usgs.gov/research/software.php and should successfully compile on Mac OS with a Modern Fortran compiler. To install Scoops3D version 1.1 and Scoops3D-i on a Macintosh operating system, the user should download the .dmg file, double click on the .dmg, and drag the Scoops3D-i icon to the Applications folder. This will require administrative privileges. The Macintosh installation package has been tested on Mac OS 10.6, 10.7, 10.9, 10.10, 10.11, 10.12, 10.13, and 10.14. Mac OS 10.8 and above include features to prevent installation of software that is not downloaded from the Mac App store. During the first launch of the newly installed Scoops3D-i, you may receive the error "Scoops3Di_1.1 can't be opened because it is from an unidentified developer." To override this error, open "System Preferences / Security and Privacy" and click "Open Anyway" under the section titled "Allow apps downloaded from:" for the Scoops3D-i app. This will require administrative privileges. The installation package may not work with Mac OS 11.x or 12.x. b3. LINUX Linux compatible Modern Fortran source code is available for download at http://landslides.usgs.gov/research/software.php. We currently do not provide a make file or compiled code for Linux. The code should successfully compile with any linux Modern Fortran compiler. Version 1.3 has implemented several features that became available with Fortran 95 and Fortran 2003. Therefore, the user should be aware that self-compilation of the provided Fortran code requires use of a compiler that supports Fortran 2003, such as the freely available Intel® Fortran Compiler. C. UNINSTALLATION c1. UNINSTALL ON WINDOWS Scoops3D and Scoops3D-i programs can be uninstalled with the Windows feature to uninstall a program. If the user would also like to delete the Scoops3D project folder, the folder '~\My Documents\Scoops3D' (Windows XP and Windows 7) or '~\Documents\Scoops3D' (Windows 8) can be dragged to the Recycle Bin. c2. UNINSTALL ON MACINTOSH Scoops3D and Scoops3D-i programs can be uninstalled by opening the applications folder and dragging the Scoops3D folder to the Trash. If the user would also like to delete the Scoops3D project folder, the folder '~/Documents/Scoops3D' can also be dragged to the Trash. D. EXAMPLES The examples contained in 'Scoops3Dexamples_1.3.zip' are described in Chapter 7 of the Scoops3D manual (Reid and others, 2014). These examples illustrate many of the capabilities of Scoops3D and demonstrate the proper formats for main parameter input files, ASCII raster grid files, and 3D input files. Files in the examples can: -Aid the user in learning to run Scoops3D and examine output files. -Serve as templates to help the user construct new files for scenarios similar to a particular example. -Allow the user to compare previous results with those generated using their current computer system. For each example, the main parameter input file (.scp file) is located in a subfolder within the examples folder. Within each of these subfolders, an input subfolder, titled 'input' contains all additional Scoops3D input files. In case the original files are modified, a second copy of the examples is located in the folder labeled 'examples/original_files'. This folder contains both input and output files. The output files can be used to familiarize the user with the content of Scoop3D output files and for verification of recompiled code. E. CODE COMPILATION The executable files provided in the Scoops3D installation packages were created using Intel® Fortran Compiler Classic 2021.4.0 for Windows with Level 2 optimization. Additional versions of the compiled Scoops3D software and source code are available for download at https://www.usgs.gov/software/scoops3d. Scoops3D is written in Modern Fortran programming language to provide computational efficiency, dynamic memory management, and cross-platform compatibility. The source code can be compiled to execute on the user's computer, provided the user has a Modern Fortran language compiler. Version 1.3 has implemented several features that became available with Fortran 95 and Fortran 2003. Therefore, the user should be aware that self-compilation of the provided Fortran code requires use of a compiler that supports Fortran 2003, such as the freely available Intel® Fortran Compiler. Thus, users may compile Scoops3D for execution on a wide variety of computer operating systems. We have successfully run versions of Scoops3D on a variety of Windows, Macintosh, Unix, and Linux operating systems. Scoops3D example files allow the user to compare previous results with those generated using their current computer system. We recommend use of these files for verification after recompilation of the source code. Scoops3D-i is compiled python code written in Python 2.7. F. VERSION HISTORY Scoops3D and Scoops3D-i Version 1.0 - original release March 2015. Scoops3D and Scoops3D-i Version 1.1 - released August 2016. Scoops3D and Scoops3D-i Version 1.1.1 - released September 2017. Scoops3D and Scoops3D-i Version 1.1.2 - released November 2021. Scoops3D and Scoops3D-i Version 1.3 - released September 2022. G. ADDITIONAL REFERENCES Reid, M.E., Christian, S.B., Brien, D.L., and Henderson, S.T., 2015, Scoops3D-- Software to analyze three-dimensional slope stability throughout a digital landscape: U.S. Geological Survey Techniques and Methods, book 14, chap. A1. http://pubs.usgs.gov/tm/14/a01 Reid, M.E., Brien, D.L., and Waythomas, C.F., 2010, Preliminary slope-stability analysis of Augustine Volcano, in Power, J.A., Coombs, M.L., and Freymueller, J.T., eds., The 2006 Eruption of Augustine Volcano, Alaska: U.S. Geological Survey Professional Paper 1769, p. 321-332. http://pubs.usgs.gov/pp/1769/ Reid, M.E., Keith, T.E.C., Kayen, R.E., Iverson, N.R., Iverson, R.M., and Brien, D.L., 2010, Volcano collapse promoted by progressive strength reduction: new data from Mount St. Helens: Bulletin of Volcanology, v. 72, p. 761-766. http://landslides.usgs.gov/docs/reid/Reid,etal_BV_2010.pdf Brien, D.L., and Reid, M.E., 2008, Assessing deep-seated landslide susceptibility using 3-D groundwater and slope-stability analyses, southwestern Seattle, Washington, in Baum, R.L., Godt, J.W., and Highland, L.M., eds., Landslides and Engineering Geology of the Seattle, Washington, Area: Geological Society of America, Reviews in Engineering Geology, v. XX, p. 83-101. Brien, D.L., and Reid, M.E., 2007, Modeling 3-D slope stability of coastal bluffs using 3-D ground-water flow, southwestern Seattle, Washington: U.S. Geological Survey Scientific Investigations Report 2007-5092, 54 p. http://pubs.usgs.gov/sir/2007/5092/ Vallance, J.W., Schilling, S.P., Devoli, G., Reid, M.E., Howell, M.M., and Brien, D.L., 2004, Lahar hazards at Casita and San Cristobal Volcanoes, Nicaragua: U.S. Geological Survey Open-File Report 2001-468, 18 p. http://pubs.usgs.gov/of/2001/0468/ Reid, M.E., Sisson, T.W., and Brien, D.L., 2001, Volcano collapse promoted by hydrothermal alteration and edifice shape, Mount Rainier, Washington: Geology, v. 29, no. 9, p. 779-782. Reid, M.E., Christian, S.B., and Brien, D.L., 2000, Gravitational stability of three-dimensional stratovolcano edifices: Journal of Geophysical Research, v. 105, no. B3, p. 6043-6056.