# Build a Python Environment for Using the FLDPLN Model

In order to use the FLDPLN model, we need to have a Python environment with the necessary packages installed. This document provides information on how to build the "fldpln" Python environment and how to use it in various development/programming environments including local and cloud JupyterLab and in Visual Studio Code (VSC). 

This includes the following major components:
* Create a Python environment and install necessary packages
* Install the fldpln_py Python package and MATLAB Runtime if it's not included in the fldpln_py package
* Install the fldpln package

## Create the fldpln Python Environment

Assuming that conda has not been installed we start from scratch. You can skip the first step if you already have conda installed on your computer.

### Install Miniconda

First we will download Miniconda to install Python and necessary Python environment management tools on your computer. Miniconda is a lightweight version of Anaconda, which is a full-fledged data science platform. Miniconda only includes Python and conda, while Anaconda includes Python, conda, and a suite of other common used packages.

* Go to the [Miniconda download page](https://docs.conda.io/en/latest/miniconda.html#windows-installers) and download the Miniconda installer for Windows. The web site provides the installer with the most recent Python version. This is fine as we can create a new Python environment with the desired Python version later.
* Run the installer and follow the instructions to install Miniconda on your computer. Make sure to check the box to add Miniconda to the system PATH so that you can use conda in the command prompt window.

### Install Mamba for faster package management

In the base environment, we will install mamba, a faster and more efficient package manager than conda, using the following command:
```
conda install -c conda-forge mamba
```

### Create the environment and install packages using a YAML file

The fldpln python environment has been exported as a YAML configuration file. So we can replicate the environment on a different machine using the YAML file. In the base environment, navigate to the folder where the .yaml file is saved, and run the following conda or mamba command to create the fldpln env using the file:
```
mamba env create -f fldpln_windows.yaml
```
```
conda env create -f fldpln_windows.yaml
```
  
Solving the environment and installing all the packages might take a surprisingly long time especially using conda, so be patient.

**Note that different YAML files are needed for Windows and Unix-based systems**. Two YAML files, fldpln_windows.yaml and fldpln_unix.yaml, are created for Windows and Unix-based systems respectively. **Those YAML files don't have the fldpln and fldpln_py packages installed.**

## Install FLDPLN Related Python Packages

Currently, there are two python packages are needed for using the FLDPLN model. The first is the fldpln_py package which is a wrapper for the FLDPLN model implemented in MATLAB. The second is the fldpln package, which contains modules for running the FLDPLN model and for tiling and mapping FLDPLN libraries.  

### Install the fldpln_py Python Package

The FLDPLN model is developed in MATLAB and compiled into the fldpln_py Python package. The MATLAB compiled Python package can be installed on both Windows or Unix systems (though not tested on Unix system yet) with the MATLAB Runtime installed. Note that the MATLAB Runtime is required but free to run the compiled Python package.

#### Install MATLAB Runtime and fldpln_py Python Package

First we need to run the installer generated by MATLAB under the fldpln_py folder. It installs the MATLAB Runtime and also unpacks and saves the fldpln_py package under the installation folder, typically under folder C:\Program Files.

The installer, depending which one used, may download MATLAB on-the-fly during the installation or has the Runtime included in the installer. Note that the installer for Windows automatically sets the MATLAB Runtime path during installation, but on Linux or macOS you must add the libraries manually. See [here](https://www.mathworks.com/help/compiler_sdk/cxx/mcr-path-settings-for-run-time-deployment.html) for more information.

To install fldpln_py package into the fldpln environment, we need to activate the fldpln environment, navigate to the folder where fldpln_py's setup.py file is located, and install it using either one of the following commands.  
```
python setup.py install
```
or
```
pip install .
```

### Install the fldpln Package

The [fldpln Python package](https://pypi.org/project/fldpln/) provides several modules to create segment-based library, tile segment-based library and map flood inundation depth with tiled library. The [source code](https://github.com/XingongLi/fldpln) of the package and [documentation](https://xingongli.github.io/fldpln/) are both available on GitHub. The package is published on PyPI and can be installed using pip:
```
pip install fldpln
``` 

## Using the fldpln Environment in Different Development Environments

The fldpln python environment can be used in different development environments including Visual Studio Code (VSC) and JupyterLab. Below are the steps to use the environment in those environments.

### Use the environment in local JupyterLab

You may also want to use the environment with Jupyter notebooks on your own machine. In this case, we need to install the jupyterlab package into the env using the following command:
  ```
  mamba install -c conda-forge jupyterlab
  ```
After installation, first navigate to the folder where your Jupyter notebooks are located and run the following command to start JupyterLab in a web browser. Note the space between the two words.
```
jupyter lab
```
You can shutdown the local JupyterLab by using "Ctrl + C" in the command window where you started JupyterLab.

You may also want to install the Git extension for JupyterLab for version control:
  ```
  conda install -c conda-forge jupyterlab-git
  ```

### Use the Environment in Visual Studio Code (VSC)

The Python environment should be available in VSC for writing Python scripts. Below are some trouble shooting steps if the environment is not available in VSC.
* Make sure the conda command is added to system’s PATH environment variable so that VSC can use it to activate a specific python environment.
  * When install miniconda (or Anaconda), the default installation setting doesn’t add its executable path (on my machine “C:\Users\lixi\Anaconda3\”) to the PATH environment variable.
  * This is done by using the Advanced System Settings in Control Panel (see the screenshot below)

    ![Setup PATH variable](./images/PATH_environment_variables.png)
* VSC terminal 
  * VSC uses powershell as the default terminal which cause some issues even after including conda path in the PATH environment variable.
  * A quick solution is to change the default powershell terminal in VSC to the regular cmd terminal by press CTRL+SHIFT+P in VSC and search for “terminal select default profile” and select “Command Prompt C:\WINDOWS\System32\cmd.exe”
* When using VSC to run Jupyter notebooks, VSC automatically installed ipykernel into the environment.

VSC also supports Jupyter notebooks. But this needs the ipython kernel package be installed into the environment with the following command. Note that the kernel can also be installed when you open a notebook in VSC and choose the environment.
  ```
  mamba install -c conda-forge ipykernel
  ```