|
1 | | -# HNN "Python" install (Mac OS) |
| 1 | +# Installing HNN via Docker on macOS |
2 | 2 |
|
3 | | -## Opening a terminal window |
| 3 | +**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). |
4 | 4 |
|
5 | | -- 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. |
| 5 | +## 1) Install Docker Desktop |
6 | 6 |
|
7 | | -## Run pre-install checks |
| 7 | +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/). |
8 | 8 |
|
9 | | -- 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. |
| 9 | +You do NOT need to create an account. |
10 | 10 |
|
11 | | - ```bash |
12 | | - curl -s "https://raw.githubusercontent.com/jonescompneurolab/hnn/master/installer/mac/check-pre.sh" | bash |
13 | | - ``` |
| 11 | +## 2) Install Xquartz |
14 | 12 |
|
15 | | -## Prerequisite 1: Xcode Command Line Tools |
| 13 | +Download the installer from [https://www.xquartz.org/](https://www.xquartz.org/). |
16 | 14 |
|
17 | | -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. |
| 15 | +## 3) Restart your computer |
18 | 16 |
|
19 | | -1. To install the package, type the following from a terminal.app window: |
| 17 | +Make sure to restart your computer. |
20 | 18 |
|
21 | | - ```bash |
22 | | - xcode-select --install |
23 | | - ``` |
| 19 | +## 4) Start Docker Desktop |
24 | 20 |
|
25 | | - - If you get the following error, you can skip this step. |
26 | | - `xcode-select: error: command line tools are already installed, use "Software Update" to install updates` |
| 21 | +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. |
27 | 22 |
|
28 | | -2. Then press `Install` in the pop-up dialog |
| 23 | +## 5) Start Xquartz |
29 | 24 |
|
30 | | - <img src="install_pngs/xcode_tools.png" width="400" /> |
| 25 | +Start the Xquartz application. You can do this easily by pressing Command + space together, typing "xquartz", and then hit enter |
31 | 26 |
|
32 | | -## Prerequisite 2: Miniconda (Python 3) |
| 27 | +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. |
33 | 28 |
|
34 | | -- 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. |
| 29 | +## 6) Obtaining the HNN code |
35 | 30 |
|
36 | | - ```bash |
37 | | - cd /tmp/ |
38 | | - curl -O https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh |
39 | | - sh ./Miniconda3-latest-MacOSX-x86_64.sh -b |
40 | | - rm /tmp/Miniconda3-latest-MacOSX-x86_64.sh |
41 | | - ``` |
| 31 | +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.) |
42 | 32 |
|
43 | | -## Download HNN source code |
| 33 | +## 7) Start HNN-GUI |
44 | 34 |
|
45 | | -- 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. |
| 35 | +Once you have completed all of the above, you will only need execute the following steps everytime you want to start the HNN-GUI: |
46 | 36 |
|
47 | | - ```bash |
48 | | - curl -OL https://github.com/jonescompneurolab/hnn/releases/latest/download/hnn.tar.gz |
49 | | - mkdir hnn_source_code |
50 | | - tar -x --strip-components 1 -f hnn.tar.gz -C hnn_source_code |
51 | | - ``` |
52 | | - |
53 | | -## Prepare the Python environment |
54 | | - |
55 | | -1. Create a conda environment with the Python prerequisites for HNN. |
56 | | - |
57 | | - ```bash |
58 | | - cd hnn_source_code |
59 | | - curl -O https://raw.githubusercontent.com/jonescompneurolab/hnn/master/environment.yml |
60 | | - conda env create -f environment.yml |
61 | | - ``` |
62 | | - |
63 | | -2. Activate the HNN conda environment and install nlopt and NEURON |
64 | | - |
65 | | - ```bash |
66 | | - source activate hnn |
67 | | - pip install nlopt NEURON |
68 | | - ``` |
69 | | - |
70 | | -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. |
71 | | - |
72 | | - ```bash |
73 | | - cd ${CONDA_PREFIX} |
74 | | - mkdir -p etc/conda/activate.d etc/conda/deactivate.d |
75 | | - echo "export OLD_DYLD_FALLBACK_LIBRARY_PATH=\$DYLD_FALLBACK_LIBRARY_PATH" >> etc/conda/activate.d/env_vars.sh |
76 | | - echo "export DYLD_FALLBACK_LIBRARY_PATH=\$DYLD_FALLBACK_LIBRARY_PATH:\${CONDA_PREFIX}/lib" >> etc/conda/activate.d/env_vars.sh |
77 | | - echo "export DYLD_FALLBACK_LIBRARY_PATH=\$OLD_DYLD_FALLBACK_LIBRARY_PATH" >> etc/conda/deactivate.d/env_vars.sh |
78 | | - echo "unset OLD_DYLD_FALLBACK_LIBRARY_PATH" >> etc/conda/deactivate.d/env_vars.sh |
79 | | - ``` |
80 | | - |
81 | | -4. Open a new terminal window for the settings in the previous step to take effect and activate the HNN conda environment |
82 | | - |
83 | | - ```bash |
84 | | - source activate hnn |
85 | | - ``` |
86 | | - |
87 | | -## Run post-install checks and compile NEURON mode files |
88 | | - |
89 | | -- Run a post-installation check to ensure that all necessary libraries were |
90 | | - successful installed. Finally, we will compile the NEURON mod files. |
91 | | - |
92 | | - ```bash |
93 | | - curl -s "https://raw.githubusercontent.com/jonescompneurolab/hnn/master/installer/mac/check-post.sh" | bash |
94 | | - cd hnn_source_code |
95 | | - make |
96 | | - ``` |
97 | | - |
98 | | -## Run the HNN model |
99 | | - |
100 | | -1. Start the HNN GUI from a terminal window: |
101 | | - |
102 | | - ```bash |
103 | | - source activate hnn |
104 | | - python hnn.py |
105 | | - ``` |
106 | | - |
107 | | -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. |
108 | | - |
109 | | -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. |
110 | | - |
111 | | - <img src="install_pngs/nrniv_firewall.png" width="400" /> |
112 | | - |
113 | | - <img src="install_pngs/orterun_firewall.png" width="400" /> |
114 | | - |
115 | | -4. You can now proceed to running the tutorials at https://hnn.brown.edu/index.php/tutorials/ . Some things to note: |
116 | | - - A directory called "hnn_out" exists in your home directory where the results from your simulations (data and param files) will be stored. |
117 | | - |
118 | | -## Upgrading to a new version of HNN |
119 | | - |
120 | | -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/). |
121 | | - |
122 | | -If you downloaded the `tar.gz` file, simply re-run the steps above, but replace `hnn_source_code` with a new directory name. |
123 | | - |
124 | | -Otherwise, if you are using `git`, then run `git pull origin master` from the source code directory. |
| 37 | +- Make sure Docker Desktop is running. |
| 38 | +- Make sure Xquartz is running. |
| 39 | +- Open the Terminal application. |
| 40 | +- 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/`. |
| 41 | +- Start the GUI by running the following: `./hnn_docker.sh start`. |
| 42 | +- You're done! Now it's time to get simulating! |
125 | 43 |
|
126 | 44 | ## Troubleshooting |
127 | 45 |
|
128 | | -For Mac OS specific issues: please see the [Mac OS troubleshooting page](troubleshooting.md) |
129 | | - |
130 | | -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. |
131 | | - |
132 | | -Another option for users that are running into problems with the above methods, we provide a VirtualBox VM pre-installed with HNN. |
| 46 | +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 . |
133 | 47 |
|
134 | | -- [Virtualbox install instructions](../virtualbox/README.md) |
| 48 | +If you have issues with the above installation method, you can view older but different install methods at [this link here](2021_instructions). |
0 commit comments