diff --git a/installer/README.md b/installer/README.md index cf99bb984..b51d2d473 100644 --- a/installer/README.md +++ b/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) diff --git a/installer/aws/README.md b/installer/aws/README.md index 9f08f2201..5b05b9be2 100644 --- a/installer/aws/README.md +++ b/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) \ No newline at end of file +For other HNN software issues, please visit the [HNN bulletin board](https://www.neuron.yale.edu/phpBB/viewforum.php?f=46) diff --git a/installer/brown_ccv/2021_instructions/README.md b/installer/brown_ccv/2021_instructions/README.md new file mode 100644 index 000000000..063dd2d01 --- /dev/null +++ b/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 diff --git a/installer/brown_ccv/install_pngs/jdk.png b/installer/brown_ccv/2021_instructions/install_pngs/jdk.png similarity index 100% rename from installer/brown_ccv/install_pngs/jdk.png rename to installer/brown_ccv/2021_instructions/install_pngs/jdk.png diff --git a/installer/brown_ccv/oscar_setup.sh b/installer/brown_ccv/2021_instructions/oscar_setup.sh similarity index 100% rename from installer/brown_ccv/oscar_setup.sh rename to installer/brown_ccv/2021_instructions/oscar_setup.sh diff --git a/installer/brown_ccv/vnc-client.md b/installer/brown_ccv/2021_instructions/vnc-client.md similarity index 100% rename from installer/brown_ccv/vnc-client.md rename to installer/brown_ccv/2021_instructions/vnc-client.md diff --git a/installer/brown_ccv/x11-forwarding.md b/installer/brown_ccv/2021_instructions/x11-forwarding.md similarity index 100% rename from installer/brown_ccv/x11-forwarding.md rename to installer/brown_ccv/2021_instructions/x11-forwarding.md diff --git a/installer/brown_ccv/README.md b/installer/brown_ccv/README.md index 063dd2d01..1d987057f 100644 --- a/installer/brown_ccv/README.md +++ b/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). diff --git a/installer/centos/README.md b/installer/centos/README.md index 01b88ce30..51e0be170 100644 --- a/installer/centos/README.md +++ b/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) diff --git a/installer/mac/2021_instructions/README.md b/installer/mac/2021_instructions/README.md new file mode 100644 index 000000000..6e2c40b38 --- /dev/null +++ b/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 + + + +## 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. + + + + + +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) diff --git a/installer/mac/check-post.sh b/installer/mac/2021_instructions/check-post.sh similarity index 100% rename from installer/mac/check-post.sh rename to installer/mac/2021_instructions/check-post.sh diff --git a/installer/mac/check-pre.sh b/installer/mac/2021_instructions/check-pre.sh similarity index 100% rename from installer/mac/check-pre.sh rename to installer/mac/2021_instructions/check-pre.sh diff --git a/installer/mac/docker-desktop.md b/installer/mac/2021_instructions/docker-desktop.md similarity index 100% rename from installer/mac/docker-desktop.md rename to installer/mac/2021_instructions/docker-desktop.md diff --git a/installer/mac/docker-toolbox.md b/installer/mac/2021_instructions/docker-toolbox.md similarity index 100% rename from installer/mac/docker-toolbox.md rename to installer/mac/2021_instructions/docker-toolbox.md diff --git a/installer/mac/docker_install.md b/installer/mac/2021_instructions/docker_install.md similarity index 100% rename from installer/mac/docker_install.md rename to installer/mac/2021_instructions/docker_install.md diff --git a/installer/mac/install_pngs/docker_cores.png b/installer/mac/2021_instructions/install_pngs/docker_cores.png similarity index 100% rename from installer/mac/install_pngs/docker_cores.png rename to installer/mac/2021_instructions/install_pngs/docker_cores.png diff --git a/installer/mac/install_pngs/neuron_continue.png b/installer/mac/2021_instructions/install_pngs/neuron_continue.png similarity index 100% rename from installer/mac/install_pngs/neuron_continue.png rename to installer/mac/2021_instructions/install_pngs/neuron_continue.png diff --git a/installer/mac/install_pngs/neuron_path.png b/installer/mac/2021_instructions/install_pngs/neuron_path.png similarity index 100% rename from installer/mac/install_pngs/neuron_path.png rename to installer/mac/2021_instructions/install_pngs/neuron_path.png diff --git a/installer/mac/install_pngs/neuron_path2.png b/installer/mac/2021_instructions/install_pngs/neuron_path2.png similarity index 100% rename from installer/mac/install_pngs/neuron_path2.png rename to installer/mac/2021_instructions/install_pngs/neuron_path2.png diff --git a/installer/mac/install_pngs/nrniv_firewall.png b/installer/mac/2021_instructions/install_pngs/nrniv_firewall.png similarity index 100% rename from installer/mac/install_pngs/nrniv_firewall.png rename to installer/mac/2021_instructions/install_pngs/nrniv_firewall.png diff --git a/installer/mac/install_pngs/orterun_firewall.png b/installer/mac/2021_instructions/install_pngs/orterun_firewall.png similarity index 100% rename from installer/mac/install_pngs/orterun_firewall.png rename to installer/mac/2021_instructions/install_pngs/orterun_firewall.png diff --git a/installer/mac/install_pngs/xcode_tools.png b/installer/mac/2021_instructions/install_pngs/xcode_tools.png similarity index 100% rename from installer/mac/install_pngs/xcode_tools.png rename to installer/mac/2021_instructions/install_pngs/xcode_tools.png diff --git a/installer/mac/install_pngs/xquartz_preferences.png b/installer/mac/2021_instructions/install_pngs/xquartz_preferences.png similarity index 100% rename from installer/mac/install_pngs/xquartz_preferences.png rename to installer/mac/2021_instructions/install_pngs/xquartz_preferences.png diff --git a/installer/mac/troubleshooting.md b/installer/mac/2021_instructions/troubleshooting.md similarity index 100% rename from installer/mac/troubleshooting.md rename to installer/mac/2021_instructions/troubleshooting.md diff --git a/installer/mac/README.md b/installer/mac/README.md index 6e2c40b38..117a58636 100644 --- a/installer/mac/README.md +++ b/installer/mac/README.md @@ -1,134 +1,48 @@ -# HNN "Python" install (Mac OS) +# Installing HNN via Docker on macOS -## Opening a terminal window +**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). -- 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. +## 1) Install Docker Desktop -## Run pre-install checks +Simply scroll down and follow the instructions on the website to download and install Docker Desktop: [https://www.docker.com/products/docker-desktop/](https://www.docker.com/products/docker-desktop/). -- 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. +You do NOT need to create an account. - ```bash - curl -s "https://raw.githubusercontent.com/jonescompneurolab/hnn/master/installer/mac/check-pre.sh" | bash - ``` +## 2) Install Xquartz -## Prerequisite 1: Xcode Command Line Tools +Download the installer from [https://www.xquartz.org/](https://www.xquartz.org/). -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. +## 3) Restart your computer -1. To install the package, type the following from a terminal.app window: +Make sure to restart your computer. - ```bash - xcode-select --install - ``` +## 4) Start Docker Desktop - - 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` +Start the Docker Desktop application. You can do this easily by pressing Command + space together, typing "docker", and then hit enter. If it asks you to accept any license agreements, select yes, but otherwise you don't need to change anything once it has started. -2. Then press `Install` in the pop-up dialog +## 5) Start Xquartz - +Start the Xquartz application. You can do this easily by pressing Command + space together, typing "xquartz", and then hit enter -## Prerequisite 2: Miniconda (Python 3) +After you've started it, in the top left, click the "XQuartz" dropdown menu, then "Settings" to open the Preferences window. Inside the Preferences window, click Security, then click the checkmark for "Allow connections from network clients". You should only have to do this once. -- 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. +## 6) Obtaining the HNN code - ```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 - ``` +Go to the HNN code repository at [https://github.com/jonescompneurolab/hnn](https://github.com/jonescompneurolab/hnn), then click the green "Code" button, then "Download ZIP". This will prompt you to download a file named `hnn-master.zip`. Download it. Open the Finder application, navigate to where you downloaded the file, then double-click it to create a new directory that contains the code. (If you are familiar with Git and Github, you can instead choose to clone the repository from the same repository URL.) -## Download HNN source code +## 7) Start HNN-GUI -- 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. +Once you have completed all of the above, you will only need execute the following steps everytime you want to start the HNN-GUI: - ```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. - - - - - -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. +- Make sure Docker Desktop is running. +- Make sure Xquartz is running. +- Open the Terminal application. +- Navigate to the folder where you have cloned the HNN repository using `cd`. For example, if you downloaded and decompressed the code in your `Downloads` folder using the instructions in **6) Obtaining the HNN code**, you can run the following in the terminal: `cd ~/Downloads/hnn-master/`. +- Start the GUI by running the following: `./hnn_docker.sh start`. +- You're done! Now it's time to get simulating! ## 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. +If you receive an error, try running `./hnn_docker.sh uninstall` first before running `./hnn_docker.sh start`. This could happen if you're trying to run an old version of HNN. Note that these instructions were based off of the instructions provided in this pull request: https://github.com/jonescompneurolab/hnn/pull/337 . -- [Virtualbox install instructions](../virtualbox/README.md) +If you have issues with the above installation method, you can view older but different install methods at [this link here](2021_instructions). diff --git a/installer/ubuntu/2021_instructions/README.md b/installer/ubuntu/2021_instructions/README.md new file mode 100644 index 000000000..82c4ae3bc --- /dev/null +++ b/installer/ubuntu/2021_instructions/README.md @@ -0,0 +1,45 @@ +# HNN "Python" install (Ubuntu) + +The script below assumes that it can update OS packages for python and prerequisites for NHNN. + +```bash +curl --remote-name https://raw.githubusercontent.com/jonescompneurolab/hnn/master/installer/ubuntu/hnn-ubuntu.sh +bash hnn-ubuntu.sh +``` + +## Start HNN + +1. From the command-line, type following commands + + ```bash + cd hnn_source_code + python3 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. You can now proceed to running the tutorials at [https://hnn.brown.edu/index.php/tutorials/](https://hnn.brown.edu/index.php/tutorials/) . Some things to note: + + * A directory called "hnn_out" exists in your home directory in Ubuntu 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/). + +To download the latest release, use the following commands within an Ubuntu terminal: + +```bash +curl --remote-name https://github.com/jonescompneurolab/hnn/releases/latest/download/hnn.tar.gz +tar -x --strip-components 1 -f hnn.tar.gz -C hnn_source_code +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) diff --git a/installer/ubuntu/docker-desktop.md b/installer/ubuntu/2021_instructions/docker-desktop.md similarity index 100% rename from installer/ubuntu/docker-desktop.md rename to installer/ubuntu/2021_instructions/docker-desktop.md diff --git a/installer/ubuntu/hnn-ubuntu.sh b/installer/ubuntu/2021_instructions/hnn-ubuntu.sh similarity index 100% rename from installer/ubuntu/hnn-ubuntu.sh rename to installer/ubuntu/2021_instructions/hnn-ubuntu.sh diff --git a/installer/ubuntu/README.md b/installer/ubuntu/README.md index 82c4ae3bc..ec7660083 100644 --- a/installer/ubuntu/README.md +++ b/installer/ubuntu/README.md @@ -1,45 +1,61 @@ -# HNN "Python" install (Ubuntu) +# Installing HNN via Python on Ubuntu Linux -The script below assumes that it can update OS packages for python and prerequisites for NHNN. +**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). -```bash -curl --remote-name https://raw.githubusercontent.com/jonescompneurolab/hnn/master/installer/ubuntu/hnn-ubuntu.sh -bash hnn-ubuntu.sh -``` +These instructions were last successfully testing in September 2025, using Kubuntu 24.04 and Linux Mint 21.2 Cinnamon. + +## 1) Install system packages -## Start HNN +First, open a terminal program and update the following system packages using a command like the following: -1. From the command-line, type following commands +```bash +sudo apt-get update +sudo apt-get install --no-install-recommends -y \ + make gcc g++ \ + openmpi-bin lsof \ + libfontconfig1 libxext6 libx11-xcb1 libxcb-glx0 \ + libxkbcommon-x11-0 libgl1-mesa-dev \ + libncurses6 libreadline8 libdbus-1-3 libopenmpi-dev \ + libc6-dev libtinfo-dev libncurses-dev \ + libx11-dev libreadline-dev \ + libxcb-icccm4 libxcb-util1 libxcb-image0 libxcb-keysyms1 \ + libxcb-render0 libxcb-shape0 libxcb-randr0 libxcb-render-util0 \ + libxcb-xinerama0 libxcb-xfixes0 +``` - ```bash - cd hnn_source_code - python3 hnn.py - ``` +## 2) Install Python and Python dependencies -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. +We recommend installing Python via the [Anaconda Distribution](https://www.anaconda.com/download/success), but any virtual environment tool should work. Create a new virtual environment and enter it. (If you are new to Python virtual environments, see [https://www.anaconda.com/docs/getting-started/getting-started](https://www.anaconda.com/docs/getting-started/getting-started)). -3. You can now proceed to running the tutorials at [https://hnn.brown.edu/index.php/tutorials/](https://hnn.brown.edu/index.php/tutorials/) . Some things to note: +We recommend you use Python 3.8. Python version 3.10 or later is unlikely to work. - * A directory called "hnn_out" exists in your home directory in Ubuntu where the results from your simulations (data and param files) will be stored. +Once you are inside your environment, install the following packages from pip using a command like the following: -## Upgrading to a new version of HNN +```bash +pip install --no-cache-dir \ + NEURON matplotlib PyOpenGL \ + pyqt5 pyqtgraph scipy numpy nlopt psutil +``` -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/). +## 3) Download HNN code and compile mechanisms -To download the latest release, use the following commands within an Ubuntu terminal: +Next, you need to download and unpack the HNN release. Note that these files are NOT the same as cloning the `hnn` repository! Once you `cd` into the directory of your choosing, you can run the following command to download, extract, and compile the NEURON mechanisms of the HNN code: ```bash -curl --remote-name https://github.com/jonescompneurolab/hnn/releases/latest/download/hnn.tar.gz -tar -x --strip-components 1 -f hnn.tar.gz -C hnn_source_code +curl -sOL https://github.com/jonescompneurolab/hnn/releases/latest/download/hnn.tar.gz +tar -x --strip-components 1 -f hnn.tar.gz --one-top-level=hnn_source_code cd hnn_source_code make -python3 hnn.py ``` -## Troubleshooting +## 4) Run HNN + +Finally, once you have done all of the above, you can start the HNN-GUI using the following command: -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. +```bash +python hnn.py +``` -Another option for users that are running into problems with the above methods, we provide a VirtualBox VM pre-installed with HNN. +## Troubleshooting -* [Virtualbox install instructions](../virtualbox/README.md) +If you have issues with the above installation method, you can view older but different install methods at [this link here](2021_instructions). You can also try downloading [Docker Desktop](https://www.docker.com/products/docker-desktop/), downloading git (`sudo apt-get install git`), then using the HNN Docker image by following the instructions starting with "Part 4" from this comment: https://github.com/jonescompneurolab/hnn/pull/337#issuecomment-1799006204 . diff --git a/installer/virtualbox/README.md b/installer/virtualbox/README.md index 8f234677e..0a05cdcea 100644 --- a/installer/virtualbox/README.md +++ b/installer/virtualbox/README.md @@ -1,5 +1,7 @@ # Running HNN in VirtualBox VM +**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). + We have created a VirtualBox VM image that allows users to run HNN using virtualization software. The virtualized machine runs Ubuntu Linux with HNN pre-installed. You will need an additional ~20 GB of storage space on your machine to set up the VirtualBox image. Of note, any virtualization software can be used to the same effect. @@ -46,10 +48,4 @@ Additional Notes: ## Updating HNN -Improvements to HNN with updated releases can be found on [our GitHub page](https://github.com/jonescompneurolab/hnn/releases">https://github.com/jonescompneurolab/hnn/releases). These changes may need to be incorporated into to the VM by running the command `git pull origin master` from the `/home/hnn_user/hnn_source_code` directory in a terminal window. - -## 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 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) +Improvements to HNN with updated releases can be found on [our GitHub page](https://github.com/jonescompneurolab/hnn/releases). These changes may need to be incorporated into to the VM by running the command `git pull origin master` from the `/home/hnn_user/hnn_source_code` directory in a terminal window. diff --git a/installer/windows/Dockerfile b/installer/windows/2021_instructions/Dockerfile similarity index 100% rename from installer/windows/Dockerfile rename to installer/windows/2021_instructions/Dockerfile diff --git a/installer/windows/2021_instructions/README.md b/installer/windows/2021_instructions/README.md new file mode 100644 index 000000000..42cf2605d --- /dev/null +++ b/installer/windows/2021_instructions/README.md @@ -0,0 +1,13 @@ +# Installing HNN on Windows + +This guide describes installing HNN on Windows 10. + +We recommend the Microsoft [Windows Subsystem for Linux (WSL) installation](wsl.md) because: + +1. The simulation code is compiled into a Linux system compatible format, which actually runs faster than when compiled to run directly on Windows. +2. With WSL installed, the installation process becomes nearly identical to that on a Linux system, which helps ensure that the installation process remains reliable with common troubleshooting steps. + +The major drawbacks to the recommend option are: + +1. Using WSL requires running a X server on the Windows OS to display graphics from the WSL environment. The steps to install VcXsrv (a free X server for Windows) are part of the HNN installation instructions above. +2. The data and parameter files from HNN simulations are stored in a filesystem specific for the Ubuntu application. You can read Windows files from Ubuntu in the Ubuntu command-line (e.g. via `/mnt/c/users/`). However, you cannot access simulation results from Windows applications without copying the file to the mount directory first. See [WSL FAQ](https://docs.microsoft.com/en-us/windows/wsl/faq#how-do-i-use-a-windows-file-with-a-linux-app). If this is a limitation for your workflow, please try the Windows-native install instructions. diff --git a/installer/windows/docker-desktop.md b/installer/windows/2021_instructions/docker-desktop.md similarity index 100% rename from installer/windows/docker-desktop.md rename to installer/windows/2021_instructions/docker-desktop.md diff --git a/installer/windows/docker-toolbox.md b/installer/windows/2021_instructions/docker-toolbox.md similarity index 100% rename from installer/windows/docker-toolbox.md rename to installer/windows/2021_instructions/docker-toolbox.md diff --git a/installer/windows/hnn-windows.ps1 b/installer/windows/2021_instructions/hnn-windows.ps1 similarity index 100% rename from installer/windows/hnn-windows.ps1 rename to installer/windows/2021_instructions/hnn-windows.ps1 diff --git a/installer/windows/install_pngs/access_filesystem.png b/installer/windows/2021_instructions/install_pngs/access_filesystem.png similarity index 100% rename from installer/windows/install_pngs/access_filesystem.png rename to installer/windows/2021_instructions/install_pngs/access_filesystem.png diff --git a/installer/windows/install_pngs/disable-hyperv.png b/installer/windows/2021_instructions/install_pngs/disable-hyperv.png similarity index 100% rename from installer/windows/install_pngs/disable-hyperv.png rename to installer/windows/2021_instructions/install_pngs/disable-hyperv.png diff --git a/installer/windows/install_pngs/docker-toolbox-error-hyperv-on.png b/installer/windows/2021_instructions/install_pngs/docker-toolbox-error-hyperv-on.png similarity index 100% rename from installer/windows/install_pngs/docker-toolbox-error-hyperv-on.png rename to installer/windows/2021_instructions/install_pngs/docker-toolbox-error-hyperv-on.png diff --git a/installer/windows/install_pngs/docker_cores.png b/installer/windows/2021_instructions/install_pngs/docker_cores.png similarity index 100% rename from installer/windows/install_pngs/docker_cores.png rename to installer/windows/2021_instructions/install_pngs/docker_cores.png diff --git a/installer/windows/install_pngs/enable_hyperv.png b/installer/windows/2021_instructions/install_pngs/enable_hyperv.png similarity index 100% rename from installer/windows/install_pngs/enable_hyperv.png rename to installer/windows/2021_instructions/install_pngs/enable_hyperv.png diff --git a/installer/windows/install_pngs/hyper-V.png b/installer/windows/2021_instructions/install_pngs/hyper-V.png similarity index 100% rename from installer/windows/install_pngs/hyper-V.png rename to installer/windows/2021_instructions/install_pngs/hyper-V.png diff --git a/installer/windows/install_pngs/hyperv_error.png b/installer/windows/2021_instructions/install_pngs/hyperv_error.png similarity index 100% rename from installer/windows/install_pngs/hyperv_error.png rename to installer/windows/2021_instructions/install_pngs/hyperv_error.png diff --git a/installer/windows/install_pngs/virtualbox_cores.png b/installer/windows/2021_instructions/install_pngs/virtualbox_cores.png similarity index 100% rename from installer/windows/install_pngs/virtualbox_cores.png rename to installer/windows/2021_instructions/install_pngs/virtualbox_cores.png diff --git a/installer/windows/install_pngs/virtualization_disabled.png b/installer/windows/2021_instructions/install_pngs/virtualization_disabled.png similarity index 100% rename from installer/windows/install_pngs/virtualization_disabled.png rename to installer/windows/2021_instructions/install_pngs/virtualization_disabled.png diff --git a/installer/windows/install_pngs/vtx_disabled.png b/installer/windows/2021_instructions/install_pngs/vtx_disabled.png similarity index 100% rename from installer/windows/install_pngs/vtx_disabled.png rename to installer/windows/2021_instructions/install_pngs/vtx_disabled.png diff --git a/installer/windows/native_install.md b/installer/windows/2021_instructions/native_install.md similarity index 100% rename from installer/windows/native_install.md rename to installer/windows/2021_instructions/native_install.md diff --git a/installer/windows/wsl.md b/installer/windows/2021_instructions/wsl.md similarity index 100% rename from installer/windows/wsl.md rename to installer/windows/2021_instructions/wsl.md diff --git a/installer/windows/README.md b/installer/windows/README.md index 42cf2605d..065ca8882 100644 --- a/installer/windows/README.md +++ b/installer/windows/README.md @@ -1,13 +1,50 @@ -# Installing HNN on Windows +# Installing HNN via Docker on Windows (WSL) -This guide describes installing HNN on Windows 10. +**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). -We recommend the Microsoft [Windows Subsystem for Linux (WSL) installation](wsl.md) because: +## 1) Install Docker Desktop -1. The simulation code is compiled into a Linux system compatible format, which actually runs faster than when compiled to run directly on Windows. -2. With WSL installed, the installation process becomes nearly identical to that on a Linux system, which helps ensure that the installation process remains reliable with common troubleshooting steps. +Simply scroll down and follow the instructions on the website to download and install Docker Desktop: [https://www.docker.com/products/docker-desktop/](https://www.docker.com/products/docker-desktop/). -The major drawbacks to the recommend option are: +You do NOT need to create an account. + +## 2) Install Windows Subsystem for Linux (WSL) + +Open the "PowerShell" or "Windows Command Prompt" programs in administrator mode by right-clicking either and selecting "Run as administrator". Then, in the window, run the following command: + +``` +wsl --install +``` + +Follow the default options for your install. For more information, see https://learn.microsoft.com/en-us/windows/wsl/install . + +## 3) Install VcXsrv + +Download "VcXsrv Windows X Server" from either https://sourceforge.net/projects/vcxsrv/ (older) or https://github.com/marchaesen/vcxsrv/releases (newer). Either should work. + +## 4) Restart your computer + +Make sure to restart your computer. + +## 5) Start Docker Desktop + +After restart, start Docker so that it is running. Make sure to accept any license agreements if it prompts you to. + +## 6) Configure VcXsrv for WSL + +Open the new program called "Ubuntu" to access your WSL install, then follow the instructions at https://sourceforge.net/p/vcxsrv/wiki/VcXsrv%20%26%20Win10/ . The "Alternate Setup" after the main text is another method that works, and is somewhat easier to follow. If you want to use the "Alternate Setup", then you can launch the program "XLaunch" from your start menu, and enter the commands that resemble `export ...` into your "Ubuntu" window. + +## 7) Download the HNN repository + +Download the repository from https://github.com/jonescompneurolab/hnn . You can do this by either installing git then running `git clone https://github.com/jonescompneurolab/hnn`, or clicking the green `Code` button and selecting `Download ZIP`. If you downloaded the ZIP file, extract it into a folder. + +## 8) Run the HNN Docker script + +In **the Ubuntu app, which is the same as your WSL installation**, navigate to inside the `hnn` or `hnn-master` folder that you just downloaded. Then, run `./hnn_docker.sh start` to start the script, which should take a minute to download the Docker image, and then it will start up the GUI. Note that you must do this through your Ubuntu/WSL install, *not* via Windows Powershell or Command-Prompt. Then get simulating! + +## Troubleshooting + +If you receive an error, try running `./hnn_docker.sh uninstall` first, before running `./hnn_docker.sh start` again. This could happen if you're trying to run an old version of HNN. Note that these instructions were based off of the instructions provided in this pull request: https://github.com/jonescompneurolab/hnn/pull/337 . See the following comment in particular: https://github.com/jonescompneurolab/hnn/pull/337#issuecomment-1799006204 . If you run into issues, follow the instructions in that comment. + +If you have further issues with the above installation method, you can view older but different install methods at [this link here](2021_instructions). -1. Using WSL requires running a X server on the Windows OS to display graphics from the WSL environment. The steps to install VcXsrv (a free X server for Windows) are part of the HNN installation instructions above. -2. The data and parameter files from HNN simulations are stored in a filesystem specific for the Ubuntu application. You can read Windows files from Ubuntu in the Ubuntu command-line (e.g. via `/mnt/c/users/`). However, you cannot access simulation results from Windows applications without copying the file to the mount directory first. See [WSL FAQ](https://docs.microsoft.com/en-us/windows/wsl/faq#how-do-i-use-a-windows-file-with-a-linux-app). If this is a limitation for your workflow, please try the Windows-native install instructions. diff --git a/scripts/docker_functions.sh b/scripts/docker_functions.sh index a26173598..77de5eda2 100644 --- a/scripts/docker_functions.sh +++ b/scripts/docker_functions.sh @@ -628,7 +628,7 @@ function get_container_port { return 1 fi - __ssh_port=$(echo $__port_string| cut -d':' -f 2) + __ssh_port=$(echo "$__port_string" | tr -d '\r' | tail -n1 | awk -F':' '{print $NF}' | tr -d '[:space:]') re='^[0-9]+$' if ! [[ $__ssh_port =~ $re ]] ; then echo "*failed*" >> "$LOGFILE"