From 4499028ecfca017a1ae14750f504f13bb9c58335 Mon Sep 17 00:00:00 2001 From: Jacob Cain Date: Fri, 22 Nov 2024 01:21:16 -0800 Subject: [PATCH 1/2] ISIS in other conda Envs --- .../using-isis-in-other-conda-envs.md | 124 ++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 125 insertions(+) create mode 100644 docs/how-to-guides/environment-setup-and-maintenance/using-isis-in-other-conda-envs.md diff --git a/docs/how-to-guides/environment-setup-and-maintenance/using-isis-in-other-conda-envs.md b/docs/how-to-guides/environment-setup-and-maintenance/using-isis-in-other-conda-envs.md new file mode 100644 index 0000000..ce57f2f --- /dev/null +++ b/docs/how-to-guides/environment-setup-and-maintenance/using-isis-in-other-conda-envs.md @@ -0,0 +1,124 @@ +# Using ISIS in other Conda Environments + +The ISIS conda package pins some of its requirements, +which may clash with other packages. + +Therefore, if you want to use ISIS in conjunction with other conda packages, +we recommend that you ***avoid*** adding other packages to the environment +you create when you +[install ISIS](../../how-to-guides/environment-setup-and-maintenance/installing-isis-via-anaconda.md). +This is similar to the best-practice of keeping your +`base` conda environment free of extra conda packages. + +Instead, when you need to run ISIS programs in other conda environments, try **Stacking**. Or, for some more complex scenarios, you can try *editing the activation script*. + +----- + +## Stacking (Easy) + +Create a working environment (we call ours `working` in this tutorial) and add the conda packages you need. + +To stack environments, first activate your `isis` environment. Then activate your `working` env on top of your isis env with the `--stack` argument. + +```sh +conda activate isis +conda activate --stack working +``` + +That's it, your `working` env is now stacked on top of your `isis` env. + +!!! note "Exiting stacked environments: run `conda deactivate` twice" + + You'll have to run `conda deactivate` two times to exit your conda environments: once to get out of `working`, and then once more to get out of `isis`. + +----- + +## Editing the Activation Script (Hard) + +Stacking might not work if you have +a complex set of packages/dependencies, +so here's one alternative: editing the activation script. + +!!! warning + + If you aren't comfortable following these steps + for editing the activation script, contact your + system administrator. + +In theory, all you really need in your `working` env are the +ISIS environmental variables and the path to the ISIS apps. You can set those up by customizing your conda env's `activate.d/` and `deactivate.d/` directories. + +1. **Working Env** + Create your `working` conda env and add the packages you need. +
+ +1. **Base Conda Prefix** + Locate the path to your base conda environment. + + echo $CONDA_PREFIX + + Our Result: `~/miniconda3`. + You should use your own result from the above command. +
+ +1. **ISIS Conda Prefix** + Locate the path to your ISIS conda environment: + + conda activate isis + echo $CONDA_PREFIX + + Our Result: `~/miniconda3/envs/isis`. + + You can do the same thing to find the path to your `working` + environment, our result being `~/miniconda3/envs/working`. +
+ +1. **Copy Scripts** + Copy the ISIS activation and deactivation scripts to your new + environment. + + !!! warning "Don't just copy & paste our commands, use your own system details." + + For steps 4-6, use your own **env names** and **folder names**, don't just copy and paste. If your shell *doesn't use bash*, you may need to use a different `env_vars.*` file, and/or different command syntax. + + ```sh + # Go to your conda envs folder + cd ~/miniconda3/envs/ + + # create activate.d and deactivate.d folders in your 'working' env + mkdir -p working/etc/conda/activate.d/ + mkdir -p working/etc/conda/deactivate.d/ + + # Copy activation and deactivation scripts + # from your 'isis' env to your 'working' env. + cp isis/etc/conda/activate.d/env_vars.sh working/etc/conda/activate.d/env_vars.sh + cp isis/etc/conda/deactivate.d/env_vars.sh working/etc/conda/deactivate.d/env_vars.sh + ``` +
+ + +1. **Add /bin to path at Activation** + Edit the copied activation file in + `~/miniconda3/envs/working/etc/conda/activate.d/` to add the + ISIS executable directory to the path, by adding this line at the + end: + + ```sh + export PATH=$PATH:$ISISROOT/bin + ``` + + It's important to add `$ISISROOT/bin` to the end of the path in your + working environment, not the beginning. +
+ +1. **Remove /bin from path at Deactivation** + Edit the copied deactivation file in + `$HOME/anaconda3/envs/working/etc/conda/deactivate.d/` to remove + the path, by adding this line at the end: + + ```sh + export PATH=`echo -n $PATH | awk -v RS=: -v ORS=: '/isis/ {next} {print}' | sed 's/:$//'`;` + ``` + + (`isis` here being the name of your isis env. You can look in + the `activate.d/env_vars.sh` file to see what it should be.) \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index fba0d18..250c3b2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -57,6 +57,7 @@ nav: - Environment Setup and Maintenance: - Installing ISIS: how-to-guides/environment-setup-and-maintenance/installing-isis-via-anaconda.md - Setting up the ISIS Data Area: how-to-guides/environment-setup-and-maintenance/isis-data-area.md + - Using ISIS in other Conda Envs: how-to-guides/environment-setup-and-maintenance/using-isis-in-other-conda-envs.md - Anaconda in a Network Environment: how-to-guides/environment-setup-and-maintenance/anaconda-in-a-network-environment.md - SPICE Kernel Updates in ISIS: how-to-guides/environment-setup-and-maintenance/spice-kernel-updates-in-isis.md - Adding USGSCSM Plugin to ISIS: how-to-guides/environment-setup-and-maintenance/adding-usgscsm-plugin-to-isis.md From d2952e5a132ee67336445713f7bc4468fda8901f Mon Sep 17 00:00:00 2001 From: Jacob Cain Date: Fri, 22 Nov 2024 09:49:00 -0800 Subject: [PATCH 2/2] downloadIsisData for isis <= 7 --- .../isis-data-area.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/how-to-guides/environment-setup-and-maintenance/isis-data-area.md b/docs/how-to-guides/environment-setup-and-maintenance/isis-data-area.md index ecb4a1c..1869b96 100644 --- a/docs/how-to-guides/environment-setup-and-maintenance/isis-data-area.md +++ b/docs/how-to-guides/environment-setup-and-maintenance/isis-data-area.md @@ -97,6 +97,23 @@ downloadIsisData [mission] [download destination] [optional flags] downloadIsisData --help ``` +??? "downloadIsisData script for ISIS 7.0.0 and earlier" + + The `downloadIsisData` was not included with earlier versions of ISIS. To use it for those versions, download three things first: rclone, the `downloadIsisData` script and the `rclone.conf` file. + + ```sh + # Install rclone + conda install -c conda-forge rclone + + # Download the script and rclone config file + curl -LJO https://github.com/USGS-Astrogeology/ISIS3/raw/dev/isis/scripts/downloadIsisData + curl -LJO https://github.com/USGS-Astrogeology/ISIS3/raw/dev/isis/config/rclone.conf + + # Use python 3 when you run the script, + # and use --config to point to where you downloaded the config file + python3 downloadIsisData --config rclone.conf $ISISDATA + ``` + ### Full Download To download **ALL** Isis data, including the base and all of the mission data areas: