# Flowy
<img src="https://raw.githubusercontent.com/flowy-code/flowy/main/res/logo.png" width="300"/>

## 1. How to run the code
From what we can tell, `mr_lava_loba.py` was run by copying the script, together with the input files into a run folder. Then, the python script was executed from that folder.

The recommended way to run `flowy` is to give it the path to the `input.toml` file and to the DEM `.asc` file via command line arguments __or__ by specifying absolute paths in `input.toml`.

Help instructions for the command line arguments are printed when using
`flowy --help`.

As an example: Let's assume we have stored the `input.toml` in a folder named `run_folder`. And we have a DEM stored in the same folder. Then we could invoke flowy like so:
`flowy run_folder/input.toml -a run_folder/dem.asc -o run_folder`.

This will tell flowy where to find `input.toml` and `dem.asc`, as well as to store the outputs in the `run_folder`.

For a simple shell script that runs the Kilauea example see [here](https://github.com/flowy-code/flowy/blob/main/run_example_kilauea.sh).
Note that this script also tries to plot the output, which relies on a few extra python packages being installed.

__On Elja__, we installed `Flowy` so that you can run it like this:

/users/home/share/flowy-stuff/flowy path/to/input.toml -a run_folder/dem.asc -o run_folder

Please note, you cannot write to the `flowy-stuff` folder. If you want to run the ETNA or KILAUEA examples, you should specify an output folder in your own home directory (or any directory you have write permissions to).

## 2. How to convert the `input.py` and `input_advanced.py` to `input.toml`

To convert a given pair of input files to the new format, create an empty file `input.toml`.
First, copy and paste the contents of `input.py` into `input.toml`.
Then write `[Advanced]` in a new line and paste the contents of `input_advanced.py` after that line.

Overall `input.toml` should look like this:

<contents of input.py>
[Advanced]
<contents of input_advanced.py>

For concrete examples see the `./examples` folder in the repository. E.g. [here](https://github.com/flowy-code/flowy/blob/main/examples/KILAUEA2014-2015/input.toml).

## 3. Prerequisites: Sanitaziation of `.asc` files
One issue, that occurred when trying to run the Mt. Etna example, from the Mr. Lava Loba repository, was that the DEM .asc file was "corrupted". It contained invisible `\r` characters. Because of that, the reading those files into `flowy` fails. In addition, 'nan' values in these files, or incorrect values of `ncols` or `nrows` in the ASCII files can cause `Flowy` to crash.

We have written a simple asc file sanitaziation script, that gets rid of the invisible characters, checks the number of rows and columns, etc. We recommend that you run this sanitization script on the input DEM asc file first, just to be safe. This script is inside the shared directory we have created, so you can use it like this:

/users/home/share/flowy-stuff/sanitize_file.py /path/to/asc-file /path/to/new-sanitized-asc-file

The first argument is the path to the asc file you want to sanitize, and the second argument is the path to the new asc file. You can set the name to be the same, in which case the old asc file would be overwritten. In addition, if you want to run this sanitization script on your own machine, you can get it from the [GitHub repository](https://github.com/flowy-code/flowy/blob/main/examples/sanitize_file.py).

## 4. Unimplemented input parameters

Some parameters have not been implemented yet. We will not list the implemented parameters here.

### Unimplemented parameters from `input.py`:
- `topo_mod_flag`: Right now, the topography is always modified by the flow. Each lobe is added to the topography.
- `n_flows_counter`: Not implemented
- `n_lobes_counter`: Not implemented. The slope is reevaluated in every step.

### Unimplemented parameters from `input_advanced.py`:
- `saveshape_flag`: Not implemented.
- `saveraster_flag`: The output is always saved in .asc format or .nc format, so this is not used.
- `flag_threshold`: We didn't know what this was.
- `plot_lobes_flag`: We don't use this, but we have a new option called `write_lobes_csv` (which can be true or false) that outputs lobe information
- `plot_flow_flag`: Not implemented. What is this?
- `force_max_length` and `max_length`: Not implemented
- `n_check_loop`: We didn't see this being used in Mr Lava Loba
- `start_from_dist_flag`: Not implemented
- `shape_name`: Not implemented.