DOC: update install docs for post-integration

jonescompneurolab · Mar 21, 2021 · 9b2f560 · 9b2f560
1 parent 80987dc
commit 9b2f560
Show file tree

Hide file tree

Showing 9 changed files with 123 additions and 173 deletions.
diff --git a/installer/centos/README.md b/installer/centos/README.md
@@ -1,4 +1,4 @@
-# HNN "Python" install (CentOS)
+# HNN install (CentOS)
 
 The script below assumes that it can update OS packages for python and prerequisites for HNN.
 
@@ -33,18 +33,20 @@ The script below assumes that it can update OS packages for python and prerequis
 
 ## 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/).
+HNN Releases can be found 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:
+To download the latest HNN release:
 
 ```bash
 curl --remote-name 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
 cd hnn_source_code
-make
 python3 hnn.py
 ```
 
+If you are using `git`, then run `git pull origin master` from the source code directory.
+
 ## 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.

diff --git a/installer/mac/README.md b/installer/mac/README.md
@@ -1,4 +1,4 @@
-# HNN "Python" install (Mac OS)
+# HNN install (Mac OS)
 
 ## Opening a terminal window
 
@@ -9,12 +9,12 @@
 - 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
+    curl -s "https://raw.githubusercontent.com/blakecaldwell/hnn/integration_docs/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.
+The Xcode Command Line Tools package includes utilities for compiling code from the terminal. This is needed for compiling NEURON mod files during the hnn-core installation.
 
 1. To install the package, type the following from a terminal.app window:
 
@@ -46,58 +46,37 @@ The Xcode Command Line Tools package includes utilities for compiling code from
 
     ```bash
     conda env create -f environment.yml
+    conda install -y -n hnn openmpi mpi4py
     ```
 
-2. Activate the HNN conda environment and install nlopt and NEURON
+2. Activate the HNN conda environment and python prerequisite packages
 
     ```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_LD_LIBRARY_PATH=\$LD_LIBRARY_PATH" >> etc/conda/activate.d/env_vars.sh
-    echo "export LD_LIBRARY_PATH=\$LD_LIBRARY_PATH:\${CONDA_PREFIX}/lib" >> etc/conda/activate.d/env_vars.sh
-    echo "export LD_LIBRARY_PATH=\$OLD_LD_LIBRARY_PATH" >> etc/conda/deactivate.d/env_vars.sh
-    echo "unset OLD_LD_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
+    conda activate hnn
+    pip install hnn-core
+    pip install nlopt
+    pip install mpi4py
     ```
 
 ## Run post-install checks
 
-- Run the command below to check that all of the steps were successful and are ready to run HNN.
-
-    ```bash
-    curl -s "https://raw.githubusercontent.com/jonescompneurolab/hnn/master/installer/mac/check-post.sh" | bash
-    ```
+```bash
+curl -s "https://raw.githubusercontent.com/blakecaldwell/hnn/integration_docs/installer/mac/check-post.sh" | bash
+```
 
 ## Download HNN source code
 
-- The following commands will download the hnn source code and compile HNN's mod files for NEURON. 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
-    cd hnn_source_code
-    make
-    ```
+```bash
+git clone https://github.com/jonescompneurolab/hnn.git
+cd hnn
+```
 
 ## Run the HNN model
 
-1. Start the HNN GUI from a terminal window:
+1. Start the HNN GUI from a terminal window. Make sure the hnn environment has been activated each time a terminal window is opened:
 
     ```bash
-    source activate hnn
+    conda activate hnn
     python hnn.py
     ```
 
@@ -109,16 +88,26 @@ The Xcode Command Line Tools package includes utilities for compiling code from
 
     <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:
+4. 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 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/).
+HNN Releases can be found 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 HNN release:
 
-If you downloaded the `tar.gz` file, simply re-run the steps above, but replace `hnn_source_code` with a new directory name.
+```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
+cd hnn_source_code
+conda activate hnn
+python3 hnn.py
+```
 
-Otherwise, if you are using `git`, then run `git pull origin master` from the source code directory.
+If you are using `git`, then run `git pull origin master` from the source code directory.
 
 ## Troubleshooting
 

diff --git a/installer/mac/check-post.sh b/installer/mac/check-post.sh
@@ -28,34 +28,6 @@ echo "--------------------------------------"
 
 CUR_DIR=$(pwd)
 
-echo -n "Checking if HNN is compiled..."
-if [[ -f ${CUR_DIR}/hnn.py ]]; then
-  if [[ -f "${CUR_DIR}/x86_64/hh2.mod" ]]; then
-    echo "ok"
-    if [[ "$VERBOSE" -eq "1" ]]; then
-      echo "HNN source code compiled and ready to use at ${CUR_DIR}"
-      echo
-    fi
-  else
-    echo "failed"
-    echo "Found a source code directory at ${CUR_DIR}, but it needs to be compiled (run make)."
-    echo
-    return=2
-  fi
-else
-  if [[ -f "$HOME/hnn/x86_64/hh2.mod" ]]; then
-    echo "warning"
-    echo "Did you mean to run this from $HOME/hnn instead?"
-    echo
-    return=1
-  else
-    echo "failed"
-    echo "Didn't find HNN source code in this directory"
-    echo
-    return=2
-  fi
-fi
-
 echo -n "Checking for miniconda..."
 MINICONDA_FOUND=
 which conda > /dev/null 2>&1
@@ -161,24 +133,6 @@ else
   echo "ok"
 fi
 
-MPI_WORKS=
-if [[ "$MPI_FOUND" -eq "1" ]]; then
-  echo -n "Checking MPI functionality..."
-  COMMAND="mpiexec -n 1 echo \"hello\" 2>&1"
-  OUTPUT=$(mpiexec -n 1 echo "hello" 2>&1)
-  if [[ "$?" -eq "0" ]] && [[ "$OUTPUT" =~ "hello" ]]; then
-    echo "ok"
-    MPI_WORKS=1
-  else
-    echo "failed"
-    echo "the command that failed was:"
-    echo "$COMMAND"
-    echo $OUTPUT
-    echo
-    return=2
-  fi
-fi
-
 # NEURON functionality checks from https://github.com/jonescompneurolab/hnn/issues/11
 NRNIV_WORKS=
 if [[ "$NRN_FOUND" -eq "1" ]]; then
@@ -202,7 +156,7 @@ else
 fi
 
 PREREQS_INSTALLED=1
-for prereq in "matplotlib" "scipy" "psutil" "numpy" "nlopt" "neuron"; do
+for prereq in "matplotlib" "scipy" "psutil" "numpy" "nlopt" "neuron" "hnn_core"; do
   echo -n "Checking Python can import $prereq module..."
   $PYTHON -c "import $prereq" > /dev/null 2>&1
   if [[ "$?" -eq "0" ]]; then
@@ -237,72 +191,52 @@ else
   echo "Skipping NEURON funtionality tests with Python."
 fi
 
-echo -n "Checking for setting LD_LIBRARY_PATH..."
-source ${CONDA_PREFIX}/etc/conda/activate.d/env_vars.sh > /dev/null 2>&1
-if [[ "$?" -eq "0" ]] && [[ -n "${LD_LIBRARY_PATH}" ]]; then
-  echo "ok"
-else
-  echo "warning"
-  echo "The LD_LIBRARY_PATH variable is not set correctly. Make sure you follow the installation"
-  echo "instructions to add the correct lines to ${CONDA_PREFIX}/etc/conda/activate.d/env_vars.sh"
-  return=1
-fi
-
-
 MPI_AND_NRNIV_WORKS=
-if [[ "$NRN_FOUND" -eq "1" ]] && [[ "$NRNIV_WORKS" -eq "1" ]] && [[ "$MPI_WORKS" -eq "1" ]]; then
+if [[ "$NRN_FOUND" -eq "1" ]] && [[ "$NRNIV_WORKS" -eq "1" ]]; then
   echo -n "Checking NEURON nrniv funtionality with MPI..."
-  mpiexec -n 2 nrniv -nobanner -nopython -mpi -c 'quit()' > /dev/null 2>&1
+  COMMAND="mpiexec -n 2 nrniv -nobanner -nopython -mpi -c 'quit()'"
+  OUTPUT=$(export LD_LIBRARY_PATH=${CONDA_PREFIX}/lib; mpiexec -n 2 nrniv -nobanner -nopython -mpi -c 'quit()')
   if [[ "$?" -eq "0" ]]; then
     echo "ok"
     MPI_AND_NRNIV_WORKS=1
   else
-    # try with LD_LIBRARY_PATH
-    COMMAND="mpiexec -n 2 nrniv -nobanner -nopython -mpi -c 'quit()'"
-    OUTPUT=$(export LD_LIBRARY_PATH=${CONDA_PREFIX}/lib; mpiexec -n 2 nrniv -nobanner -nopython -mpi -c 'quit()')
-    if [[ "$?" -eq "0" ]]; then
-      echo "warning"
-      echo "The LD_LIBRARY_PATH variable is not set correctly. Make sure you follow the installation"
-      echo "instructions to add the correct lines to ${CONDA_PREFIX}/etc/conda/activate.d/env_vars.sh"
-      echo
-      return=1
-      MPI_AND_NRNIV_WORKS=1
-    else
-      echo "failed"
-      echo "Could not run nrniv with MPI"
-      echo "The command that failed was:"
-      echo "$COMMAND"
-      echo "Tried environment variable LD_LIBRARY_PATH=${CONDA_PREFIX}/lib"
-      echo "Command output (on a single line):"
-      echo $OUTPUT
-      echo
-      return=2
-    fi
+    echo "failed"
+    echo "Could not run nrniv with MPI"
+    echo "The command that failed was:"
+    echo "$COMMAND"
+    echo "Tried environment variable LD_LIBRARY_PATH=${CONDA_PREFIX}/lib"
+    echo "Command output (on a single line):"
+    echo $OUTPUT
+    echo
+    return=2
   fi
 else
   echo "Skipping NEURON funtionality tests with MPI."
 fi
 
 NRNIV_AND_PYTHON_AND_MPI_WORKS=
 if [[ "$NRN_FOUND" -eq "1" ]] && [[ "$NRNIV_WORKS" -eq "1" ]] &&
-  [[ "$PREREQS_INSTALLED" -eq "1" ]] && [[ "$MPI_WORKS" -eq "1" ]] &&
+  [[ "$PREREQS_INSTALLED" -eq "1" ]] &&
   [[ "$MPI_AND_NRNIV_WORKS" -eq "1" ]]; then
- echo -n "Checking NEURON nrniv funtionality with Python and MPI..."
- COMMAND="mpiexec -n 2 nrniv -nobanner -mpi -python -c 'from neuron import h; pc = h.ParallelContext(); h.quit()'  2>&1"
- OUTPUT=$(mpiexec -n 2 nrniv -nobanner -mpi -python -c 'from neuron import h; pc = h.ParallelContext(); h.quit()'  2>&1)
- if [[ "$?" -eq "0" ]]; then
-   echo "ok"
-   NRNIV_AND_PYTHON_AND_MPI_WORKS=1
- else
-   echo "failed"
-   echo "Could not run nrniv with Python and MPI"
-   echo "the command that failed was:"
-   echo "$COMMAND"
-   echo $OUTPUT
-   return=2
-   fi
+  echo -n "Checking NEURON nrniv funtionality with Python and MPI..."
+  COMMAND="mpiexec -n 2 nrniv -nobanner -mpi -python -c 'from neuron import h; pc = h.ParallelContext(); h.quit()'  2>&1"
+  OUTPUT=$(export LD_LIBRARY_PATH=${CONDA_PREFIX}/lib; mpiexec -n 2 nrniv -nobanner -mpi -python -c 'from neuron import h; pc = h.ParallelContext(); h.quit()' 2>&1)
+  if [[ "$?" -eq "0" ]]; then
+    echo "ok"
+    NRNIV_AND_PYTHON_AND_MPI_WORKS=1
+  else
+    echo "failed"
+    echo "Could not run nrniv with Python and MPI"
+    echo "the command that failed was:"
+    echo "$COMMAND"
+    echo "Tried environment variable LD_LIBRARY_PATH=${CONDA_PREFIX}/lib"
+    echo "Command output (on a single line):"
+    echo $OUTPUT
+    echo
+    return=2
+  fi
 else
- echo "Skipping NEURON funtionality tests with Python and MPI."
+  echo "Skipping NEURON funtionality tests with Python and MPI."
 fi
 
 

diff --git a/installer/mac/check-pre.sh b/installer/mac/check-pre.sh
@@ -91,8 +91,7 @@ if [ -n "$PYTHONPATH" ]; then
   if [[ "$PYTHONPATH" =~ "NEURON" ]] || [[ "$PYTHONPATH" =~ "NRN" ]]; then
     echo "warning"
     echo "NEURON libraries found in PYTHONPATH variable. This was used before "
-    echo "the 'pip install' method. Make sure this matches the version used to "
-    echo "compile HNN modules with 'make'"
+    echo "the 'pip install' method."
     echo "PYTHONPATH=$PYTHONPATH"
     echo
     return=1