# User Guide & Tutorial

This guide takes you through each step to run a debris flow simulation with UBCDFLOW. For this example, we will use data for the Blueberry Creek debris flow. Download Blueberry Creek data.

**1) Launching UBCDFLOW**
**2) Setting initialization values**
**3) Setting reach values**
**4) Changing the number of reaches**
**5) Schematic views**
**6) Calculating results**
**7) Errors and warnings**
**8) Saving results**

## 1) Launching UBCDFLOW

UBCDFLOW can be launched in two ways, either using default data values, or using supplied values from a data file. In either case, you can change any of the values from within UBCDFLOW, and repeat the simulation.

(Note : the default values are as follows : Number of reaches : 5, Initial volume : 1.0 m^{3},
Uncertainties (initial volume and widths) : 0%, Lengths/widths : 1.0 m^{3}, Slopes/azimuths : 1.0°,
Flow type : Unconfined)

To launch UBCDFLOW using your own data, supply a .csv file with the following format :

reach_number,length,width,slope_angle,path_azimuth,flow_typewhere length and width are in metres, slope_angle and path_azimuth are in degrees, and flow_type is either u, c, or t for unconfined, confined, and transition flows accordingly. Your file should not include column headings, and there should be no spaces between values (just commas), eg. :

2,46,3,24.2,40,u

3,21,4,26.6,55,u

4,104,3,26.6,36,c

To run UBCDFLOW with the default values, click "Launch UBCDFLOW!"; to run UBCDFLOW with your data, browse for the file then click "Launch UBCDFLOW!". The main UBCDFLOW window will then load.

## 2) Setting initialization values

The top of the UBCDFLOW tool contains three input parameters, the **initial
volume**, the **uncertainty in initial volume**, and the **uncertainty in
width**.

The **initial volume** is the failure volume at the start of the
debris flow. The **uncertainty in initial volume** and
**uncertainty in width** are percent
uncertainties that you can use to calculate three sets of results. (See
Calculating Results for more details on
using uncertainties.

Blueberry Creek had an initial failure volume of 129.6 m^{3}. Let's
set the uncertainties to 50% to see what effect they have on our calculations.

Initiation zone of Blueberry Creek. |

## 3) Setting reach values

Each reach has 5 values which can be independently controlled. These are the
**length** and **width** of the reach in metres, the **slope angle (TH)**
in degrees, the **path azimuth (AZ)** in degrees clockwise from north, and the **flow type** (either
**unconfined**, **confined**, or **transition**). These parameters determine which
regression equation is used to calculate the change in volume (either positive in
the case of entrainment or negative in the case of deposition) for
this reach.

**Note :** All values must be positive. The slope angle must be between
0 and 55 degrees, and the path azimuth angle must be between 0 and 360 degrees.
If the chosen parameters of slope and flow type will result in no change
in volume, a warning will display. The calculation can still be done in
this case, but no change in volume will be calculated for this reach.

In this example, we have loaded in values from a file, so we do not have to change any values. If we wish to see what effect a change in these parameters would make, we can edit them and run the calculations again.

Reach 17 of Blueberry Creek, a confined flow with a width of three metres. |

## 4) Changing the number of reaches

The number of reaches can be increased or decreased. Reaches are
added or removed from the **end** of the flow (i.e. if you have 7 reaches,
and you click "Remove a reach", the 7th reach is removed). Any reaches
added to the flow are added with the default values (see
Launching UBCDFLOW for default values).

When loading values from a file, the number of reaches will be set to the number of rows of values in the .csv file. If you wish to run the calculation with fewer or greater reaches than your file provided, you can change this with the add/remove buttons once you are running UBCDFLOW.

## 5) Schematic views

You may view your reach parameters in graphical form by clicking "Visualisation of input data".

The top graphic shows a top-down **Schematic plan view** of the reach morphology,
allowing you to view your input reach lengths, widths and path azimuths.

The bottom panel shows a **Schematic cross-section view** of the slope angles (TH) of
your reach inputs.

Also included in this display are the **Total reach distance** (the sum of
the lengths of all reaches), the **Horizontal projected distance** ("map" distance),
and the **Vertical drop**. Note that these calculations use __all__ the reaches
defined by the input data, although the final calculation may indicate that
the flow volume would drop below zero (thus ending the debris flow) earlier
that the last input reach.

## 6) Calculating results

Three options are provided for calculating results. Calculating with
**no uncertainty** simply calculates one set of results using your input
data as defined in the main applet window.

Results are calculated from the user-defined input values using the
regression equations.
From these results we can see that the flow volume does not fall to 0 within
the specified number of reaches. We can also determine that the maximum flow
volume during these reaches was 2459 m^{3}.

Calculating with **initial
volume uncertainty** first applies the uncertainty positively and
negatively to the initial volume, then runs the calculation for all three
initial volumes (regular, positive, and negative). For example, with a
50% uncertainty in initial volume on the Blueberry Creek flow, we
calculated the results using :

1) 129.6 m^{3}

2) 129.6 - 0.5 * 129.6 m^{3} = 64.8 m^{3}

3) 129.6 + 0.5 * 129.6 m^{3} = 194.4 m^{3}

Again, we can see that the flow volume does not reach 0, for any of these three sets of results.

Next, we calculate three sets of results using the uncertainty in width. When using
width uncertainty, the results are first calculated with the user-defined reach widths, then with
widths modified both positively and negatively by the user-defined width uncertainty. For example,
given a flow with 4 reaches with a width uncertainty of 50% and reach widths

6.0 m, 3.0 m, 4.0 m, 3.0 m

One set of results would be calculated using those widths, one set would be calculated using
the widths :

3.0 m, 1.5 m, 2.0 m, 1.5 m

and one set of results would be calculated using the widths :

9.0 m, 4.5 m, 6.0 m, 4.5 m

Calculating results for Blueberry Creek with a 50% uncertainty in the reach widths gives a wider range in flow distances. Although the unmodified and negatively modified reach widths still result in a travel distance which is greater than the user-defined number of reaches, the positively modified reach widths cause the flow to end in the 24th reach. Further "tweaking" of this final reach's length could determine the precise travel distance.

## 7) Errors and warnings

If any of your input values (either file input data or manually entered values) are faulty, i.e. you input a non-numeric value, or a negative value, or an angle that exceeds the maximum for slope (55°) or azimuth (360°), you will see an error message. All input errors must be resolved before you can calculate your results.

Some valid reach input values will results in a zero change in flow volume for that reach. In this case, you will see a warning letting you know which reaches have a zero change in flow volume.

You can run calculations with reaches that cause zero change in flow volume.

## 8) Saving results

If you wish, you can save the results that you generated into a .csv file, which
you can later view in Microsoft Excel, OpenOffice, or another spreadsheet program.
As in your calculation, select the uncertainty type and then click **Save Results**.
You will be presented with a set of data formatted for use in a .csv file.

Copy the data and paste it into a text file and save the file with the file extension .csv. You can then view your results in Excel.