This resource contains the following Bash script which can be used by the user in any of the JupyterHub instances accessible via the "Open with" functionality of HydroShare to create a custom Conda environment to run AORC related notebooks. In order to run this Bash script files in JupyterHub, first make the file executable using the JupyterHub terminal as shown below:

chmod +x setup_aorc_jupyterhub_conda_env.sh

Then the above script can be executed from the command line as follows:

./setup_aorc_jupyterhub_conda_env.sh

NOTE: The notebook (CondaEnvironmentSetup.ipynb) available in this resource also can be used for creating the 'aorc' Conda environment if you prefer not to use the terminal.

After executing the script, it will create a new Conda environment called 'aorc'. It will also register this new Conda environment as a new Jupyter kernel. Though the script creates a new kernel and names it as 'Python3 (AORC)'', the conda environment by default also registers the 'aorc' environment as a new kernel with the name of 'Python [conda env:aorc]' or 'Python [conda env:.conda-aorc]'. In order for any of the AORC related notebooks to use this new kernel you have to first shut down all kernels and then use the option 'Change Kernel" to select this new kernel. Depending on the JupyterHub instance that you are using, you have to select a specific kernel name as described below:

- 2i2c JupyterHub: Select kernel 'Python [conda env:.conda-aorc]'. In the list of kernels, you may see 'Python3 (AORC)'. Don't select this kernel!
- CyberGIS JupyterHub: Select kernel 'Python3 (AORC)'
- CUAHSI JupyterHub: Select kernel 'Python [conda env:aorc]'. In the list of kernels, you may see 'Python3 (AORC)'. Don't select this kernel!

This resource also contain this yml file:

- environment.yml (This file contains the python modules needed to run the AORC notebooks - similar to requirements.txt file used with pip install). The above Bash script file uses this yml file to install the python modules listed in that file.

- delete_aorc_jupyterhub_conda_env.sh (This script can be run to delete the 'aorc' Conda env. Note this file needs to be first set as an executable file - chmod +x delete_aorc_jupyterhub_conda_env.sh)

- sample_commands_to_create_conda_env_jh.md (This file contains example commands to create a new Conda environment - without using a bash script)

How to use the new kernel created by the script (see above)?
If you just created the new aorc Conda environment, shut down all kernels. Open the notebook that needs to use the aorc Conda environment. Change the kernel for the notebook to aorc kernel. (for the exact name of the kernel see above).

How to update the aorc Conda environment after it has been created?
Update here means installing additional python modules or upgrading to a newer version of any modules that is already installed in the aorc conda environment.

- Update the environment.yml file by adding new modules or updating the version of any modules in that file.

- In the JupyterHub instance, use a terminal and run the following 2 commands:

- conda activate aorc
- mamba env update -f environment.yml

If you just want to install few new modules or upgrade existing modules without updating environment, then run (after activating the aorc env):

conda install <module-1-name> <module-2-name>
OR
pip install <module-1-name> <module-2-name>

NOTE: It is better to update the environment yml file when there is a need to update the environment as it helps reproducibility.