🌊 ADCIRC UserGuide Update

user-guide/docs/tools/simulation.md

@@ -2,7 +2,7 @@
 
 {% include-markdown 'simulation/overview.md' %}
 
-{% include-markdown 'simulation/adcirc.md' %}
+{% include-markdown 'simulation/adcirc/adcirc.md' %}
 
 {% include-markdown 'simulation/clawpack.md' %}
 

user-guide/docs/tools/simulation/adcirc/adcirc_cli.md

@@ -0,0 +1,62 @@
+
+#### `adcirc` Command Line Options
+
+| Option                            | Description                                                                                   | Special Notes                                                                                 |
+| --------------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `-I INPUTDIR`                     | Set the directory for input files.                                                            |                                                                                               |
+| `-O GLOBALDIR`                    | Set the directory for fulldomain output files.                                                |                                                                                               |
+| `-W NUM_WRITERS`                  | Dedicate NUM_WRITERS MPI processes to writing ascii output files.                             | Affects ascii formatted fort.63, fort.64, fort.73, and fort.74 files.                         |
+
+#### `adcprep` Command Line Options
+
+| Option                | Description                                                                                   | Special Notes                                                                    |
+| --------------------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `--np NUM_SUBDOMAINS` | Decompose the domain into NUM_SUBDOMAINS subdomains.                                          | Required for parallel computation.                                               |
+| `--partmesh`          | Partition the mesh only, resulting in a partmesh.txt file.                                    | Should be done first. Generates partmesh.txt for subdomain assignments.          |
+| `--prepall`           | Decompose all ADCIRC input files using the partmesh.txt file.                                 | Requires previous execution with `--partmesh`. Expects default input file names. |
+
+**`adcprep` Runs**
+
+The usual workflow of running `adcprep` consists of two steps - (1) partitioning of the mesh into sub-domains that each core will work on. (2) Decomposing other input files over the partitioned mesh.
+
+Note that running `adcprep` alone with no command line options will bring up an interactive menu. 
+
+Common `adcprep` options used include:
+
+- **Partitioning Mesh Only**
+
+  ```
+  adcprep --partmesh --np 32
+  ```
+
+  This command partitions the mesh into 32 subdomains, creating a partmesh.txt file.
+
+- **Preparing All Input Files**
+
+  ```
+  adcprep --prepall --np 32
+  ```
+
+  Utilizes the previously created partmesh.txt file to decompose all input files into PE* subdirectories.
+
+### PADIRC Runs
+
+Some common options used when using PADCIRC are the following:
+
+- **Specifying Input/Output Directories**
+
+  ```
+  padcirc -I /path/to/input -O /path/to/output
+  ```
+
+  Looks for input files in `/path/to/input` and writes output files to `/path/to/output`.
+
+- **Adjusting Writer Cores**
+
+  ```
+  padcirc -W 4
+  ```
+
+  Dedicates 4 MPI processes to write ASCII output files.
+
+For more information see - [ADCIRC Webpage Documentation](https://adcirc.org/home/documentation/generic-adcirc-command-line-options/)

user-guide/docs/tools/simulation/adcirc/examples/examples.md

@@ -0,0 +1,4 @@
+
+{% include-markdown './quarter_annular_harbor.md' %}
+
+{% include-markdown './shinnecock.md' %}

user-guide/docs/tools/simulation/adcirc/examples/quarter_annular_harbor.md

@@ -0,0 +1,72 @@
+#### Quarter Annular Harbor with Tidal Forcing Example: ADCIRC Simulation Guide
+
+The Quarter Annular Harbor is commonly used as a test case to assess the performance of finite lement numerical schemes applied to shallow water equations.
+
+##### Problem Setup
+
+The Quarter Annular Harbor problem features a domain that is a quarter of an annulus, bounded by land on three sides and an open ocean boundary. The setup includes:
+
+- Inner radius (`r1`): 60,960 m
+- Outer radius (`r2`): 152,400 m
+- Bathymetry: Varies quadratically from `h1` = 3.048 m at `r1` to `h2` = 19.05 m at `r2`
+- Finite element grid: Radial spacing of 15,240 m and angular spacing of 11.25 degrees
+
+The problem's geometry tests the model's performance in both horizontal coordinate directions, with an emphasis on identifying spurious modes and numerical dissipation.
+
+###### ADCIRC Inputs
+
+Two primary input files are required:
+
+1. *Grid and Boundary Information File (`fort.14`)*
+
+    This file outlines the mesh configuration, including:
+
+    - **Grid Information**: 96 elements and 63 nodes.
+    - **Nodal Information**: Node number, horizontal coordinates, and depth.
+    - **Elemental Information**: Element number, nodes per element, and comprising node numbers.
+    - **Boundary Conditions**:
+        - Elevation specified boundary: 1 segment with 9 nodes (Node 7 to Node 63).
+        - Normal flow boundary: 1 segment with 21 nodes (Node 63 to Node 7).
+
+2. *Model Parameter and Periodic Boundary Condition File (`fort.15`)*
+
+    Specifies model parameters, including:
+
+    - **Initialization**: Cold started from a state of rest.
+    - **Coordinate System**: Cartesian.
+    - **Nonlinearities**: Finite amplitude, advection, and quadratic bottom friction.
+    - **Forcings**: No tidal potential or wind stress. Gravity in m/s².
+    - **Boundary Forcing**: Sinusoidal elevation with a period of 44,712 s, amplitude of 0.3048 m, and phase of 0 degrees, ramped up over the first two days.
+    - **Simulation Duration**: 5 days with a time step of 174.656 s.
+    - **Output Settings**: Water level and velocity time series output at specified intervals and locations. Harmonic analysis of model elevation and velocity fields for the M2 constituent on the final day. Hot start files generated every 512 time steps.
+
+###### ADCIRC Outputs
+
+The simulation generates several output files, briefly summarized as follows:
+
+- **General Diagnostic Output** (`fort.16`): Echoes input file information, ADCIRC processing data, and error messages.
+- **Iterative Solver Diagnostic** (`fort.33`): Contains solver diagnostics, typically empty after successful runs.
+- **Harmonic Constituents**:
+    - Elevation at specified stations (`fort.51`).
+    - Velocity at specified stations (`fort.52`).
+    - Elevation at all nodes (`fort.53`).
+    - Velocity at all nodes (`fort.54`).
+- **Time Series Output**:
+    - Elevation at specified stations (`fort.61`).
+    - Velocity at specified stations (`fort.62`).
+    - Elevation at all nodes (`fort.63`).
+    - Velocity at all nodes (`fort.64`).
+- **Hot Start Files** (`fort.67`, `fort.68`): Facilitate restarting simulations from specific states.
+
+##### Running Example**
+
+This simulation example is best run from the ADCIRC Interactive VM.
+
+1. [Start the ADCIRC Interactive VM](../adcirc.md#adcirc-through-the-interactive-vm)
+2. Copy the inputs from 
+3. Execute ADCIRC, specifying the input files and any runtime options as needed.
+
+##### References
+
+- [ADCIRC Website Examples](https://adcirc.org/home/documentation/example-problems/quarter-annular-harbor-with-tidal-forcing-example)
+- Lynch, D.R. and W.G. Gray. 1979. A wave equation model for finite element tidal computations. Computers and Fluids. 7:207-228.

user-guide/docs/tools/simulation/adcirc/examples/shinnecock.md

@@ -0,0 +1,54 @@
+#### Shinnecock Inlet, NY with Tidal Forcing Example: ADCIRC Simulation Guide
+
+This documentation outlines the procedure and details for setting up and running an ADCIRC simulation focused on the tidal hydrodynamics in the vicinity of Shinnecock Inlet, NY.
+This example derives from a study conducted at the U.S. Army Corps of Engineers Coastal Hydraulics Laboratory.
+It is commonly used as a test-case for ADCIRC releases.
+
+##### Problem Setup
+
+Shinnecock Inlet is a geographical feature located along the outer shore of Long Island, New York.
+The simulation utilizes a finite element grid to model the hydrodynamics in this area, reflecting the following characteristics:
+
+- The grid's discretization varies from approximately 2 km offshore to around 75 m in nearshore areas.
+- Due to the coarse resolution, this model does not accurately resolve circulation near the inlet and the back bay.
+
+The input files for this simulation can be found in the CommunityData directory at [``CommunityData/Use Case Products/ADCIRC/adcirc/adcirc_shinnecock_inlet``](https://www.designsafe-ci.org/data/browser/public/designsafe.storage.community/Use%20Case%20Products/ADCIRC/adcirc/adcirc_shinnecock_inlet).
+
+###### ADCIRC Input
+
+1. **Grid and Boundary Information File (`fort.14`)**
+
+    This file defines the simulation's spatial domain, containing:
+
+    - **5780 elements** and **3070 nodes**, detailing the mesh used for the simulation.
+    - Nodal and elemental information, including node numbers, horizontal coordinates, depth, and elements' composition.
+    - Boundary specifications:
+        - An **elevation specified open boundary** with 75 nodes (from node 75 to node 1).
+        - A **normal flow mainland boundary** with 285 nodes (from node 1 to node 75).
+
+2. **Model Parameter and Periodic Boundary Condition File (`fort.15`)**
+
+      This file outlines the simulation's parameters:
+
+      - Initialization from a state of rest (cold start).
+      - Use of a longitude-latitude coordinate system.
+      - Inclusion of nonlinearities such as finite amplitude (with elemental wetting and drying), advection, and hybrid bottom friction.
+      - The model is forced using tidal potential terms and along the elevation boundary with 5 tidal constituents (M2, S2, N2, O1, K1), ramped up over the first two days.
+      - The simulation duration is 5 days with a time step of 6 seconds.
+      - Output of water level and velocity time series every 300 time steps (half-hour) at all nodes from days 3.8 to 5. No harmonic output or hot start files are produced.
+
+###### ADCIRC Output
+
+The simulation generates the following output files:
+
+- **General Diagnostic Output** (`fort.16`): Includes input file information, ADCIRC processing data, and error messages.
+- **Iterative Solver Diagnostic** (`fort.33`): Contains diagnostic information from the iterative solver, typically empty upon successful completion.
+- **Elevation Time Series** (`fort.63`): Outputs elevation time series at all nodes every 300 time steps.
+- **Depth-averaged Velocity Time Series** (`fort.64`): Outputs velocity time series at all nodes every 300 time steps.
+
+##### References
+
+- [ADCIRC Website Examples](https://adcirc.org/home/documentation/example-problems/shinnecock-inlet-ny-with-tidal-forcing-example)
+- Militello, A., and Kraus, N. C. (2000). *Shinnecock Inlet, New York, Site Investigation, Report 4, Evaluation of Flood and Ebb Shoal Sediment Source Alternatives for the West of Shinnecock Interim Project, New York*. Technical Report CHL-98-32. U.S. Army Engineer Research and Development Center, Vicksburg, Mississippi.
+- Morang, A. (1999). *Shinnecock Inlet, New York, Site Investigation Report 1, Morphology and Historical Behavior*. Technical Report CHL-98-32, US Army Engineer Waterways Experiment Station, Vicksburg, Mississippi.
+- Williams, G. L., Morang, A., Lillycrop, L. (1998). *Shinnecock Inlet, New York, Site Investigation Report 2, Evaluation of Sand Bypass Options*. Technical Report CHL-98-32, US Army Engineer Waterways Experiment Station, Vicksburg, Mississippi.

user-guide/docs/tools/simulation/adcirc/inputs/inputs.md

@@ -0,0 +1,30 @@
+
+**Input File Table Summary**
+
+| Default File Name(s)   | Description                                          | Condition   |
+| ---------------------- | ---------------------------------------------------- | ----------- |
+| `fort.14`              | Grid and Boundary Information File                   | Required    |
+| `fort.15`              | Model Parameter and Periodic Boundary Condition File | Required    |
+| `fort.10`              | Passive Scalar Transport Input File                  | Conditional |
+| `fort.11`              | Density Initial Condition Input File                 | Conditional |
+| `fort.13`              | Nodal Attributes File                                | Conditional |
+| `fort.19`              | Non-periodic Elevation Boundary Condition File       | Conditional |
+| `fort.20`              | Non-periodic, Normal Flux Boundary Condition File    | Conditional |
+| `fort.22`              | Meteorological Forcing Data                          | Conditional |
+| `fort.200, ...`        | Multiple File Meteorological Forcing Input           | Conditional |
+| `fort.23`              | Wave Radiation Stress Forcing File                   | Conditional |
+| `fort.24`              | Self Attraction/Earth Load Tide Forcing File         | Conditional |
+| `fort.25`, `225/227`   | Ice Coverage Input Files                             | Conditional |
+| `fort.35`              | Level of No Motion Boundary Condition Input          | Conditional |
+| `fort.36`              | Salinity Boundary Condition Input                    | Conditional |
+| `fort.37`              | Temperature Boundary Condition Input                 | Conditional |
+| `fort.38`              | Surface Temperature Boundary Values                  | Conditional |
+| `fort.39`              | Salinity and Temperature River Boundary Values       | Conditional |
+| `fort.67` or `fort.68` | 2DDI Hot Start Files                                 | Conditional |
+| `fort.141`             | Time Varying Bathymetry Input File                   | Conditional |
+| `elev_stat.151`        | Elevation Station Location input file                | Conditional |
+| `vel_stat.151`         | Velocity Station Location input file                 | Conditional |
+| `conc_stat.151`        | Concentration Station Location input file            | Conditional |
+| `met_stat.151`         | Meteorological Recording Station Location Input file | Conditional |
+| N/A                    | Time-Varying Weir Input File                         | Conditional |
+| N/A                    | Time Varying Weirs Schedule File                     | Conditional |

user-guide/docs/tools/simulation/adcirc/installation.md

@@ -0,0 +1,55 @@
+
+For the advanced user, below is a guide on how to install ADCIRC locally.
+The below instructions can be executed within a users Jupyter Hub environment (HPC and non-HPC), to get a local install of ADCIRC.
+Note this is for advanced users only.
+
+#### Spack ADCIRC Installation (DesignSafe JupyterHub)
+
+> The below instructions are for DesignSafe on JupyterHub instances (non HPC). They will allow you to test and run ADCIRC examples within a Jupyter session, without having to use HPC resources. This is in particular useful for 
+
+
+Move into your MyData directory and clone the spack repo. Note we put the spack repo in MyData so that it persists over Jupyter sessions.
+
+```shell
+cd ~/MyData
+git clone -c feature.manyFiles=true https://github.com/spack/spack.git ~/spack
+```
+
+After installing spack, initialize it with:
+
+```shell
+source ~/MyData/spack/share/spack/setup-env.sh
+```
+
+This needs to be run every time a new jupyter terminal environment is spawned. To automatically do this, add the command to your `~/.bashrc` or alternatively, set up an alias:
+
+```shell
+alias spack-setup='source ~/spack/share/spack/setup-env.sh'
+```
+
+Now we clone the spack ADCIRC repo, and add the ADCIRC spack repository to spack.
+
+```shell
+cd ~/MyData
+git clone https://github.com/adcirc/adcirc-spack.git 
+spack repo add ~/MyData/adcirc-spack
+```
+
+Now to install ADCIRC:
+
+```shell
+spack install adcirc@main +swan +grib
+```
+
+**Note**: The installation above may take a long time!
+
+To activate ADCIRC in your environment just run:
+
+```shell
+spack load adcirc
+```
+
+That should make the `padcirc`, `adcirc`, `adcprep`, and `padcswan` executablex available in your path.
+
+For more information on how to use spack see the [documentation](https://spack.readthedocs.io/en/latest/index.html)
+For more information on ADCIRC's spack repository and build options, see the [ADCIRC Spack Repository](https://github.com/adcirc/adcirc-spack)