# Run example D-Claw simulations

In order to provide examples of using [`digger.analyze`](#digger.analyze) and [`digger.compare`](#digger.compare), we need some D-Claw output. This section describes how to set up and run two example simulations used to describe typical usage.

As an alternative to running the example simulations, precomputed output is provided within the `digger/data` directory. The file associated with each example is named `<example-name>_output.zip`. For example, the file associated with the example `digger/examples/post-run/barry_arm` is in `digger/data/barry_arm_output.zip`. Place the required zip file into the experiment directory and unzip it before running any example code.

(run-install)=
## Install D-Claw

Installing D-Claw [(installation instructions)](https://claw.code-pages.usgs.gov/dclaw/src/installation.html) requires getting the source code for Clawpack and D-Claw, having a fortran compiler, and setting environment variables. To run the examples, you will also need to install digger.

D-Claw will not work on Windows. It should work on Mac, Linux, and WSL.

### Create an environment and install digger

The general installation instructions for `digger` are located [here](install-digger). Here we briefly summarize one approach that will work for both `digger` and D-Claw. 

First, create a python 3.11 environment. We have found this version to be compatible with all other dependencies. You may find other python versions also work. We also install [ffpmeg](https://anaconda.org/conda-forge/ffmpeg) here rather than with pip because we have found that the conda-forge distribution works better than those distributed by pip. ffmpeg is used by D-Claw to make animations.

```bash
conda create -n myenv -c conda-forge python=3.11 ffmpeg
conda activate myenv
cd \path\to\digger\directory
pip install -e .
```

### Compile D-Claw

Navigate to one of the digger example directories (`digger/examples/post-run/<example-name>`) and compile D-Claw by executing the following: 

```bash
make new
```

To see all of the options defined in the D-Claw makefile execute:
```bash
make help
```

### Run the simulation

Assuming that compilation has executed successfully, you should have a file called `xgeoclaw` in the example directory. To run the example, you will run five commands.

**make input**

The first command executes a file `setinput.py`. This file contains digger commands that generate D-Claw format input files generated using [`digger.make`](#digger.make) functions.

```bash
make input
```

**make .data**

The second command uses the `setrun.py` file to generate required D-Claw input files that end in '.data'. This file is a standard Clawpack input file and more information about its contents may be found [here](https://www.clawpack.org/setrun_geoclaw.html).

This step includes checking that any topography or material thickness files needed to run the simulation exist.  

```bash
make .data
```

**make .output**

The third command uses the `.data` files and conducts the D-Claw simulation, generating output (located in the `_output` directory).

```bash
make .output
```

**make .plots**

The fourth command uses the `setplot.py` file to generate plots based on D-Claw output. Similar to the `setrun.py` file, the `setplot.py` file is a standard Clawpack file. It specifies how to plot using the [visclaw tools](https://www.clawpack.org/plotting.html).

```bash
make .plots
```

This command will make a large number of plots in the `_plots` directory and also generate some *mp4 animations.

**make postprocess**

The final command executes the file `setpostprocess.py` and conducts postprocessing analysis with [`digger.analyze`](#digger.analyze) and [`digger.compare`](#digger.compare) functions.

```bash
make postprocess
```