diff --git a/Examples/hdro-0001/README.rst b/Examples/hdro-0001/README.rst index aaa78f9..f0c8893 100644 --- a/Examples/hdro-0001/README.rst +++ b/Examples/hdro-0001/README.rst @@ -36,6 +36,7 @@ The dataset in this example originates from experimental tests conducted in the .. figure:: figures/Coupled.png :align: center + :alt: Screenshot of a software interface with various settings. On the left side, there is a vertical navigation menu with items like UQ, GI, SIM, EVT, FEM, EDP, RV, and RES highlighted in different shades of grey and blue, with EVT (Event) selected in blue. In the larger right panel, the interface shows a section titled "Event Type" with a dropdown menu set to "Coupled Digital Twin". Below, there are instructions for defining models and outputs, as well as tabs labeled "Settings", "OpenSees", "OpenFOAM", "Outputs", and "Visualization". The visible content under the "OpenSees" and "OpenFOAM" tabs includes options for "Output VTK" set to "Yes", and fields to input "Time Interval", set to "0.05 sec." for OpenSees and "0.01 sec." for OpenFOAM. Other available options are "Free Surface Probes" and "Section Cuts". The interface has a clean, modern design with a blue and grey color scheme. :figclass: align-center :width: 400 @@ -67,6 +68,7 @@ The inputs can also be set up manually through the following steps: .. figure:: figures/UQ.png :align: center + :alt: Screenshot of a user interface with a section titled "UQ Method" featuring options such as "Forward Propagation," a dropdown menu for "UQ Engine" set to "Dakota," checkboxes for "Parallel Execution" and "Save Working dirs," another dropdown menu for the "Method" set to "LHS," and fields to input the number of "Samples" (set to 500) and "Seed" (set to 700). On the left side, there is a vertical navigation bar with various abbreviated items like "UQ," "GI," "SIM," "EVT," "FEM," "EDP," "RV," and "RES" highlighted. :figclass: align-center :width: 600 @@ -79,6 +81,7 @@ The inputs can also be set up manually through the following steps: .. figure:: figures/FEM.png :align: center + :alt: Screenshot of a configuration interface for a finite element analysis application, with options for setting analysis type, integration method, algorithm, convergence test, solver, and damping model. Various fields are filled with specific parameters such as "Analysis: {umSubLevels 2 -numSubSteps 10}", "Integration: Newmark 0.5 0.25", and "ConvergenceTest: NormUnbalance 1.0e-2 10". The interface also includes dropdown menus for algorithm and damping model, input fields for specifying mode shape numbers, and a button to choose an analysis script. On the left side, there is a vertical navigation menu with highlighted options like "FEM", "EDP", and other abbreviations possibly referring to different modules or steps in the engineering analysis process. :figclass: align-center :width: 600 @@ -91,6 +94,7 @@ The inputs can also be set up manually through the following steps: .. figure:: figures/RV.png :align: center + :alt: Screenshot of a user interface for inputting random variables, with a section titled "Input Random Variables". The interface includes fields for 'Variable Name', 'Distribution', 'Mean', and 'Standard Dev' with an example input of 'w' for Variable Name, 'Normal' for Distribution, '150' for Mean, and '10' for Standard Dev. There are buttons for 'Add', 'Clear All', 'Correlation Matrix', 'Export', and 'Import'. On the left side, a vertical menu with the options 'UQ', 'GI', 'SIM', 'EVT', 'FEM', 'EDP', 'RV', 'RES' is visible, with 'RV' highlighted in a lighter shade. A 'Show PDF' button is also in view. :figclass: align-center :width: 600 diff --git a/Examples/hdro-0002/README.rst b/Examples/hdro-0002/README.rst index 4869ca4..4daa733 100644 --- a/Examples/hdro-0002/README.rst +++ b/Examples/hdro-0002/README.rst @@ -1,381 +1,410 @@ -.. _hdro-0002: - -==================================================================================== -Validation - Multiple Debris Impacts on a Raised Structure - Digital Twin (OSU LWF) -==================================================================================== - -+---------------+----------------------------------------------+ -| Problem files | :github:`Github ` | -+---------------+----------------------------------------------+ - - -.. contents:: Table of Contents - :local: - :backlinks: none - - -.. _hdro-0002-overview: - -Overview --------- - -In this digital twin validation example, debris-field wave-flume tests at a NHERI facility, Oregon State University's Large Wave Flume (OSU LWF), are briefly summarized before demonstrating the use of HydroUQ's OSU LWF digital twin paired with the Material Point Method (MPM). - -.. figure:: figures/HydroUQ_MPM_3DViewPort_OSULWF_2024.04.25.gif - :align: center - :width: 600 - :figclass: align-center - - HydroUQ's desktop GUI for the NHERI OSU LWF digital wave-flume twin. - -Details for the experiments are available in various publications. Namely, the work of Andrew Winter [Winter2020]_ [Winter2019]_, Krishnendu Shekhar [Shekhar2020]_ and Dakota Mascarenas [Mascarenas2022]_ [Mascarenas2022PORTS]_. The simulations replicated in this example appeared originally in Bonus 2023 [Bonus2023Dissertation]_. - -Experiments were performed in the NHERI OSU LWF, a 100 meter long flume with adjustable bathymetry, in order to quantify stochastic impact loads of ordered and disordered debris-fields on effectively rigid, raised structure. - -.. figure:: figures/OSU_Flume_Schematic_Dakota_Alam.png - :align: center - :width: 600 - :figclass: align-center - - NHERI OSU LWF facilty's experimental schematic used in this example. Adapted from Winter 2019 [Winter2019]_, and Mascarenas 2022 [Mascarenas2022]_. - -This example may help to produce a robust database (numerical and physical) from which to eventually be able to extract both the first-principals of wave-driven debris-field phenomena and design guidelines on induced forces. - -We validate against two very similar (but not identical) physical studies done in the OSU LWF by [Shekhar2020]_ and [Mascarenas2022]_, indicating high accuracy of our model and low bias to minor experiment specifications. - -Results for free surface elevation and streamwise structural loads are to be recorded for validation at a specified interval. - -Qualitatively, an MPM simulation of debris impacts on a raised structure in the OSU LWF is shown below. - -.. figure:: figures/OSU_LWF_MPM_32L_Impact_3Photos.png - :align: center - :width: 600 - :figclass: align-center - - OSU LWF debris impact photos from HydroUQ's MPM simulations. - -It appears similar in the mechanism of debris impact, stalling, and deflection relative to the structure and flow for a similar case in Mascarenas 2022 [Mascarenas2022]_. - -.. figure:: figures/OSU_LWF_Dakota_8L_Impact_3Photos.PNG - :align: center - :width: 600 - :figclass: align-center - - OSU LWF debris impact photos from Mascarenas 2022 [Mascarenas2022]_ experiments. - - -The experiments by Shekhar et al. 2020 [Shekhar2020]_ are also shown below for comparison. These tests had a slightly different configuartion, primarily the debris were located 0.5 meters further upstream from the box and the water level was 0.10-0.15 meters lower than the 2.0 meter datum used in the simulations and Mascarenas 2022 [Mascarenas2022]_ experiments. - -.. figure:: figures/OSU_LWF_Krish_Debris_8L_3Panel_Impacts_Photograph_Shekhar2020.PNG - :align: center - :width: 600 - :figclass: align-center - - OSU LWF debris impact photos from Shekhar et al. 2020 [Shekhar2020]_ experiments. - -Similar figures can be made for the whole range of order debris-array experiments done at the OSU LWF. However, this example focuses on teaching you how to replicate the above results. - - -.. _hdro-0002-setup: - -Set-Up ------- - -A step-by-step walkthrough on replicating an MPM simulation result from Bonus 2023 [Bonus2023Dissertation]_ is provided below. - -Open ``Settings``. Here we set the simulation time, the time step, and the number of processors to use, among other pre-simulation decisions. - -.. figure:: figures/GUI_Settings.PNG - :align: center - :width: 600 - :figclass: align-center - - HydroUQ Settings GUI - - -Open ``Bodies`` / ``Fluid`` / ``Material``. Here we set the material properties of the fluid and the debris. - -.. figure:: figures/GUI_Bodies_Fluid_Material.PNG - :align: center - :width: 600 - :figclass: align-center - - HydroUQ Bodies Fluid Material GUI - -Open ``Bodies`` / ``Fluid`` / ``Geometry``. Here we set the geometry of the flume, the debris, and the raised structure. - -.. figure:: figures/GUI_Bodies_Fluid_Geometry.PNG - :align: center - :width: 600 - :figclass: align-center - - HydroUQ Bodies Fluid Geometry GUI - - -Open ``Algorithm``. Here we set the algorithm parameters for the simulation. We choose to apply F-Bar antilocking to aid in the pressure field's accuracy on the fluid. The associated toggle must be checked, and the antilocking ratio set to 0.9, loosely. - -.. figure:: figures/GUI_Bodies_Fluid_Algorithm.PNG - :align: center - :width: 600 - :figclass: align-center - - HydroUQ Bodies Fluid Algorithm GUI - -Open ``Bodies`` / ``Fluid`` / ``Partitions``. Here we set the number of partitions for the simulation. This is the domain decomposition across discrete hardware units, i.e. Multi-GPUs. These may be kept as there default values. - -.. figure:: figures/GUI_Bodies_Fluid_Partitions.PNG - :align: center - :width: 600 - :figclass: align-center - - HydroUQ Bodies Fluid Partitions GUI - -Moving onto the creation of an ordered debris-array, we set the debris properties in the ``Bodies`` / ``Debris`` / ``Material`` tab. We will assume debris are made of HDPE plastic, as in experiments by Mascarenas 2022 [Mascarenas2022]_ and Shekhar et al. 2020 [Shekhar2020]_. - -.. figure:: figures/GUI_Bodies_Debris_Material.PNG - :align: center - :width: 600 - :figclass: align-center - - HydroUQ Bodies Debris Material GUI - -Open ``Bodies`` / ``Debris`` / ``Geometry``. Here we set the debris properties, such as the number of debris, the size of the debris, and the spacing between the debris. Rotation is another option, though not used in this example. We've elected to use an 8 x 4 grid of debris (longitudinal axis parallel to long-axis of the flume). - -.. figure:: figures/GUI_Bodies_Debris_Geometry.PNG - :align: center - :width: 600 - :figclass: align-center - - HydroUQ Bodies Debris Geometry GUI - -The ``Bodies`` / ``Debris`` / ``Algorithm`` and ``Debris`` / ``Partitions`` tabs are not used in this example, but are available for more advanced users. - -Open ``Bodies`` / ``Structures``. Uncheck the box that enables this body, if it is checked. We will not model the structure as a body in this example, instead, we will modify it as a boundary later. - -.. figure:: figures/GUI_Bodies_Structure_Disabled.PNG - :align: center - :width: 600 - :figclass: align-center - - HydroUQ Bodies Structures GUI - -Open ``Boundaries`` / ``Wave Flume``. We will set the boundary to be a rigid body, with a fixed separable velocity condition, that is faithful to the digital tiwn of the NHERI OSU LWF. Bathmyetry joint points should be indetical to the ones used in ``Bodeis`` / ``FLuid``. - -.. figure:: figures/GUI_Boundaries_Flume.PNG - :align: center - :width: 600 - :figclass: align-center - - HydroUQ Boundaries Wave Flume Facility GUI - -Open ``Boundaries`` / ``Wave Generator``. Fill in the appropriate file-path for the wave generator paddle motion. It is designed to produce near-solitary like waves. - -.. figure:: figures/GUI_Boundaries_WaveGenerator.PNG - :align: center - :width: 600 - :figclass: align-center - - HydroUQ Boundaries Wave Generator GUI - -Open ``Boundaries`` / ``Rigid Structure``. This is where we will specify the raised structure as a boundary condition. By doing so, we can determine exact loads on the rigid boundary grid-nodes, which may then be mapped to the FEM tab for nonlinear UQ structural response analysis. - -.. figure:: figures/GUI_Boundaries_RigidStructure.PNG - :align: center - :width: 600 - :figclass: align-center - - HydroUQ Boundaries Rigid Structure GUI - -Open ``Boundaries`` / ``RigidWalls``. - -.. figure:: figures/GUI_Boundaries_RigidWalls.PNG - :align: center - :width: 600 - :figclass: align-center - - HydroUQ Boundaries Wave-Flume Facility GUI - -Open ``Sensors`` / ``Wave Gauges``. Set the ``Use these sensor?`` box to ``True`` so that the simulation will output results for the instruments we set on this page. - -Three wave gauges will be defined. The first is located prior to the bathymetry ramps, the second partially up the ramps, and the third near the the bathymetry crest, debris, and raised structure. - -Set the origins and dimensions of each wave as in the table below. To match experimental conditions, we also apply a 120 Hz sampling rate to the wave gauges, meaning they record data every 0.0083 seconds. - -.. figure:: figures/GUI_Sensors_WaveGauges.PNG - :align: center - :width: 600 - :figclass: align-center - - HydroUQ Sensors Wave-Gauge GUI - -These wave gauges will read all numerical bodies (i.e. particles) within their defined regions every sampling step, and will report the highest elevation value (Position Y) of a contained body as the free-surface elevation at that gauge. The results is written into our sensor results files. - - -Open ``Sensors`` / ``Load Cells``. Set the ``Use these sensor?`` box to ``True`` so that the simulation will output results for the instruments we set on this page. - -.. figure:: figures/GUI_Sensors_LoadCells.PNG - :align: center - :width: 600 - :figclass: align-center - - HydroUQ Sensors Load-Cells GUI - - -Open ``Outputs``. Here we set the non-physical output parameters for the simulation, e.g. attributes to save per frame and file extension types. The particle bodies' output frequency is set to 10 Hz (0.1 seconds), meaning the simulation will output results every 0.1 seconds. This is decent for animations without taking too much space. Fill in the rest of the data in the figure into your GUI to ensure all your outputs match this example. - -.. figure:: figures/GUI_Outputs.PNG - :align: center - :width: 600 - :figclass: align-center - - HydroUQ Outputs GUI - - - -.. _hdro-0002-simulation: - -Simulation ----------- - -We assume that 2 hours are reserved for your simulation. For those using the reduce fluid bulk modulus or reduced resolution, this may be more than neccesary. - -This simulation was ran on the TACC Lonestar6 system. It uesd three NVIDIA A100 GPUs on a single node in the ``gpu-a100`` queue. Real time to complete was 2 hours. Simulated time in the digital twin is 26 seconds. - -In order to retrieve results from the analysis, the analysis must complete and postprocess the model output files into an appropriate format before the end of the allotted submission time. - -.. important:: - Provide a large amount of time for the ``Max Run Time`` field in HydroUQ when submitting a job to ensure the model completes before the time allotted runs out! We recommend 2 hours in this example. - -.. warning:: - Only ask for what you need in terms of sensor size, count, and output sampling rate. Otherwise you will end up with massive amounts of data which can slow simulations due to I/O constraints. - - -.. _hdro-0002-analysis: - -Analysis --------- - -When the simulation job has completed, the results will be available on the remote system for retrieval or remote post-processing. - -Retrieving the ``results.zip`` folder from the ``Tools & Applications`` Page of Design Safe starts by navigating to the designsafe-ci.org website. Login and go to ``Use DesignSafe`` / ``Tools & Applications`` - -.. figure:: figures/DSToolsAndAppsJobsStatus.PNG - :align: center - :width: 600 - :figclass: align-center - - Locating the job files on DesignSafe - - -Check if the job has finished in the right-side vertical drawer by clicking the refresh icon. If it has, click ``More info``. - -.. figure:: figures/DSToolsAndAppsJobsStatusFinished.PNG - :align: center - :width: 600 - :figclass: align-center - - Job status is finished on DesignSafe - - -Once the job is finished, the output files should be available in the directory which the analysis results were sent to - -Find the files by clicking ``View``. - -.. figure:: figures/DSToolsAndAppsJobsStatusViewFiles.PNG - :align: center - :width: 600 - :figclass: align-center - - Viewing the job files on DesignSafe - -Move the ``results.zip`` to somewhere in ``My Data/``. Use the Extractor tool available on DesignSafe. Unzip the results.zip folder. - -.. figure:: figures/extractonDS.PNG - :align: center - :width: 600 - :figclass: align-center - - Extracting the ``results.zip`` folder on DesignSafe - - -OR Download the ``results.zip`` folder to your PC and unzip to look at the model results. - -.. figure:: figures/downloadResults.PNG - :align: center - :width: 600 - :figclass: align-center - - Download button on DesignSafe shown in red - - -Download the results to look at the geometry files of the analysis. - -Extract the ``results.zip`` folder either on DesignSafe or on your local machine. You will likely want to have a free Side FX Houdini Apprentice installation to view ``BGEO`` files. - -.. figure:: figures/resultsZip.png - :align: center - :width: 600 - :figclass: align-center - - File-system view of results zip folder on DesignSafe. - - -Locate the zip folder and extract it somewhere convenient. The local or remote work directory on your computer is a good option, but note that these files may be erased if another simulation is set-up in HydroUQ, so keep a backup somewhere outside the working directories. - -HydroUQ's sensor / probe / instrument output is available in ``{your_path_to_HydroUQ_WorkDir}/HydroUQ/RemoteWorkDir/results/`` as ``CSV`` files. - -Particle geometry files often have a ``BGEO`` extension, open Side FX Houdini Apprentice (free to use) to look at MPM results in high-detail. - -Once complete, the simulation data at the three wave gauges (WG1, WG2, and WG3, left-to-right) is as showm below when plotted against experimental trials of Mascarenas 2022 [Mascarenas2022]_ for the "unbroken" solitary wave case. - -.. figure:: figures/OSU_LWF_Wave_Gauges_Hydro_2D_Plots3_2023.10.31.png - :align: center - :width: 600 - :figclass: align-center - - OSU LWF simulated free-surface elevation wave gauges vs. experimental data from Mascarenas 2022 [Mascarenas2022]_. - - -The simulation data at the load-cell is as shown below when plotted against experimental trials of Mascarenas 2022 [Mascarenas2022]_ for the "unbroken" solitary wave case. The experimental streamwise load is the combination of "LC5" and "LC8" in Mascarenas 2022 [Mascarenas2022]_, as both measured streamwise load on the box to reduce errors from position / slight box apparatus out-of-plane rotation. - -.. figure:: figures/OSU_LWF_Load_Cells_Hydro_2023.10.31.png - :align: center - :width: 600 - :figclass: align-center - - OSU LWF simulated streamwise load-cells vs. experimental data from Mascarenas 2022 [Mascarenas2022]_. - - -Though only one case was considered here, if many experimental debris-field cases are ran (10+) we can use HydroUQ to perform a sensitivity analysis on the debris-field parameters. This isn't pursued here-in. - -However, the following box-and-whisker charts demonstrates the strengh of the numerical replication, as most points fall within experimental interquartile ranges and never outside of the experimental envelope for impact loads. - -.. figure:: figures/OSU_U_FirstPeak_BoxAndWhiskers_KrishExpOnly_31072023.png - :align: center - :width: 600 - :figclass: align-center - - OSU LWF simulated first peak debris impact loads vs. experimental data from Mascarenas 2022 [Mascarenas2022]_. - - -This complete our HydroUQ validation example for multiple debris impacts on a raised structure in the OSU LWF, Bonus 2023 [Bonus2023Dissertation]_. - - -.. _hdro-0002-references: - -References ----------- - -.. [Winter2019] Winter, A. (2019). "Effects of Flow Shielding and Channeling on Tsunami-Induced Loading of Coastal Structures." PhD thesis. University of Washington, Seattle. - -.. [Winter2020] Andrew O Winter, Mohammad S Alam, Krishnendu Shekhar, Michael R Motley, Marc O Eberhard, Andre R Barbosa, Pedro Lomonaco, Pedro Arduino, Daniel T Cox (2019). "Tsunami-Like Wave Forces on an Elevated Coastal Structure: Effects of Flow Shielding and Channeling." Journal of Waterway, Port, Coastal, and Ocean Engineering. - -.. [Shekhar2020] Shekhar, K., Mascarenas, D., and Cox, D. (2020). "Wave-Driven Debris Impact on a Raised Structure in the Large Wave Flume." 17th International Conference on Hydroinformatics, Seoul, South Korea. - -.. [Mascarenas2022] Mascarenas, Dakota. (2022). "Quantification of Wave-Driven Debris Impact on a Raised Structure in a Large Wave Flume." Masters thesis. University of Washington, Seattle. - -.. [Mascarenas2022PORTS] Mascarenas, Dakota, Motley, M., Eberhard, M. (2022). "Wave-Driven Debris Impact on a Raised Structure in the Large Wave Flume." Journal of Waterway, Port, Coastal, and Ocean Engineering. - -.. [Bonus2023Dissertation] Bonus, Justin (2023). "Evaluation of Fluid-Driven Debris Impacts in a High-Performance Multi-GPU Material Point Method." PhD thesis. University of Washington, Seattle. - - +.. _hdro-0002: + +==================================================================================== +Validation - Multiple Debris Impacts on a Raised Structure - Digital Twin (OSU LWF) +==================================================================================== + ++---------------+----------------------------------------------+ +| Problem files | :github:`Github ` | ++---------------+----------------------------------------------+ + + +.. contents:: Table of Contents + :local: + :backlinks: none + + +.. _hdro-0002-overview: + +Overview +-------- + +In this digital twin validation example, debris-field wave-flume tests at a NHERI facility, Oregon State University's Large Wave Flume (OSU LWF), are briefly summarized before demonstrating the use of HydroUQ's OSU LWF digital twin paired with the Material Point Method (MPM). + +.. figure:: figures/HydroUQ_MPM_3DViewPort_OSULWF_2024.04.25.gif + :align: center + :alt: Screenshot of a computer application, possibly a hydraulic simulation software named Hydro-UQ with various interface panels. On the left side, there's a user interface with several tabs such as "Event Type," "Materials," and "FEM." It includes input fields and a case directory path, along with a digital photo of what appears to be water overflowing a dam. On the right side, there's a 3D graphical representation of a blue, slender structural model with sensors or measurement points highlighted in yellow and red. + :width: 600 + :figclass: align-center + + HydroUQ's desktop GUI for the NHERI OSU LWF digital wave-flume twin. + +Details for the experiments are available in various publications. Namely, the work of Andrew Winter [Winter2020]_ [Winter2019]_, Krishnendu Shekhar [Shekhar2020]_ and Dakota Mascarenas [Mascarenas2022]_ [Mascarenas2022PORTS]_. The simulations replicated in this example appeared originally in Bonus 2023 [Bonus2023Dissertation]_. + +Experiments were performed in the NHERI OSU LWF, a 100 meter long flume with adjustable bathymetry, in order to quantify stochastic impact loads of ordered and disordered debris-fields on effectively rigid, raised structure. + +.. figure:: figures/OSU_Flume_Schematic_Dakota_Alam.png + :align: center + :alt: Schematic diagrams of an experimental wave flume setup with measurements and equipment notations. Image (a) shows a side view with dimensional markers, a piston-type wave maker, multiple sensors such as wave gauges (WG), ultrasonic wave gauges (USWG), and velocimeters (ADV), and a specimen at the end of the flume. The slope changes are labeled 1:12 and 1:24 referencing incline ratios. Image (b) is a top-down view of the flume, marking the locations of the sensors, the specimen, and bay sections, with distance measurements in numbers along the bottom of the diagram. + :width: 600 + :figclass: align-center + + NHERI OSU LWF facilty's experimental schematic used in this example. Adapted from Winter 2019 [Winter2019]_, and Mascarenas 2022 [Mascarenas2022]_. + +This example may help to produce a robust database (numerical and physical) from which to eventually be able to extract both the first-principals of wave-driven debris-field phenomena and design guidelines on induced forces. + +We validate against two very similar (but not identical) physical studies done in the OSU LWF by [Shekhar2020]_ and [Mascarenas2022]_, indicating high accuracy of our model and low bias to minor experiment specifications. + +Results for free surface elevation and streamwise structural loads are to be recorded for validation at a specified interval. + +Qualitatively, an MPM simulation of debris impacts on a raised structure in the OSU LWF is shown below. + +.. figure:: figures/OSU_LWF_MPM_32L_Impact_3Photos.png + :align: center + :alt: A triptych of images showing the simulation of fluid flow around a cube-shaped obstacle. The left image displays the initial smooth laminar flow with neatly aligned flow lines in blue and orange before hitting the obstacle. The middle image captures the moment of disruption as the flow encounters the obstacle, creating complex patterns and vortices in varying shades of blue, indicating turbulence. The right image shows the aftermath with turbulent, chaotic flow patterns swirling past the obstacle, highlighted in intense shades of blue, suggesting dynamic fluid behavior. + :width: 600 + :figclass: align-center + + OSU LWF debris impact photos from HydroUQ's MPM simulations. + +It appears similar in the mechanism of debris impact, stalling, and deflection relative to the structure and flow for a similar case in Mascarenas 2022 [Mascarenas2022]_. + +.. figure:: figures/OSU_LWF_Dakota_8L_Impact_3Photos.PNG + :align: center + :alt: A triptych of dark, grainy images showing a sheet of material being progressively printed with a series of decorated tiles. There is a green mechanical element with a sun-like emblem at the top; underneath, the sheet, printed with square patterns, moves through a red-colored machine element, showing different stages of the printing process in each panel. The surrounding area is mostly dark, with some reflections suggesting a metallic or wet surface. + :width: 600 + :figclass: align-center + + OSU LWF debris impact photos from Mascarenas 2022 [Mascarenas2022]_ experiments. + + +The experiments by Shekhar et al. 2020 [Shekhar2020]_ are also shown below for comparison. These tests had a slightly different configuartion, primarily the debris were located 0.5 meters further upstream from the box and the water level was 0.10-0.15 meters lower than the 2.0 meter datum used in the simulations and Mascarenas 2022 [Mascarenas2022]_ experiments. + +.. figure:: figures/OSU_LWF_Krish_Debris_8L_3Panel_Impacts_Photograph_Shekhar2020.PNG + :align: center + :alt: A sequence of four images depicting a debris trial with progressive stages of obstruction in front of an orange and grey structure, possibly for scientific research. In the first image, there is a single white rectangular object on a dark wet surface. Each subsequent image shows an additional piece of debris; the second has two such objects, the third shows three white objects, and the fourth displays a large cylindrical brown object in addition to the other items. The wet surface reflects light and creates a ripple effect around the debris. The reference "Shekhar et al. (2020)" suggests this is a figure from a research study or publication. + :width: 600 + :figclass: align-center + + OSU LWF debris impact photos from Shekhar et al. 2020 [Shekhar2020]_ experiments. + +Similar figures can be made for the whole range of order debris-array experiments done at the OSU LWF. However, this example focuses on teaching you how to replicate the above results. + + +.. _hdro-0002-setup: + +Set-Up +------ + +A step-by-step walkthrough on replicating an MPM simulation result from Bonus 2023 [Bonus2023Dissertation]_ is provided below. + +Open ``Settings``. Here we set the simulation time, the time step, and the number of processors to use, among other pre-simulation decisions. + +.. figure:: figures/GUI_Settings.PNG + :align: center + :alt: Screenshot of a simulation settings interface with various parameters. Categories include Ambient, Spatial, Temporal, Scaling Laws, and Computer. Values are assigned to parameters such as CFL Number, Gravity, Grid Cell Size, Max Time Step, Dominant Law, and computer specifications like Computing Facility, Queue, Maximum Number of GPUs, GPU Name, and GPU Global Memory. The interface contains fields for input and selection with checkboxes, dropdown menus, and numerical inputs. + :width: 600 + :figclass: align-center + + HydroUQ Settings GUI + + +Open ``Bodies`` / ``Fluid`` / ``Material``. Here we set the material properties of the fluid and the debris. + +.. figure:: figures/GUI_Bodies_Fluid_Material.PNG + :align: center + :alt: Screenshot of a user interface from a simulation software showing configuration options for a fluid body. There are tabs for Settings, Bodies, Boundaries, Sensors, Outputs, and Results at the top. Below are options to 'Create Body' and 'Remove Body', with fluid, debris, and structure checkboxes. The 'Fluid' checkbox is checked and details such as 'Enable Body', 'Velocity', and 'Material Preset' with 'Water (Fresh)' selected are visible. The section also includes parameters like 'CFL Number', 'Density', and 'Constitutive Law Properties' with values for 'Bulk Modulus', 'Viscosity', and 'Bulk Derivative'. + :width: 600 + :figclass: align-center + + HydroUQ Bodies Fluid Material GUI + +Open ``Bodies`` / ``Fluid`` / ``Geometry``. Here we set the geometry of the flume, the debris, and the raised structure. + +.. figure:: figures/GUI_Bodies_Fluid_Geometry.PNG + :align: center + :alt: A screenshot of a software interface for creating and configuring geometrical bodies, likely for simulation purposes. The interface includes options for setting the body type, dimensions, and material properties. Sections like "Create Body," "Remove Body," "Create Geometry," and "Remove Geometry" are visible, as well as input fields for specifying dimensions and other parameters such as velocity, origin, and operation on prior geometry. The section labeled "Digital Twin Geometry" lists parameters for a facility named "Hinsdale Large Wave Flume (OSU LWF)" with dimensions and a table for filling in "Joint Position" coordinates. + :width: 600 + :figclass: align-center + + HydroUQ Bodies Fluid Geometry GUI + + +Open ``Algorithm``. Here we set the algorithm parameters for the simulation. We choose to apply F-Bar antilocking to aid in the pressure field's accuracy on the fluid. The associated toggle must be checked, and the antilocking ratio set to 0.9, loosely. + +.. figure:: figures/GUI_Bodies_Fluid_Algorithm.PNG + :align: center + :alt: Screenshot of a user interface from a simulation software showing settings for a computational body with options related to fluids, debris, and structures. The interface includes parameters for enabling the body, setting velocity, choosing material, geometry, algorithm, and particle representation, with specific fields for particle-per-cell value, ASFLIP advection options, and F-BAR anti-locking settings. + :width: 600 + :figclass: align-center + + HydroUQ Bodies Fluid Algorithm GUI + +Open ``Bodies`` / ``Fluid`` / ``Partitions``. Here we set the number of partitions for the simulation. This is the domain decomposition across discrete hardware units, i.e. Multi-GPUs. These may be kept as there default values. + +.. figure:: figures/GUI_Bodies_Fluid_Partitions.PNG + :align: center + :alt: Screenshot of a user interface from a simulation software, with various tabs like Settings, Bodies, Boundaries, Sensors, Outputs, and Results. The 'Bodies' tab is selected, showing options for creating and removing bodies categorized as Fluid, Debris, and Structures. The interface includes settings to enable body, set velocity, choose material, geometry, algorithm, and manage partitions with options to create and remove a partition, and configure related parameters such as GPU device ID, body ID, and partition dimensions. + :width: 600 + :figclass: align-center + + HydroUQ Bodies Fluid Partitions GUI + +Moving onto the creation of an ordered debris-array, we set the debris properties in the ``Bodies`` / ``Debris`` / ``Material`` tab. We will assume debris are made of HDPE plastic, as in experiments by Mascarenas 2022 [Mascarenas2022]_ and Shekhar et al. 2020 [Shekhar2020]_. + +.. figure:: figures/GUI_Bodies_Debris_Material.PNG + :align: center + :alt: Screenshot of a software interface with options for simulating physical bodies in a virtual environment. The interface includes tabs such as Settings, Bodies, Boundaries, Sensors, Outputs, and Results. There is a section for creating or removing a body, with checkboxes for fluid, debris, and structures. The selected options display settings related to a body's physics, including switches to enable the body, input fields for velocity in XYZ coordinates, material presets, constitutive law, CFL number, density, and elastic properties like Young's Modulus and Poisson's Ratio. The interface is designed for configuring simulations with a focus on the material and physical characteristics of a body within the simulation. + :width: 600 + :figclass: align-center + + HydroUQ Bodies Debris Material GUI + +Open ``Bodies`` / ``Debris`` / ``Geometry``. Here we set the debris properties, such as the number of debris, the size of the debris, and the spacing between the debris. Rotation is another option, though not used in this example. We've elected to use an 8 x 4 grid of debris (longitudinal axis parallel to long-axis of the flume). + +.. figure:: figures/GUI_Bodies_Debris_Geometry.PNG + :align: center + :alt: Screenshot of a software interface used for creating and manipulating geometrical objects, likely for simulation purposes. The interface includes sections labeled "Settings," "Bodies," "Boundaries," "Sensors," "Outputs," and "Results" at the top. The main focus is on a section for creating a new body, with options to enable/disable the body, set velocity, and choose material. There is a subsection titled "Create Geometry" with fields for defining an object named "Custom 1," with parameters such as Body Preset (Debris), Object Type (Sphere), Origin, Dimensions, Radius, and other geometric configurations. It appears to be designed for users to input specific values to define a spherical object for a simulation model. + :width: 600 + :figclass: align-center + + HydroUQ Bodies Debris Geometry GUI + +The ``Bodies`` / ``Debris`` / ``Algorithm`` and ``Debris`` / ``Partitions`` tabs are not used in this example, but are available for more advanced users. + +Open ``Bodies`` / ``Structures``. Uncheck the box that enables this body, if it is checked. We will not model the structure as a body in this example, instead, we will modify it as a boundary later. + +.. figure:: figures/GUI_Bodies_Structure_Disabled.PNG + :align: center + :alt: Screenshot of a user interface from a software application with a toolbar at the top displaying various categories such as Settings, Bodies, Boundaries, Sensors, Outputs, and Results. The highlighted tab is Bodies, with two main options presented: "Create Body" and "Remove Body," both with blue button styling. Below these options, there is a set of toggle switches labeled "Fluid," "Debris," and "Structures," with "Fluid" and "Debris" enabled, indicated by a checkmark, and "Structures" disabled with a crossed-out mark. To the left, there is an unchecked checkbox next to the text "Enable Body." The overall color scheme of the interface consists of shades of blue, gray, and white. + :width: 600 + :figclass: align-center + + HydroUQ Bodies Structures GUI + +Open ``Boundaries`` / ``Wave Flume``. We will set the boundary to be a rigid body, with a fixed separable velocity condition, that is faithful to the digital tiwn of the NHERI OSU LWF. Bathmyetry joint points should be indetical to the ones used in ``Bodeis`` / ``FLuid``. + +.. figure:: figures/GUI_Boundaries_Flume.PNG + :align: center + :alt: Screenshot of a software interface with various buttons and settings related to hydrodynamic modeling. At the top, there are buttons labeled "Create Boundary" and "Remove Boundary." There are tabs for "Flume Facility," "Wave Generator," "Rigid Structure," and "Rigid Walls." The open tab displays settings for a "Flume Facility" with dimensions and origin points listed, as well as a "Point List" section where 'Joint Position (X)' and 'Joint Position (Y)' values are specified, with options to add or delete entries. + :width: 600 + :figclass: align-center + + HydroUQ Boundaries Wave Flume Facility GUI + +Open ``Boundaries`` / ``Wave Generator``. Fill in the appropriate file-path for the wave generator paddle motion. It is designed to produce near-solitary like waves. + +.. figure:: figures/GUI_Boundaries_WaveGenerator.PNG + :align: center + :alt: Screenshot of a software interface for setting up simulation parameters related to wave generation. The interface includes options to 'Create Boundary' or 'Remove Boundary' and toggles for 'Flume Facility,' 'Wave Generator,' 'Rigid Structure,' and 'Rigid Walls.' The selected 'Boundary Preset' is 'Wave Generator,' and various details such as 'Wave Generation Method,' 'Contact Type,' 'Dimensions,' and 'Origin' are visible with fields for numerical input. A file path for a 'Paddle Motion File' is provided at the bottom with an option to 'Choose' the file. + :width: 600 + :figclass: align-center + + HydroUQ Boundaries Wave Generator GUI + +Open ``Boundaries`` / ``Rigid Structure``. This is where we will specify the raised structure as a boundary condition. By doing so, we can determine exact loads on the rigid boundary grid-nodes, which may then be mapped to the FEM tab for nonlinear UQ structural response analysis. + +.. figure:: figures/GUI_Boundaries_RigidStructure.PNG + :align: center + :alt: Screenshot of a graphical user interface for simulation software, showing a section for defining a "Rigid Structure" boundary. The interface includes fields for object type selection, contact type, load-cell face, dimensions, origin coordinates, and options for applying Coulomb friction with input fields for static and dynamic friction on faces. Buttons for "Create Boundary" and "Remove Boundary" are visible, along with tabs for "Flume Facility," "Wave Generator," and "Rigid Walls" settings. + :width: 600 + :figclass: align-center + + HydroUQ Boundaries Rigid Structure GUI + +Open ``Boundaries`` / ``RigidWalls``. + +.. figure:: figures/GUI_Boundaries_RigidWalls.PNG + :align: center + :alt: Screenshot of a software interface used for simulation or modeling, showing options related to setting up boundaries. The top menu includes tabs labeled Settings, Bodies, Boundaries, Sensors, Outputs, and Results. There are buttons for "Create Boundary" and "Remove Boundary," and check boxes for "Flume Facility," "Wave Generator," "Rigid Structure," and "Rigid Walls" settings. Under "Boundary Preset," "Rigid Walls" is selected with options for "Contact Type," "Dimensions (X,Y,Z)," "Origin (X,Y,Z)," "Apply Coulomb Friction," and fields for "Static Friction on Walls (X,Y,Z)" and "Dynamic Friction on Walls (X,Y,Z)." There is also a checkbox for "Apply Inlet/Outlet?" + :width: 600 + :figclass: align-center + + HydroUQ Boundaries Wave-Flume Facility GUI + +Open ``Sensors`` / ``Wave Gauges``. Set the ``Use these sensor?`` box to ``True`` so that the simulation will output results for the instruments we set on this page. + +Three wave gauges will be defined. The first is located prior to the bathymetry ramps, the second partially up the ramps, and the third near the the bathymetry crest, debris, and raised structure. + +Set the origins and dimensions of each wave as in the table below. To match experimental conditions, we also apply a 120 Hz sampling rate to the wave gauges, meaning they record data every 0.0083 seconds. + +.. figure:: figures/GUI_Sensors_WaveGauges.PNG + :align: center + :alt: Screenshot of a user interface for sensor configuration within a simulation software. The highlighted tab is "Wave-Gauges" within a row of sensor options like "Velocity-Meters" and "Load-Cells." Options within the Wave-Gauges tab include toggles and dropdowns for sensor presets, application on specific entities such as 'particles,' attribute measurement like 'Elevation,' and sampling frequency. There's also a table listing individual wave gauges with their respective Origin X, Y, Z coordinates, dimensions, and controls for adding or deleting entries. + :width: 600 + :figclass: align-center + + HydroUQ Sensors Wave-Gauge GUI + +These wave gauges will read all numerical bodies (i.e. particles) within their defined regions every sampling step, and will report the highest elevation value (Position Y) of a contained body as the free-surface elevation at that gauge. The results is written into our sensor results files. + + +Open ``Sensors`` / ``Load Cells``. Set the ``Use these sensor?`` box to ``True`` so that the simulation will output results for the instruments we set on this page. + +.. figure:: figures/GUI_Sensors_LoadCells.PNG + :align: center + :alt: Screenshot of an engineering software interface with a focus on sensor configuration settings. The "Create Sensor" and "Remove Sensor" buttons are at the top, followed by check boxes for different sensor types like Wave-Gauges, Velocity-Meters, Load-Cells, and Piezo-Meters. Below, a section labeled "Sensor Preset" is set to "Load-Cells" with options to specify the sensor usage, including drop-down menus for applying the sensor, measuring attribute, operation to perform, and sampling frequency. There is also an input table for defining a sensor named "LoadCell1," with fields for its origin coordinates and dimensions along the X, Y, and Z axes, and "Add" and "Del" buttons for managing the sensor list. + :width: 600 + :figclass: align-center + + HydroUQ Sensors Load-Cells GUI + + +Open ``Outputs``. Here we set the non-physical output parameters for the simulation, e.g. attributes to save per frame and file extension types. The particle bodies' output frequency is set to 10 Hz (0.1 seconds), meaning the simulation will output results every 0.1 seconds. This is decent for animations without taking too much space. Fill in the rest of the data in the figure into your GUI to ensure all your outputs match this example. + +.. figure:: figures/GUI_Outputs.PNG + :align: center + :alt: A screenshot of a software interface related to simulation or data processing, showing settings for outputting data related to "Bodies," "Checkpoint-Resume State," "Boundaries," "Sensors," and "Energies." The "Bodies" section includes options for Output File Type, Output Frequency, and different Output Attributes such as Pressure, Velocity (X, Y, Z), and Von Mises Stress. Other sections allow specifying file types such as BGEO, OBJ, TXT, and CSV, with their respective output frequencies. The interface includes checkboxes for "Only Save Exterior," "Output Kinetic," "Output Gravity," and "Output Strain," along with "Add" and "Delete" buttons for managing output attributes. + :width: 600 + :figclass: align-center + + HydroUQ Outputs GUI + + + +.. _hdro-0002-simulation: + +Simulation +---------- + +We assume that 2 hours are reserved for your simulation. For those using the reduce fluid bulk modulus or reduced resolution, this may be more than neccesary. + +This simulation was ran on the TACC Lonestar6 system. It uesd three NVIDIA A100 GPUs on a single node in the ``gpu-a100`` queue. Real time to complete was 2 hours. Simulated time in the digital twin is 26 seconds. + +In order to retrieve results from the analysis, the analysis must complete and postprocess the model output files into an appropriate format before the end of the allotted submission time. + +.. important:: + Provide a large amount of time for the ``Max Run Time`` field in HydroUQ when submitting a job to ensure the model completes before the time allotted runs out! We recommend 2 hours in this example. + +.. warning:: + Only ask for what you need in terms of sensor size, count, and output sampling rate. Otherwise you will end up with massive amounts of data which can slow simulations due to I/O constraints. + + +.. _hdro-0002-analysis: + +Analysis +-------- + +When the simulation job has completed, the results will be available on the remote system for retrieval or remote post-processing. + +Retrieving the ``results.zip`` folder from the ``Tools & Applications`` Page of Design Safe starts by navigating to the designsafe-ci.org website. Login and go to ``Use DesignSafe`` / ``Tools & Applications`` + +.. figure:: figures/DSToolsAndAppsJobsStatus.PNG + :align: center + :alt: Screenshot of a user interface for an application named "TOOLS & APPLICATIONS" featuring three main sections. On the left, there is a 'DATA DEPOT BROWSER' allowing the user to select a data source and displays a list with items such as 'Trash', 'archive', and 'Hydro-UQ'. In the center, a large heading reads 'SELECT AN APP' with text below inviting users to select an application from the tray above, and describing the type of simulations and analyses that can be performed with different tools. On the right, a 'JOBS STATUS' panel lists several jobs related to 'HydroUQ' with their status such as 'RUNNING' or 'FINISHED', along with links to 'More info'. There are tabs across the top labeled 'Simulation', 'SimCenter Tools', 'Visualization', 'Analysis', 'Hazard Apps', 'Utilities', and 'My Apps'. + :width: 600 + :figclass: align-center + + Locating the job files on DesignSafe + + +Check if the job has finished in the right-side vertical drawer by clicking the refresh icon. If it has, click ``More info``. + +.. figure:: figures/DSToolsAndAppsJobsStatusFinished.PNG + :align: center + :alt: Screenshot of a user interface element showing the word "FINISHED" in bold with a green background and a button next to it labeled "More info" featuring an information icon. + :width: 600 + :figclass: align-center + + Job status is finished on DesignSafe + + +Once the job is finished, the output files should be available in the directory which the analysis results were sent to + +Find the files by clicking ``View``. + +.. figure:: figures/DSToolsAndAppsJobsStatusViewFiles.PNG + :align: center + :alt: The image shows a user interface with details of a completed job. The application name is 'simcenter-openfoam-frontera-1.0.0' and the Job ID is provided. The job status indicates 'FINISHED', with submission and finish timestamps listed. The last status message states "Transitioning from status ARCHIVING to FINISHED in phase ARCHIVING." There is a highlighted button labeled 'View' under 'Output' and another button labeled 'Delete' under 'Actions'. A 'Close' button is at the bottom. + :width: 600 + :figclass: align-center + + Viewing the job files on DesignSafe + +Move the ``results.zip`` to somewhere in ``My Data/``. Use the Extractor tool available on DesignSafe. Unzip the results.zip folder. + +.. figure:: figures/extractonDS.PNG + :align: center + :alt: Screenshot of a software interface with a menu bar containing tabs such as "Simulation," "SimCenter Tools," "Visualization," "Analysis," "Hazard Apps," "Utilities," and "My Apps." There are two highlighted options underneath the "Utilities" tab: "Compress Files" with an icon of a file being compressed, and "Extract Compressed File" with an icon of a file being unzipped, which is currently selected. The interface has a dark theme. + :width: 600 + :figclass: align-center + + Extracting the ``results.zip`` folder on DesignSafe + + +OR Download the ``results.zip`` folder to your PC and unzip to look at the model results. + +.. figure:: figures/downloadResults.PNG + :align: center + :alt: "Screenshot of a web-based file management interface with a directory listing of files, including a .log, two .err, and two .out files, as well as a highlighted 'results.zip' file. The interface includes features such as a search bar, buttons for actions like 'Rename', 'Move', 'Copy', 'Preview', 'Preview Images', 'Download', and 'Move to Trash'. The 'Download' button is encircled in red, indicating an action or focus on the option to download files." + :width: 600 + :figclass: align-center + + Download button on DesignSafe shown in red + + +Download the results to look at the geometry files of the analysis. + +Extract the ``results.zip`` folder either on DesignSafe or on your local machine. You will likely want to have a free Side FX Houdini Apprentice installation to view ``BGEO`` files. + +.. figure:: figures/resultsZip.png + :align: center + :alt: A screenshot of a file directory with a list of files. The file "results.zip" is highlighted with a file size of 962.1 MB and a last modified date of 10/8/23 at 10:36 AM. Other files in the list include logs, error outputs, and another zip file, all with differing file sizes and the same modification date. + :width: 600 + :figclass: align-center + + File-system view of results zip folder on DesignSafe. + + +Locate the zip folder and extract it somewhere convenient. The local or remote work directory on your computer is a good option, but note that these files may be erased if another simulation is set-up in HydroUQ, so keep a backup somewhere outside the working directories. + +HydroUQ's sensor / probe / instrument output is available in ``{your_path_to_HydroUQ_WorkDir}/HydroUQ/RemoteWorkDir/results/`` as ``CSV`` files. + +Particle geometry files often have a ``BGEO`` extension, open Side FX Houdini Apprentice (free to use) to look at MPM results in high-detail. + +Once complete, the simulation data at the three wave gauges (WG1, WG2, and WG3, left-to-right) is as showm below when plotted against experimental trials of Mascarenas 2022 [Mascarenas2022]_ for the "unbroken" solitary wave case. + +.. figure:: figures/OSU_LWF_Wave_Gauges_Hydro_2D_Plots3_2023.10.31.png + :align: center + :alt: This image contains three line graphs labeled (a) Wave-Gauge[1], (b) Wave-Gauge[2], and (c) Wave-Gauge[3], each displaying water elevation change over time elapsed in seconds. The graphs compare different trials labeled as 'MPM - Bonus 2023', 'EXP - Trial 7', 'EXP - Trial 5', 'EXP - Trial 2', and a reference line for 'Still Water'. All graphs show a similar pattern of peaked curves, rising sharply then falling back down, with slight variations among the trials. + :width: 600 + :figclass: align-center + + OSU LWF simulated free-surface elevation wave gauges vs. experimental data from Mascarenas 2022 [Mascarenas2022]_. + + +The simulation data at the load-cell is as shown below when plotted against experimental trials of Mascarenas 2022 [Mascarenas2022]_ for the "unbroken" solitary wave case. The experimental streamwise load is the combination of "LC5" and "LC8" in Mascarenas 2022 [Mascarenas2022]_, as both measured streamwise load on the box to reduce errors from position / slight box apparatus out-of-plane rotation. + +.. figure:: figures/OSU_LWF_Load_Cells_Hydro_2023.10.31.png + :align: center + :alt: A line graph displaying "Streamwise Force on Structure [Newtons]" versus "Time Elapsed [seconds]". There are five lines representing different trials or methods: a red dashed line labeled "MPM - Bonus 2023 - Stabilized", a black dashed line labeled "MPM - Bonus 2023 - Original", and three solid lines in shades of gray to blue representing "EXP - Mascarenas 2022 - Trial 7", "Trial 5", and "Trial 2". The lines show a general increase in force over time, peaking around 36 seconds before gradually declining. The graph ranges from 30 to 45 seconds on the x-axis and from 0 to 300 Newtons on the y-axis. + :width: 600 + :figclass: align-center + + OSU LWF simulated streamwise load-cells vs. experimental data from Mascarenas 2022 [Mascarenas2022]_. + + +Though only one case was considered here, if many experimental debris-field cases are ran (10+) we can use HydroUQ to perform a sensitivity analysis on the debris-field parameters. This isn't pursued here-in. + +However, the following box-and-whisker charts demonstrates the strengh of the numerical replication, as most points fall within experimental interquartile ranges and never outside of the experimental envelope for impact loads. + +.. figure:: figures/OSU_U_FirstPeak_BoxAndWhiskers_KrishExpOnly_31072023.png + :align: center + :alt: A detailed scatter plot with box-and-whisker elements showing the impact force (N) relative to debris count ordered by array. Data points are differentiated by color and shape, representing different studies and types of simulations or experiments. Red and blue circles indicate "Longitudinal" and "Transverse" simulations from Bonus 2023. Black and gray circles denote "Total" force from experiments by Mascarenas 2022, while green triangles and inverted triangles are associated with Shekhar 2018's "Total" and "Debris" experiments, respectively. The impact force values range from 0 to 3000 N, with varying debris count configurations along the x-axis. + :width: 600 + :figclass: align-center + + OSU LWF simulated first peak debris impact loads vs. experimental data from Mascarenas 2022 [Mascarenas2022]_. + + +This complete our HydroUQ validation example for multiple debris impacts on a raised structure in the OSU LWF, Bonus 2023 [Bonus2023Dissertation]_. + + +.. _hdro-0002-references: + +References +---------- + +.. [Winter2019] Winter, A. (2019). "Effects of Flow Shielding and Channeling on Tsunami-Induced Loading of Coastal Structures." PhD thesis. University of Washington, Seattle. + +.. [Winter2020] Andrew O Winter, Mohammad S Alam, Krishnendu Shekhar, Michael R Motley, Marc O Eberhard, Andre R Barbosa, Pedro Lomonaco, Pedro Arduino, Daniel T Cox (2019). "Tsunami-Like Wave Forces on an Elevated Coastal Structure: Effects of Flow Shielding and Channeling." Journal of Waterway, Port, Coastal, and Ocean Engineering. + +.. [Shekhar2020] Shekhar, K., Mascarenas, D., and Cox, D. (2020). "Wave-Driven Debris Impact on a Raised Structure in the Large Wave Flume." 17th International Conference on Hydroinformatics, Seoul, South Korea. + +.. [Mascarenas2022] Mascarenas, Dakota. (2022). "Quantification of Wave-Driven Debris Impact on a Raised Structure in a Large Wave Flume." Masters thesis. University of Washington, Seattle. + +.. [Mascarenas2022PORTS] Mascarenas, Dakota, Motley, M., Eberhard, M. (2022). "Wave-Driven Debris Impact on a Raised Structure in the Large Wave Flume." Journal of Waterway, Port, Coastal, and Ocean Engineering. + +.. [Bonus2023Dissertation] Bonus, Justin (2023). "Evaluation of Fluid-Driven Debris Impacts in a High-Performance Multi-GPU Material Point Method." PhD thesis. University of Washington, Seattle. + + diff --git a/Examples/hdro-0003/README.rst b/Examples/hdro-0003/README.rst index b4e4ba3..5490ac9 100644 --- a/Examples/hdro-0003/README.rst +++ b/Examples/hdro-0003/README.rst @@ -1,329 +1,347 @@ -.. _hdro-0003: - -======================================================================================= -Cylinder Half-Submerged in Flow - UW WASIRF Twin - FOAMySees (OpenFOAM + OpenSees) -======================================================================================= - -+---------------+------------------------------------------------------------------------------------------------------+ -| Problem files | :github:`Github ` | -+---------------+------------------------------------------------------------------------------------------------------+ - - -.. contents:: Table of Contents - :local: - :backlinks: none - -.. _hdro-0003-overview: - -Overview --------- - -This example demonstrates how to run a coupled **OpenSees-OpenFOAM** simulation (**FOAMySees**) to determine floor loads on a building caused by strongly-coupled, two-way fluid-structure interaction. -You can then perform an **OpenSees** simulation of the building assuming uncertainties in the building properties. - -A truncated digital twin of the UW WASIRF wave flume contains a simple cantilevered cylinder. The cylinder, our structure, is half-submerged. The flow around the cylinder is calculated for a given period of time in order to determine a simulated structural response time-series under wave loading. - -Outputs of the **EVT** simulation will include results, sampled at specified frequenies, for the: - -#. Fluid flow's free surface elevation at wave gauges -#. Flow velocity at velocimeter locations -#. Fluid pressure at piezometers locations -#. FSI forces and moments at the structural interface -#. Cross-section cuts of the OpenFOAM continuum - -As the **EVT** and **FEM** functionality are effectively fused for FOAMySees, the **FEM** tab will be envisioned as providing additional results in the form of: - -#. Time-series motion of any structural nodes with defined *recorders* in the **OpenSees** model. - -The **EDP** tab will then process these results. - -#. Displacement of the cylinder tip from rest, peak relative-floor displacement (PFD) -#. Displacement of the cylinder tip relative to its base or supporting , peak inter-story drift (PID) -#. Peak floor acceleration (PFA) - - -.. _hdro-0003-setup: - -Set-Up ------- - -The case is set up in the HydroUQ tool on DesignSafe. You can select the case from the list of available examples off of the HydroUQ menubar, i.e. ``Examples / hdro-0003``. The case is set up as follows. - -The flume is 1 meter wide (from Y=-0.5m to Y=0.5 m), 1 meter tall (Z=0.0m to Z=1.0m), and 4 meters long (X=0.0m to X=4.0m). The cardinal direction Z+ is vertical, X+ is downstream, and Y+ is crossflow. Gravity is -9.81 m / s^2 in the Z direction. - -The case is initialized with a still water level of 0.25 meters. The velocity at the inlet is given a time history boundary condition, ``src/VelTime.csv``. - -This structure is a simple cylinder. It has a diameter 0.1 meters and it is located at X=1.5, Y=0.0, Z=0.0. The length of the cylinder is 0.5 meters in Z+. - -The cylinder is represented in OpenSees by a cantilevered beam, with an elastic section, modelled with displacement-action controlled beam elements. The bottom of the cantilevered beam is fixed at Z=0.0. - -The constrained node is removed from the coupled solution, by omitting it from the list *coupledNodes* in the OpenSees model file. - -The interface surface file is ``'src/interface.stl'``. - - - -.. _hdro-0003-fig-schematic: - -.. figure:: figures/hdro-0003 example.png - :align: center - :width: 600 - :figclass: align-center - - Schematic of the digital twin example in the UW WASIRF truncated flume - -Probe positions in the digital flume are set at the following locations: - -.. figure:: figures/hdro-0003 example probeLoc.png - :align: center - :width: 600 - :figclass: align-center - - Instrumentation locations in theUW WASIRF truncated digital flume - -Inlet Velocity Time History (U(t)) for the truncated digital twin is given by the following function in OpenFOAM: - -.. figure:: figures/inletVTH.png - :align: center - :width: 600 - :figclass: align-center - - Inlet Velocity Time History for the UW WASIRF digital twin - - -We now have a coupled simulation configured for fluid flow around, and the structural response of, a cylinder. Next, we will run the simulation on a remote TACC high-performance computing system. - - -.. _hdro-0003-simulation: - -Simulation ----------- - -Login to DesignSafe and submit the job to run remotely on a TACC system, either *Frontera* or *Stampede3*. - -Simulation time for 1 second in the digital flume took 1 hour and 20 minutes. This was using one computational node on TACC Frontera, possessing 56 cores. - -The case can be run for as long as desired, but mind that the longer the case runs, the longer the postprocessing routines will be. - -In order to retrieve results from the analysis, the job must complete and postprocess the model output files into a VTK format before the end of the allotted submission time. - -.. important:: - Provide a large amount of time for the *Max Run Time* field in HydroUQ when submitting a job to ensure the model completes before the time allotted runs out! - -.. note:: - Be aware that the smaller the OpenFOAM Outputs and OpenSees Outputs *Time Interval* value is, the longer the post processing of the case will take after analysis has completed, - and the larger the ``results.zip`` folder will be. - -.. warning:: - Be modest when requesting simulation outputs across many recording probes or full geometry snapshots. - Only ask for what you need, or your simulation will become slow due to I/O constraints and the output data will be too large to effecitvely post-process or host on your local machine. - - - - -.. _hdro-0003-results: - -Results ------------ - -First, we must retrieve the ``results.zip`` folder from the DesignSafe file storage. This zip file will contain all our from the Tools and Applications Page of Design Safe - -.. figure:: figures/DSToolsAndAppsJobsStatus.PNG - :align: center - :width: 600 - :figclass: align-center - - Locating the job files on DesignSafe - -Check if the job has finished. If it has, click 'More info'. - -.. figure:: figures/DSToolsAndAppsJobsStatusFinished.PNG - :align: center - :width: 600 - :figclass: align-center - - Once the job is finished, the output files should be available in the directory which the analysis results were sent to - -Find the files by clicking 'View'. - -.. figure:: figures/DSToolsAndAppsJobsStatusViewFiles.PNG - :align: center - :width: 600 - :figclass: align-center - - Directory shown on DesignSafe contains the ``results.zip`` output for a HydroUQ EVT simulation. Download the results.zip folder to your local machine to view the model results. - - -Move the ``results.zip`` to somewhere in ``My Data/``. Use the Extractor tool available on DesignSafe. Unzip the ``results.zip`` folder. - -.. figure:: figures/extractonDS.PNG - :align: center - :width: 600 - :figclass: align-center - - -OR Download the ``results.zip`` folder to your PC and unzip to look at the model results. - -.. figure:: figures/downloadResults.PNG - :align: center - :width: 600 - :figclass: align-center - - Download the results to look at the VTK files of the analysis. This will include OpenFOAM and OpenSees field data and model geometry - -Extract the Zip folder either on DesignSafe or on your local machine. You will need Paraview to view the model data. - -.. figure:: figures/resultsZip.png - :align: center - :width: 600 - :figclass: align-center - - Locate the zip folder and extract it to somewhere convenient - -The results folder should look something like this. - -.. figure:: figures/results.png - :align: center - :width: 600 - :figclass: align-center - - This is the output of the model - - - -.. _hdro-0003-analysis: - -Analysis --------- - -Paraview files have a .PVD extension. Open VTK/Fluid.vtm.series to look at OpenFOAM results. -Open OpenSeesOutput.pvd to look at OpenSees results. - -.. figure:: figures/Paraview.PNG - :align: center - :width: 600 - :figclass: align-center - - This is the model output data as seen from ParaView - -OpenSees Displacements And Reactions - - -.. figure:: figures/TipDisplacement.png - :align: center - :width: 600 - :figclass: align-center - - This is the model output data as seen from ParaView - -.. figure:: figures/ReactionForces.png - :align: center - :width: 600 - :figclass: align-center - - This is the model output data as seen from ParaView - - -OpenFOAM probe and function object output is available in ``results/postProcessing/``. OpenFOAM output is currently unorganized. An example Matlab script is provided in the ``src/`` directory to post process the OpenFOAM output for this particular case and output. -This file can be modified to work for any case. The names of the data folders will need to be changed according to the name of the probe given in HydroUQ. - -.. figure:: figures/MatlabScriptCopyToLocation.PNG - :align: center - :width: 600 - :figclass: align-center - In the /src/ folder in the hrdo-0003 folder, an example matlab script is provided to look at time history data of the output probes - - -OpenFOAM Calculated Story Forces are - -.. figure:: figures/storyForces.png - :align: center - :width: 600 - :figclass: align-center - - Story Forces in OpenFOAM - -OpenFOAM Calculated Coupled Interface Forces are visualized in the following figure - -.. figure:: figures/Forces.png - :align: center - :width: 600 - :figclass: align-center - - Coupled Interface Forces in OpenFOAM-OpenSees - -OpenFOAM calculated, coupled interface moments at the structural surface are - -.. figure:: figures/Moments.png - :align: center - :width: 600 - :figclass: align-center - - Coupled Interface Moments in OpenFOAM-OpenSees - -OpenFOAM calculated pressure probe values throughout the flume are - -.. figure:: figures/Pressures.png - :align: center - :width: 600 - :figclass: align-center - Pressure Probe Values in OpenFOAM - -OpenFOAM calculated fluid velocity probe values throughout the flume are - -.. figure:: figures/Velocities.png - :align: center - :width: 600 - :figclass: align-center - - Velocity Probe Values in OpenFOAM - - -OpenFOAM calculated wave gauge free-surface values at key locations in the facility are - -.. figure:: figures/WaveGauges.png - :align: center - :width: 600 - :figclass: align-center - - Wave Gauge Free-Surface Probe Values in OpenFOAM - -This completes the analysis of the model. In validation of any flume experimental case, a similar process may be employed with an added step of comparison to experimental data. - - - -.. _hdro-0003-references: - -References ----------- - -.. [Lewis2023] - Lewis, N. (2023). Development of An Open-Source Methodology for Simulation of Civil Engineering Structures Subject to Multi-Hazards. *PhD thesis*, University of Washington, Seattle, WA. ISBN: 979-8-381408-69-0. - -.. [OpenFOAM] - OpenFOAM. OpenFOAM Foundation. https://www.openfoam.com/ - -.. [OpenSees] - OpenSees. Pacific Earthquake Engineering Research Center. http://opensees.berkeley.edu/ - -.. [Paraview] - Paraview. Kitware. https://www.paraview.org/ - -.. [DesignSafe] - DesignSafe**. DesignSafe-CI. https://www.designsafe-ci.org/ - -.. [TACC] - TACC. Texas Advanced Computing Center. https://www.tacc.utexas.edu/ - -.. [Frontera] - Frontera. Texas Advanced Computing Center. https://frontera-portal.tacc.utexas.edu/ - -.. [Stampede3] - Stampede3. Texas Advanced Computing Center. https://stampede2.tacc.utexas.edu/ - - - - - - - +.. _hdro-0003: + +======================================================================================= +Cylinder Half-Submerged in Flow - UW WASIRF Twin - FOAMySees (OpenFOAM + OpenSees) +======================================================================================= + ++---------------+------------------------------------------------------------------------------------------------------+ +| Problem files | :github:`Github ` | ++---------------+------------------------------------------------------------------------------------------------------+ + + +.. contents:: Table of Contents + :local: + :backlinks: none + +.. _hdro-0003-overview: + +Overview +-------- + +This example demonstrates how to run a coupled **OpenSees-OpenFOAM** simulation (**FOAMySees**) to determine floor loads on a building caused by strongly-coupled, two-way fluid-structure interaction. +You can then perform an **OpenSees** simulation of the building assuming uncertainties in the building properties. + +A truncated digital twin of the UW WASIRF wave flume contains a simple cantilevered cylinder. The cylinder, our structure, is half-submerged. The flow around the cylinder is calculated for a given period of time in order to determine a simulated structural response time-series under wave loading. + +Outputs of the **EVT** simulation will include results, sampled at specified frequenies, for the: + +#. Fluid flow's free surface elevation at wave gauges +#. Flow velocity at velocimeter locations +#. Fluid pressure at piezometers locations +#. FSI forces and moments at the structural interface +#. Cross-section cuts of the OpenFOAM continuum + +As the **EVT** and **FEM** functionality are effectively fused for FOAMySees, the **FEM** tab will be envisioned as providing additional results in the form of: + +#. Time-series motion of any structural nodes with defined *recorders* in the **OpenSees** model. + +The **EDP** tab will then process these results. + +#. Displacement of the cylinder tip from rest, peak relative-floor displacement (PFD) +#. Displacement of the cylinder tip relative to its base or supporting , peak inter-story drift (PID) +#. Peak floor acceleration (PFA) + + +.. _hdro-0003-setup: + +Set-Up +------ + +The case is set up in the HydroUQ tool on DesignSafe. You can select the case from the list of available examples off of the HydroUQ menubar, i.e. ``Examples / hdro-0003``. The case is set up as follows. + +The flume is 1 meter wide (from Y=-0.5m to Y=0.5 m), 1 meter tall (Z=0.0m to Z=1.0m), and 4 meters long (X=0.0m to X=4.0m). The cardinal direction Z+ is vertical, X+ is downstream, and Y+ is crossflow. Gravity is -9.81 m / s^2 in the Z direction. + +The case is initialized with a still water level of 0.25 meters. The velocity at the inlet is given a time history boundary condition, ``src/VelTime.csv``. + +This structure is a simple cylinder. It has a diameter 0.1 meters and it is located at X=1.5, Y=0.0, Z=0.0. The length of the cylinder is 0.5 meters in Z+. + +The cylinder is represented in OpenSees by a cantilevered beam, with an elastic section, modelled with displacement-action controlled beam elements. The bottom of the cantilevered beam is fixed at Z=0.0. + +The constrained node is removed from the coupled solution, by omitting it from the list *coupledNodes* in the OpenSees model file. + +The interface surface file is ``'src/interface.stl'``. + + + +.. _hdro-0003-fig-schematic: + +.. figure:: figures/hdro-0003 example.png + :align: center + :width: 600 + :figclass: align-center + + Schematic of the digital twin example in the UW WASIRF truncated flume + +Probe positions in the digital flume are set at the following locations: + +.. figure:: figures/hdro-0003 example probeLoc.png + :align: center + :width: 600 + :figclass: align-center + + Instrumentation locations in theUW WASIRF truncated digital flume + +Inlet Velocity Time History (U(t)) for the truncated digital twin is given by the following function in OpenFOAM: + +.. figure:: figures/inletVTH.png + :align: center + :alt: A line graph titled "Inlet Velocity TH" showing a progressive increase in velocity (y-axis) over time (x-axis). The vertical y-axis is labeled "Velocity [m/s]" with values ranging from 0 to 0.6 m/s in increments of 0.1, and the horizontal x-axis is labeled "Time [s]" with values ranging from 0 to 12 seconds in increments of 2. The line starts at the origin and shows a curved increase, plateauing slightly as it approaches 0.6 m/s near the 10-second mark. The curve suggests a smooth and consistent acceleration of velocity over time. + :width: 600 + :figclass: align-center + + Inlet Velocity Time History for the UW WASIRF digital twin + + +We now have a coupled simulation configured for fluid flow around, and the structural response of, a cylinder. Next, we will run the simulation on a remote TACC high-performance computing system. + + +.. _hdro-0003-simulation: + +Simulation +---------- + +Login to DesignSafe and submit the job to run remotely on a TACC system, either *Frontera* or *Stampede3*. + +Simulation time for 1 second in the digital flume took 1 hour and 20 minutes. This was using one computational node on TACC Frontera, possessing 56 cores. + +The case can be run for as long as desired, but mind that the longer the case runs, the longer the postprocessing routines will be. + +In order to retrieve results from the analysis, the job must complete and postprocess the model output files into a VTK format before the end of the allotted submission time. + +.. important:: + Provide a large amount of time for the *Max Run Time* field in HydroUQ when submitting a job to ensure the model completes before the time allotted runs out! + +.. note:: + Be aware that the smaller the OpenFOAM Outputs and OpenSees Outputs *Time Interval* value is, the longer the post processing of the case will take after analysis has completed, + and the larger the ``results.zip`` folder will be. + +.. warning:: + Be modest when requesting simulation outputs across many recording probes or full geometry snapshots. + Only ask for what you need, or your simulation will become slow due to I/O constraints and the output data will be too large to effecitvely post-process or host on your local machine. + + + + +.. _hdro-0003-results: + +Results +----------- + +First, we must retrieve the ``results.zip`` folder from the DesignSafe file storage. This zip file will contain all our from the Tools and Applications Page of Design Safe + +.. figure:: figures/DSToolsAndAppsJobsStatus.PNG + :align: center + :alt: Screenshot of a web interface for a simulation platform titled 'TOOLS & APPLICATIONS'. On the top are tabs labeled 'Simulation', 'SimCenter Tools', 'Visualization', 'Analysis', 'Hazard Apps', 'Utilities', and 'My Apps'. To the left is a 'DATA DEPOT BROWSER' showing directories and files with names like 'Trash', 'archive', and 'Hydro-UQ'. The center section states 'SELECT AN APP' and describes how to pick an application from the tabs above, mentioning tools like OpenSees, ADCIRC, OpenFOAM, Jupyter, MATLAB, Paraview, and VisIt. To the right is a 'JOBS STATUS' section showing a list of tasks with names like 'HydroUQ: hdra-0003Short' and 'HydroUQ: Example002Shorter', indicating their statuses as 'RUNNING' or 'FINISHED'. + :width: 600 + :figclass: align-center + + Locating the job files on DesignSafe + +Check if the job has finished. If it has, click 'More info'. + +.. figure:: figures/DSToolsAndAppsJobsStatusFinished.PNG + :align: center + :alt: A graphical user interface element showing a status tag with the word "FINISHED" next to a button labeled "More info" which includes an information icon consisting of a lowercase "i" within a circle. + :width: 600 + :figclass: align-center + + Once the job is finished, the output files should be available in the directory which the analysis results were sent to + +Find the files by clicking 'View'. + +.. figure:: figures/DSToolsAndAppsJobsStatusViewFiles.PNG + :align: center + :alt: A screenshot of a computer interface showing the details of a completed job in an application. The Application name is "simcenter-openfoam-frontera-1.0.0," and there is a unique Job ID provided. The status indicates "FINISHED," and the submission and completion times are listed as "Oct 8, 2023 7:53:52 AM" and "Oct 8, 2023 10:36:54 AM" respectively. The Last Status Message states "Transitioning from status ARCHIVING to FINISHED in phase ARCHIVING." There are buttons for "View" with an arrow indicating it, and "Delete" under the Output and Actions sections. There is also a "Close" button at the bottom right corner. + :width: 600 + :figclass: align-center + + Directory shown on DesignSafe contains the ``results.zip`` output for a HydroUQ EVT simulation. Download the results.zip folder to your local machine to view the model results. + + +Move the ``results.zip`` to somewhere in ``My Data/``. Use the Extractor tool available on DesignSafe. Unzip the ``results.zip`` folder. + +.. figure:: figures/extractonDS.PNG + :align: center + :alt: Screenshot of a software interface with tabs labeled "Simulation," "SimCenter Tools," "Visualization," "Analysis," "Hazard Apps," "Utilities," and "My Apps." Under the "SimCenter Tools" tab, two options are shown: "Compress Files" with a symbol representing compression, and "Extract Compressed File" highlighted in blue with a corresponding symbol of a file being extracted. Below is a button with the text "RUN EXTRACT COMPRESSED FILE." + :width: 600 + :figclass: align-center + + +OR Download the ``results.zip`` folder to your PC and unzip to look at the model results. + +.. figure:: figures/downloadResults.PNG + :align: center + :alt: Screenshot of a data management interface showing a directory listing with files and folders. At the top, there are search and action buttons like "Rename," "Move," "Copy," "Preview," "Preview Images," "Download," and "Move to Trash." The "Download" button is encircled, highlighting it. The main panel lists files such as "agave.log," "hydroqu-example002shorter-*-out," and "results.zip," with details on file size and the date of last modification. The file "results.zip" is selected with a green checkmark. + :width: 600 + :figclass: align-center + + Download the results to look at the VTK files of the analysis. This will include OpenFOAM and OpenSees field data and model geometry + +Extract the Zip folder either on DesignSafe or on your local machine. You will need Paraview to view the model data. + +.. figure:: figures/resultsZip.png + :align: center + :alt: A screenshot of a file directory interface highlighting a file named "results.zip." The directory contains other files with names like "agave.log," and files starting with "hydroqu-example002shorter," each with different file extensions such as .log, .err, and .out. The selected "results.zip" file is encircled in red, indicating its importance or selection. File sizes and last modified dates are visible next to each file, with the dates showing 10/8/23 and times ranging from 10:35 AM to 10:36 AM. + :width: 600 + :figclass: align-center + + Locate the zip folder and extract it to somewhere convenient + +The results folder should look something like this. + +.. figure:: figures/results.png + :align: center + :alt: Screenshot of a computer file explorer window showing a directory listing within the 'results' folder. There are three folders named 'postProcessing', 'SeesOutput', and 'VTK', all modified on '10/8/2023 10:30 AM'. Below the folders, there is a PVD file named 'OpenSeesOutput.pvd' with the same modification date and a size of 13 KB. + :width: 600 + :figclass: align-center + + This is the output of the model + + + +.. _hdro-0003-analysis: + +Analysis +-------- + +Paraview files have a .PVD extension. Open VTK/Fluid.vtm.series to look at OpenFOAM results. +Open OpenSeesOutput.pvd to look at OpenSees results. + +.. figure:: figures/Paraview.PNG + :align: center + :alt: Screenshot of a scientific visualization software interface displaying a 3D model of a simulation. The main window shows a long, rectangular object with a gradient color scale indicating displacement magnitude, from blue (no displacement) to red (maximum displacement). A small portion is highlighted with a spectrum of colors showing increased displacement. Two scale bars, one for displacement magnitude and one for a variable labelled as 'alpha.water', are visible on the right side. The software's graphical user interface, including the pipeline browser, properties, and animation view panels, frames the model display. + :width: 600 + :figclass: align-center + + This is the model output data as seen from ParaView + +OpenSees Displacements And Reactions + + +.. figure:: figures/TipDisplacement.png + :align: center + :alt: "A graph titled 'Tip Displacement VS Time' with the X-axis representing time in seconds and the Y-axis representing displacement in meters. The graph displays a line plot showing the tip displacement labeled as 'Tip Displacement_X (originalId=16 block=2)' with values starting at zero displacement, then rising sharply around 2 seconds and displaying fluctuating but generally increasing values up to around 0.0055 meters by 12 seconds." + :width: 600 + :figclass: align-center + + This is the model output data as seen from ParaView + +.. figure:: figures/ReactionForces.png + :align: center + :alt: The image depicts a line graph titled "OpenSees Reaction Forces" with the y-axis labeled "Force (N)" and the x-axis showing an unlabeled numerical scale from 0 to 10. There are three distinct lines representing 'Base Reaction_X,' 'Base Reaction_Y,' and 'Base Reaction_Z,' each annotated with '(originalId=0 block=2)' in red, green, and blue respectively. The 'Base Reaction_X' in red shows a sinusoidal pattern with amplitude decreasing over time. The 'Base Reaction_Y' in green demonstrates a more consistent, slightly undulating pattern. The 'Base Reaction_Z' in blue displays a high-frequency oscillating pattern with relatively steady amplitude. The lines overlap and intersect at various points throughout the graph. + :width: 600 + :figclass: align-center + + This is the model output data as seen from ParaView + + +OpenFOAM probe and function object output is available in ``results/postProcessing/``. OpenFOAM output is currently unorganized. An example Matlab script is provided in the ``src/`` directory to post process the OpenFOAM output for this particular case and output. +This file can be modified to work for any case. The names of the data folders will need to be changed according to the name of the probe given in HydroUQ. + +.. figure:: figures/MatlabScriptCopyToLocation.PNG + :align: center + :alt: Screenshot of a computer file explorer window with a list of directories and files inside a folder named 'postProcessing.' Most items are folders named with different labels such as 'baseForces,' 'freeSurfaceVTK,' 'interface,' and several 'PressureProbe' and 'WaveGauge' folders, all modified on '10/8/2023 10:30 AM.' One file named 'plotData.m,' identified as MATLAB Code and sized 5 KB, has a red arrow pointing to it, highlighting its size. The breadcrumb navigation path at the top indicates the 'postProcessing' folder is inside the 'results' folder, which is within another 'results' folder in the 'Downloads' directory. + :width: 600 + :figclass: align-center + In the /src/ folder in the hrdo-0003 folder, an example matlab script is provided to look at time history data of the output probes + + +OpenFOAM Calculated Story Forces are + +.. figure:: figures/storyForces.png + :align: center + :alt: A set of three line graphs titled "Story Forces", with each graph depicting force over time in seconds for three stories (levels) of a structure, along the X, Y, and Z axes. The top chart shows forces in the X direction, with lines for Story 1 X Force, Story 2 X Force, and Story 3 X Force, oscillating and diverging slightly. The middle chart depicts forces in the Y direction with similar oscillating patterns. The bottom chart shows forces in the Z direction, with the lines for Story 1 Z Force and Story 2 Z Force remaining almost constant and close to zero, while the Story 3 Z Force shows minor oscillation. Each force is measured in Newtons (N) and the time spans from 0 to 10 seconds. + :width: 600 + :figclass: align-center + + Story Forces in OpenFOAM + +OpenFOAM Calculated Coupled Interface Forces are visualized in the following figure + +.. figure:: figures/Forces.png + :align: center + :alt: A line graph titled "FSI Interface Forces" displaying three differently colored lines representing force in the X, Y, and Z directions over a period of 10 seconds. The X-force (blue) exhibits a significant increase and fluctuations, peaking just below 7 N. The Y-force (orange) shows smaller, regular oscillations around 0 N. The Z-force (yellow) shows minor activity around 0 N with no significant peaks. The time in seconds is on the x-axis and the force in Newtons is on the y-axis. + :width: 600 + :figclass: align-center + + Coupled Interface Forces in OpenFOAM-OpenSees + +OpenFOAM calculated, coupled interface moments at the structural surface are + +.. figure:: figures/Moments.png + :align: center + :alt: A line graph titled "FSI Interface Moments" displaying three different moment components (Mxx, Myy, Mzz) over time, measured in seconds, from 0 to 10. The Mxx component is represented by an orange line oscillating and decreasing over time. The Myy component is a blue oscillating line that becomes stable after an initial drop. The Mzz component is depicted by a yellow line that remains mostly flat across the time period. The moments are measured in Newton-meters (N*m) ranging from 0.1 to -0.7 on the y-axis. + :width: 600 + :figclass: align-center + + Coupled Interface Moments in OpenFOAM-OpenSees + +OpenFOAM calculated pressure probe values throughout the flume are + +.. figure:: figures/Pressures.png + :align: center + :alt: A line graph titled "Pressure Sensors" plotting the pressure readings from four different sensors, P1 through P4, over a time period of 10 seconds. The y-axis is labeled "Pressure [Pa]" and ranges from -2000 to 3000 Pa, while the x-axis is labeled "Time [s]" and ranges from 0 to 10 seconds. The P1 sensor reading starts at approximately 2500 Pa and decreases slightly over time, represented by a blue line. The P2 reading is an orange line starting around 1700 Pa and also decreases. The P3 reading, in a yellow line, begins just under 1000 Pa and follows the same downward trend. The P4 sensor reading is a purple line that remains flat close to 0 Pa throughout the period. All lines show a smooth and gradual decline except P4, which is constant. + :width: 600 + :figclass: align-center + Pressure Probe Values in OpenFOAM + +OpenFOAM calculated fluid velocity probe values throughout the flume are + +.. figure:: figures/Velocities.png + :align: center + :alt: A line graph titled "Velocity Probe" with the X-axis labeled "Time [s]" ranging from 0 to 10 seconds, and the Y-axis labeled "Velocity [m/s]" ranging from -0.1 to 0.6 meters per second. There are three lines representing velocity components in X, Y, and Z directions. The X component shows a rising curve starting from zero and approaching approximately 0.6 m/s. The Y and Z components are relatively flat, hovering near zero throughout the graph. A legend in the upper right corner matches the X component with blue, the Y component with orange, and the Z component with grey, indicating the velocity in each respective axis. + :width: 600 + :figclass: align-center + + Velocity Probe Values in OpenFOAM + + +OpenFOAM calculated wave gauge free-surface values at key locations in the facility are + +.. figure:: figures/WaveGauges.png + :align: center + :alt: A line graph titled "Wave Gauges" tracking free surface elevation (in meters) against time (in seconds) from 0 to 10 seconds. Seven different lines representing wave gauges WG1 through WG7 exhibit various oscillating patterns with a notable spike and subsequent oscillations starting at approximately 3.5 seconds. The legend in the upper right corner associates each wave gauge with a different color line on the graph. + :width: 600 + :figclass: align-center + + Wave Gauge Free-Surface Probe Values in OpenFOAM + +This completes the analysis of the model. In validation of any flume experimental case, a similar process may be employed with an added step of comparison to experimental data. + + + +.. _hdro-0003-references: + +References +---------- + +.. [Lewis2023] + Lewis, N. (2023). Development of An Open-Source Methodology for Simulation of Civil Engineering Structures Subject to Multi-Hazards. *PhD thesis*, University of Washington, Seattle, WA. ISBN: 979-8-381408-69-0. + +.. [OpenFOAM] + OpenFOAM. OpenFOAM Foundation. https://www.openfoam.com/ + +.. [OpenSees] + OpenSees. Pacific Earthquake Engineering Research Center. http://opensees.berkeley.edu/ + +.. [Paraview] + Paraview. Kitware. https://www.paraview.org/ + +.. [DesignSafe] + DesignSafe**. DesignSafe-CI. https://www.designsafe-ci.org/ + +.. [TACC] + TACC. Texas Advanced Computing Center. https://www.tacc.utexas.edu/ + +.. [Frontera] + Frontera. Texas Advanced Computing Center. https://frontera-portal.tacc.utexas.edu/ + +.. [Stampede3] + Stampede3. Texas Advanced Computing Center. https://stampede2.tacc.utexas.edu/ + + + + + + + diff --git a/Examples/hdro-0004/README.rst b/Examples/hdro-0004/README.rst index a2a5c97..38ac285 100644 --- a/Examples/hdro-0004/README.rst +++ b/Examples/hdro-0004/README.rst @@ -1,245 +1,265 @@ -.. _hdro-0004: - -=============================================================================== -Tsunami Debris Motion Through a Scaled Port Setting - WU TWB Digital Twin - MPM -=============================================================================== - -+---------------+----------------------------------------------+ -| Problem files | :github:`Github ` | -+---------------+----------------------------------------------+ - -.. contents:: Table of Contents - :local: - :backlinks: none - -.. _hdro-0004-overview: - -Outline -------- - -Example to demonstrate how to run a MPM simulation to determine loads on an array of port buildings during a tsunami with respect to debris impacts and damming. After, we perform -an OpenSees simulation of one building assuming uncertainties in the building properties. - -The Waseda University Tsunami Wave Basin (WU TBW) flume is 4 meter wide (from X=-2m to X=2 m), 1 meter tall (Z=0.0m to Z=1.0m), and 9 meters long (Y=0.0m to Y=9.0m). - -The case is initialized with a still water level of 0.23 meters. - -Results for free surface, velocity, and pressure, as well as structural load forces are output at a specified interval to match experimental instruments. - - - -.. figure:: figures/TOKYO_BoreFrontImage_Debris3_o5x1_Frame20_29072023.png - :align: center - :width: 600 - :figclass: align-center - - Simulation of MPM debris impacts on one row of five obstacles - - -.. figure:: figures/B4_Flume_Schematic.png - :align: center - :width: 600 - :figclass: align-center - - Schematic of the flume and sensor locations - - -.. figure:: figures/B4_Debris_Picture.PNG - :align: center - :width: 600 - :figclass: align-center - - Smart debris used in experiments - - -.. _hdro-0004-simulation: - -Simulation ----------- - -Simulation Time: 6 seconds - Ran on TACC Lonestar6, 56 processors, 3 NVIDIA A100 GPUs, 1 node -> Real Time: 1hr, 20 minutes - -The case can be run for as long as desired, but mind that the longer the case runs, the longer the postprocessing routines will be. - -In order to retrieve results from the analysis, the analysis must complete and postprocess the model output files into a VTK format before the end of the allotted submission time. - -Provide a large amount of time for the 'Max Run Time' field in HydroUQ when submitting a job to ensure the model completes before the time allotted runs out! - -Be aware that the smaller the OpenFOAM Outputs and OpenSees Outputs 'Time Interval' value is, the longer the post processing of the case will take after analysis has completed, and the larger the results.zip folder will be. - -.. warning:: - Use caution when requesting sensors and using high sampling rates. Only ask for what you need, or you will end up will massive amounts of data. - - - -.. _hdro-0004-analysis: - -Analysis --------- - -Retrieving the results.zip folder from the Tools and Applications Page of Design Safe.. - -.. figure:: figures/DSToolsAndAppsJobsStatus.PNG - :align: center - :width: 600 - :figclass: align-center - - Locating the job files on DesignSafe - -Check if the job has finished. If it has, click 'More info'. - -.. figure:: figures/DSToolsAndAppsJobsStatusFinished.PNG - :align: center - :width: 600 - :figclass: align-center - - Once the job is finished, the output files should be available in the directory which the analysis results were sent to - -Find the files by clicking 'View'. - -.. figure:: figures/DSToolsAndAppsJobsStatusViewFiles.PNG - :align: center - :width: 600 - :figclass: align-center - - Locating this directory is easy. - - -Move the results.zip to somewhere in My Data/. Use the Extractor tool available on DesignSafe. Unzip the results.zip folder. - -.. figure:: figures/extractonDS.PNG - :align: center - :width: 600 - :figclass: align-center - - -OR Download the results.zip folder to your PC and unzip to look at the model results. - -.. figure:: figures/downloadResults.PNG - :align: center - :width: 600 - :figclass: align-center - - Download the results to look at the VTK files of the analysis. This will include OpenFOAM and OpenSees field data and model geometry - -Extract the Zip folder either on DesignSafe or on your local machine. You will need Paraview to view the model data. - -.. figure:: figures/resultsZip.png - :align: center - :width: 600 - :figclass: align-center - - Locate the zip folder and extract it to somewhere convenient - - -.. The results folder should look something like this. - -.. .. figure:: figures/results.png -.. :align: center -.. :width: 600 -.. :figclass: align-center - -.. This is the output of the model - -.. Paraview files have a .PVD extension. Open VTK/Fluid.vtm.series to look at OpenFOAM results. -.. Open OpenSeesOutput.pvd to look at OpenSees results. - -.. .. figure:: figures/Paraview.PNG -.. :align: center -.. :width: 600 -.. :figclass: align-center - -.. This is the model output data as seen from ParaView - -.. OpenSees Displacements And Reactions - -.. .. figure:: figures/TipDisplacement.png -.. :align: center -.. :width: 600 -.. :figclass: align-center - -.. This is the model output data as seen from ParaView - -.. .. figure:: figures/ReactionForces.png -.. :align: center -.. :width: 600 -.. :figclass: align-center - -.. This is the model output data as seen from ParaView - - -.. OpenFOAM probe and function object output is available in results/postProcessing/. - -.. OpenFOAM output is messy. An example Matlab script is provided in the /src/ directory to post process the OpenFOAM output for this particular case and output. -.. This file can be modified to work for any case. The names of the data folders will need to be changed according to the name of the probe given in HydroUQ. - -.. .. figure:: figures/MatlabScriptCopyToLocation.PNG -.. :align: center -.. :width: 600 -.. :figclass: align-center -.. In the /src/ folder in the hdro-0004 folder, an example matlab script is provided to look at time history data of the output probes - - -.. OpenFOAM Calculated Story Forces - -.. .. figure:: figures/storyForces.png -.. :align: center -.. :width: 600 -.. :figclass: align-center - -.. Story Forces - -.. OpenFOAM Calculated Coupled Interface Forces - -.. .. figure:: figures/Forces.png -.. :align: center -.. :width: 600 -.. :figclass: align-center - -.. Forces - -.. OpenFOAM Calculated Coupled Interface Moments - -.. .. figure:: figures/Moments.png -.. :align: center -.. :width: 600 -.. :figclass: align-center - -.. Moments - -.. OpenFOAM Calculated Pressure Probe Values - -.. .. figure:: figures/Pressures.png -.. :align: center -.. :width: 600 -.. :figclass: align-center - -.. Pressures - -.. OpenFOAM Calculated Velocity Probe Values - -.. .. figure:: figures/Velocities.png -.. :align: center -.. :width: 600 -.. :figclass: align-center -.. Velocities - - -.. OpenFOAM Calculated Free Surface Values - -.. .. figure:: figures/WaveGauges.png -.. :align: center -.. :width: 600 -.. :figclass: align-center - -.. Wave Gauges - - -.. _hdro-0004-references: - -References ----------- - - - - +.. _hdro-0004: + +=============================================================================== +Tsunami Debris Motion Through a Scaled Port Setting - WU TWB Digital Twin - MPM +=============================================================================== + ++---------------+----------------------------------------------+ +| Problem files | :github:`Github ` | ++---------------+----------------------------------------------+ + +.. contents:: Table of Contents + :local: + :backlinks: none + +.. _hdro-0004-overview: + +Outline +------- + +Example to demonstrate how to run a MPM simulation to determine loads on an array of port buildings during a tsunami with respect to debris impacts and damming. After, we perform +an OpenSees simulation of one building assuming uncertainties in the building properties. + +The Waseda University Tsunami Wave Basin (WU TBW) flume is 4 meter wide (from X=-2m to X=2 m), 1 meter tall (Z=0.0m to Z=1.0m), and 9 meters long (Y=0.0m to Y=9.0m). + +The case is initialized with a still water level of 0.23 meters. + +Results for free surface, velocity, and pressure, as well as structural load forces are output at a specified interval to match experimental instruments. + + + +.. figure:: figures/TOKYO_BoreFrontImage_Debris3_o5x1_Frame20_29072023.png + :align: center + :alt: A digital simulation of fluid dynamics showing wave patterns interacting with a series of solid objects. The simulated water has a clear blue gradient, and the waves are visualized as lines that bend and spread around the brown cuboid objects. There are also dark shadows beneath the objects, suggesting depth in the water. In the foreground, there's a noticeable rectangular outline representing a boundary or a measurement tool. The image has a watermark with the text "Houdini," indicating that the simulation was likely created using the Houdini visual effects software. + :width: 600 + :figclass: align-center + + Simulation of MPM debris impacts on one row of five obstacles + + +.. figure:: figures/B4_Flume_Schematic.png + :align: center + :alt: Technical diagrams depicting the top-down (plain) and side (profile) views of a wave propagation testing setup with labeled components such as flow direction, air valves, wave markers (WG1, WG2), electronic current meters (ECM1), cameras (CAM1, CAM2), locators, debris, fixed obstacles, and a harbor apron area. The diagrams include measurements for spacing and sizes of components in millimeters, and depth specifications for the testing section. + :width: 600 + :figclass: align-center + + Schematic of the flume and sensor locations + + +.. figure:: figures/B4_Debris_Picture.PNG + :align: center + :alt: The image depicts two panels, labeled (a) and (b), showing a green plastic object with specific dimensions. In panel (a), two identical green plastic casings with a rectangular base and two cylindrical towers on one end are presented alongside small black components. One casing has a black switch or button installed. In panel (b), a close-up view of one green casing is shown, featuring two holes on its surface, with a scale indicating a length of 0.15 meters, and measurement markers for depth at 0.05 meters on the side. + :width: 600 + :figclass: align-center + + Smart debris used in experiments + + +.. _hdro-0004-simulation: + +Simulation +---------- + +Simulation Time: 6 seconds - Ran on TACC Lonestar6, 56 processors, 3 NVIDIA A100 GPUs, 1 node -> Real Time: 1hr, 20 minutes + +The case can be run for as long as desired, but mind that the longer the case runs, the longer the postprocessing routines will be. + +In order to retrieve results from the analysis, the analysis must complete and postprocess the model output files into a VTK format before the end of the allotted submission time. + +Provide a large amount of time for the 'Max Run Time' field in HydroUQ when submitting a job to ensure the model completes before the time allotted runs out! + +Be aware that the smaller the OpenFOAM Outputs and OpenSees Outputs 'Time Interval' value is, the longer the post processing of the case will take after analysis has completed, and the larger the results.zip folder will be. + +.. warning:: + Use caution when requesting sensors and using high sampling rates. Only ask for what you need, or you will end up will massive amounts of data. + + + +.. _hdro-0004-analysis: + +Analysis +-------- + +Retrieving the results.zip folder from the Tools and Applications Page of Design Safe.. + +.. figure:: figures/DSToolsAndAppsJobsStatus.PNG + :align: center + :alt: Screenshot of a software interface labeled "TOOLS & APPLICATIONS" with several sections. On the left, there is a "DATA DEPOT BROWSER" with a list of items including Trash, archive, and Hydro-UQ. In the center, a large heading says "SELECT AN APP," followed by a description of the Tools & Applications space capabilities, mentioning simulation codes like OpenSees, ADCIRC, OpenFOAM, and visualization tools like Jupyter, MATLAB, Paraview, and VisIt. On the right, there is a "JOBS STATUS" section listing several jobs related to HydroUQ with statuses like 'RUNNING' and 'FINISHED.' The top navigation tabs include Simulation, SimCenter Tools, Visualization, Analysis, Hazard Apps, Utilities, and My Apps. + :width: 600 + :figclass: align-center + + Locating the job files on DesignSafe + +Check if the job has finished. If it has, click 'More info'. + +.. figure:: figures/DSToolsAndAppsJobsStatusFinished.PNG + :align: center + :alt: A screenshot of a button with the word "FINISHED" in bold lettering next to a clickable link or button labeled "More info" with an information icon, which is placed on a light green background. + :width: 600 + :figclass: align-center + + Once the job is finished, the output files should be available in the directory which the analysis results were sent to + +Find the files by clicking 'View'. + +.. figure:: figures/DSToolsAndAppsJobsStatusViewFiles.PNG + :align: center + :alt: Screenshot of a job status interface showing that a computational job has finished. It includes the application name 'simcenter-openfoam-frontera-1.0.0', a unique Job ID, the status 'FINISHED', submission and finish timestamps, and a last status message indicating a transition from 'ARCHIVING' to 'FINISHED'. There is an 'Output' section with a 'View' button indicated by a red arrow, and an 'Actions' section with a 'Delete' button. A 'Close' button is also visible at the bottom right corner. + :width: 600 + :figclass: align-center + + Locating this directory is easy. + + +Move the results.zip to somewhere in My Data/. Use the Extractor tool available on DesignSafe. Unzip the results.zip folder. + +.. figure:: figures/extractonDS.PNG + :align: center + :alt: Screenshot of a computer interface with menu tabs labeled Simulation, SimCenter Tools, Visualization, Analysis, Hazard Apps, Utilities, and My Apps. Two options are displayed under the SimCenter Tools tab: "Compress Files" with an icon of a file being compressed and "Extract Compressed File" highlighted in blue with an icon of a file being extracted. + :width: 600 + :figclass: align-center + + +OR Download the results.zip folder to your PC and unzip to look at the model results. + +.. figure:: figures/downloadResults.PNG + :align: center + :alt: A screenshot of a file management interface displaying a list of files within a directory labeled "archive / jobs / job-3c316421-dfe5-47bc-98b2-f339e08d9a19-007." The files shown include 'agave.log,' 'hydroqu-example002shorter._____.err,' 'hydroqu-example002shorter._____.out,' and 'results.zip,' with 'results.zip' being selected. File sizes and last modified dates are visible next to each file. Above the file list, there are toolbar options including 'Rename,' 'Move,' 'Copy,' 'Preview,' 'Preview Images,' 'Download,' and 'Move to Trash,' with the 'Download' button encircled presumably to indicate its function. + :width: 600 + :figclass: align-center + + Download the results to look at the VTK files of the analysis. This will include OpenFOAM and OpenSees field data and model geometry + +Extract the Zip folder either on DesignSafe or on your local machine. You will need Paraview to view the model data. + +.. figure:: figures/resultsZip.png + :align: center + :alt: Screenshot of a file manager window with a directory listing including files such as "agave.log," "hydrouq-example002shorter-3c316421.err," "hydrouq-example002shorter-3c316421.out," and a highlighted file named "results.zip." The "results.zip" file is 962.1 MB in size and was last modified on 10/8/23 at 10:36 AM. Other files vary in size and share similar modification times. + :width: 600 + :figclass: align-center + + Locate the zip folder and extract it to somewhere convenient + + +.. The results folder should look something like this. + +.. .. figure:: figures/results.png +.. :align: center + :alt: Screenshot of a file explorer window showing a directory named 'results' within a larger 'results' folder. There are three subfolders named 'postProcessing,' 'SeesOutput,' and 'VTK,' and one PVD file named 'OpenSeesOutput.pvd,' all with the 'Date modified' timestamp of '10/8/2023 10:30 AM.' The 'Size' is visible only for the 'OpenSeesOutput.pvd' file, which is 13 KB. +.. :width: 600 +.. :figclass: align-center + +.. This is the output of the model + +.. Paraview files have a .PVD extension. Open VTK/Fluid.vtm.series to look at OpenFOAM results. +.. Open OpenSeesOutput.pvd to look at OpenSees results. + +.. .. figure:: figures/Paraview.PNG +.. :align: center + :alt: Screenshot of a scientific visualization software interface displaying a 3D model of a fluid simulation. The model shows a color gradient representing displacement magnitude on a rectangular domain with a central vertical structure experiencing more displacement, indicated by a column of red and orange colors. Two legend bars illustrate the range of displacement magnitudes and water volume fraction (alpha.water) values. The interface contains various toolbars, a pipeline browser, properties panel, and an animation timeline view. +.. :width: 600 +.. :figclass: align-center + +.. This is the model output data as seen from ParaView + +.. OpenSees Displacements And Reactions + +.. .. figure:: figures/TipDisplacement.png +.. :align: center + :alt: A line graph titled "Tip Displacement VS Time" with the x-axis representing time and the y-axis representing displacement in meters. The line, labeled "Tip Displacement_X (originalId=16 block=2)", shows a fluctuating increase in displacement from approximately 0 to just over 0.006 meters as time progresses from -2 to 12 units. The graph line is colored in brown with a distinct zigzag pattern indicating varying displacement over time. +.. :width: 600 +.. :figclass: align-center + +.. This is the model output data as seen from ParaView + +.. .. figure:: figures/ReactionForces.png +.. :align: center + :alt: A line graph titled "OpenSees Reaction Forces," plotting three separate lines representing base reaction forces in the X, Y, and Z directions, each identified by different colors: red for X, green for Y, and blue for Z. The force values are measured in newtons (N) and the X-axis appears to be a time or step index ranging from 0 to 10. The red X-direction line shows large oscillations that increase in amplitude over time, the green Y-direction line shows smaller, consistent oscillations, and the blue Z-direction line shows medium oscillations with increasing amplitude but less regular than the X-direction. +.. :width: 600 +.. :figclass: align-center + +.. This is the model output data as seen from ParaView + + +.. OpenFOAM probe and function object output is available in results/postProcessing/. + +.. OpenFOAM output is messy. An example Matlab script is provided in the /src/ directory to post process the OpenFOAM output for this particular case and output. +.. This file can be modified to work for any case. The names of the data folders will need to be changed according to the name of the probe given in HydroUQ. + +.. .. figure:: figures/MatlabScriptCopyToLocation.PNG +.. :align: center + :alt: Screenshot of a computer file explorer window focused on the 'postProcessing' directory, which contains several file folders and a MATLAB code file named 'plotData.m' listed with details such as name, date modified, type, and size. One of the items, 'plotData.m,' is highlighted, and an arrow points to its size (5 KB) indicating a smaller file amongst the folders. All folders and files have a last modified date of '10/8/2023 10:30 AM', except for 'plotData.m' which was modified on '10/8/2023 9:49 AM'. +.. :width: 600 +.. :figclass: align-center +.. In the /src/ folder in the hdro-0004 folder, an example matlab script is provided to look at time history data of the output probes + + +.. OpenFOAM Calculated Story Forces + +.. .. figure:: figures/storyForces.png +.. :align: center + :alt: A series of three line graphs titled "Story Forces," plotted on a grid, representing forces over time in seconds for three different stories (levels). The first graph depicts X Forces, the second graph shows Y Forces, and the third graph illustrates Z Forces, each with lines representing Story 1, Story 2, and Story 3. The X and Y Forces show oscillatory patterns, while Z Forces remain relatively flat. Each story's force is color-coded: Story 1 in blue, Story 2 in orange, and Story 3 in gray. The time axis ranges from 0 to 10 seconds, and the force axis for each graph is scaled in Newtons (N) with varying ranges. +.. :width: 600 +.. :figclass: align-center + +.. Story Forces + +.. OpenFOAM Calculated Coupled Interface Forces + +.. .. figure:: figures/Forces.png +.. :align: center + :alt: A line graph titled "FSI Interface Forces" displaying three different force components over time measured in seconds (s) on the x-axis and force in newtons (N) on the y-axis. The blue line represents force in the X direction, the orange line represents force in the Y direction, and the brown line represents force in the Z direction. The blue line shows a rising sawtooth pattern starting from 0 and reaching approximately 6 N at 10 seconds. The orange line fluctuates around 0 N with small amplitude oscillations. The brown line also shows minor fluctuations with a slight downward trend towards -1 N by the end of the 10-second interval. +.. :width: 600 +.. :figclass: align-center + +.. Forces + +.. OpenFOAM Calculated Coupled Interface Moments + +.. .. figure:: figures/Moments.png +.. :align: center + :alt: A line graph titled "FSI Interface Moments" plotting three different moments (Mxx, Myy, Mzz) over time in seconds on the x-axis and moment in Newton-meters (N*m) on the y-axis. The Mxx curve is a constant line near 0, Myy shows oscillating decay, and Mzz shows a steady decrease with some oscillations. The time range is from 0 to 10 seconds and the moment range is from 0.1 to -0.7 N*m. +.. :width: 600 +.. :figclass: align-center + +.. Moments + +.. OpenFOAM Calculated Pressure Probe Values + +.. .. figure:: figures/Pressures.png +.. :align: center + :alt: A line graph titled "Pressure Sensors" displaying pressure readings in pascals from four sensors (P1, P2, P3, P4) over time in seconds. P1 starts highest, above 3000 Pa and slightly decreases over 10 seconds. P2 starts around 2250 Pa and also decreases. P3 and P4 start at approximately 1500 Pa and 250 Pa, respectively, both showing a slight downward trend. The time on the x-axis ranges from 0 to 10 seconds, and the pressure on the y-axis ranges from -2000 to 3000 Pa. Each sensor's line is color-coded: P1 in blue, P2 in orange, P3 in yellow, and P4 in purple. +.. :width: 600 +.. :figclass: align-center + +.. Pressures + +.. OpenFOAM Calculated Velocity Probe Values + +.. .. figure:: figures/Velocities.png +.. :align: center + :alt: A line graph titled "Velocity Probe" plotting velocity in meters per second (m/s) on the y-axis against time in seconds (s) on the x-axis. Three lines, labeled X, Y, and Z, represent distinct velocity components. The X-component shows a steady increase in velocity, reaching approximately 0.6 m/s at the 10-second mark. The Y and Z components are relatively flat lines hovering near zero throughout the 10-second time span. +.. :width: 600 +.. :figclass: align-center +.. Velocities + + +.. OpenFOAM Calculated Free Surface Values + +.. .. figure:: figures/WaveGauges.png +.. :align: center + :alt: A line graph titled "Wave Gauges" with free surface elevation in meters on the y-axis and time in seconds on the x-axis. Multiple lines representing different wave gauges labeled WG1 through WG7 show fluctuations in surface elevation over a period of 10 seconds. The lines exhibit a pattern of waves with varying amplitudes and frequencies, with one line in particular showing a larger amplitude with a descending oscillation. +.. :width: 600 +.. :figclass: align-center + +.. Wave Gauges + + +.. _hdro-0004-references: + +References +---------- + + + + diff --git a/Examples/hdro-0005/README.rst b/Examples/hdro-0005/README.rst index b980b58..ceee96f 100644 --- a/Examples/hdro-0005/README.rst +++ b/Examples/hdro-0005/README.rst @@ -21,6 +21,7 @@ Overview .. figure:: figures/hdro-0005_WaveTimeSeries.png :align: center + :alt: The image displays two charts related to "Wave Generation." The top chart is a time series graph showing "Wave Elevation (m)" over "Time [s]" with values ranging from roughly -5 to 5 meters, fluctuating over a period of 0 to 3500 seconds in a noisy, seemingly random pattern. The bottom chart is a spectral density graph, plotting "Spectral density [m^2/s]" from 0 to 150 against "Frequency [Hz]" from 0 to 0.4 Hz. There are two overlapping curves on this graph: one labeled "Generated," which is a line plot that peaks near 0.1 Hz and tapers off, and another labeled "Jonswap," which seems to be a reference plot closely tracking the "Generated" curve but with some minor deviations. Both charts are colored in shades of blue, with a white background and axis labels in black text. :width: 600 :figclass: align-center @@ -34,6 +35,7 @@ Set-Up .. figure:: figures/hdro-0005_UQ.png :align: center + :alt: A screenshot of a software interface with a section labeled "UQ Method" displaying settings for uncertainty quantification. The UQ Engine is set to "Dakota" with options for "Forward Propagation." Checkboxes for "Parallel Execution" and "Save Working dirs" are ticked. Under Method, "LHS" (Latin Hypercube Sampling) is selected from a dropdown menu with inputs for "# Samples" set at 5 and "Seed" also set at 5. The left sidebar shows tabs labeled UQ, GI, SIM, EVT, FEM, EDP, RV, and RES, indicating different modules or sections of the software. :width: 600 :figclass: align-center @@ -45,6 +47,7 @@ Experiments were performed in the NHERI OSU LWF, a 100 meter long flume with adj .. figure:: figures/hdro-0005_GI.png :align: center + :alt: Screenshot of a building information form with fields for name, properties, location, and units. Under properties, it includes 'Year Built' as 1990, '# Stories' as 4, 'Struct. Type' as RM1, 'Height' as 576, 'Width' as 360, 'Depth' as 360, and 'Plan Area' as 129600. Location details show 'Latitude' as 37.8715 and 'Longitude' as -122.273. Units selected are 'Force' in Kips, 'Length' in Inches, and 'Temperature' in Celsius. There is a menu on the left side with various tabs such as UQ, GI, SIM, EVT, FEM, EDP, RV, and RES. :width: 600 :figclass: align-center @@ -60,6 +63,7 @@ Qualitatively, an MPM simulation of debris impacts on a raised structure in the .. figure:: figures/hdro-0005_SIM.png :align: center + :alt: A screenshot of a user interface for a "Building Model Generator" with a dropdown menu set to "OpenSees". The interface contains fields for "Input Script" with a file path provided, "Centroid Nodes", "Response Nodes" with the value 1,3 entered, "Spatial Dimension" with the value 2, "# DOF at Nodes" with the value 3, and "Damping Ratio" with the value 0.02. On the left side, a vertical menu shows tabs for UQ, GI, SIM, EVT, and FEM, with the SIM tab currently selected. There is also a "Choose" button on the right side of the "Input Script" field. :width: 600 :figclass: align-center @@ -69,6 +73,7 @@ It appears similar in the mechanism of debris impact, stalling, and deflection r .. figure:: figures/hdro-0005_EVT.png :align: center + :alt: Screenshot of a software interface with various input fields related to "Stochastic Wave Loading". A dropdown menu for "Event Type" is set to "Stochastic Wave Loading", and another dropdown for "Stochastic Loading Model" is set to "JONSWAP". There are multiple input fields with values for parameters such as "Water Depth", "Significant Wave Height", "Peak Period", and others related to the simulation of wave conditions. At the bottom, an option for "Provide seed value" with a numerical input box is visible. The interface has a tabbed layout with tabs labeled UQ, GI, SIM, EVT, FEM, EDP, RV, and RES at the top. The current view is under the "EVT" tab, indicating event-specific parameters are being configured. :width: 600 :figclass: align-center @@ -79,6 +84,7 @@ The experiments by Shekhar et al. 2020 [Shekhar2020]_ are also shown below for c .. figure:: figures/hdro-0005_EDP.png :align: center + :alt: Screenshot of a software interface with a vertical navigation menu on the left side showing various abbreviated menu items such as "UQ," "GI," "SIM," "EVT," "FEM," with "EDP" highlighted. The main area displays the header "Engineering Demand Parameters Generator" with a dropdown menu set to "Standard." The rest of the main area is blank. :width: 600 :figclass: align-center @@ -97,6 +103,7 @@ Open ``Settings``. Here we set the simulation time, the time step, and the numbe .. figure:: figures/hdro-0005_RV.png :align: center + :alt: Screenshot of a software interface for inputting random variables with an 'Add' button at the top. Three variables are listed—fc, fy, and E—with each set to a 'Normal' distribution and respective mean and standard deviation values. Each variable has an option to 'Show PDF'. Menu options for UQ, GI, SIM, EVT, FEM, EDP, RV, and RES are visible on the left side, with 'RV' highlighted. 'Clear All', 'Correlation Matrix', 'Export', and 'Import' options are available at the top right corner of the input section. :width: 600 :figclass: align-center @@ -107,6 +114,7 @@ Open ``Bodies`` / ``Fluid`` / ``Material``. Here we set the material properties .. figure:: figures/hdro-0005_RES_Summary_Forward.png :align: center + :alt: Screenshot of a software interface displaying statistical data values for different items categorized under labels UQ, SIM, EVT, FEM, and EDP. Each category shows a name such as 1-PFA-1-1, and values for Mean, StdDev, Skewness, and Kurtosis. The data presented is numerical, with values like 12.7422 for Mean under UQ and varying standard deviations and other statistical measures for each item. The interface has a tab selection with "Summary" and "Data Values" as options; "Data Values" is highlighted. :width: 600 :figclass: align-center @@ -116,6 +124,7 @@ Open ``Bodies`` / ``Fluid`` / ``Geometry``. Here we set the geometry of the flum .. figure:: figures/hdro-0005_RES_Scatter.png :align: center + :alt: Screenshot of "HydroUQ: Water-borne Hazards Engineering with Uncertainty Quantification" software interface displaying a scatter plot with several data points and a correlation coefficient of -0.95. On the right side of the screen, there is a table with multiple columns showing engineering data like "Run #," "fc," "fy," "E," and several columns with labeling consistent with engineering nomenclature such as "1-RMSA-1-1," "1-PDF-1-1," and "1-PID-1-1." The user interface has tabs for "Summary" and "Data Values" and buttons such as "Save Table," "Save Columns Separately," "Save RVs," and "Save QoIs" at the top right. At the bottom, there are buttons for "RUN," "RUN at DesignSafe," "GET from DesignSafe," and "Exit." The interface suggests a tool for engineering analysis and simulation with focus on uncertainty quantification. :width: 600 :figclass: align-center @@ -126,6 +135,7 @@ Open ``Algorithm``. Here we set the algorithm parameters for the simulation. We .. figure:: figures/hdro-0005_RES_Cumulative_Forward.png :align: center + :alt: Screenshot of a data analysis software interface showing a cumulative frequency distribution chart on the left and a detailed data table on the right. The chart depicts a step-like increase, representing a cumulative probability distribution. The table includes numerical values for various parameters including 'Run #', 'fc', 'fy', 'E', and several probability values. Color-coded buttons for saving and exiting the table are visible at the bottom. :width: 600 :figclass: align-center @@ -144,6 +154,7 @@ Moving onto the creation of an ordered debris-array, we set the debris propertie .. figure:: figures/hdro-0005_RV_Sensitivity.png :align: center + :alt: Screenshot of an interface with tabs on the left which include "UQ", "GI", "SIM", "EVT", "FEM", "EDP", "RV", and "RES". The main panel is titled "Input Random Variables" and has three options: "Add", "Clear All", and "Correlation Matrix", along with "Export" and "Import" buttons on the right. Below this, there are three entries of random variables listed with their corresponding distribution, mean, and standard deviation values. The first variable "fc" has a normal distribution with a mean of 6.0 and a standard deviation of 0.6. The second variable "fy" has a constant distribution with a constant value of 60.0. The third variable "E" also has a normal distribution with a mean of 30000 and a standard deviation of 3000. Each variable entry has a button labeled "Show PDF". The background is light with a color scheme of blues and grays. :width: 600 :figclass: align-center @@ -153,6 +164,7 @@ Open ``Bodies`` / ``Debris`` / ``Geometry``. Here we set the debris properties, .. figure:: figures/hdro-0005_RES_Summary_Sensitivity.png :align: center + :alt: Screenshot of the "HydroUQ: Water-borne Hazards Engineering with Uncertainty Quantification" web interface, showing tables and bar graphs of Sobol' indices for different random variables 'fc' and 'E'. The interface features four sets of indices: 1-PFA-1-1 Sobol', 1-RMSA-1-1 Sobol', 1-PFD-1-1 Sobol', and 1-PID-1-1 Sobol'. Each set includes numerical values and corresponding bar graphs with green bars representing 'Main' effects and blue bars representing 'Total' effects. The numerical values range from negative to positive, indicating varying degrees of sensitivity or influence of the variables on a particular model or system. The page has a navigation sidebar on the left with options such as UQ, GI, SIM, EVT, FEM, EDP, RV, and RES highlighted. There are "Cite" and "Login" buttons at the top right corner. :width: 600 :figclass: align-center @@ -164,6 +176,7 @@ Open ``Bodies`` / ``Structures``. Uncheck the box that enables this body, if it .. figure:: figures/hdro-0005_RES_Scatter_Sensitivity.png :align: center + :alt: Screenshot of a software application titled "HydroUQ: Water-borne Hazards Engineering with Uncertainty Quantification". The left side of the screen shows a navigation menu with various categories such as UQ, GI, SIM, EVT, and others highlighted in blue. The main area displays a scatter plot with the label "Samples" and numerous blue dots representing data points, along with a correlation coefficient value of -0.95 displayed below the plot. On the right side, there is a data table with columns titled "Run #", "fc", "E", "fy", and several others with numerical data, and options to save or export the data are provided above the table. There is a button labeled "GET from DesignSafe" at the bottom right corner. :width: 600 :figclass: align-center @@ -173,6 +186,7 @@ Open ``Boundaries`` / ``Wave Flume``. We will set the boundary to be a rigid bod .. figure:: figures/hdro-0005_RES_Summary_Reliability.png :align: center + :alt: A complex graphical interface displaying a graph titled "HydroUQ: Water-borne Hazards Engineering with Uncertainty Quantification." The graph maps a curved line ascending from left to right representing a probability level on the Y-axis and a 1-RMSA-1-1 index on the X-axis. Below the graph, several numerical data entries are visible, correlating the RMSA index to probability levels. There's a top navigation bar with the options "Cite" and "Login." Also, there's a left navigation bar with various options including UQ, GI, SIM, EVT, FEM, EDP, RV, and RES highlighted in blue. :width: 600 :figclass: align-center @@ -182,6 +196,7 @@ Open ``Boundaries`` / ``Wave Generator``. Fill in the appropriate file-path for .. figure:: figures/hdro-0005_forces.png :align: center + :alt: The image displays eight line graphs in a 2x4 grid format, illustrating changes in inline force (measured in kN/m) versus depth (measured in meters) at different normalized time intervals of a cyclical process, denoted as t/T, where T is the period. Each time interval (0, 1/8, 1/4, 3/8, 1/2, 5/8, 3/4, 7/8) is represented above its respective graph. Three types of forces are plotted in each graph: 'finertia' in blue, 'fdrag' in black, and 'ftot' in red, each showing varying patterns of force distribution with depth. The forces exhibit dynamic behavior, alternating direction and magnitude as time progresses. :width: 600 :figclass: align-center @@ -191,6 +206,7 @@ Open ``Boundaries`` / ``Rigid Structure``. This is where we will specify the rai .. figure:: figures/hdro-0005_moments.png :align: center + :alt: The image displays a series of eight graphs arranged in a two-row, four-column grid, each depicting curves that represent inline moment in kilonewton-meters per meter (kNm/m) plotted against depth in meters (m). Each graph is labeled with a fractional time value (t/T) ranging from 0 to 7/8 incrementally. Two types of curves are shown in each graph: 'dMtot with Wheeler' represented by solid lines and 'dMtot no-correction' indicated by plus signs. The shapes of the curves vary across the different time steps, mainly describing negative sloped lines that illustrate the relationship between the inline moment and depth at the given time fractions. The overall presentation suggests an analysis of structural or mechanical data over time, with Wheeler correction applied in one scenario and omitted in the other. :width: 600 :figclass: align-center @@ -200,6 +216,7 @@ Open ``Boundaries`` / ``RigidWalls``. .. figure:: figures/hdro-0005_IntegratedPileLoads.png :align: center + :alt: A set of three line graphs plotted against Dimensionless Time, t/T, on the x-axis, ranging from 0 to 1. The top graph shows Cumulative Elevation in meters ranging from -4 to 4, the middle graph shows Scaled Moment [kNm/m] ranging from -3 to 3, and the bottom graph shows Scaled Moment [kNm/m] ranging from -40 to 20. Each graph has two lines representing 'Standard' and 'Wheeler Correction'. All lines show a wave-like pattern with peaks and troughs. The 'Standard' line is represented in blue and the 'Wheeler Correction' in black, with the middle graph showing a larger amplitude in the curves than the bottom graph. :width: 600 :figclass: align-center