[MRG]: DOC: Final install instructions

installer/README.md

@@ -1,5 +1,7 @@
 # HNN Installation
 
+**Note**: these are instructions for installing the *original* version of HNN, which is **no longer actively-developed**, and only made available for scientific reproducibility. If you are reading this, you probably want to be using the actively-developed version, called *HNN-Core*, which is [available here](https://github.com/jonescompneurolab/hnn-core).
+
 This directory contains instructions and files supporting installation of HNN on supported platforms. Click on the link below corresponding to your operating system:
 
 * [Windows](windows)

installer/aws/README.md

@@ -1,5 +1,7 @@
 # HNN on Amazon Cloud (AWS)
 
+**Note**: these are instructions for installing the *original* version of HNN, which is **no longer actively-developed**, and only made available for scientific reproducibility. If you are reading this, you probably want to be using the actively-developed version, called *HNN-Core*, which is [available here](https://github.com/jonescompneurolab/hnn-core).
+
 This guide describes running HNN on Amazon Web Services (AWS). An image containing HNN pre-installed is available as a Community AMI.
 
 ## Starting an Amazon EC2 instance with HNN pre-installed
@@ -44,4 +46,4 @@ The script used to create the AMI referenced above on Ubuntu 18.04 can be found
 
 If you run into other issues with the installation, please [open an issue on our GitHub](https://github.com/jonescompneurolab/hnn/issues). Our team monitors these issues and will be able to suggest possible fixes.
 
-For other HNN software issues, please visit the [HNN bulletin board](https://www.neuron.yale.edu/phpBB/viewforum.php?f=46)
+For other HNN software issues, please visit the [HNN bulletin board](https://www.neuron.yale.edu/phpBB/viewforum.php?f=46)

installer/brown_ccv/2021_instructions/README.md

@@ -0,0 +1,20 @@
+# Running HNN on Brown's Oscar supercomputer
+
+**(Brown students, staff, faculty only)**
+
+Brown's [Oscar supercomputer](https://ccv.brown.edu/services/infrastructure/oscar/) operated by the Center for Computation and Visualization (CCV) group is able to run HNN as a Docker container using [Singularity](https://www.sylabs.io/guides/3.0/user-guide/). This method greatly simplifies installing HNN and its prerequisites. Instead, HNN is pre-installed in a vetted environment inside a Docker container that is pulled from Docker Hub before starting on Oscar.
+
+## Getting an account on Oscar
+
+Please fill out a [new user account form](https://brown.edu/cis/forms/CCV/newuseraccount.php). If you are a member of a lab that has priority or condo access on Oscar, make sure to list the PI and request those accesses. Otherwise choose an exploratory account for access to 16 cores, which is adequate for most HNN simulations.
+
+## Choose a method for displaying GUI
+
+In order to display the HNN GUI on your computer (while HNN is running on Oscar), you can use X11 forwarding or the Java VNC client. X11 forwarding is typically easier once you have installed an X client on your system (XQuartz for Mac and VcXsrv for Windows)
+
+* [X11 Forwarding (recommended)](./x11-forwarding.md)
+* [VNC Client](./vnc-client.md)
+
+## Installing HNN in a user directory (Advanced users)
+
+Alternatively, advanced users may wish to install HNN and run it from their home directory rather than a Docker container

installer/brown_ccv/README.md

@@ -1,20 +1,36 @@
 # Running HNN on Brown's Oscar supercomputer
 
+**Note**: these are instructions for installing the *original* version of HNN, which is **no longer actively-developed**, and only made available for scientific reproducibility. If you are reading this, you probably want to be using the actively-developed version, called *HNN-Core*, which is [available here](https://github.com/jonescompneurolab/hnn-core).
+
 **(Brown students, staff, faculty only)**
 
-Brown's [Oscar supercomputer](https://ccv.brown.edu/services/infrastructure/oscar/) operated by the Center for Computation and Visualization (CCV) group is able to run HNN as a Docker container using [Singularity](https://www.sylabs.io/guides/3.0/user-guide/). This method greatly simplifies installing HNN and its prerequisites. Instead, HNN is pre-installed in a vetted environment inside a Docker container that is pulled from Docker Hub before starting on Oscar.
+Brown's [Oscar supercomputer](https://docs.ccv.brown.edu/oscar) operated by the Center for Computation and Visualization (CCV) group is able to run HNN as a Docker container using [Singularity](https://www.sylabs.io/guides/3.0/user-guide/). This method greatly simplifies installing HNN and its prerequisites. Instead, HNN is pre-installed in a vetted environment inside a Docker container that is pulled from Docker Hub before starting on Oscar.
 
 ## Getting an account on Oscar
 
-Please fill out a [new user account form](https://brown.edu/cis/forms/CCV/newuseraccount.php). If you are a member of a lab that has priority or condo access on Oscar, make sure to list the PI and request those accesses. Otherwise choose an exploratory account for access to 16 cores, which is adequate for most HNN simulations.
+To create an Oscar account, follow the instructions and click the New User Account link on [Oscar's frontpage](https://docs.ccv.brown.edu/oscar). If you are a member of a lab that has priority or Condo access on Oscar, make sure to list the PI and request those accesses. Otherwise choose an free "Exploratory" account for access to 16 cores, which is adequate for most HNN simulations.
+
+## Running HNN
+
+1. Go to [Oscar-on-Demand](https://ood.ccv.brown.edu/pun/sys/dashboard).
+2. Choose the Desktop application and launch a new session (pick the "6 cores" option).
+3. Once the Desktop is launched, open the "Terminal Emulator" program (one of the options at the bottom of the Desktop), and enter the following command. (Note that after you have installed and run HNN for the first time, you no longer need to run this line.)
+
+```bash
+singularity pull docker://jonescompneurolab/hnn
+```
 
-## Choose a method for displaying GUI
+3. To open the HNN graphical user interface (GUI), run the following commands:
 
-In order to display the HNN GUI on your computer (while HNN is running on Oscar), you can use X11 forwarding or the Java VNC client. X11 forwarding is typically easier once you have installed an X client on your system (XQuartz for Mac and VcXsrv for Windows)
+```bash
+singularity shell hnn_latest.sif
+source /home/hnn_user/hnn_envs
+cd /home/hnn_user/hnn_source_code
+python3 hnn.py
+```
 
-* [X11 Forwarding (recommended)](./x11-forwarding.md)
-* [VNC Client](./vnc-client.md)
+4. HNN should open with two windows, and you should be able to click the "Run Simulation" button and see a small dialogue box appear displaying the time steps of the simulation appear in real-time. Now it's time to simulate!
 
-## Installing HNN in a user directory (Advanced users)
+## Troubleshooting
 
-Alternatively, advanced users may wish to install HNN and run it from their home directory rather than a Docker container
+If you have issues with the above installation method, you can view older but different install methods at [this link here](2021_instructions).

installer/centos/README.md

@@ -1,5 +1,7 @@
 # HNN "Python" install (CentOS)
 
+**Note**: these are instructions for installing the *original* version of HNN, which is **no longer actively-developed**, and only made available for scientific reproducibility. If you are reading this, you probably want to be using the actively-developed version, called *HNN-Core*, which is [available here](https://github.com/jonescompneurolab/hnn-core).
+
 The script below assumes that it can update OS packages for python and prerequisites for HNN.
 
 * CentOS 7: [hnn-centos7.sh](hnn-centos7.sh)
@@ -44,11 +46,3 @@ cd hnn_source_code
 make
 python3 hnn.py
 ```
-
-## Troubleshooting
-
-If you run into other issues with the installation, please [open an issue on our GitHub](https://github.com/jonescompneurolab/hnn/issues). Our team monitors these issues and will investigate possible fixes.
-
-Another option for users that are running into problems with the above methods, we provide a VirtualBox VM pre-installed with HNN.
-
-* [Virtualbox install instructions](../virtualbox/README.md)

installer/mac/2021_instructions/README.md

@@ -0,0 +1,134 @@
+# HNN "Python" install (Mac OS)
+
+## Opening a terminal window
+
+- Open up macOS's terminal.app by searching for terminal in Spotlight (upper right search icon). We will use this terminal for running the commands below.
+
+## Run pre-install checks
+
+- The command below will run a script to check for existing installations of prerequisites. If a compatible version is installed, it will say which steps can be skipped below.
+
+    ```bash
+    curl -s "https://raw.githubusercontent.com/jonescompneurolab/hnn/master/installer/mac/check-pre.sh" | bash
+    ```
+
+## Prerequisite 1: Xcode Command Line Tools
+
+The Xcode Command Line Tools package includes utilities for compiling code from the terminal (gcc, make, etc.). This is needed for compiling mod files in NEURON.
+
+1. To install the package, type the following from a terminal.app window:
+
+    ```bash
+    xcode-select --install
+    ```
+
+     - If you get the following error, you can skip this step.
+      `xcode-select: error: command line tools are already installed, use "Software Update" to install updates`
+
+2. Then press `Install` in the pop-up dialog
+
+  <img src="install_pngs/xcode_tools.png" width="400" />
+
+## Prerequisite 2: Miniconda (Python 3)
+
+- Run the commands below from a terminal window (as a regular user). This will create a python environment isolated from other installations on the system. You could use homebrew `brew install python3` if you wish (has been tested with HNN), but this guide will cover the miniconda version.
+
+    ```bash
+    cd /tmp/
+    curl -O https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh
+    sh ./Miniconda3-latest-MacOSX-x86_64.sh -b
+    rm /tmp/Miniconda3-latest-MacOSX-x86_64.sh
+    ```
+
+## Download HNN source code
+
+- The following commands will download the hnn source code. We use the directory `hnn_source_code` for consistency with all of our instructions, but any directory can be used. You can use `git` if you prefer.
+
+    ```bash
+    curl -OL https://github.com/jonescompneurolab/hnn/releases/latest/download/hnn.tar.gz
+    mkdir hnn_source_code
+    tar -x --strip-components 1 -f hnn.tar.gz -C hnn_source_code
+    ```
+
+## Prepare the Python environment
+
+1. Create a conda environment with the Python prerequisites for HNN.
+
+    ```bash
+    cd hnn_source_code
+    curl -O https://raw.githubusercontent.com/jonescompneurolab/hnn/master/environment.yml
+    conda env create -f environment.yml
+    ```
+
+2. Activate the HNN conda environment and install nlopt and NEURON
+
+    ```bash
+    source activate hnn
+    pip install nlopt NEURON
+    ```
+
+3. Set the LD_LIBRARY_PATH for openmpi on conda activation. This environnement variable must be set before HNN can run simulations with openmpi. The variable is only useful inside the 'hnn' conda environment, so we will set the variable when conda is activated with `source activate hnn`. Run the following commands to make this automatic.
+
+    ```bash
+    cd ${CONDA_PREFIX}
+    mkdir -p etc/conda/activate.d etc/conda/deactivate.d
+    echo "export OLD_DYLD_FALLBACK_LIBRARY_PATH=\$DYLD_FALLBACK_LIBRARY_PATH" >> etc/conda/activate.d/env_vars.sh
+    echo "export DYLD_FALLBACK_LIBRARY_PATH=\$DYLD_FALLBACK_LIBRARY_PATH:\${CONDA_PREFIX}/lib" >> etc/conda/activate.d/env_vars.sh
+    echo "export DYLD_FALLBACK_LIBRARY_PATH=\$OLD_DYLD_FALLBACK_LIBRARY_PATH" >> etc/conda/deactivate.d/env_vars.sh
+    echo "unset OLD_DYLD_FALLBACK_LIBRARY_PATH" >> etc/conda/deactivate.d/env_vars.sh
+    ```
+
+4. Open a new terminal window for the settings in the previous step to take effect and activate the HNN conda environment
+
+    ```bash
+    source activate hnn
+    ```
+
+## Run post-install checks and compile NEURON mode files
+
+- Run a post-installation check to ensure that all necessary libraries were 
+  successful installed. Finally, we will compile the NEURON mod files.
+
+    ```bash
+    curl -s "https://raw.githubusercontent.com/jonescompneurolab/hnn/master/installer/mac/check-post.sh" | bash
+    cd hnn_source_code
+    make
+    ```
+
+## Run the HNN model
+
+1. Start the HNN GUI from a terminal window:
+
+    ```bash
+    source activate hnn
+    python hnn.py
+    ```
+
+2. The HNN GUI should show up. Make sure that you can run simulations by clicking the 'Run Simulation' button. This will run a simulation with the default configuration. After it completes, graphs should be displayed in the main window.
+
+3. When you run simulations for the first time, the following dialog boxes may pop-up and ask you for permission to allow connections through the firewall. Saying 'Deny' is fine since simulations will just run locally on your Mac.
+
+    <img src="install_pngs/nrniv_firewall.png" width="400" />
+
+    <img src="install_pngs/orterun_firewall.png" width="400" />
+
+4. You can now proceed to running the tutorials at https://hnn.brown.edu/index.php/tutorials/ . Some things to note:
+    - A directory called "hnn_out" exists in your home directory where the results from your simulations (data and param files) will be stored.
+
+## Upgrading to a new version of HNN
+
+HNN Releases can be seen on the [GitHub releases page](https://github.com/jonescompneurolab/hnn/releases/). You can also be notified of new releases by watching the hnn [repository on GitHub](https://github.com/jonescompneurolab/hnn/).
+
+If you downloaded the `tar.gz` file, simply re-run the steps above, but replace `hnn_source_code` with a new directory name.
+
+Otherwise, if you are using `git`, then run `git pull origin master` from the source code directory.
+
+## Troubleshooting
+
+For Mac OS specific issues: please see the [Mac OS troubleshooting page](troubleshooting.md)
+
+If you run into other issues with the installation, please [open an issue on our GitHub](https://github.com/jonescompneurolab/hnn/issues). Our team monitors these issues and will investigate possible fixes.
+
+Another option for users that are running into problems with the above methods, we provide a VirtualBox VM pre-installed with HNN.
+
+- [Virtualbox install instructions](../virtualbox/README.md)